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

Defines the cryptographic API. This API mainly relies on the SOPC_CryptoProvider, which is composed of lib-specific data alongside a read-only SOPC_CryptoProfile or SOPC_CryptoProfile_PubSub. More...

#include "sopc_crypto_decl.h"
#include "sopc_enums.h"
#include "sopc_key_sets.h"
#include "sopc_pki_decl.h"

Go to the source code of this file.

Data Structures
struct	SOPC_CryptoProvider
	The SOPC_CryptoProvider context. More...

Functions
SOPC_CryptoProvider *	SOPC_CryptoProvider_Create (const char *uri)
	Creates an initialized SOPC_CryptoProvider context for a client-server connection from a string containing the desired security policy URI. More...

SOPC_CryptoProvider *	SOPC_CryptoProvider_CreatePubSub (const char *uri)
	Creates an initialized SOPC_CryptoProvider context for PubSub exchanges from a string containing the desired security policy URI. More...

void	SOPC_CryptoProvider_Free (SOPC_CryptoProvider *pCryptoProvider)
	Frees a SOPC_CryptoProvider created with SOPC_CryptoProvider_Create(). More...

const SOPC_CryptoProfile *	SOPC_CryptoProvider_GetProfileServices (const SOPC_CryptoProvider *pProvider)
	Returns the non NULL client-server crypto profile but returns NULL if the PubSub profile is non NULL. More...

const SOPC_CryptoProfile_PubSub *	SOPC_CryptoProvider_GetProfilePubSub (const SOPC_CryptoProvider *pProvider)
	Returns the non NULL PubSub crypto profile but returns NULL if the client-server profile is non NULL. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_SymmetricGetLength_CryptoKey (const SOPC_CryptoProvider pProvider, uint32_t pLength)
	Writes the length in bytes in `pLength` of the key used for symmetric encryption/decryption. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_SymmetricGetLength_Encryption (const SOPC_CryptoProvider pProvider, uint32_t lengthIn, uint32_t pLengthOut)
	Writes the length in bytes in `pLengthOut` of an encrypted message of `lengthIn` bytes. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_SymmetricGetLength_Decryption (const SOPC_CryptoProvider pProvider, uint32_t lengthIn, uint32_t pLengthOut)
	Writes the length in bytes in `pLengthOut` of a decrypted message of `lengthIn` bytes. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_SymmetricGetLength_SignKey (const SOPC_CryptoProvider pProvider, uint32_t pLength)
	Writes the length in bytes in `pLength` of the key used for symmetric signature. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_SymmetricGetLength_Signature (const SOPC_CryptoProvider pProvider, uint32_t pLength)
	Provides the length in bytes of the symmetric signature message. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_SymmetricGetLength_Blocks (const SOPC_CryptoProvider pProvider, uint32_t pCipherTextBlockSize, uint32_t *pPlainTextBlockSize)
	Provides the lengths in bytes of the blocks used in the symmetric encryption process. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_SymmetricGetLength_SecureChannelNonce (const SOPC_CryptoProvider pProvider, uint32_t pLenNonce)
	Provides the length in bytes of the SecureChannel nonces used in the symmetric encryption process. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_DeriveGetLengths (const SOPC_CryptoProvider pProvider, uint32_t pSymmCryptoKeyLength, uint32_t pSymmSignKeyLength, uint32_t pSymmInitVectorLength)
	Provides the lengths in bytes of the secrets derived from the nonce exchange. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_AsymmetricGetLength_KeyBytes (const SOPC_CryptoProvider pProvider, const SOPC_AsymmetricKey pKey, uint32_t *pLenKeyBytes)
	Writes the length in bytes in `pLenKeyBytes` of the asymmetric key `pKey`. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_AsymmetricGetLength_OAEPHashLength (const SOPC_CryptoProvider pProvider, uint32_t length)
	Provides the length of the hash used for OAEP encryption/decryption. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_AsymmetricGetLength_Msgs (const SOPC_CryptoProvider pProvider, const SOPC_AsymmetricKey pKey, uint32_t pCipherTextBlockSize, uint32_t pPlainTextBlockSize)
	Provides the lengths in bytes of the messages used in asymmetric encryption process. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_AsymmetricGetLength_Encryption (const SOPC_CryptoProvider pProvider, const SOPC_AsymmetricKey pKey, uint32_t lengthIn, uint32_t *pLengthOut)
	Calculates the size of the required output buffer to cipher lengthIn bytes through asymmetric encryption. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_AsymmetricGetLength_Decryption (const SOPC_CryptoProvider pProvider, const SOPC_AsymmetricKey pKey, uint32_t lengthIn, uint32_t *pLengthOut)
	Calculates the size of the required output buffer to decipher lengthIn bytes through asymmetric decryption. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_AsymmetricGetLength_Signature (const SOPC_CryptoProvider pProvider, const SOPC_AsymmetricKey pKey, uint32_t *pLength)
	Calculates the size of the required output buffer to contain the asymmetric signature. More...

const char *	SOPC_CryptoProvider_AsymmetricGetUri_SignAlgorithm (const SOPC_CryptoProvider *pProvider)
	Returns the URI of the AsymetricSignatureAlgorithm. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_CertificateGetLength_Thumbprint (const SOPC_CryptoProvider pProvider, uint32_t pLength)
	Calculates the size of the signature of the certificates. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_PubSubGetLength_KeyNonce (const SOPC_CryptoProvider pProvider, uint32_t pLength)
	Writes the length in bytes in `pLength` of the key nonce used for PubSub encryption/decryption. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_PubSubGetLength_MessageRandom (const SOPC_CryptoProvider pProvider, uint32_t pLength)
	Writes the length in bytes in `pLength` of the random bytes used for PubSub encryption/decryption. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_SymmetricEncrypt (const SOPC_CryptoProvider pProvider, const uint8_t pInput, uint32_t lenPlainText, SOPC_SecretBuffer pKey, SOPC_SecretBuffer pIV, uint8_t *pOutput, uint32_t lenOutput)
	Encrypts a padded payload `pInput` of `lenPlainText` bytes. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_SymmetricDecrypt (const SOPC_CryptoProvider pProvider, const uint8_t pInput, uint32_t lenCipherText, SOPC_SecretBuffer pKey, SOPC_SecretBuffer pIV, uint8_t *pOutput, uint32_t lenOutput)
	Decrypts a payload `pInput` of `lenPlainText` bytes into a padded deciphered payload `pOutput`. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_PubSubCrypt (const SOPC_CryptoProvider pProvider, const uint8_t pInput, uint32_t lenInput, SOPC_SecretBuffer pKey, SOPC_SecretBuffer pKeyNonce, const SOPC_ExposedBuffer pRandom, uint32_t lenRandom, uint32_t uSequenceNumber, uint8_t pOutput, uint32_t lenOutput)
	Encrypts or Decrypts a payload `pInput` of `lenInput` bytes. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_SymmetricSign (const SOPC_CryptoProvider pProvider, const uint8_t pInput, uint32_t lenInput, SOPC_SecretBuffer pKey, uint8_t pOutput, uint32_t lenOutput)
	Signs a payload `pInput` of `lenInput` bytes, writes the signature in `pOutput` of `lenOutput` bytes. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_SymmetricVerify (const SOPC_CryptoProvider pProvider, const uint8_t pInput, uint32_t lenInput, SOPC_SecretBuffer pKey, const uint8_t pSignature, uint32_t lenOutput)
	Verifies the signature `pSignature` of the payload `pInput` of `lenInput` bytes. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_GenerateRandomBytes (const SOPC_CryptoProvider pProvider, uint32_t nBytes, SOPC_ExposedBuffer *ppBuffer)
	Generates truly random data of arbitrary length. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_GenerateSecureChannelNonce (const SOPC_CryptoProvider pProvider, SOPC_SecretBuffer *ppNonce)
	Generates a single truly random nonce for the SecureChannel creation. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_GenerateRandomID (const SOPC_CryptoProvider pProvider, uint32_t pID)
	Generates 4 bytes of truly random data. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_DerivePseudoRandomData (const SOPC_CryptoProvider pProvider, const SOPC_ExposedBuffer pSecret, uint32_t lenSecret, const SOPC_ExposedBuffer pSeed, uint32_t lenSeed, SOPC_ExposedBuffer pOutput, uint32_t lenOutput)
	Derives pseudo-random data from the randomly generated and shared secrets. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_DeriveKeySets (const SOPC_CryptoProvider pProvider, const SOPC_ExposedBuffer pClientNonce, uint32_t lenClientNonce, const SOPC_ExposedBuffer pServerNonce, uint32_t lenServerNonce, SOPC_SC_SecurityKeySet pClientKeySet, SOPC_SC_SecurityKeySet *pServerKeySet)
	Derive pseudo-random key sets from the randomly generated and shared secrets. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_DeriveKeySetsClient (const SOPC_CryptoProvider pProvider, SOPC_SecretBuffer pClientNonce, const SOPC_ExposedBuffer pServerNonce, uint32_t lenServerNonce, SOPC_SC_SecurityKeySet pClientKeySet, SOPC_SC_SecurityKeySet *pServerKeySet)
	Derive pseudo-random key sets from the randomly generated and shared secrets. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_DeriveKeySetsServer (const SOPC_CryptoProvider pProvider, const SOPC_ExposedBuffer pClientNonce, uint32_t lenClientNonce, SOPC_SecretBuffer pServerNonce, SOPC_SC_SecurityKeySet pClientKeySet, SOPC_SC_SecurityKeySet *pServerKeySet)
	Derive pseudo-random key sets from the randomly generated and shared secrets. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_AsymmetricEncrypt (const SOPC_CryptoProvider pProvider, const uint8_t pInput, uint32_t lenInput, const SOPC_AsymmetricKey pKey, uint8_t pOutput, uint32_t lenOutput, const char **errorReason)
	Encrypts a payload `pInput` of `lenInput` bytes. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_AsymmetricDecrypt (const SOPC_CryptoProvider pProvider, const uint8_t pInput, uint32_t lenInput, const SOPC_AsymmetricKey pKey, uint8_t pOutput, uint32_t lenOutput, uint32_t pLenWritten, const char *errorReason)
	Decrypts a payload `pInput` of `lenInput` bytes. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_AsymmetricSign (const SOPC_CryptoProvider pProvider, const uint8_t pInput, uint32_t lenInput, const SOPC_AsymmetricKey pKeyPrivateLocal, uint8_t pSignature, uint32_t lenSignature, const char **errorReason)
	Signs a payload `pInput` of `lenInput` bytes. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_AsymmetricVerify (const SOPC_CryptoProvider pProvider, const uint8_t pInput, uint32_t lenInput, const SOPC_AsymmetricKey pKeyRemotePublic, const uint8_t pSignature, uint32_t lenSignature, const char **errorReason)
	Verifies the signature `pSignature` of a payload `pInput` of `lenInput` bytes. More...

SOPC_ReturnStatus	SOPC_CryptoProvider_Certificate_Validate (const SOPC_CryptoProvider pProvider, SOPC_PKIProvider pPKI, const SOPC_PKI_Type PKIType, const SOPC_CertificateList pCert, uint32_t error)
	Validates the given Certificate `pCert`. More...

Detailed Description

Defines the cryptographic API. This API mainly relies on the SOPC_CryptoProvider, which is composed of lib-specific data alongside a read-only SOPC_CryptoProfile or SOPC_CryptoProfile_PubSub.

Function Documentation

◆ SOPC_CryptoProvider_Create()

SOPC_CryptoProvider* SOPC_CryptoProvider_Create ( const char * uri )

Creates an initialized SOPC_CryptoProvider context for a client-server connection from a string containing the desired security policy URI.

The SOPC_CryptoProvider contains the SOPC_CryptoProfile corresponding to the security policy. It should never be modified.

Parameters

uri	The URI describing the security policy. Should not be NULL. Should describe only client-server security policies.

Note: Use SOPC_CryptoProvider_CreatePubSub() to create a SOPC_CryptoProvider for PubSub exchanges.

Returns: An initialized SOPC_CryptoProvider* or NULL if the context could not be created.

◆ SOPC_CryptoProvider_CreatePubSub()

SOPC_CryptoProvider* SOPC_CryptoProvider_CreatePubSub ( const char * uri )

Creates an initialized SOPC_CryptoProvider context for PubSub exchanges from a string containing the desired security policy URI.

The SOPC_CryptoProvider contains the SOPC_CryptoProfile_PubSub corresponding to the security policy. It should never be modified.

Parameters

uri	The URI describing the security policy. Should not be NULL. Should only describe PubSub security policies.

Note: Use SOPC_CryptoProvider_Create() to create a SOPC_CryptoProvider for a client-server connection.

Returns: An initialized SOPC_CryptoProvider* or NULL if the context could not be created.

◆ SOPC_CryptoProvider_Free()

void SOPC_CryptoProvider_Free ( SOPC_CryptoProvider * pCryptoProvider )

Frees a SOPC_CryptoProvider created with SOPC_CryptoProvider_Create().

Parameters

pCryptoProvider The SOPC_CryptoProvider to free.

◆ SOPC_CryptoProvider_GetProfileServices()

const SOPC_CryptoProfile* SOPC_CryptoProvider_GetProfileServices ( const SOPC_CryptoProvider * pProvider )

Returns the non NULL client-server crypto profile but returns NULL if the PubSub profile is non NULL.

Note: Internal API.

◆ SOPC_CryptoProvider_GetProfilePubSub()

const SOPC_CryptoProfile_PubSub* SOPC_CryptoProvider_GetProfilePubSub ( const SOPC_CryptoProvider * pProvider )

Returns the non NULL PubSub crypto profile but returns NULL if the client-server profile is non NULL.

Note: Internal API.

◆ SOPC_CryptoProvider_SymmetricGetLength_CryptoKey()

SOPC_ReturnStatus SOPC_CryptoProvider_SymmetricGetLength_CryptoKey	(	const SOPC_CryptoProvider *	pProvider,
		uint32_t *	pLength
	)

Writes the length in bytes in pLength of the key used for symmetric encryption/decryption.

The length of the key depends on the security policy associated with pProvider.

Parameters

pProvider	An initialized cryptographic context.
pLength	A valid pointer to the length in bytes of the key. Its content is unspecified when return value is not SOPC_STATUS_OK.

Note: For both client-server and PubSub security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized.

◆ SOPC_CryptoProvider_SymmetricGetLength_Encryption()

SOPC_ReturnStatus SOPC_CryptoProvider_SymmetricGetLength_Encryption	(	const SOPC_CryptoProvider *	pProvider,
		uint32_t	lengthIn,
		uint32_t *	pLengthOut
	)

Writes the length in bytes in pLengthOut of an encrypted message of lengthIn bytes.

Warning: Does not take padding into account.

Parameters

pProvider	An initialized cryptographic context.
lengthIn	The length in bytes of the message to encrypt.
pLengthOut	A valid pointer to the length in bytes of the ciphered message. Its content is unspecified when return value is not SOPC_STATUS_OK.

Note: For both client-server and PubSub security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when given pointers are NULL or pProvider not correctly initialized.

◆ SOPC_CryptoProvider_SymmetricGetLength_Decryption()

SOPC_ReturnStatus SOPC_CryptoProvider_SymmetricGetLength_Decryption	(	const SOPC_CryptoProvider *	pProvider,
		uint32_t	lengthIn,
		uint32_t *	pLengthOut
	)

Writes the length in bytes in pLengthOut of a decrypted message of lengthIn bytes.

Warning: Does not take padding into account.

Parameters

pProvider	An initialized cryptographic context.
lengthIn	The length in bytes of the message to decrypt.
pLengthOut	A valid pointer to the length in bytes of the deciphered message. Its content is unspecified when return value is not SOPC_STATUS_OK.

Note: For both client-server and PubSub security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when given pointers are NULL or pProvider not correctly initialized.

◆ SOPC_CryptoProvider_SymmetricGetLength_SignKey()

SOPC_ReturnStatus SOPC_CryptoProvider_SymmetricGetLength_SignKey	(	const SOPC_CryptoProvider *	pProvider,
		uint32_t *	pLength
	)

Writes the length in bytes in pLength of the key used for symmetric signature.

The length of the key depends on the security policy associated with pProvider.

Parameters

pProvider	An initialized cryptographic context.
pLength	A valid pointer to the length in bytes of the key. Its content is unspecified when return value is not SOPC_STATUS_OK.

Note: For both client-server and PubSub security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized.

◆ SOPC_CryptoProvider_SymmetricGetLength_Signature()

SOPC_ReturnStatus SOPC_CryptoProvider_SymmetricGetLength_Signature	(	const SOPC_CryptoProvider *	pProvider,
		uint32_t *	pLength
	)

Provides the length in bytes of the symmetric signature message.

Parameters

pProvider	An initialized cryptographic context.
pLength	A valid pointer to the length in bytes of the signature message. Its content is unspecified when return value is not SOPC_STATUS_OK.

Note: For both client-server and PubSub security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized.

◆ SOPC_CryptoProvider_SymmetricGetLength_Blocks()

SOPC_ReturnStatus SOPC_CryptoProvider_SymmetricGetLength_Blocks	(	const SOPC_CryptoProvider *	pProvider,
		uint32_t *	pCipherTextBlockSize,
		uint32_t *	pPlainTextBlockSize
	)

Provides the lengths in bytes of the blocks used in the symmetric encryption process.

These lengths are useful to predict the padding sizes required by the symmetric encryption process.

Parameters

pProvider	An initialized cryptographic context.
pCipherTextBlockSize	An optional pointer to the length in bytes of the block size used by the encryption process.
pPlainTextBlockSize	An optional pointer to the length in bytes of the block size used by the decryption process.

Note: The values held by pCipherTextBlockSize and pPlainTextBlockSize are unspecified when return value is not SOPC_STATUS_OK.; Specific to client-server security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized.

◆ SOPC_CryptoProvider_SymmetricGetLength_SecureChannelNonce()

SOPC_ReturnStatus SOPC_CryptoProvider_SymmetricGetLength_SecureChannelNonce	(	const SOPC_CryptoProvider *	pProvider,
		uint32_t *	pLenNonce
	)

Provides the length in bytes of the SecureChannel nonces used in the symmetric encryption process.

Parameters

pProvider	An initialized cryptographic context.
pLenNonce	A valid pointer to the length in bytes of the nonce used by the encryption process. Its content is unspecified when return value is not SOPC_STATUS_OK.

Note: Specific to client-server security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized.

◆ SOPC_CryptoProvider_DeriveGetLengths()

SOPC_ReturnStatus SOPC_CryptoProvider_DeriveGetLengths	(	const SOPC_CryptoProvider *	pProvider,
		uint32_t *	pSymmCryptoKeyLength,
		uint32_t *	pSymmSignKeyLength,
		uint32_t *	pSymmInitVectorLength
	)

Provides the lengths in bytes of the secrets derived from the nonce exchange.

Parameters

pProvider	An initialized cryptographic context.
pSymmCryptoKeyLength	A valid pointer to the length in bytes of the symmetric key used for encryption.
pSymmSignKeyLength	A valid pointer to the length in bytes of the symmetric key used for signing.
pSymmInitVectorLength	A valid pointer to the length in bytes of the symmetric initialization vector.

Note: The values held by pSymmCryptoKeyLength, pSymmSignKeyLength and pSymmInitVectorLength are unspecified when return value is not SOPC_STATUS_OK.; Specific to client-server security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized.

◆ SOPC_CryptoProvider_AsymmetricGetLength_KeyBytes()

SOPC_ReturnStatus SOPC_CryptoProvider_AsymmetricGetLength_KeyBytes	(	const SOPC_CryptoProvider *	pProvider,
		const SOPC_AsymmetricKey *	pKey,
		uint32_t *	pLenKeyBytes
	)

Writes the length in bytes in pLenKeyBytes of the asymmetric key pKey.

The main purpose of this function is to verify the length of the modulus of the asymmetric key pKey with respect to the security policy.

Parameters

pProvider	An initialized cryptographic context.
pKey	A valid pointer to an SOPC_AsymmetricKey.
pLenKeyBytes	A valid pointer to the output length in bytes. Its content is unspecified when return value is not SOPC_STATUS_OK.

Note: Specific to client-server security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized.

◆ SOPC_CryptoProvider_AsymmetricGetLength_OAEPHashLength()

SOPC_ReturnStatus SOPC_CryptoProvider_AsymmetricGetLength_OAEPHashLength	(	const SOPC_CryptoProvider *	pProvider,
		uint32_t *	length
	)

Provides the length of the hash used for OAEP encryption/decryption.

Note: Internal API.; Specific to client-server security policies.

Parameters

pProvider	An initialized cryptographic context.
length	A valid pointer to the output length in bytes. Its content 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 pProvider not correctly initialized and SOPC_STATUS_NOK if hthe policy does not support this feature.

◆ SOPC_CryptoProvider_AsymmetricGetLength_Msgs()

SOPC_ReturnStatus SOPC_CryptoProvider_AsymmetricGetLength_Msgs	(	const SOPC_CryptoProvider *	pProvider,
		const SOPC_AsymmetricKey *	pKey,
		uint32_t *	pCipherTextBlockSize,
		uint32_t *	pPlainTextBlockSize
	)

Provides the lengths in bytes of the messages used in asymmetric encryption process.

These lengths are useful to predict the padding sizes required by the asymmetric encryption process.

Parameters

pProvider	An initialized cryptographic context.
pKey	A valid pointer to an SOPC_AsymmetricKey.
pCipherTextBlockSize	An optional pointer to the maximum length in bytes of the plain text message used by the encryption process.
pPlainTextBlockSize	An optional pointer to the length in bytes of the ciphered message used by the decryption process.

Note: Specific to client-server security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized.

◆ SOPC_CryptoProvider_AsymmetricGetLength_Encryption()

SOPC_ReturnStatus SOPC_CryptoProvider_AsymmetricGetLength_Encryption	(	const SOPC_CryptoProvider *	pProvider,
		const SOPC_AsymmetricKey *	pKey,
		uint32_t	lengthIn,
		uint32_t *	pLengthOut
	)

Calculates the size of the required output buffer to cipher lengthIn bytes through asymmetric encryption.

Hence, the computation takes into account the padding, but it does not include any signature length.

Parameters

pProvider	An initialized cryptographic context.
pKey	A valid pointer to an SOPC_AsymmetricKey.
lengthIn	The length in bytes of the payload to encrypt.
pLengthOut	A valid pointer to the length in bytes of the corresponding encrypted payload. Its content is unspecified when return value is not SOPC_STATUS_OK.

Note: Specific to client-server security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized, SOPC_STATUS_NOK when there was an error.

◆ SOPC_CryptoProvider_AsymmetricGetLength_Decryption()

SOPC_ReturnStatus SOPC_CryptoProvider_AsymmetricGetLength_Decryption	(	const SOPC_CryptoProvider *	pProvider,
		const SOPC_AsymmetricKey *	pKey,
		uint32_t	lengthIn,
		uint32_t *	pLengthOut
	)

Calculates the size of the required output buffer to decipher lengthIn bytes through asymmetric decryption.

Hence, the computation takes into account the padding, but it does not include any signature length.

Parameters

pProvider	An initialized cryptographic context.
pKey	A valid pointer to an SOPC_AsymmetricKey.
lengthIn	The length in bytes of the payload to decrypt.
pLengthOut	A valid pointer to the length in bytes of the corresponding decrypted payload. Its content is unspecified when return value is not SOPC_STATUS_OK.

Note: Specific to client-server security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized, SOPC_STATUS_NOK when there was an error.

◆ SOPC_CryptoProvider_AsymmetricGetLength_Signature()

SOPC_ReturnStatus SOPC_CryptoProvider_AsymmetricGetLength_Signature	(	const SOPC_CryptoProvider *	pProvider,
		const SOPC_AsymmetricKey *	pKey,
		uint32_t *	pLength
	)

Calculates the size of the required output buffer to contain the asymmetric signature.

It is a single ciphered-message long.

Parameters

pProvider	An initialized cryptographic context.
pKey	A valid pointer to an SOPC_AsymmetricKey.
pLength	A valid pointer to the length in bytes of the signature. Its content is unspecified when return value is not SOPC_STATUS_OK.

Note: Specific to client-server security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized, SOPC_STATUS_NOK when there was an error.

◆ SOPC_CryptoProvider_AsymmetricGetUri_SignAlgorithm()

const char* SOPC_CryptoProvider_AsymmetricGetUri_SignAlgorithm ( const SOPC_CryptoProvider * pProvider )

Returns the URI of the AsymetricSignatureAlgorithm.

Parameters

pProvider An initialized cryptographic context.

Note: Specific to client-server security policies.

Returns: A zero-terminated string to the URI or NULL.

◆ SOPC_CryptoProvider_CertificateGetLength_Thumbprint()

SOPC_ReturnStatus SOPC_CryptoProvider_CertificateGetLength_Thumbprint	(	const SOPC_CryptoProvider *	pProvider,
		uint32_t *	pLength
	)

Calculates the size of the signature of the certificates.

Parameters

pProvider	An initialized cryptographic context.
pLength	A valid pointer to the length in bytes of the signature. Its content is unspecified when return value is not SOPC_STATUS_OK.

Note: Specific to client-server security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized, and SOPC_STATUS_NOK for an unsupported security policy.

◆ SOPC_CryptoProvider_PubSubGetLength_KeyNonce()

SOPC_ReturnStatus SOPC_CryptoProvider_PubSubGetLength_KeyNonce	(	const SOPC_CryptoProvider *	pProvider,
		uint32_t *	pLength
	)

Writes the length in bytes in pLength of the key nonce used for PubSub encryption/decryption.

The length of the nonce depends on the security policy associated with pProvider.

Parameters

pProvider	An initialized cryptographic context.
pLength	A valid pointer to the length in bytes of the key. Its content is unspecified when return value is not SOPC_STATUS_OK.

Note: Specific to PubSub security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized, and SOPC_STATUS_NOK for an unsupported security policy.

◆ SOPC_CryptoProvider_PubSubGetLength_MessageRandom()

SOPC_ReturnStatus SOPC_CryptoProvider_PubSubGetLength_MessageRandom	(	const SOPC_CryptoProvider *	pProvider,
		uint32_t *	pLength
	)

Writes the length in bytes in pLength of the random bytes used for PubSub encryption/decryption.

This length depends on the security policy associated with pProvider.

Parameters

pProvider	An initialized cryptographic context.
pLength	A valid pointer to the length in bytes of the key. Its content is unspecified when return value is not SOPC_STATUS_OK.

Note: Specific to PubSub security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized, and SOPC_STATUS_NOK for an unsupported security policy.

◆ SOPC_CryptoProvider_SymmetricEncrypt()

SOPC_ReturnStatus SOPC_CryptoProvider_SymmetricEncrypt	(	const SOPC_CryptoProvider *	pProvider,
		const uint8_t *	pInput,
		uint32_t	lenPlainText,
		SOPC_SecretBuffer *	pKey,
		SOPC_SecretBuffer *	pIV,
		uint8_t *	pOutput,
		uint32_t	lenOutput
	)

Encrypts a padded payload pInput of lenPlainText bytes.

Writes the ciphered payload in pOutput of lenOutput bytes. Does not apply a padding scheme, which must be done before calling this function. To calculate the padded size, use SOPC_CryptoProvider_SymmetricGetLength_Blocks().

The key and initialization vectors are usually derived from shared secrets with SOPC_CryptoProvider_DeriveKeySets().

Parameters

pProvider	An initialized cryptographic context.
pInput	A valid pointer to the payload to cipher. The payload must be padded.
lenPlainText	Length in bytes of the payload to cipher.
pKey	A valid pointer to a SecretBuffer containing the symmetric encryption key.
pIV	A valid pointer to a SecretBuffer containing the initialization vector.
pOutput	A valid pointer to the buffer which will contain the ciphered payload.
lenOutput	The exact length of the ciphered payload. SOPC_CryptoProvider_SymmetricGetLength_Encryption() provides the expected size of this buffer.

Note: Content of the output is unspecified when return value is not SOPC_STATUS_OK.; Specific to client-server security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized or sizes are incorrect, and SOPC_STATUS_NOK when there was an error.

◆ SOPC_CryptoProvider_SymmetricDecrypt()

SOPC_ReturnStatus SOPC_CryptoProvider_SymmetricDecrypt	(	const SOPC_CryptoProvider *	pProvider,
		const uint8_t *	pInput,
		uint32_t	lenCipherText,
		SOPC_SecretBuffer *	pKey,
		SOPC_SecretBuffer *	pIV,
		uint8_t *	pOutput,
		uint32_t	lenOutput
	)

Decrypts a payload pInput of lenPlainText bytes into a padded deciphered payload pOutput.

Writes the deciphered payload in pOutput of lenOutput bytes. Does not use a padding scheme, which must be done after calling this function to obtain the initial message. To calculate the padded size, use SOPC_CryptoProvider_SymmetricGetLength_Blocks().

The encryption key and initialization vectors are usually derived from shared secrets with SOPC_CryptoProvider_DeriveKeySets().

Parameters

pProvider	An initialized cryptographic context.
pInput	A valid pointer to the payload to decipher.
lenCipherText	Length in bytes of the payload to decipher. The payload size must be a multiple of the decipher block size, see SOPC_CryptoProvider_SymmetricGetLength_Blocks().
pKey	A valid pointer to a SecretBuffer containing the symmetric encryption key.
pIV	A valid pointer to a SecretBuffer containing the initialization vector.
pOutput	A valid pointer to the buffer which will contain the deciphered payload.
lenOutput	The exact length of the deciphered payload. SOPC_CryptoProvider_SymmetricGetLength_Decryption() provides the expected size of this buffer.

Note: Content of the output is unspecified when return value is not SOPC_STATUS_OK.; Specific to client-server security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized or sizes are incorrect, and SOPC_STATUS_NOK when there was an error.

◆ SOPC_CryptoProvider_PubSubCrypt()

SOPC_ReturnStatus SOPC_CryptoProvider_PubSubCrypt	(	const SOPC_CryptoProvider *	pProvider,
		const uint8_t *	pInput,
		uint32_t	lenInput,
		SOPC_SecretBuffer *	pKey,
		SOPC_SecretBuffer *	pKeyNonce,
		const SOPC_ExposedBuffer *	pRandom,
		uint32_t	lenRandom,
		uint32_t	uSequenceNumber,
		uint8_t *	pOutput,
		uint32_t	lenOutput
	)

Encrypts or Decrypts a payload pInput of lenInput bytes.

Writes the ciphered payload in pOutput of lenOutput bytes. The length of the output must be the same as the input.

This mode of operation does not require block alignment or padding.

Parameters

pProvider	An initialized cryptographic context.
pInput	A valid pointer to the payload to cipher/decipher.
lenInput	Length in bytes of the payload to cipher/decipher.
pKey	A valid pointer to a SecretBuffer containing the symmetric encryption key.
pKeyNonce	A valid pointer to a SecretBuffer containing the key nonce associated to the key.
pRandom	A valid pointer to an ExposedBuffer containing the random nonce of the message.
lenRandom	Length in bytes of the message random buffer.
uSequenceNumber	The sequence number of the message. It forms the block counter alongside the key nonce and random.
pOutput	A valid pointer to the buffer which will contain the transformed payload.
lenOutput	The output length must be the same as the input length.

Note: Content of the output is unspecified when return value is not SOPC_STATUS_OK.; See SOPC_CryptoProvider_SymmetricGetLength_CryptoKey() for the key length, SOPC_CryptoProvider_PubSubGetLength_KeyNonce() for the nonce length, and SOPC_CryptoProvider_PubSubGetLength_MessageRandom() for lenRandom.; Specific to PubSub security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized or pProvider is initialized for a client-server security policy or sizes are incorrect, and SOPC_STATUS_NOK when there was an error.

◆ SOPC_CryptoProvider_SymmetricSign()

SOPC_ReturnStatus SOPC_CryptoProvider_SymmetricSign	(	const SOPC_CryptoProvider *	pProvider,
		const uint8_t *	pInput,
		uint32_t	lenInput,
		SOPC_SecretBuffer *	pKey,
		uint8_t *	pOutput,
		uint32_t	lenOutput
	)

Signs a payload pInput of lenInput bytes, writes the signature in pOutput of lenOutput bytes.

The signature is as long as the underlying hash digest, which size is computed with SOPC_CryptoProvider_SymmetricGetLength_Signature(). Usually, the unpadded plain text message is signed.

The signing key is usually derived from shared secrets with SOPC_CryptoProvider_DeriveKeySets().

Parameters

pProvider	An initialized cryptographic context.
pInput	A valid pointer to the payload to sign.
lenInput	Length in bytes of the payload to sign.
pKey	A valid pointer to a SecretBuffer containing the symmetric signing key.
pOutput	A valid pointer to the buffer which will contain the signature.
lenOutput	The exact length of the signature buffer. SOPC_CryptoProvider_SymmetricGetLength_Signature() provides the expected size of this buffer.

Note: Content of the output is unspecified when return value is not SOPC_STATUS_OK.; For both client-server and PubSub security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized or sizes are incorrect, and SOPC_STATUS_NOK when there was an error.

◆ SOPC_CryptoProvider_SymmetricVerify()

SOPC_ReturnStatus SOPC_CryptoProvider_SymmetricVerify	(	const SOPC_CryptoProvider *	pProvider,
		const uint8_t *	pInput,
		uint32_t	lenInput,
		SOPC_SecretBuffer *	pKey,
		const uint8_t *	pSignature,
		uint32_t	lenOutput
	)

Verifies the signature pSignature of the payload pInput of lenInput bytes.

The signature is as long as the underlying hash digest, which size is computed with SOPC_CryptoProvider_SymmetricGetLength_Signature(). Usually, the unpadded plain text message is signed. The signature verification process computes the signature from pInput and compares it with the content of pSignature.

The signing key is usually derived from shared secrets with SOPC_CryptoProvider_DeriveKeySets().

Parameters

pProvider	An initialized cryptographic context.
pInput	A valid pointer to the payload to sign.
lenInput	Length in bytes of the payload to sign.
pKey	A valid pointer to a SecretBuffer containing the symmetric signing key.
pSignature	A valid pointer to the signature.
lenOutput	The exact length of the signature buffer. SOPC_CryptoProvider_SymmetricGetLength_Signature() provides the expected size of this buffer.

Note: Content of the output is unspecified when return value is not SOPC_STATUS_OK.; For both client-server and PubSub security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized or sizes are incorrect, and SOPC_STATUS_NOK when there was an error.

◆ SOPC_CryptoProvider_GenerateRandomBytes()

SOPC_ReturnStatus SOPC_CryptoProvider_GenerateRandomBytes	(	const SOPC_CryptoProvider *	pProvider,
		uint32_t	nBytes,
		SOPC_ExposedBuffer **	ppBuffer
	)

Generates truly random data of arbitrary length.

Uses the entropy generator provided by the underlying cryptographic library. The new ExposedBuffer is to be freed by the caller.

Note: Prefer the functions SOPC_CryptoProvider_GenerateSecureChannelNonce() and SOPC_CryptoProvider_GenerateRandomID().

Parameters

pProvider	An initialized cryptographic context.
nBytes	Number of bytes to generate (and length of the created `ppBuffer`).
ppBuffer	A valid handle to the newly created ExposedBuffer.

Note: Content of the output is unspecified when return value is not SOPC_STATUS_OK.; For both client-server and PubSub security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized or sizes are incorrect, and SOPC_STATUS_NOK when there was an error (e.g. no entropy source).

◆ SOPC_CryptoProvider_GenerateSecureChannelNonce()

SOPC_ReturnStatus SOPC_CryptoProvider_GenerateSecureChannelNonce	(	const SOPC_CryptoProvider *	pProvider,
		SOPC_SecretBuffer **	ppNonce
	)

Generates a single truly random nonce for the SecureChannel creation.

The length of the nonce is defined by the current security policy (see TBD). Uses the entropy generator provided by the underlying cryptographic library. The new SecretBuffer is to be freed by the caller.

Parameters

pProvider	An initialized cryptographic context.
ppNonce	A valid handle to the newly created SecretBuffer.

Note: Content of the output is unspecified when return value is not SOPC_STATUS_OK.; Specific to client-server security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized or sizes are incorrect, and SOPC_STATUS_NOK when there was an error (e.g. no entropy source).

◆ SOPC_CryptoProvider_GenerateRandomID()

SOPC_ReturnStatus SOPC_CryptoProvider_GenerateRandomID	(	const SOPC_CryptoProvider *	pProvider,
		uint32_t *	pID
	)

Generates 4 bytes of truly random data.

Parameters

pProvider	An initialized cryptographic context.
pID	A valid pointer which will contain the random data.

Note: Content of the output is unspecified when return value is not SOPC_STATUS_OK.; Specific to client-server security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized or sizes are incorrect, and SOPC_STATUS_NOK when there was an error (e.g. no entropy source).

◆ SOPC_CryptoProvider_DerivePseudoRandomData()

SOPC_ReturnStatus SOPC_CryptoProvider_DerivePseudoRandomData	(	const SOPC_CryptoProvider *	pProvider,
		const SOPC_ExposedBuffer *	pSecret,
		uint32_t	lenSecret,
		const SOPC_ExposedBuffer *	pSeed,
		uint32_t	lenSeed,
		SOPC_ExposedBuffer *	pOutput,
		uint32_t	lenOutput
	)

Derives pseudo-random data from the randomly generated and shared secrets.

Note: Internal API, use SOPC_CryptoProvider_DeriveKeySetsClient() or SOPC_CryptoProvider_DeriveKeySetsServer() instead.; Specific to client-server security policies.

◆ SOPC_CryptoProvider_DeriveKeySets()

SOPC_ReturnStatus SOPC_CryptoProvider_DeriveKeySets	(	const SOPC_CryptoProvider *	pProvider,
		const SOPC_ExposedBuffer *	pClientNonce,
		uint32_t	lenClientNonce,
		const SOPC_ExposedBuffer *	pServerNonce,
		uint32_t	lenServerNonce,
		SOPC_SC_SecurityKeySet *	pClientKeySet,
		SOPC_SC_SecurityKeySet *	pServerKeySet
	)

Derive pseudo-random key sets from the randomly generated and shared secrets.

See also: SOPC_CryptoProvider_SymmetricGenerateKey(), SOPC_CryptoProvider_DeriveKeySetsClient(), and SOPC_CryptoProvider_DeriveKeySetsServer().

Parameters

pProvider	An initialized cryptographic context.
pClientNonce	A valid pointer to the client nonce buffer, the client part of the secret.
lenClientNonce	Length in bytes of the buffer of the client nonce. Its size should be TBD.
pServerNonce	A valid pointer to the server nonce buffer, the server part of the secret.
lenServerNonce	Length in bytes of the buffer of the server nonce. Its size should be TBD.
pClientKeySet	A valid pointer to a pre-allocated SC_SecurityKeySet which will contain the client side derived data.
pServerKeySet	A valid pointer to a pre-allocated SC_SecurityKeySet which will contain the server side derived data.

Note: Contents of the outputs is unspecified when return value is not SOPC_STATUS_OK.; Specific to client-server security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized or sizes are incorrect, and SOPC_STATUS_NOK when there was an error.

◆ SOPC_CryptoProvider_DeriveKeySetsClient()

SOPC_ReturnStatus SOPC_CryptoProvider_DeriveKeySetsClient	(	const SOPC_CryptoProvider *	pProvider,
		SOPC_SecretBuffer *	pClientNonce,
		const SOPC_ExposedBuffer *	pServerNonce,
		uint32_t	lenServerNonce,
		SOPC_SC_SecurityKeySet *	pClientKeySet,
		SOPC_SC_SecurityKeySet *	pServerKeySet
	)

Derive pseudo-random key sets from the randomly generated and shared secrets.

This function is similar to SOPC_CryptoProvider_DeriveKeySets but uses the client nonce as a SecretBuffer.

Parameters

pProvider	An initialized cryptographic context.
pClientNonce	A valid pointer to the client nonce as a SecretBuffer.
pServerNonce	A valid pointer to the server nonce buffer, the server part of the secret.
lenServerNonce	Length in bytes of the buffer of the server nonce. Its size should be TBD.
pClientKeySet	A valid pointer to a pre-allocated SC_SecurityKeySet which will contain the client side derived data.
pServerKeySet	A valid pointer to a pre-allocated SC_SecurityKeySet which will contain the server side derived data.

Note: Contents of the outputs is unspecified when return value is not SOPC_STATUS_OK.; Specific to client-server security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized or sizes are incorrect, and SOPC_STATUS_NOK when there was an error.

◆ SOPC_CryptoProvider_DeriveKeySetsServer()

SOPC_ReturnStatus SOPC_CryptoProvider_DeriveKeySetsServer	(	const SOPC_CryptoProvider *	pProvider,
		const SOPC_ExposedBuffer *	pClientNonce,
		uint32_t	lenClientNonce,
		SOPC_SecretBuffer *	pServerNonce,
		SOPC_SC_SecurityKeySet *	pClientKeySet,
		SOPC_SC_SecurityKeySet *	pServerKeySet
	)

Derive pseudo-random key sets from the randomly generated and shared secrets.

This function is similar to SOPC_CryptoProvider_DeriveKeySets but uses the server nonce as a SecretBuffer.

Parameters

pProvider	An initialized cryptographic context.
pClientNonce	A valid pointer to the client nonce buffer, the client part of the secret.
lenClientNonce	Length in bytes of the buffer of the client nonce. Its size should be TBD.
pServerNonce	A valid pointer to the server nonce as a SecretBuffer.
pClientKeySet	A valid pointer to a pre-allocated SC_SecurityKeySet which will contain the client side derived data.
pServerKeySet	A valid pointer to a pre-allocated SC_SecurityKeySet which will contain the server side derived data.

Note: Contents of the outputs is unspecified when return value is not SOPC_STATUS_OK.; Specific to client-server security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized or sizes are incorrect, and SOPC_STATUS_NOK when there was an error.

◆ SOPC_CryptoProvider_AsymmetricEncrypt()

SOPC_ReturnStatus SOPC_CryptoProvider_AsymmetricEncrypt	(	const SOPC_CryptoProvider *	pProvider,
		const uint8_t *	pInput,
		uint32_t	lenInput,
		const SOPC_AsymmetricKey *	pKey,
		uint8_t *	pOutput,
		uint32_t	lenOutput,
		const char **	errorReason
	)

Encrypts a payload pInput of lenInput bytes.

Writes the ciphered payload in pOutput of lenOutput bytes. The message may be padded. Depending on the chosen security policy, optimal padding is performed if lenPlainText is less than the maximum message size (computed with SOPC_CryptoProvider_AsymmetricGetLength_MsgPlainText()). If the payload is larger than the maximum message size for a single encryption pass, it is split in several smaller messages of at most that maximum length.

The key is usually taken from a signed public key (Certificate) and is the public key of the receiver.

Parameters

pProvider	An initialized cryptographic context.
pInput	A valid pointer to the payload to cipher. The payload may be padded by the function, if necessary.
lenInput	Length in bytes of the payload to cipher.
pKey	A valid pointer to an SOPC_AsymmetricKey containing the asymmetric encryption key (public key).
pOutput	A valid pointer to the buffer which will contain the ciphered payload.
lenOutput	The exact length of the ciphered payload. SOPC_CryptoProvider_AsymmetricGetLength_Encryption() provides the expected size of this buffer.
errorReason	Pointer to a C string used to point on error reason string when returned status != SOPC_STATUS_OK

Note: Contents of the outputs is unspecified when return value is not SOPC_STATUS_OK.; Specific to client-server security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized or sizes are incorrect, and SOPC_STATUS_NOK when there was an error.

◆ SOPC_CryptoProvider_AsymmetricDecrypt()

SOPC_ReturnStatus SOPC_CryptoProvider_AsymmetricDecrypt	(	const SOPC_CryptoProvider *	pProvider,
		const uint8_t *	pInput,
		uint32_t	lenInput,
		const SOPC_AsymmetricKey *	pKey,
		uint8_t *	pOutput,
		uint32_t	lenOutput,
		uint32_t *	pLenWritten,
		const char **	errorReason
	)

Decrypts a payload pInput of lenInput bytes.

Writes the deciphered payload in pOutput of lenOutput bytes. Depending on the chosen security policy, when the message was padded with SOPC_CryptoProvider_AsymmetricEncrypt(), the output is unpadded by this function and the initial payload is written to pOutput. If the payload is larger than the maximum message size for a single decryption pass, it is split in several smaller messages of at most that maximum length (SOPC_CryptoProvider_AsymmetricGetLength_MsgCipherText()).

The key is usually taken from a private key (Certificate, SOPC_KeyManager_AsymmetricKey_CreateFromFile()) and is the private key of the sender.

Parameters

pProvider	An initialized cryptographic context.
pInput	A valid pointer to the payload to cipher. The payload may be padded by the function, if necessary.
lenInput	Length in bytes of the payload to cipher.
pKey	A valid pointer to an SOPC_AsymmetricKey containing the asymmetric decryption key (private key).
pOutput	A valid pointer to the buffer which will contain the deciphered payload.
lenOutput	The exact length of the deciphered payload. SOPC_CryptoProvider_AsymmetricGetLength_Decryption() provides the expected size of this buffer.
pLenWritten	An optional pointer to the length in bytes that are written to the `pOutput` buffer. Useful to determine the actual size of the plain text.
errorReason	Pointer to a C string used to point on error reason string when returned status != SOPC_STATUS_OK

Note: Contents of the outputs is unspecified when return value is not SOPC_STATUS_OK.; Specific to client-server security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized or sizes are incorrect, and SOPC_STATUS_NOK when there was an error.

◆ SOPC_CryptoProvider_AsymmetricSign()

SOPC_ReturnStatus SOPC_CryptoProvider_AsymmetricSign	(	const SOPC_CryptoProvider *	pProvider,
		const uint8_t *	pInput,
		uint32_t	lenInput,
		const SOPC_AsymmetricKey *	pKeyPrivateLocal,
		uint8_t *	pSignature,
		uint32_t	lenSignature,
		const char **	errorReason
	)

Signs a payload pInput of lenInput bytes.

Writes the signature to pSignature, which is exactly lenSignature bytes long. The signature is as long as a single ciphered message, which size is computed with SOPC_CryptoProvider_AsymmetricGetLength_Signature(). Usually, the unpadded plain text message is signed. The asymmetric signature process first hashes the pInput.

The key is usually taken from a private key (SOPC_KeyManager_AsymmetricKey_CreateFromFile()) and is the private key of the sender, which authenticates the sender as the signer.

The signature is already encrypted and does not require to be ciphered again before being sent to the receiver.

Note: The signature process may use the entropy source of the SOPC_CryptoProvider (depending on the current security policy).

Parameters

pProvider	An initialized cryptographic context.
pInput	A valid pointer to the payload to sign.
lenInput	Length in bytes of the payload to sign.
pKeyPrivateLocal	A valid pointer to an SOPC_AsymmetricKey containing the asymmetric signing key (private key of the sender).
pSignature	A valid pointer to the buffer which will contain the signature.
lenSignature	The exact length of the signature payload. SOPC_CryptoProvider_AsymmetricGetLength_Signature() provides the expected size of this buffer.
errorReason	Pointer to a C string used to point on error reason string when returned status != SOPC_STATUS_OK

Note: Contents of the outputs is unspecified when return value is not SOPC_STATUS_OK.; Specific to client-server security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized or sizes are incorrect, and SOPC_STATUS_NOK when there was an error (e.g. no entropy source).

◆ SOPC_CryptoProvider_AsymmetricVerify()

SOPC_ReturnStatus SOPC_CryptoProvider_AsymmetricVerify	(	const SOPC_CryptoProvider *	pProvider,
		const uint8_t *	pInput,
		uint32_t	lenInput,
		const SOPC_AsymmetricKey *	pKeyRemotePublic,
		const uint8_t *	pSignature,
		uint32_t	lenSignature,
		const char **	errorReason
	)

Verifies the signature pSignature of a payload pInput of lenInput bytes.

The signature pSignature is exactly lenSignature bytes long. The signature is as long as a single ciphered message, which size is computed with SOPC_CryptoProvider_AsymmetricGetLength_Signature(). The asymmetric verify process first deciphers the signature which should provide the hash of pInput. Usually, the unpadded plain text message is signed.

The key is usually taken from a public key (Certificate) and is the public key of the sender, which authenticates the sender as the signer.

Parameters

pProvider	An initialized cryptographic context.
pInput	A valid pointer to the signed payload to verify.
lenInput	Length in bytes of the signed payload to verify.
pKeyRemotePublic	A valid pointer to an SOPC_AsymmetricKey containing the asymmetric verification key (public key of the sender).
pSignature	A valid pointer to the buffer which will contain the signature.
lenSignature	The exact length of the signature payload. SOPC_CryptoProvider_AsymmetricGetLength_Signature() provides the expected size of this buffer.
errorReason	Pointer to a C string used to point on error reason string when returned status != SOPC_STATUS_OK

Note: Contents of the outputs is unspecified when return value is not SOPC_STATUS_OK.; Specific to client-server security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized or sizes are incorrect, and SOPC_STATUS_NOK when there was an error.

◆ SOPC_CryptoProvider_Certificate_Validate()

SOPC_ReturnStatus SOPC_CryptoProvider_Certificate_Validate	(	const SOPC_CryptoProvider *	pProvider,
		SOPC_PKIProvider *	pPKI,
		const SOPC_PKI_Type	PKIType,
		const SOPC_CertificateList *	pCert,
		uint32_t *	error
	)

Validates the given Certificate pCert.

This function verifies that the signed public key respects the current security policy (asymmetric key type and length, signature hash type, ...), and also handle the signature chain up to the certificate authority. The verifications are not endorsed by the SOPC_CryptoProvider, but by the PKIProvider.

Parameters

pProvider	An initialized cryptographic context.
pPKI	An initialized public key infrastructure (PKIProvider).
PKIType	Defines the type of PKI (user, client or server)
pCert	A valid pointer to the Certificate to validate.
error	Ouput error code set when returned status is not SOPC_STATUS_OK (see sopc_pki_stack.h for values)

Note: Contents of the outputs is unspecified when return value is SOPC_STATUS_NOK.; Specific to client-server security policies.

Returns: SOPC_STATUS_OK when successful, SOPC_STATUS_INVALID_PARAMETERS when parameters are NULL or pProvider not correctly initialized or sizes are incorrect, and SOPC_STATUS_NOK when there was an error.

Data Structures

Functions

Detailed Description

Function Documentation

◆ SOPC_CryptoProvider_Create()

◆ SOPC_CryptoProvider_CreatePubSub()

◆ SOPC_CryptoProvider_Free()

◆ SOPC_CryptoProvider_GetProfileServices()

◆ SOPC_CryptoProvider_GetProfilePubSub()

◆ SOPC_CryptoProvider_SymmetricGetLength_CryptoKey()

◆ SOPC_CryptoProvider_SymmetricGetLength_Encryption()

◆ SOPC_CryptoProvider_SymmetricGetLength_Decryption()

◆ SOPC_CryptoProvider_SymmetricGetLength_SignKey()

◆ SOPC_CryptoProvider_SymmetricGetLength_Signature()

◆ SOPC_CryptoProvider_SymmetricGetLength_Blocks()

◆ SOPC_CryptoProvider_SymmetricGetLength_SecureChannelNonce()

◆ SOPC_CryptoProvider_DeriveGetLengths()

◆ SOPC_CryptoProvider_AsymmetricGetLength_KeyBytes()

◆ SOPC_CryptoProvider_AsymmetricGetLength_OAEPHashLength()

◆ SOPC_CryptoProvider_AsymmetricGetLength_Msgs()

◆ SOPC_CryptoProvider_AsymmetricGetLength_Encryption()

◆ SOPC_CryptoProvider_AsymmetricGetLength_Decryption()

◆ SOPC_CryptoProvider_AsymmetricGetLength_Signature()

◆ SOPC_CryptoProvider_AsymmetricGetUri_SignAlgorithm()

◆ SOPC_CryptoProvider_CertificateGetLength_Thumbprint()

◆ SOPC_CryptoProvider_PubSubGetLength_KeyNonce()

◆ SOPC_CryptoProvider_PubSubGetLength_MessageRandom()

◆ SOPC_CryptoProvider_SymmetricEncrypt()

◆ SOPC_CryptoProvider_SymmetricDecrypt()

◆ SOPC_CryptoProvider_PubSubCrypt()

◆ SOPC_CryptoProvider_SymmetricSign()

◆ SOPC_CryptoProvider_SymmetricVerify()

◆ SOPC_CryptoProvider_GenerateRandomBytes()

◆ SOPC_CryptoProvider_GenerateSecureChannelNonce()

◆ SOPC_CryptoProvider_GenerateRandomID()

◆ SOPC_CryptoProvider_DerivePseudoRandomData()

◆ SOPC_CryptoProvider_DeriveKeySets()

◆ SOPC_CryptoProvider_DeriveKeySetsClient()

◆ SOPC_CryptoProvider_DeriveKeySetsServer()

◆ SOPC_CryptoProvider_AsymmetricEncrypt()

◆ SOPC_CryptoProvider_AsymmetricDecrypt()

◆ SOPC_CryptoProvider_AsymmetricSign()

◆ SOPC_CryptoProvider_AsymmetricVerify()

◆ SOPC_CryptoProvider_Certificate_Validate()