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_GenRSA (uint32_t RSAKeySize, SOPC_AsymmetricKey **ppKey)
	Generate an RSA asymmetric key. 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_AsymmetricKey_ToPEMFile (SOPC_AsymmetricKey pKey, const bool bIsPublic, const char filePath, const char *pwd, const uint32_t pwdLen)
	Write an asymmetric key to a PEM file. 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_ToDER_Files (SOPC_CertificateList pCerts, const char directoryPath)
	Write all the certificates of `pCerts` in DER files at destination `directoryPath` . File names are defined using the SHA1 of the certificates. 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_Certificate_GetSubjectName (const SOPC_CertificateList pCert, char ppSubjectName, uint32_t pSubjectNameLen)
	Returns the subject name of certificate `pCert` as a C String. More...

SOPC_ReturnStatus	SOPC_KeyManager_Certificate_GetSanDnsNames (const SOPC_CertificateList pCert, char *ppDnsNameArray, uint32_t pArrayLength)
	Returns all the DNS names of certificate `pCert` as an array of C String. More...

SOPC_ReturnStatus	SOPC_KeyManager_CertificateList_RemoveCAWithoutCRL (SOPC_CertificateList *ppCert, const SOPC_CRLList pCRL, bool *pbMatch)
	Removes (and frees) certificates from `ppCert` 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_CertificateList_RemoveCertFromSHA1 (SOPC_CertificateList ppCertList, SOPC_CRLList ppCRLList, const char pThumbprint, bool pbMatch, bool *pbIsIssuer)
	Remove a single Certificate from its thumbprint. If the Certificate is a CA Certificate then all the CRLs for that CA are removed. 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 (const SOPC_CertificateList *pCert)
	Returns the SHA-1 thumbprint of a certificate. More...

SOPC_ReturnStatus	SOPC_KeyManager_Certificate_IsSelfSigned (const SOPC_CertificateList pCert, bool pbIsSelfSigned)
	Whether the first item of a certificate list is self signed. More...

SOPC_ReturnStatus	SOPC_KeyManager_Certificate_Copy (const SOPC_CertificateList pCert, SOPC_CertificateList *ppCertCopy)
	Makes a copy of a given certificate list. 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...

SOPC_ReturnStatus	SOPC_KeyManager_CRL_ToDER_Files (SOPC_CRLList pCrls, const char directoryPath)
	Write all the CRL ( `pCrls` ) in DER files. at destination `directoryPath` . File names are defined using the SHA1 of the crls. More...

SOPC_ReturnStatus	SOPC_KeyManager_CRL_Copy (const SOPC_CRLList pCrl, SOPC_CRLList *ppCrlCopy)
	Makes a copy of a given CRL list. More...

SOPC_ReturnStatus	SOPC_KeyManager_CRL_GetListLength (const SOPC_CRLList pCrl, size_t pLength)
	Returns the number of chained CRL in `pCrl` 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...

SOPC_ReturnStatus	SOPC_KeyManager_CSR_Create (const char subjectName, const bool bIsServer, const char mdType, const char uri, char pDnsArray, uint32_t arrayLength, SOPC_CSR *ppCSR)
	Create a certificate signing request signed with `pKey`. More...

SOPC_ReturnStatus	SOPC_KeyManager_CSR_ToDER (SOPC_CSR pCSR, SOPC_AsymmetricKey pKey, uint8_t *ppDest, uint32_t pLenAllocated)
	Encodes CSR `pCSR` as a DER buffer and writes the result in `ppDest`. More...

void	SOPC_KeyManager_CSR_Free (SOPC_CSR *pCSR)
	Frees a CSR created with SOPC_KeyManager_CSR_Create. 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.
[out]	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.
[out]	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_GenRSA()

SOPC_ReturnStatus SOPC_KeyManager_AsymmetricKey_GenRSA	(	uint32_t	RSAKeySize,
		SOPC_AsymmetricKey **	ppKey
	)

Generate an RSA asymmetric key.

Parameters

	RSAKeySize	The RSA key length to generate.
[out]	ppKey	A handle to the generated key. This object must be freed with a call to SOPC_KeyManager_AsymmetricKey_Free

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

◆ 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.
[out]	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 .

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.
[out]	pDest	A valid pointer to the buffer which will receive the DER encoded key.
	lenDest	The length in bytes of the buffer `pDest`.
[out]	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_AsymmetricKey_ToPEMFile()

SOPC_ReturnStatus SOPC_KeyManager_AsymmetricKey_ToPEMFile	(	SOPC_AsymmetricKey *	pKey,
		const bool	bIsPublic,
		const char *	filePath,
		const char *	pwd,
		const uint32_t	pwdLen
	)

Write an asymmetric key to a PEM file.

Parameters

pKey	A valid pointer to the asymmetric key (public/private).
bIsPublic	Whether the key is public or private.
filePath	Path to the file.
pwd	An optional password (!= NULL). The password must be a zero-terminated string with at most `pwdLen` non null chars, and at least `pwdLen` + 1 allocated chars.
pwdLen	The length of the password.

Note: The supported encryption algorithm is AES-256-CBC. pwd and pwdLen are used only to encrypt the key when it is private.

Warning: Only PKCS#1 format is supported, In other words, the function is limited to RSA keys.

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

◆ 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
[out]	key	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
[out]	key	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.
[out]	key	the newly allocated serialized key.
	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]	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
[out]	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.
[out]	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.
[out]	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. 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.
[out]	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.
[out]	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_ToDER_Files()

SOPC_ReturnStatus SOPC_KeyManager_Certificate_ToDER_Files	(	SOPC_CertificateList *	pCerts,
		const char *	directoryPath
	)

Write all the certificates of pCerts in DER files at destination directoryPath . File names are defined using the SHA1 of the certificates.

Parameters

pCerts	A valid pointer to the certificate list.
directoryPath	The directory path to write the DER files.

Returns: SOPC_STATUS_OK when successful.

◆ 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.
[out]	pDest	A valid pointer to the buffer that will contain the thumbprint.
[out]	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.
[out]	ppApplicationUri	A pointer to the newly allocated zero-terminated string containing the application URI.
[out]	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.
[out]	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_Certificate_GetSubjectName()

SOPC_ReturnStatus SOPC_KeyManager_Certificate_GetSubjectName	(	const SOPC_CertificateList *	pCert,
		char **	ppSubjectName,
		uint32_t *	pSubjectNameLen
	)

Returns the subject name of certificate pCert as a C String.

Parameters

	pCert	The certificate.
[out]	ppSubjectName	The newly subject name of certificate `pCert` (NULL terminated C string)
[out]	pSubjectNameLen	The length of `ppSubjectName` .

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

Warning: pCert must contain a single certificate.

Returns: SOPC_STATUS_OK when successful.

◆ SOPC_KeyManager_Certificate_GetSanDnsNames()

SOPC_ReturnStatus SOPC_KeyManager_Certificate_GetSanDnsNames	(	const SOPC_CertificateList *	pCert,
		char ***	ppDnsNameArray,
		uint32_t *	pArrayLength
	)

Returns all the DNS names of certificate pCert as an array of C String.

Parameters

	pCert	The certificate.
[out]	ppDnsNameArray	The newly allocated array of DNS names for the certificate `pCert` (each name shall be a NULL terminated C string)
[out]	pArrayLength	The length of `ppDnsNameArray` .

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

Warning: pCert must contain a single certificate. No error is returned if no DNS is defined.

Returns: SOPC_STATUS_OK when successful.

◆ SOPC_KeyManager_CertificateList_RemoveCAWithoutCRL()

SOPC_ReturnStatus SOPC_KeyManager_CertificateList_RemoveCAWithoutCRL	(	SOPC_CertificateList **	ppCert,
		const SOPC_CRLList *	pCRL,
		bool *	pbMatch
	)

Removes (and frees) certificates from ppCert 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 ppCert that are not authorities.

Warning: If the list ppCert became empty then the list ppCert is set to NULL.

Parameters

	ppCert	A valid pointer to the Certificate list.
	pCRL	A valid pointer to the CRL list.
[out]	pbMatch	An optional pointer to the result of the test. True value indicates that each certificate in `ppCert` 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_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.
[out]	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_CertificateList_RemoveCertFromSHA1()

SOPC_ReturnStatus SOPC_KeyManager_CertificateList_RemoveCertFromSHA1	(	SOPC_CertificateList **	ppCertList,
		SOPC_CRLList **	ppCRLList,
		const char *	pThumbprint,
		bool *	pbMatch,
		bool *	pbIsIssuer
	)

Remove a single Certificate from its thumbprint. If the Certificate is a CA Certificate then all the CRLs for that CA are removed.

Warning: This function will fail if pThumbprint does not match the SHA1 length. If ppCertList becomes empty, the list is freed and its content is set to NULL. If ppCRLList becomes empty, the list is freed and its content is set to NULL.

Parameters

	ppCertList	A valid pointer to the Certificate list.
	ppCRLList	A valid pointer to the CRL list.
	pThumbprint	The SHA1 of the certificate formatted as a hexadecimal C string (NULL terminated) 40 bytes shall be allocated in `pThumbprint` (+ 1 byte for the NULL character)
[out]	pbMatch	A valid pointer indicating whether the certificate has been found and deleted.
[out]	pbIsIssuer	A valid pointer indicating whether the deleted certificate is an issuer.

Returns: SOPC_STATUS_OK when successful

◆ 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
[out]	cert	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
[out]	cert	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
[out]	res	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 ( const SOPC_CertificateList * pCert )

Returns the SHA-1 thumbprint of a certificate.

Parameters

pCert A pointer to a single Certificate.

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_Certificate_IsSelfSigned()

SOPC_ReturnStatus SOPC_KeyManager_Certificate_IsSelfSigned	(	const SOPC_CertificateList *	pCert,
		bool *	pbIsSelfSigned
	)

Whether the first item of a certificate list is self signed.

Parameters

	pCert	A valid pointer to the certificate list.
[out]	pbIsSelfSigned	A valid pointer to the result.

Note: Only the first certificate of pCert is processed.

Returns: SOPC_STATUS_OK when successful otherwise SOPC_STATUS_NOK.

◆ SOPC_KeyManager_Certificate_Copy()

SOPC_ReturnStatus SOPC_KeyManager_Certificate_Copy	(	const SOPC_CertificateList *	pCert,
		SOPC_CertificateList **	ppCertCopy
	)

Makes a copy of a given certificate list.

Parameters

	pCert	A valid pointer to the certificate list to copy.
[out]	ppCertCopy	A pointer to store the newly allocated certificate list copy. Caller is responsible to call SOPC_KeyManager_Certificate_Free if needed.

Returns: SOPC_STATUS_OK when successful.

◆ 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.
[out]	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.
[out]	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_ToDER_Files()

SOPC_ReturnStatus SOPC_KeyManager_CRL_ToDER_Files	(	SOPC_CRLList *	pCrls,
		const char *	directoryPath
	)

Write all the CRL ( pCrls ) in DER files. at destination directoryPath . File names are defined using the SHA1 of the crls.

Parameters

pCrls	A valid pointer to the CRL list.
directoryPath	The directory path to write the DER files.

Returns: SOPC_STATUS_OK when successful.

◆ SOPC_KeyManager_CRL_Copy()

SOPC_ReturnStatus SOPC_KeyManager_CRL_Copy	(	const SOPC_CRLList *	pCrl,
		SOPC_CRLList **	ppCrlCopy
	)

Makes a copy of a given CRL list.

Parameters

	pCrl	A valid pointer to the CRL list to copy.
[out]	ppCrlCopy	A pointer to store the newly allocated CRL list copy. Caller is responsible to call SOPC_KeyManager_CRL_Free if needed.

Returns: SOPC_STATUS_OK when successful.

◆ SOPC_KeyManager_CRL_GetListLength()

SOPC_ReturnStatus SOPC_KeyManager_CRL_GetListLength	(	const SOPC_CRLList *	pCrl,
		size_t *	pLength
	)

Returns the number of chained CRL in pCrl list.

Parameters

	pCrl	A valid pointer to the CRL list.
[out]	pLength	A valid pointer to the computed length of the list.

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

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

◆ 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.

◆ SOPC_KeyManager_CSR_Create()

SOPC_ReturnStatus SOPC_KeyManager_CSR_Create	(	const char *	subjectName,
		const bool	bIsServer,
		const char *	mdType,
		const char *	uri,
		char **	pDnsArray,
		uint32_t	arrayLength,
		SOPC_CSR **	ppCSR
	)

Create a certificate signing request signed with pKey.

Parameters

	subjectName	The subject name to set. The format is a sequence of name (OID types) value pairs separated by a ‘,’.
	bIsServer	Whether this CSR is to request a server or a client certificate.
	mdType	The MD algorithm (terminated by '\0') use for the signature eg SHA1, SHA256...
	uri	The application URI (terminated by '\0'). Shall not be NULL.
	pDnsArray	Array of DSN names of the server (name terminated by '\0'). Shall not be NULL. Array is not modified by the function.
	arrayLength	The length of `pDnsArray`.
[out]	ppCSR	A handle to the created CSR. This object must be freed with a call to SOPC_KeyManager_CSR_Free .

Note: The keyUsage is filled with digitalSignature, nonRepudiation, keyEncipherment and dataEncipherment. The extendedKeyUsage is filled with serverAuth if bIsServer is true, otherwise clientAuth. The subject alternative name is filled with uri and/or dns . The basic constraints is set to false for the CA flag.

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

◆ SOPC_KeyManager_CSR_ToDER()

SOPC_ReturnStatus SOPC_KeyManager_CSR_ToDER	(	SOPC_CSR *	pCSR,
		SOPC_AsymmetricKey *	pKey,
		uint8_t **	ppDest,
		uint32_t *	pLenAllocated
	)

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

Parameters

	pCSR	A valid pointer to the CSR.
	pKey	A valid pointer to the asymmetric key. The key shall be private. The key is attached to the CSR but not freed by SOPC_KeyManager_CSR_Free .
[out]	ppDest	A valid pointer to the newly created buffer that stores the DER. The allocated buffer must be freed by the caller.
[out]	pLenAllocated	A valid pointer to the length allocated by this operation.

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

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

◆ SOPC_KeyManager_CSR_Free()

void SOPC_KeyManager_CSR_Free ( SOPC_CSR * pCSR )

Frees a CSR created with SOPC_KeyManager_CSR_Create.

Parameters

pCSR	The CSR 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_GenRSA()

◆ SOPC_KeyManager_AsymmetricKey_CreateFromCertificate()

◆ SOPC_KeyManager_AsymmetricKey_Free()

◆ SOPC_KeyManager_AsymmetricKey_ToDER()

◆ SOPC_KeyManager_AsymmetricKey_ToPEMFile()

◆ 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_ToDER_Files()

◆ SOPC_KeyManager_Certificate_GetThumbprint()

◆ SOPC_KeyManager_Certificate_CheckApplicationUri()

◆ SOPC_KeyManager_Certificate_GetMaybeApplicationUri()

◆ SOPC_KeyManager_Certificate_GetListLength()

◆ SOPC_KeyManager_Certificate_GetSubjectName()

◆ SOPC_KeyManager_Certificate_GetSanDnsNames()

◆ SOPC_KeyManager_CertificateList_RemoveCAWithoutCRL()

◆ SOPC_KeyManager_CertificateList_FindCertInList()

◆ SOPC_KeyManager_CertificateList_RemoveCertFromSHA1()

◆ SOPC_KeyManager_SerializedCertificate_CreateFromDER()

◆ SOPC_KeyManager_SerializedCertificate_CreateFromFile()

◆ SOPC_KeyManager_SerializedCertificate_Deserialize()

◆ SOPC_KeyManager_SerializedCertificate_Data()

◆ SOPC_KeyManager_Certificate_GetCstring_SHA1()

◆ SOPC_KeyManager_Certificate_IsSelfSigned()

◆ SOPC_KeyManager_Certificate_Copy()

◆ SOPC_KeyManager_SerializedCertificate_Delete()

◆ SOPC_KeyManager_CRL_CreateOrAddFromDER()

◆ SOPC_KeyManager_CRL_CreateOrAddFromFile()

◆ SOPC_KeyManager_CRL_ToDER_Files()

◆ SOPC_KeyManager_CRL_Copy()

◆ SOPC_KeyManager_CRL_GetListLength()

◆ SOPC_KeyManager_CRL_Free()

◆ SOPC_KeyManager_CSR_Create()

◆ SOPC_KeyManager_CSR_ToDER()

◆ SOPC_KeyManager_CSR_Free()