S2OPC OPCUA Toolkit: /builds/systerel/S2OPC/src/Common/crypto/sopc_key_cert

The SOPC_KeyCertPair stores a private key and certificate pair and allows to update it and triggering an associated external treatment. SOPC_KeyCertPair is thread-safe for accessing / updating the key and certificate pair. More...

#include <stddef.h>
#include <stdint.h>
#include "sopc_enums.h"
#include "sopc_key_manager.h"

Go to the source code of this file.

Typedefs
typedef struct SOPC_KeyCertPair	SOPC_KeyCertPair
	An abstract structure used to store a pair of private key and certificate. More...

typedef void	SOPC_KeyCertPairUpdateCb(uintptr_t updateParam)
	Type of the callback triggered on key / certificate update. More...

typedef SOPC_KeyCertPair	SOPC_CertHolder
	An abstract structure used to store a certificate in a thread-safe context. More...

Functions
SOPC_ReturnStatus	SOPC_KeyCertPair_CreateFromPaths (const char certPath, const char privateKeyPath, char keyPassword, SOPC_KeyCertPair *ppKeyCertPair)
	Creates a private key / certificate pair from file paths. The private key decryption password shall be provided if the key file is encrypted. More...

SOPC_ReturnStatus	SOPC_KeyCertPair_CreateFromBytes (size_t certificateNbBytes, const unsigned char certificate, size_t keyNbBytes, const unsigned char privateKey, SOPC_KeyCertPair **ppKeyCertPair)
	Creates a private key / certificate pair from bytes arrays. More...

SOPC_ReturnStatus	SOPC_KeyCertPair_SetUpdateCb (SOPC_KeyCertPair keyCertPair, SOPC_KeyCertPairUpdateCb updateCb, uintptr_t updateParam)
	Defines the callback to be called when a key/certificate update is done with SOPC_KeyCertPair_UpdateFromBytes. It is mandatory to define an associated behavior to allow calls to SOPC_KeyCertPair_UpdateFromBytes. This is used to re-evaluate connections using the previous key/certificate. More...

SOPC_ReturnStatus	SOPC_KeyCertPair_UpdateFromBytes (SOPC_KeyCertPair keyCertPair, size_t certificateNbBytes, const unsigned char certificate, size_t keyNbBytes, const unsigned char *privateKey)
	Updates the private key and/or certificate of the pair from bytes arrays. If the certificate uses the same public/private keys pair, the private key might not be updated. More...

SOPC_ReturnStatus	SOPC_KeyCertPair_GetSerializedCertCopy (SOPC_KeyCertPair keyCertPair, SOPC_SerializedCertificate *ppCertCopy)
	Gets a copy of the serialized certificate contained in the key /certificate pair. More...

SOPC_ReturnStatus	SOPC_KeyCertPair_GetCertCopy (SOPC_KeyCertPair keyCertPair, SOPC_CertificateList *ppCertCopy)
	Gets a copy of the certificate contained in the key /certificate pair. More...

SOPC_ReturnStatus	SOPC_KeyCertPair_GetKeyCopy (SOPC_KeyCertPair keyCertPair, SOPC_AsymmetricKey *ppKeyCopy)
	Gets a copy of the private key contained in the key /certificate pair. More...

void	SOPC_KeyCertPair_Delete (SOPC_KeyCertPair **ppKeyCertPair)
	Clears and frees the key / certificate pair and set pointer to NULL. More...

SOPC_ReturnStatus	SOPC_KeyCertPair_CreateCertHolderFromPath (const char certPath, SOPC_CertHolder *ppCertHolder)
	Creates a certificate holder from file path. More...

SOPC_ReturnStatus	SOPC_KeyCertPair_CreateCertHolderFromBytes (size_t certificateNbBytes, const unsigned char certificate, SOPC_CertHolder *ppCertHolder)
	Creates a certificate holder from bytes arrays. More...

Detailed Description

Typedef Documentation

◆ SOPC_KeyCertPair

typedef struct SOPC_KeyCertPair SOPC_KeyCertPair

An abstract structure used to store a pair of private key and certificate.

◆ SOPC_KeyCertPairUpdateCb

typedef void SOPC_KeyCertPairUpdateCb(uintptr_t updateParam)

Type of the callback triggered on key / certificate update.

Parameters

updateParam a user defined parameter for the callback

◆ SOPC_CertHolder

typedef SOPC_KeyCertPair SOPC_CertHolder

An abstract structure used to store a certificate in a thread-safe context.

Function Documentation

◆ SOPC_KeyCertPair_CreateFromPaths()

SOPC_ReturnStatus SOPC_KeyCertPair_CreateFromPaths	(	const char *	certPath,
		const char *	privateKeyPath,
		char *	keyPassword,
		SOPC_KeyCertPair **	ppKeyCertPair
	)

Creates a private key / certificate pair from file paths. The private key decryption password shall be provided if the key file is encrypted.

Parameters

	certPath	the file path to a X509 certificate in DER format
	privateKeyPath	the file path to a private key in PEM or DER format (PEM if encrypted)
	keyPassword	(optional) the password to decrypt the private key file if it is encrypted or NULL. If not NULL it shall be a NULL terminated C string.
[out]	ppKeyCertPair	A pointer to the newly allocated and filled with key/certificate pair in case of success

Returns: SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case a parameter is NULL (except keyPassword ), SOPC_STATUS_OUT_OF_MEMORY in case of memory issue or SOPC_STATUS_NOK in other cases.

◆ SOPC_KeyCertPair_CreateFromBytes()

SOPC_ReturnStatus SOPC_KeyCertPair_CreateFromBytes	(	size_t	certificateNbBytes,
		const unsigned char *	certificate,
		size_t	keyNbBytes,
		const unsigned char *	privateKey,
		SOPC_KeyCertPair **	ppKeyCertPair
	)

Creates a private key / certificate pair from bytes arrays.

Parameters

	certificateNbBytes	the number of bytes in `certificate`
	certificate	the bytes array containing one X509 certificate (DER / PEM)
	keyNbBytes	the number of bytes in `privateKey`
	privateKey	the bytes array containing the private key associated to `certificate` (DER / PEM)
[out]	ppKeyCertPair	A pointer to the newly allocated and filled with key/certificate pair in case of success

Returns: SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case a parameter is NULL (except keyPassword ) and SOPC_STATUS_OUT_OF_MEMORY in case of memory issue.

◆ SOPC_KeyCertPair_SetUpdateCb()

SOPC_ReturnStatus SOPC_KeyCertPair_SetUpdateCb	(	SOPC_KeyCertPair *	keyCertPair,
		SOPC_KeyCertPairUpdateCb *	updateCb,
		uintptr_t	updateParam
	)

Defines the callback to be called when a key/certificate update is done with SOPC_KeyCertPair_UpdateFromBytes. It is mandatory to define an associated behavior to allow calls to SOPC_KeyCertPair_UpdateFromBytes. This is used to re-evaluate connections using the previous key/certificate.

Parameters

keyCertPair	the key / certificate pair for which an update callback will be defined
updateCb	the callback to be called when a key/certificate update is done
updateParam	a user defined parameter for the callback

Returns: SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of NULL parameter and SOPC_STATUS_INVALID_STATE in case a callback is already defined.

◆ SOPC_KeyCertPair_UpdateFromBytes()

SOPC_ReturnStatus SOPC_KeyCertPair_UpdateFromBytes	(	SOPC_KeyCertPair *	keyCertPair,
		size_t	certificateNbBytes,
		const unsigned char *	certificate,
		size_t	keyNbBytes,
		const unsigned char *	privateKey
	)

Updates the private key and/or certificate of the pair from bytes arrays. If the certificate uses the same public/private keys pair, the private key might not be updated.

Warning: A callback shall have been defined using SOPC_KeyCertPair_SetUpdateCb otherwise update is not authorized

Parameters

keyCertPair	the key / certificate pair for which an update will be done
certificateNbBytes	the number of bytes in `certificate`
certificate	the bytes array containing one X509 certificate (DER / PEM)
keyNbBytes	(optional) the number of bytes in `privateKey` or 0
privateKey	(optional) the bytes array containing the private key associated to `certificate` (DER / PEM) or NULL if the certificate public key is unchanged

Returns: SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case a parameter is NULL (except privateKey) or invalid, SOPC_STATUS_INVALID_STATE in case update callback is not set and SOPC_STATUS_OUT_OF_MEMORY in case of memory issue.

◆ SOPC_KeyCertPair_GetSerializedCertCopy()

SOPC_ReturnStatus SOPC_KeyCertPair_GetSerializedCertCopy	(	SOPC_KeyCertPair *	keyCertPair,
		SOPC_SerializedCertificate **	ppCertCopy
	)

Gets a copy of the serialized certificate contained in the key /certificate pair.

Parameters

	keyCertPair	the key / certificate pair for which a copy of the serialized certificate is requested
[out]	ppCertCopy	a pointer to the newly allocated serialized certificate copy in case of success. It shall be deallocated by caller using SOPC_KeyManager_SerializedCertificate_Delete.

Returns: SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of NULL parameter and SOPC_STATUS_OUT_OF_MEMORY in case of memory issue.

◆ SOPC_KeyCertPair_GetCertCopy()

SOPC_ReturnStatus SOPC_KeyCertPair_GetCertCopy	(	SOPC_KeyCertPair *	keyCertPair,
		SOPC_CertificateList **	ppCertCopy
	)

Gets a copy of the certificate contained in the key /certificate pair.

Parameters

	keyCertPair	the key / certificate pair for which a copy of the certificate is requested
[out]	ppCertCopy	a pointer to the newly allocated certificate copy in case of success. It shall be deallocated by caller using SOPC_KeyManager_Certificate_Free.

Returns: SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of NULL parameter and SOPC_STATUS_OUT_OF_MEMORY in case of memory issue.

◆ SOPC_KeyCertPair_GetKeyCopy()

SOPC_ReturnStatus SOPC_KeyCertPair_GetKeyCopy	(	SOPC_KeyCertPair *	keyCertPair,
		SOPC_AsymmetricKey **	ppKeyCopy
	)

Gets a copy of the private key contained in the key /certificate pair.

Parameters

	keyCertPair	the key / certificate pair for which a copy of the key is requested
[out]	ppKeyCopy	a pointer to the newly allocated key copy in case of success. It shall be deallocated by caller using SOPC_KeyManager_AsymmetricKey_Free.

Returns: SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case of NULL parameter and SOPC_STATUS_OUT_OF_MEMORY in case of memory issue.

◆ SOPC_KeyCertPair_Delete()

void SOPC_KeyCertPair_Delete ( SOPC_KeyCertPair ** ppKeyCertPair )

Clears and frees the key / certificate pair and set pointer to NULL.

Parameters

[out] ppKeyCertPair pointer to the key / certificate pair to delete, it is set to NULL in case of success

◆ SOPC_KeyCertPair_CreateCertHolderFromPath()

SOPC_ReturnStatus SOPC_KeyCertPair_CreateCertHolderFromPath	(	const char *	certPath,
		SOPC_CertHolder **	ppCertHolder
	)

Creates a certificate holder from file path.

Note: SOPC_KeyCertPair functions should then be used to access/update the stored certificate

Parameters

	certPath	the file path to a X509 certificate in DER format
[out]	ppCertHolder	A pointer to the newly allocated holder filled with certificate holder in case of success

Returns: SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case a parameter is NULL SOPC_STATUS_OUT_OF_MEMORY in case of memory issue or SOPC_STATUS_NOK in other cases.

◆ SOPC_KeyCertPair_CreateCertHolderFromBytes()

SOPC_ReturnStatus SOPC_KeyCertPair_CreateCertHolderFromBytes	(	size_t	certificateNbBytes,
		const unsigned char *	certificate,
		SOPC_CertHolder **	ppCertHolder
	)

Creates a certificate holder from bytes arrays.

Note: SOPC_KeyCertPair functions should then be used to access/update the stored certificate

Parameters

	certificateNbBytes	the number of bytes in `certificate`
	certificate	the bytes array containing one X509 certificate (DER / PEM)
[out]	ppCertHolder	A pointer to the newly allocated holder filled with certificate in case of success

Returns: SOPC_STATUS_OK in case of success, SOPC_STATUS_INVALID_PARAMETERS in case a parameter is NULL and SOPC_STATUS_OUT_OF_MEMORY in case of memory issue.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ SOPC_KeyCertPair

◆ SOPC_KeyCertPairUpdateCb

◆ SOPC_CertHolder

Function Documentation

◆ SOPC_KeyCertPair_CreateFromPaths()

◆ SOPC_KeyCertPair_CreateFromBytes()

◆ SOPC_KeyCertPair_SetUpdateCb()

◆ SOPC_KeyCertPair_UpdateFromBytes()

◆ SOPC_KeyCertPair_GetSerializedCertCopy()

◆ SOPC_KeyCertPair_GetCertCopy()

◆ SOPC_KeyCertPair_GetKeyCopy()

◆ SOPC_KeyCertPair_Delete()

◆ SOPC_KeyCertPair_CreateCertHolderFromPath()

◆ SOPC_KeyCertPair_CreateCertHolderFromBytes()