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

The SOPC_KeyManager provides an API for Asymmetric Key Management such as loading signed public keys (Certificate) and the corresponding private key. More...

#include <stddef.h>
#include "sopc_buffer.h"
#include "sopc_crypto_decl.h"
#include "sopc_secret_buffer.h"

Go to the source code of this file.

Typedefs
typedef SOPC_SecretBuffer	SOPC_SerializedAsymmetricKey
	A serialized representation of an asymmetric key. More...

typedef SOPC_Buffer	SOPC_SerializedCertificate
	A serialized representation of a certificate. More...

Functions
SOPC_ReturnStatus	SOPC_KeyManager_AsymmetricKey_CreateFromBuffer (const uint8_t buffer, uint32_t lenBuf, bool is_public, SOPC_AsymmetricKey *ppKey)
	Creates an asymmetric key (usually a private key) from in-memory buffer `buffer`. More...

SOPC_ReturnStatus	SOPC_KeyManager_AsymmetricKey_CreateFromFile (const char szPath, SOPC_AsymmetricKey ppKey, char password, uint32_t lenPassword)
	Creates an asymmetric key (usually a private key) from a file in the DER or PEM format. More...

SOPC_ReturnStatus	SOPC_KeyManager_AsymmetricKey_CreateFromCertificate (const SOPC_CertificateList pCert, SOPC_AsymmetricKey *pKey)
	Returns the public key of the signed public key. More...

void	SOPC_KeyManager_AsymmetricKey_Free (SOPC_AsymmetricKey *pKey)
	Frees a previously created asymmetric key created with SOPC_KeyManager_AsymmetricKey_CreateFromBuffer() or SOPC_KeyManager_AsymmetricKey_CreateFromFile(). More...

SOPC_ReturnStatus	SOPC_KeyManager_AsymmetricKey_ToDER (const SOPC_AsymmetricKey pKey, bool is_public, uint8_t pDest, uint32_t lenDest, uint32_t *pLenWritten)
	Encodes the `pKey` as a DER buffer, and writes the result in `pDest`. More...

SOPC_ReturnStatus	SOPC_KeyManager_SerializedAsymmetricKey_CreateFromData (const uint8_t data, uint32_t len, SOPC_SerializedAsymmetricKey *key)
	Creates a serialized asymmetric key from a DER or PEM payload. More...

SOPC_ReturnStatus	SOPC_KeyManager_SerializedAsymmetricKey_CreateFromFile (const char path, SOPC_SerializedAsymmetricKey *key)
	Creates a serialized asymmetric key from a file in DER or PEM format. More...

SOPC_ReturnStatus	SOPC_KeyManager_SerializedAsymmetricKey_CreateFromFile_WithPwd (const char keyPath, SOPC_SerializedAsymmetricKey key, char password, uint32_t lenPassword)
	Creates a serialized asymmetric key from a file in DER or PEM format with an optional `password` for the encrypted private key (PEM format). More...

SOPC_ReturnStatus	SOPC_KeyManager_SerializedAsymmetricKey_CreateFromKey (const SOPC_AsymmetricKey pKey, bool is_public, SOPC_SerializedAsymmetricKey *out)
	Creates a serialized asymmetric key from an SOPC_AsymmetricKey structure. More...

SOPC_ReturnStatus	SOPC_KeyManager_SerializedAsymmetricKey_Deserialize (const SOPC_SerializedAsymmetricKey key, bool is_public, SOPC_AsymmetricKey *res)
	Deserializes a serialized key. More...

void	SOPC_KeyManager_SerializedAsymmetricKey_Delete (SOPC_SerializedAsymmetricKey *key)
	Releases all resources associated to a serialized asymmetric key. More...

SOPC_ReturnStatus	SOPC_KeyManager_Certificate_CreateOrAddFromDER (const uint8_t bufferDER, uint32_t lenDER, SOPC_CertificateList *ppCert)
	Creates a new Certificate (signed public key) from a DER encoded buffer, or add it to an existing certificate list. More...

SOPC_ReturnStatus	SOPC_KeyManager_Certificate_CreateOrAddFromFile (const char szPath, SOPC_CertificateList *ppCert)
	Creates a new Certificate (signed public key) from a file in the DER or PEM format, or add it to an existing certificate list. More...

void	SOPC_KeyManager_Certificate_Free (SOPC_CertificateList *pCert)
	Frees a Certificate created with SOPC_KeyManager_Certificate_CreateOrAddFromFile() or SOPC_KeyManager_Certificate_CreateOrAddFromDER() More...

SOPC_ReturnStatus	SOPC_KeyManager_Certificate_ToDER (const SOPC_CertificateList pCert, uint8_t ppDest, uint32_t pLenAllocated)
	Encodes a `pCert` as a DER buffer and writes the result in `ppDest`. More...

SOPC_ReturnStatus	SOPC_KeyManager_Certificate_GetThumbprint (const SOPC_CryptoProvider pProvider, const SOPC_CertificateList pCert, uint8_t *pDest, uint32_t lenDest)
	Computes and writes the thumbprint of `pCert` to `pDest`. More...

bool	SOPC_KeyManager_Certificate_CheckApplicationUri (const SOPC_CertificateList pCert, const char applicationUri)
	Verify the application URI embedded in a certificate. More...

SOPC_ReturnStatus	SOPC_KeyManager_Certificate_GetMaybeApplicationUri (const SOPC_CertificateList pCert, char ppApplicationUri, size_t pStringLength)
	Copy the application URI embedded in a certificate. More...

SOPC_ReturnStatus	SOPC_KeyManager_Certificate_GetListLength (const SOPC_CertificateList pCert, size_t pLength)
	Return the number of chained certificates in the certificate list `pCert`. More...

SOPC_ReturnStatus	SOPC_KeyManager_CertificateList_RemoveUnmatchedCRL (SOPC_CertificateList pCert, const SOPC_CRLList pCRL, bool *pbMatch)
	Removes (and frees) certificates from `pCert` that do not have exactly one revocation list in `pCRL`. More...

SOPC_ReturnStatus	SOPC_KeyManager_CertificateList_FindCertInList (const SOPC_CertificateList pList, const SOPC_CertificateList pCert, bool *pbMatch)
	Finds whether a certificate is in the given certificate list or not. More...

SOPC_ReturnStatus	SOPC_KeyManager_SerializedCertificate_CreateFromDER (const uint8_t der, uint32_t len, SOPC_SerializedCertificate *cert)
	Creates a serialized certificate from a DER payload. More...

SOPC_ReturnStatus	SOPC_KeyManager_SerializedCertificate_CreateFromFile (const char path, SOPC_SerializedCertificate *cert)
	Creates a serialized certificate from a file in DER format. More...

SOPC_ReturnStatus	SOPC_KeyManager_SerializedCertificate_Deserialize (const SOPC_SerializedCertificate cert, SOPC_CertificateList *res)
	Deserializes a serialized certificate. More...

const SOPC_Buffer *	SOPC_KeyManager_SerializedCertificate_Data (const SOPC_SerializedCertificate *cert)
	Returns the data held in a serialized certificate. More...

char *	SOPC_KeyManager_Certificate_GetCstring_SHA1 (SOPC_CertificateList *pCert)
	Returns the SHA-1 thumbprint of a certificate. More...

void	SOPC_KeyManager_SerializedCertificate_Delete (SOPC_SerializedCertificate *cert)
	Releases all resources associated to a serialized certificate. More...

SOPC_ReturnStatus	SOPC_KeyManager_CRL_CreateOrAddFromDER (const uint8_t bufferDER, uint32_t lenDER, SOPC_CRLList *ppCRL)
	Creates a new Certificate Revocation List (CRL) from a DER encoded buffer, or add it to an existing CRL list. More...

SOPC_ReturnStatus	SOPC_KeyManager_CRL_CreateOrAddFromFile (const char szPath, SOPC_CRLList *ppCRL)
	Creates a new Certificate Revocation List (CRL) from a file in the DER or PEM format, or add it to an existing CRL list. More...

void	SOPC_KeyManager_CRL_Free (SOPC_CRLList *pCRL)
	Frees a Certificate created with SOPC_KeyManager_CRL_CreateOrAddFromFile() or SOPC_KeyManager_CRL_CreateOrAddFromDER() More...

Detailed Description

The SOPC_KeyManager provides an API for Asymmetric Key Management such as loading signed public keys (Certificate) and the corresponding private key.

KeyManager is different than PKIProvider, which only handles signed public key validation and storage.

KeyManager API is context-less. The KeyManager is generic, and is not linked to the current security policy.

Typedef Documentation

◆ SOPC_SerializedAsymmetricKey

typedef SOPC_SecretBuffer SOPC_SerializedAsymmetricKey

A serialized representation of an asymmetric key.

This representation is safe to share across threads.

◆ SOPC_SerializedCertificate

typedef SOPC_Buffer SOPC_SerializedCertificate

A serialized representation of a certificate.

This representation is safe to share across threads.

Function Documentation

◆ SOPC_KeyManager_AsymmetricKey_CreateFromBuffer()

SOPC_ReturnStatus SOPC_KeyManager_AsymmetricKey_CreateFromBuffer	(	const uint8_t *	buffer,
		uint32_t	lenBuf,
		bool	is_public,
		SOPC_AsymmetricKey **	ppKey
	)

Creates an asymmetric key (usually a private key) from in-memory buffer buffer.

buffer is lenBuf long, and describes the key in the DER of PEM format.

Public keys are usually extracted from Certificate, see SOPC_KeyManager_AsymmetricKey_CreateFromCertificate() or SOPC_KeyManager_AsymmetricKey_CreateFromCertificate().

Parameters

buffer	A valid pointer to the buffer containing the DER or PEM description.
lenBuf	The length in bytes of the DER/PEM description of the key.
is_public	Whether the buffer holds a public or a private key.
ppKey	A handle to the created key. This object must be freed with a call to SOPC_KeyManager_AsymmetricKey_Free().

Note: Content of the key is unspecified when return value is not SOPC_STATUS_OK.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL, and SOPC_STATUS_NOK when there was an error.

◆ SOPC_KeyManager_AsymmetricKey_CreateFromFile()

SOPC_ReturnStatus SOPC_KeyManager_AsymmetricKey_CreateFromFile	(	const char *	szPath,
		SOPC_AsymmetricKey **	ppKey,
		char *	password,
		uint32_t	lenPassword
	)

Creates an asymmetric key (usually a private key) from a file in the DER or PEM format.

szPath is the path to the file containing the key. It should be zero-terminated. The key may be described in the DER of PEM format.

Public keys are usually extracted from Certificate, see SOPC_KeyManager_AsymmetricKey_CreateFromCertificate() or SOPC_KeyManager_AsymmetricKey_CreateFromCertificate().

Parameters

szPath	The path to the DER/PEM file.
ppKey	A handle to the created key. This object must be freed with a call to SOPC_KeyManager_AsymmetricKey_Free().
password	An optional password. The password must be a zero-terminated string with at most `lenPassword` non null chars, and at least `lenPassword` + 1 allocated chars.
lenPassword	The length of the password.

Note: Content of the key is unspecified when return value is not SOPC_STATUS_OK. Supported encryption algorithm: AES-128-CBC, AES-192-CBC and AES-256-CBC

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL, and SOPC_STATUS_NOK when there was an error.

◆ SOPC_KeyManager_AsymmetricKey_CreateFromCertificate()

SOPC_ReturnStatus SOPC_KeyManager_AsymmetricKey_CreateFromCertificate	(	const SOPC_CertificateList *	pCert,
		SOPC_AsymmetricKey **	pKey
	)

Returns the public key of the signed public key.

Warning: The returned SOPC_AsymmetricKey must not be used after the Certificate is freed by SOPC_KeyManager_Certificate_Free().

Parameters

pCert	A valid pointer to the signed public key.
pKey	A handle to the created key structure, the SOPC_AsymmetricKey will then be rewritten to contain the public key. This is not a deep copy, and the key is not valid anymore when the certificate is not valid. This object must be freed with a call to SOPC_KeyManager_AsymmetricKey_Free() which will only deallocate the structure.

Note: Content of the certificate is unspecified when return value is not SOPC_STATUS_OK.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL, and SOPC_STATUS_NOK when there was an error.

◆ SOPC_KeyManager_AsymmetricKey_Free()

void SOPC_KeyManager_AsymmetricKey_Free ( SOPC_AsymmetricKey * pKey )

Frees a previously created asymmetric key created with SOPC_KeyManager_AsymmetricKey_CreateFromBuffer() or SOPC_KeyManager_AsymmetricKey_CreateFromFile().

Note: Do not use this function on a key obtained from SOPC_KeyManager_Certificate_GetPublicKey().

Parameters

pKey	A valid pointer to the key to free.

◆ SOPC_KeyManager_AsymmetricKey_ToDER()

SOPC_ReturnStatus SOPC_KeyManager_AsymmetricKey_ToDER	(	const SOPC_AsymmetricKey *	pKey,
		bool	is_public,
		uint8_t *	pDest,
		uint32_t	lenDest,
		uint32_t *	pLenWritten
	)

Encodes the pKey as a DER buffer, and writes the result in pDest.

The encoding process is not predictable, and a buffer of sufficient length must be provided. A rule of thumb is to provide a buffer which is at least 8 times longer than the key (8*SOPC_CryptoProvider_AsymmetricGetLength_KeyBytes()).

When SOPC_STATUS_NOK is returned, the function may be called again with a larger buffer.

Parameters

pKey	A valid pointer to the asymmetric key (public/private) to encode.
is_public	Whether the key is public or private.
pDest	A valid pointer to the buffer which will receive the DER encoded key.
lenDest	The length in bytes of the buffer `pDest`.
pLenWritten	A valid pointer to the number of bytes written to pDest.

Note: Content of the output is unspecified when return value is not SOPC_STATUS_OK.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL, and SOPC_STATUS_NOK when there was an error.

◆ SOPC_KeyManager_SerializedAsymmetricKey_CreateFromData()

SOPC_ReturnStatus SOPC_KeyManager_SerializedAsymmetricKey_CreateFromData	(	const uint8_t *	data,
		uint32_t	len,
		SOPC_SerializedAsymmetricKey **	key
	)

Creates a serialized asymmetric key from a DER or PEM payload.

Parameters

data	the key data in DER or PEM format
len	length of the data
key	out parameter, the created serialized key

Returns: SOPC_STATUS_OK on success, or an error code in case of failure.

◆ SOPC_KeyManager_SerializedAsymmetricKey_CreateFromFile()

SOPC_ReturnStatus SOPC_KeyManager_SerializedAsymmetricKey_CreateFromFile	(	const char *	path,
		SOPC_SerializedAsymmetricKey **	key
	)

Creates a serialized asymmetric key from a file in DER or PEM format.

Parameters

path	path to the file
key	out parameter, the created serialized key

Deprecated:: Use SOPC_KeyManager_SerializedAsymmetricKey_CreateFromFile_WithPwd instead

Returns: SOPC_STATUS_OK on success, or an error code in case of failure.

◆ SOPC_KeyManager_SerializedAsymmetricKey_CreateFromFile_WithPwd()

SOPC_ReturnStatus SOPC_KeyManager_SerializedAsymmetricKey_CreateFromFile_WithPwd	(	const char *	keyPath,
		SOPC_SerializedAsymmetricKey **	key,
		char *	password,
		uint32_t	lenPassword
	)

Creates a serialized asymmetric key from a file in DER or PEM format with an optional password for the encrypted private key (PEM format).

Parameters

keyPath	The path to the DER/PEM file.
key	the newly allocated serialized.
password	An optional password (!= NULL). The password must be a zero-terminated string with at most `lenPassword` non null chars, and at least `lenPassword` + 1 allocated chars.
lenPassword	The length of the password.

Note: Supported encryption algorithm: AES-128-CBC, AES-192-CBC and AES-256-CBC

Returns: SOPC_STATUS_OK on success, or an error code in case of failure.

◆ SOPC_KeyManager_SerializedAsymmetricKey_CreateFromKey()

SOPC_ReturnStatus SOPC_KeyManager_SerializedAsymmetricKey_CreateFromKey	(	const SOPC_AsymmetricKey *	pKey,
		bool	is_public,
		SOPC_SerializedAsymmetricKey **	out
	)

Creates a serialized asymmetric key from an SOPC_AsymmetricKey structure.

Parameters

pKey	A valid pointer to the asymmetric key (public/private) to serialize.
is_public	Whether the key is public or private.
out	the newly allocated serialized key

Returns: SOPC_STATUS_OK on success, or an error code in case of failure.

◆ SOPC_KeyManager_SerializedAsymmetricKey_Deserialize()

SOPC_ReturnStatus SOPC_KeyManager_SerializedAsymmetricKey_Deserialize	(	const SOPC_SerializedAsymmetricKey *	key,
		bool	is_public,
		SOPC_AsymmetricKey **	res
	)

Deserializes a serialized key.

Parameters

key	the serialized key
is_public	whether the serialized key is a public or a private key
res	out parameter, the decoded key as a newly allocated SOPC_AsymmetricKey

Returns: SOPC_STATUS_OK on success, or an error code in case of failure.

◆ SOPC_KeyManager_SerializedAsymmetricKey_Delete()

void SOPC_KeyManager_SerializedAsymmetricKey_Delete ( SOPC_SerializedAsymmetricKey * key )

Releases all resources associated to a serialized asymmetric key.

Parameters

key	The serialized key

◆ SOPC_KeyManager_Certificate_CreateOrAddFromDER()

SOPC_ReturnStatus SOPC_KeyManager_Certificate_CreateOrAddFromDER	(	const uint8_t *	bufferDER,
		uint32_t	lenDER,
		SOPC_CertificateList **	ppCert
	)

Creates a new Certificate (signed public key) from a DER encoded buffer, or add it to an existing certificate list.

bufferDER is lenDER long, and describes the certificate in the DER format.

Parameters

bufferDER	A valid pointer to the buffer containing the DER description.
lenDER	The length in bytes of the DER description of the certificate.
ppCert	Creation: a valid handle which will point to the newly created Certificate. Addition: a pointer to a pointer to a Certificate list to which add the certificate. In either cases, this object must be freed with a call to SOPC_KeyManager_Certificate_Free().

Note: Content of the certificate is unspecified when return value is not SOPC_STATUS_OK. However, in case of a failed addition, the whole certificate list is freed, and ppCert set to NULL to avoid double frees.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL, and SOPC_STATUS_NOK when there was an error.

◆ SOPC_KeyManager_Certificate_CreateOrAddFromFile()

SOPC_ReturnStatus SOPC_KeyManager_Certificate_CreateOrAddFromFile	(	const char *	szPath,
		SOPC_CertificateList **	ppCert
	)

Creates a new Certificate (signed public key) from a file in the DER or PEM format, or add it to an existing certificate list.

szPath is the path to the file containing the key. It should be zero-terminated. The key may be described in the DER of PEM format.

Parameters

szPath	The path to the DER/PEM file.
ppCert	Creation: a valid handle which will point to the newly created Certificate. Addition: a pointer to a pointer to a Certificate list to which add the certificate. In either cases, this object must be freed with a call to SOPC_KeyManager_Certificate_Free().

Note: Content of the certificate is unspecified when return value is not SOPC_STATUS_OK. However, in case of a failed addition, the whole certificate list is freed, and ppCert set to NULL to avoid double frees.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL, and SOPC_STATUS_NOK when there was an error.

◆ SOPC_KeyManager_Certificate_Free()

void SOPC_KeyManager_Certificate_Free ( SOPC_CertificateList * pCert )

Frees a Certificate created with SOPC_KeyManager_Certificate_CreateOrAddFromFile() or SOPC_KeyManager_Certificate_CreateOrAddFromDER()

Warning: You must not free a Certificate for which a key is still being used. See SOPC_KeyManager_Certificate_GetPublicKey() and SOPC_KeyManager_AsymmetricKey_CreateFromCertificate().

Parameters

pCert The Certificate to free.

◆ SOPC_KeyManager_Certificate_ToDER()

SOPC_ReturnStatus SOPC_KeyManager_Certificate_ToDER	(	const SOPC_CertificateList *	pCert,
		uint8_t **	ppDest,
		uint32_t *	pLenAllocated
	)

Encodes a pCert as a DER buffer and writes the result in ppDest.

Parameters

pCert	A valid pointer to the Certificate. There must be only one certificate in the list.
ppDest	A valid pointer to the newly created buffer that stores the DER description of the signed public key. The allocated buffer must be freed by the caller.
pLenAllocated	A valid pointer to the length allocated by this operation.

Note: Content of the output is unspecified when return value is not SOPC_STATUS_OK.

Warning: pCert must contain a single certificate.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or the certificate list contains more than one certificate, and SOPC_STATUS_NOK when there was an error.

◆ SOPC_KeyManager_Certificate_GetThumbprint()

SOPC_ReturnStatus SOPC_KeyManager_Certificate_GetThumbprint	(	const SOPC_CryptoProvider *	pProvider,
		const SOPC_CertificateList *	pCert,
		uint8_t *	pDest,
		uint32_t	lenDest
	)

Computes and writes the thumbprint of pCert to pDest.

The computation of the thumbprint and its size depends on the current security policy. The thumbprint is usually a SHA digest of the DER representation of the certificate.

The size of the thumbprint is provided by SOPC_CryptoProvider_CertificateGetLength_Thumbprint().

Parameters

pProvider	An initialized cryptographic context.
pCert	A valid pointer to the signed public key to thumbprint.
pDest	A valid pointer to the buffer that will contain the thumbprint.
lenDest	The length in bytes of `pDest`.

Note: Content of the output is unspecified when return value is not SOPC_STATUS_OK.

Warning: pCert must contain a single certificate.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or the certificate list contains more than one certificate, and SOPC_STATUS_NOK when there was an error.

◆ SOPC_KeyManager_Certificate_CheckApplicationUri()

bool SOPC_KeyManager_Certificate_CheckApplicationUri	(	const SOPC_CertificateList *	pCert,
		const char *	applicationUri
	)

Verify the application URI embedded in a certificate.

This function does a strict, case sensitive comparison of the URIs and does not respect the URI comparison rules from RFC3986 (the URI scheme comparison for example is case sensitive).

Warning: Some limitations apply, see SOPC_KeyManager_Certificate_GetMaybeApplicationUri.

Parameters

pCert	The certificate.
applicationUri	The value that should be stored in the URI subject altName of the certificate. This should be a zero-terminated string.

Warning: pCert must contain a single certificate.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or the certificate list contains more than one certificate,; TRUE if the values match, return FALSE else.

◆ SOPC_KeyManager_Certificate_GetMaybeApplicationUri()

SOPC_ReturnStatus SOPC_KeyManager_Certificate_GetMaybeApplicationUri	(	const SOPC_CertificateList *	pCert,
		char **	ppApplicationUri,
		size_t *	pStringLength
	)

Copy the application URI embedded in a certificate.

Warning: Some limitations apply when using the MbedTLS crypto backend: MbedTLS has no way to extract anything else than the DNS altName from the certificate extensions (see https://github.com/ARMmbed/mbedtls/pull/731). We have for now a poor man's ASN.1 "parser" that tries to find it. It should not be considered as secure, as it can produce false positives (ie. extract the application URI from a field that is not the right one).

Parameters

pCert	The certificate.
ppApplicationUri	A pointer to the newly allocated zero-terminated string containing the application URI.
pStringLength	Optional pointer to the string length (excluding the trailing \0).

Warning: pCert must contain a single certificate.

Returns: SOPC_STATUS_OK when successfully copied.

◆ SOPC_KeyManager_Certificate_GetListLength()

SOPC_ReturnStatus SOPC_KeyManager_Certificate_GetListLength	(	const SOPC_CertificateList *	pCert,
		size_t *	pLength
	)

Return the number of chained certificates in the certificate list pCert.

Parameters

pCert	The certificate or certificate list.
pLength	A valid pointer to the computed length of the list.

Note: Content of the output is unspecified when return value is not SOPC_STATUS_OK.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL.

◆ SOPC_KeyManager_CertificateList_RemoveUnmatchedCRL()

SOPC_ReturnStatus SOPC_KeyManager_CertificateList_RemoveUnmatchedCRL	(	SOPC_CertificateList *	pCert,
		const SOPC_CRLList *	pCRL,
		bool *	pbMatch
	)

Removes (and frees) certificates from pCert that do not have exactly one revocation list in pCRL.

This function does not set match to false if there are CRL that do not match any Certificate. This function skips certificates in /p pCert that are not authorities. Warning: this function fails with SOPC_STATUS_NOK if there are only CA without CRL.

Parameters

pCert	A valid pointer to the Certificate list.
pCRL	A valid pointer to the CRL list.
pbMatch	An optional pointer to the result of the test. True value indicates that each certificate in `pCert` has exactly one associated CRL in `pCRL`, and no certificate has been freed. Otherwise false.

Note: Content of pbMatch is unspecified when return value is not SOPC_STATUS_OK.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL, and SOPC_STATUS_NOK when all certificate are CA without CRL.

◆ SOPC_KeyManager_CertificateList_FindCertInList()

SOPC_ReturnStatus SOPC_KeyManager_CertificateList_FindCertInList	(	const SOPC_CertificateList *	pList,
		const SOPC_CertificateList *	pCert,
		bool *	pbMatch
	)

Finds whether a certificate is in the given certificate list or not.

Parameters

pList	An optional pointer to the Certificate list.
pCert	An optional pointer to a single Certificate to find in the list.
pbMatch	A valid pointer to the result of the find. True indicates that the certificate was found in the list. Otherwise false.

Warning: pCert must contain a single certificate.

Note: Content of the output is unspecified when return value is not SOPC_STATUS_OK.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pCert has more than one certificate.

◆ SOPC_KeyManager_SerializedCertificate_CreateFromDER()

SOPC_ReturnStatus SOPC_KeyManager_SerializedCertificate_CreateFromDER	(	const uint8_t *	der,
		uint32_t	len,
		SOPC_SerializedCertificate **	cert
	)

Creates a serialized certificate from a DER payload.

Parameters

der	the certificate data in DER format
len	length of the DER data
cert	out parameter, the created serialized certificate

Returns: SOPC_STATUS_OK on success, or an error code in case of failure.

◆ SOPC_KeyManager_SerializedCertificate_CreateFromFile()

SOPC_ReturnStatus SOPC_KeyManager_SerializedCertificate_CreateFromFile	(	const char *	path,
		SOPC_SerializedCertificate **	cert
	)

Creates a serialized certificate from a file in DER format.

Parameters

path	path to the file
cert	out parameter, the created serialized certificate

Returns: SOPC_STATUS_OK on success, or an error code in case of failure.

◆ SOPC_KeyManager_SerializedCertificate_Deserialize()

SOPC_ReturnStatus SOPC_KeyManager_SerializedCertificate_Deserialize	(	const SOPC_SerializedCertificate *	cert,
		SOPC_CertificateList **	res
	)

Deserializes a serialized certificate.

Parameters

cert	the serialized certificate
res	out parameter, the decoded certificate as a newly allocated SOPC_CertificateList

Returns: SOPC_STATUS_OK on success, or an error code in case of failure.

◆ SOPC_KeyManager_SerializedCertificate_Data()

const SOPC_Buffer* SOPC_KeyManager_SerializedCertificate_Data ( const SOPC_SerializedCertificate * cert )

Returns the data held in a serialized certificate.

Parameters

cert	the serialized certificate

Returns: The data held in the serialized certificate. The returned memory is owned by the serialized certificate, and should not be modified or freed.

◆ SOPC_KeyManager_Certificate_GetCstring_SHA1()

char* SOPC_KeyManager_Certificate_GetCstring_SHA1 ( SOPC_CertificateList * pCert )

Returns the SHA-1 thumbprint of a certificate.

Parameters

pCert A pointer to a single Certificate to find in the list.

Warning: pCert must contain a single certificate.

Note: The returned SHA-1 Cstring must be freed by the caller.

Returns: NULL if error otherwise the SHA-1 thumbprint of pCert .

◆ SOPC_KeyManager_SerializedCertificate_Delete()

void SOPC_KeyManager_SerializedCertificate_Delete ( SOPC_SerializedCertificate * cert )

Releases all resources associated to a serialized certificate.

Parameters

cert	The serialized certificate

◆ SOPC_KeyManager_CRL_CreateOrAddFromDER()

SOPC_ReturnStatus SOPC_KeyManager_CRL_CreateOrAddFromDER	(	const uint8_t *	bufferDER,
		uint32_t	lenDER,
		SOPC_CRLList **	ppCRL
	)

Creates a new Certificate Revocation List (CRL) from a DER encoded buffer, or add it to an existing CRL list.

bufferDER is lenDER long, and describes one CRL in the DER format.

Parameters

bufferDER	A valid pointer to the buffer containing the DER description.
lenDER	The length in bytes of the DER description of the certificate.
ppCRL	Creation: a valid handle which will point to the newly created CRL. Addition: a pointer to a pointer to a CRL list to which add the CRL. In either cases, this object must be freed with a call to SOPC_KeyManager_CRL_Free().

Note: Content of the CRL is unspecified when return value is not SOPC_STATUS_OK. However, in case of a failed addition, the whole CRL list is freed, and ppCRL set to NULL to avoid double frees.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL, and SOPC_STATUS_NOK when there was an error.

◆ SOPC_KeyManager_CRL_CreateOrAddFromFile()

SOPC_ReturnStatus SOPC_KeyManager_CRL_CreateOrAddFromFile	(	const char *	szPath,
		SOPC_CRLList **	ppCRL
	)

Creates a new Certificate Revocation List (CRL) from a file in the DER or PEM format, or add it to an existing CRL list.

szPath is the path to the file containing the key. It should be zero-terminated. The key may be described in the DER of PEM format.

Parameters

szPath	The path to the DER/PEM file.
ppCRL	Creation: a valid handle which will point to the newly created CRL. Addition: a pointer to a pointer to a CRL list to which add the CRL. In either cases, this object must be freed with a call to SOPC_KeyManager_CRL_Free().

Note: Content of the certificate is unspecified when return value is not SOPC_STATUS_OK. However, in case of a failed addition, the whole CRL list is freed, and ppCRL set to NULL to avoid double frees.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL, and SOPC_STATUS_NOK when there was an error.

◆ SOPC_KeyManager_CRL_Free()

void SOPC_KeyManager_CRL_Free ( SOPC_CRLList * pCRL )

Frees a Certificate created with SOPC_KeyManager_CRL_CreateOrAddFromFile() or SOPC_KeyManager_CRL_CreateOrAddFromDER()

Parameters

pCRL	The CRL to free.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ SOPC_SerializedAsymmetricKey

◆ SOPC_SerializedCertificate

Function Documentation

◆ SOPC_KeyManager_AsymmetricKey_CreateFromBuffer()

◆ SOPC_KeyManager_AsymmetricKey_CreateFromFile()

◆ SOPC_KeyManager_AsymmetricKey_CreateFromCertificate()

◆ SOPC_KeyManager_AsymmetricKey_Free()

◆ SOPC_KeyManager_AsymmetricKey_ToDER()

◆ SOPC_KeyManager_SerializedAsymmetricKey_CreateFromData()

◆ SOPC_KeyManager_SerializedAsymmetricKey_CreateFromFile()

◆ SOPC_KeyManager_SerializedAsymmetricKey_CreateFromFile_WithPwd()

◆ SOPC_KeyManager_SerializedAsymmetricKey_CreateFromKey()

◆ SOPC_KeyManager_SerializedAsymmetricKey_Deserialize()

◆ SOPC_KeyManager_SerializedAsymmetricKey_Delete()

◆ SOPC_KeyManager_Certificate_CreateOrAddFromDER()

◆ SOPC_KeyManager_Certificate_CreateOrAddFromFile()

◆ SOPC_KeyManager_Certificate_Free()

◆ SOPC_KeyManager_Certificate_ToDER()

◆ SOPC_KeyManager_Certificate_GetThumbprint()

◆ SOPC_KeyManager_Certificate_CheckApplicationUri()

◆ SOPC_KeyManager_Certificate_GetMaybeApplicationUri()

◆ SOPC_KeyManager_Certificate_GetListLength()

◆ SOPC_KeyManager_CertificateList_RemoveUnmatchedCRL()

◆ SOPC_KeyManager_CertificateList_FindCertInList()

◆ SOPC_KeyManager_SerializedCertificate_CreateFromDER()

◆ SOPC_KeyManager_SerializedCertificate_CreateFromFile()

◆ SOPC_KeyManager_SerializedCertificate_Deserialize()

◆ SOPC_KeyManager_SerializedCertificate_Data()

◆ SOPC_KeyManager_Certificate_GetCstring_SHA1()

◆ SOPC_KeyManager_SerializedCertificate_Delete()

◆ SOPC_KeyManager_CRL_CreateOrAddFromDER()

◆ SOPC_KeyManager_CRL_CreateOrAddFromFile()

◆ SOPC_KeyManager_CRL_Free()