This module includes the platform abstraction for Crypto.

Classes
struct	otCryptoKey
	This structure represents the Key Material required for Crypto operations.

struct	otCryptoContext
	This structure stores the context object for platform APIs.

Typedefs
typedef uint32_t	otCryptoKeyRef
	This datatype represents the key reference.

typedef struct otCryptoKey	otCryptoKey

typedef struct otCryptoContext	otCryptoContext

Enumerations
enum	otCryptoKeyType { OT_CRYPTO_KEY_TYPE_RAW , OT_CRYPTO_KEY_TYPE_AES , OT_CRYPTO_KEY_TYPE_HMAC }
	This enumeration defines the key types.

enum	otCryptoKeyAlgorithm { OT_CRYPTO_KEY_ALG_VENDOR , OT_CRYPTO_KEY_ALG_AES_ECB , OT_CRYPTO_KEY_ALG_HMAC_SHA_256 }
	This enumeration defines the key algorithms.

enum	{ OT_CRYPTO_KEY_USAGE_NONE = 0, OT_CRYPTO_KEY_USAGE_EXPORT = 1 << 0, OT_CRYPTO_KEY_USAGE_ENCRYPT = 1 << 1, OT_CRYPTO_KEY_USAGE_DECRYPT = 1 << 2, OT_CRYPTO_KEY_USAGE_SIGN_HASH = 1 << 3 }
	This enumeration defines the key usage flags.

enum	otCryptoKeyStorage { OT_CRYPTO_KEY_STORAGE_VOLATILE , OT_CRYPTO_KEY_STORAGE_PERSISTENT }
	This enumeration defines the key storage types.

Functions
void	otPlatCryptoInit (void)
	Initialize the Crypto module.

otError	otPlatCryptoImportKey ( otCryptoKeyRef aKeyRef, otCryptoKeyType aKeyType, otCryptoKeyAlgorithm aKeyAlgorithm, int aKeyUsage, otCryptoKeyStorage aKeyPersistence, const uint8_t aKey, size_t aKeyLen)
	Import a key into PSA ITS.

otError	otPlatCryptoExportKey ( otCryptoKeyRef aKeyRef, uint8_t aBuffer, size_t aBufferLen, size_t aKeyLen)
	Export a key stored in PSA ITS.

otError	otPlatCryptoDestroyKey ( otCryptoKeyRef aKeyRef)
	Destroy a key stored in PSA ITS.

bool	otPlatCryptoHasKey ( otCryptoKeyRef aKeyRef)
	Check if the key ref passed has an associated key in PSA ITS.

otError	otPlatCryptoHmacSha256Init ( otCryptoContext *aContext)
	Initialize the HMAC operation.

otError	otPlatCryptoHmacSha256Deinit ( otCryptoContext *aContext)
	Uninitialize the HMAC operation.

otError	otPlatCryptoHmacSha256Start ( otCryptoContext aContext, const otCryptoKey aKey)
	Start HMAC operation.

otError	otPlatCryptoHmacSha256Update ( otCryptoContext aContext, const void aBuf, uint16_t aBufLength)
	Update the HMAC operation with new input.

otError	otPlatCryptoHmacSha256Finish ( otCryptoContext aContext, uint8_t aBuf, size_t aBufLength)
	Complete the HMAC operation.

otError	otPlatCryptoAesInit ( otCryptoContext *aContext)
	Initialise the AES operation.

otError	otPlatCryptoAesSetKey ( otCryptoContext aContext, const otCryptoKey aKey)
	Set the key for AES operation.

otError	otPlatCryptoAesEncrypt ( otCryptoContext aContext, const uint8_t aInput, uint8_t *aOutput)
	Encrypt the given data.

otError	otPlatCryptoAesFree ( otCryptoContext *aContext)
	Free the AES context.

otError	otPlatCryptoHkdfInit ( otCryptoContext *aContext)
	Initialise the HKDF context.

otError	otPlatCryptoHkdfExpand ( otCryptoContext aContext, const uint8_t aInfo, uint16_t aInfoLength, uint8_t *aOutputKey, uint16_t aOutputKeyLength)
	Perform HKDF Expand step.

otError	otPlatCryptoHkdfExtract ( otCryptoContext aContext, const uint8_t aSalt, uint16_t aSaltLength, const otCryptoKey *aInputKey)
	Perform HKDF Extract step.

otError	otPlatCryptoHkdfDeinit ( otCryptoContext *aContext)
	Uninitialize the HKDF context.

otError	otPlatCryptoSha256Init ( otCryptoContext *aContext)
	Initialise the SHA-256 operation.

otError	otPlatCryptoSha256Deinit ( otCryptoContext *aContext)
	Uninitialize the SHA-256 operation.

otError	otPlatCryptoSha256Start ( otCryptoContext *aContext)
	Start SHA-256 operation.

otError	otPlatCryptoSha256Update ( otCryptoContext aContext, const void aBuf, uint16_t aBufLength)
	Update SHA-256 operation with new input.

otError	otPlatCryptoSha256Finish ( otCryptoContext aContext, uint8_t aHash, uint16_t aHashSize)
	Finish SHA-256 operation.

void	otPlatCryptoRandomInit (void)
	Initialize cryptographically-secure pseudorandom number generator (CSPRNG).

void	otPlatCryptoRandomDeinit (void)
	Deinitialize cryptographically-secure pseudorandom number generator (CSPRNG).

otError	otPlatCryptoRandomGet (uint8_t *aBuffer, uint16_t aSize)
	Fills a given buffer with cryptographically secure random bytes.

Detailed Description

This module includes the platform abstraction for Crypto.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

This enumeration defines the key usage flags.

Enumerator
OT_CRYPTO_KEY_USAGE_NONE	Key Usage: Key Usage is empty.
OT_CRYPTO_KEY_USAGE_EXPORT	Key Usage: Key can be exported.
OT_CRYPTO_KEY_USAGE_ENCRYPT	Key Usage: Encryption (vendor defined).
OT_CRYPTO_KEY_USAGE_DECRYPT	Key Usage: AES ECB.
OT_CRYPTO_KEY_USAGE_SIGN_HASH	Key Usage: HMAC SHA-256.

◆ otCryptoKeyAlgorithm

enum otCryptoKeyAlgorithm

This enumeration defines the key algorithms.

Enumerator
OT_CRYPTO_KEY_ALG_VENDOR	Key Algorithm: Vendor Defined.
OT_CRYPTO_KEY_ALG_AES_ECB	Key Algorithm: AES ECB.
OT_CRYPTO_KEY_ALG_HMAC_SHA_256	Key Algorithm: HMAC SHA-256.

◆ otCryptoKeyStorage

enum otCryptoKeyStorage

This enumeration defines the key storage types.

Enumerator
OT_CRYPTO_KEY_STORAGE_VOLATILE	Key Persistence: Key is volatile.
OT_CRYPTO_KEY_STORAGE_PERSISTENT	Key Persistence: Key is persistent.

◆ otCryptoKeyType

enum otCryptoKeyType

This enumeration defines the key types.

Enumerator
OT_CRYPTO_KEY_TYPE_RAW	Key Type: Raw Data.
OT_CRYPTO_KEY_TYPE_AES	Key Type: AES.
OT_CRYPTO_KEY_TYPE_HMAC	Key Type: HMAC.

Function Documentation

◆ otPlatCryptoAesEncrypt()

otError otPlatCryptoAesEncrypt	(	otCryptoContext *	`aContext,`
		const uint8_t *	`aInput,`
		uint8_t *	`aOutput`
	)

Encrypt the given data.

Parameters

[in]	`aContext`	Context for AES operation.
[in]	`aInput`	Pointer to the input buffer.
[in]	`aOutput`	Pointer to the output buffer.

Return values

`OT_ERROR_NONE`	Successfully encrypted `aInput` .
`OT_ERROR_FAILED`	Failed to encrypt `aInput` .
`OT_ERROR_INVALID_ARGS`	`aContext` or `aKey` or `aOutput` were NULL

◆ otPlatCryptoAesFree()

otError otPlatCryptoAesFree ( otCryptoContext * aContext )

Free the AES context.

Parameters

[in] aContext Context for AES operation.

Return values

`OT_ERROR_NONE`	Successfully freed AES context.
`OT_ERROR_FAILED`	Failed to free AES context.
`OT_ERROR_INVALID_ARGS`	`aContext` was NULL

◆ otPlatCryptoAesInit()

otError otPlatCryptoAesInit ( otCryptoContext * aContext )

Initialise the AES operation.

Parameters

[in] aContext Context for AES operation.

Return values

`OT_ERROR_NONE`	Successfully Initialised AES operation.
`OT_ERROR_FAILED`	Failed to Initialise AES operation.
`OT_ERROR_INVALID_ARGS`	`aContext` was NULL
`OT_ERROR_NO_BUFS`	Cannot allocate the context.

Note: The platform driver shall point the context to the correct object such as psa_key_id or mbedtls_aes_context_t.

◆ otPlatCryptoAesSetKey()

otError otPlatCryptoAesSetKey	(	otCryptoContext *	`aContext,`
		const otCryptoKey *	`aKey`
	)

Set the key for AES operation.

Parameters

[in]	`aContext`	Context for AES operation.
[out]	`aKey`	Key to use for AES operation.

Return values

`OT_ERROR_NONE`	Successfully set the key for AES operation.
`OT_ERROR_FAILED`	Failed to set the key for AES operation.
`OT_ERROR_INVALID_ARGS`	`aContext` or `aKey` was NULL

◆ otPlatCryptoDestroyKey()

otError otPlatCryptoDestroyKey ( otCryptoKeyRef aKeyRef )

Destroy a key stored in PSA ITS.

Parameters

[in] aKeyRef The key ref to be destroyed

Return values

`OT_ERROR_NONE`	Successfully destroyed the key.
`OT_ERROR_FAILED`	Failed to destroy the key.

Note: This API is only used by OT core when OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE is enabled.

◆ otPlatCryptoExportKey()

otError otPlatCryptoExportKey	(	otCryptoKeyRef	`aKeyRef,`
		uint8_t *	`aBuffer,`
		size_t	`aBufferLen,`
		size_t *	`aKeyLen`
	)

Export a key stored in PSA ITS.

Parameters

[in]	`aKeyRef`	The key ref to be used for crypto operations.
[out]	`aBuffer`	Pointer to the buffer where key needs to be exported.
[in]	`aBufferLen`	Length of the buffer passed to store the exported key.
[out]	`aKeyLen`	Pointer to return the length of the exported key.

Return values

`OT_ERROR_NONE`	Successfully exported `aKeyRef` .
`OT_ERROR_FAILED`	Failed to export `aKeyRef` .
`OT_ERROR_INVALID_ARGS`	`aBuffer` was NULL

Note: This API is only used by OT core when OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE is enabled.

◆ otPlatCryptoHasKey()

bool otPlatCryptoHasKey ( otCryptoKeyRef aKeyRef )

Check if the key ref passed has an associated key in PSA ITS.

Parameters

[in] aKeyRef The Key Ref to check.

Return values

`TRUE`	There is an associated key with `aKeyRef` .
`FALSE`	There is no associated key with `aKeyRef` .

Note: This API is only used by OT core when OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE is enabled.

◆ otPlatCryptoHkdfDeinit()

otError otPlatCryptoHkdfDeinit ( otCryptoContext * aContext )

Uninitialize the HKDF context.

Parameters

[in] aContext Context for HKDF operation.

Return values

`OT_ERROR_NONE`	Successfully un-initialised HKDF operation.
`OT_ERROR_FAILED`	Failed to un-initialised HKDF operation.
`OT_ERROR_INVALID_ARGS`	`aContext` was NULL

◆ otPlatCryptoHkdfExpand()

otError otPlatCryptoHkdfExpand	(	otCryptoContext *	`aContext,`
		const uint8_t *	`aInfo,`
		uint16_t	`aInfoLength,`
		uint8_t *	`aOutputKey,`
		uint16_t	`aOutputKeyLength`
	)

Perform HKDF Expand step.

Parameters

[in]	`aContext`	Operation context for HKDF operation.
[in]	`aInfo`	Pointer to the Info sequence.
[in]	`aInfoLength`	Length of the Info sequence.
[out]	`aOutputKey`	Pointer to the output Key.
[in]	`aOutputKeyLength`	Size of the output key buffer.

Return values

`OT_ERROR_NONE`	HKDF Expand was successful.
`OT_ERROR_FAILED`	HKDF Expand failed.
`OT_ERROR_INVALID_ARGS`	`aContext` was NULL

◆ otPlatCryptoHkdfExtract()

otError otPlatCryptoHkdfExtract	(	otCryptoContext *	`aContext,`
		const uint8_t *	`aSalt,`
		uint16_t	`aSaltLength,`
		const otCryptoKey *	`aInputKey`
	)

Perform HKDF Extract step.

Parameters

[in]	`aContext`	Operation context for HKDF operation.
[in]	`aSalt`	Pointer to the Salt for HKDF.
[in]	`aSaltLength`	Length of Salt.
[in]	`aInputKey`	Pointer to the input key.

Return values

`OT_ERROR_NONE`	HKDF Extract was successful.
`OT_ERROR_FAILED`	HKDF Extract failed.

◆ otPlatCryptoHkdfInit()

otError otPlatCryptoHkdfInit ( otCryptoContext * aContext )

Initialise the HKDF context.

Parameters

[in] aContext Context for HKDF operation.

Return values

`OT_ERROR_NONE`	Successfully Initialised AES operation.
`OT_ERROR_FAILED`	Failed to Initialise AES operation.
`OT_ERROR_INVALID_ARGS`	`aContext` was NULL

Note: The platform driver shall point the context to the correct object such as psa_key_derivation_operation_t or HmacSha256::Hash

◆ otPlatCryptoHmacSha256Deinit()

otError otPlatCryptoHmacSha256Deinit ( otCryptoContext * aContext )

Uninitialize the HMAC operation.

Parameters

[in] aContext Context for HMAC operation.

Return values

`OT_ERROR_NONE`	Successfully uninitialized HMAC operation.
`OT_ERROR_FAILED`	Failed to uninitialized HMAC operation.
`OT_ERROR_INVALID_ARGS`	`aContext` was NULL

◆ otPlatCryptoHmacSha256Finish()

otError otPlatCryptoHmacSha256Finish	(	otCryptoContext *	`aContext,`
		uint8_t *	`aBuf,`
		size_t	`aBufLength`
	)

Complete the HMAC operation.

Parameters

[in]	`aContext`	Context for HMAC operation.
[out]	`aBuf`	A pointer to the output buffer.
[in]	`aBufLength`	The length of `aBuf` in bytes.

Return values

`OT_ERROR_NONE`	Successfully completed HMAC operation.
`OT_ERROR_FAILED`	Failed to complete HMAC operation.
`OT_ERROR_INVALID_ARGS`	`aContext` or `aBuf` was NULL

◆ otPlatCryptoHmacSha256Init()

otError otPlatCryptoHmacSha256Init ( otCryptoContext * aContext )

Initialize the HMAC operation.

Parameters

[in] aContext Context for HMAC operation.

Return values

`OT_ERROR_NONE`	Successfully initialized HMAC operation.
`OT_ERROR_FAILED`	Failed to initialize HMAC operation.
`OT_ERROR_INVALID_ARGS`	`aContext` was NULL

Note: The platform driver shall point the context to the correct object such as psa_mac_operation_t or mbedtls_md_context_t.

◆ otPlatCryptoHmacSha256Start()

otError otPlatCryptoHmacSha256Start	(	otCryptoContext *	`aContext,`
		const otCryptoKey *	`aKey`
	)

Start HMAC operation.

Parameters

[in]	`aContext`	Context for HMAC operation.
[in]	`aKey`	Key material to be used for for HMAC operation.

Return values

`OT_ERROR_NONE`	Successfully started HMAC operation.
`OT_ERROR_FAILED`	Failed to start HMAC operation.
`OT_ERROR_INVALID_ARGS`	`aContext` or `aKey` was NULL

◆ otPlatCryptoHmacSha256Update()

otError otPlatCryptoHmacSha256Update	(	otCryptoContext *	`aContext,`
		const void *	`aBuf,`
		uint16_t	`aBufLength`
	)

Update the HMAC operation with new input.

Parameters

[in]	`aContext`	Context for HMAC operation.
[in]	`aBuf`	A pointer to the input buffer.
[in]	`aBufLength`	The length of `aBuf` in bytes.

Return values

`OT_ERROR_NONE`	Successfully updated HMAC with new input operation.
`OT_ERROR_FAILED`	Failed to update HMAC operation.
`OT_ERROR_INVALID_ARGS`	`aContext` or `aBuf` was NULL

◆ otPlatCryptoImportKey()

otError otPlatCryptoImportKey	(	otCryptoKeyRef *	`aKeyRef,`
		otCryptoKeyType	`aKeyType,`
		otCryptoKeyAlgorithm	`aKeyAlgorithm,`
		int	`aKeyUsage,`
		otCryptoKeyStorage	`aKeyPersistence,`
		const uint8_t *	`aKey,`
		size_t	`aKeyLen`
	)

Import a key into PSA ITS.

Parameters

[in,out]	`aKeyRef`	Pointer to the key ref to be used for crypto operations.
[in]	`aKeyType`	Key Type encoding for the key.
[in]	`aKeyAlgorithm`	Key algorithm encoding for the key.
[in]	`aKeyUsage`	Key Usage encoding for the key (combinations of `OT_CRYPTO_KEY_USAGE_*` ).
[in]	`aKeyPersistence`	Key Persistence for this key
[in]	`aKey`	Actual key to be imported.
[in]	`aKeyLen`	Length of the key to be imported.

Return values

`OT_ERROR_NONE`	Successfully imported the key.
`OT_ERROR_FAILED`	Failed to import the key.
`OT_ERROR_INVALID_ARGS`	`aKey` was set to NULL.

Note: If OT_CRYPTO_KEY_STORAGE_PERSISTENT is passed for aKeyPersistence then aKeyRef is input and platform should use the given aKeyRef and MUST not change it.

If OT_CRYPTO_KEY_STORAGE_VOLATILE is passed for aKeyPersistence then aKeyRef is output, the initial value does not matter and platform API MUST update it to return the new key ref.

This API is only used by OT core when OPENTHREAD_CONFIG_PLATFORM_KEY_REFERENCES_ENABLE is enabled.

◆ otPlatCryptoRandomGet()

otError otPlatCryptoRandomGet	(	uint8_t *	`aBuffer,`
		uint16_t	`aSize`
	)

Fills a given buffer with cryptographically secure random bytes.

Parameters

[out]	`aBuffer`	A pointer to a buffer to fill with the random bytes.
[in]	`aSize`	Size of buffer (number of bytes to fill).

Return values

`OT_ERROR_NONE`	Successfully filled buffer with random values.
`OT_ERROR_FAILED`	Operation failed.

◆ otPlatCryptoSha256Deinit()

otError otPlatCryptoSha256Deinit ( otCryptoContext * aContext )

Uninitialize the SHA-256 operation.

Parameters

[in] aContext Context for SHA-256 operation.

Return values

`OT_ERROR_NONE`	Successfully un-initialised SHA-256 operation.
`OT_ERROR_FAILED`	Failed to un-initialised SHA-256 operation.
`OT_ERROR_INVALID_ARGS`	`aContext` was NULL

◆ otPlatCryptoSha256Finish()

otError otPlatCryptoSha256Finish	(	otCryptoContext *	`aContext,`
		uint8_t *	`aHash,`
		uint16_t	`aHashSize`
	)

Finish SHA-256 operation.

Parameters

[in]	`aContext`	Context for SHA-256 operation.
[in]	`aHash`	A pointer to the output buffer, where hash needs to be stored.
[in]	`aHashSize`	The length of `aHash` in bytes.

Return values

`OT_ERROR_NONE`	Successfully completed the SHA-256 operation.
`OT_ERROR_FAILED`	Failed to complete SHA-256 operation.
`OT_ERROR_INVALID_ARGS`	`aContext` or `aHash` was NULL

◆ otPlatCryptoSha256Init()

otError otPlatCryptoSha256Init ( otCryptoContext * aContext )

Initialise the SHA-256 operation.

Parameters

[in] aContext Context for SHA-256 operation.

Return values

`OT_ERROR_NONE`	Successfully initialised SHA-256 operation.
`OT_ERROR_FAILED`	Failed to initialise SHA-256 operation.
`OT_ERROR_INVALID_ARGS`	`aContext` was NULL

Note: The platform driver shall point the context to the correct object such as psa_hash_operation_t or mbedtls_sha256_context.

◆ otPlatCryptoSha256Start()

otError otPlatCryptoSha256Start ( otCryptoContext * aContext )

Start SHA-256 operation.

Parameters

[in] aContext Context for SHA-256 operation.

Return values

`OT_ERROR_NONE`	Successfully started SHA-256 operation.
`OT_ERROR_FAILED`	Failed to start SHA-256 operation.
`OT_ERROR_INVALID_ARGS`	`aContext` was NULL

◆ otPlatCryptoSha256Update()

otError otPlatCryptoSha256Update	(	otCryptoContext *	`aContext,`
		const void *	`aBuf,`
		uint16_t	`aBufLength`
	)

Update SHA-256 operation with new input.

Parameters

[in]	`aContext`	Context for SHA-256 operation.
[in]	`aBuf`	A pointer to the input buffer.
[in]	`aBufLength`	The length of `aBuf` in bytes.

Return values

`OT_ERROR_NONE`	Successfully updated SHA-256 with new input operation.
`OT_ERROR_FAILED`	Failed to update SHA-256 operation.
`OT_ERROR_INVALID_ARGS`	`aContext` or `aBuf` was NULL

Crypto - Platform Platform Abstraction

Classes

Typedefs

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ anonymous enum

◆ otCryptoKeyAlgorithm

◆ otCryptoKeyStorage

◆ otCryptoKeyType

Function Documentation

◆ otPlatCryptoAesEncrypt()

◆ otPlatCryptoAesFree()

◆ otPlatCryptoAesInit()

◆ otPlatCryptoAesSetKey()

◆ otPlatCryptoDestroyKey()

◆ otPlatCryptoExportKey()

◆ otPlatCryptoHasKey()

◆ otPlatCryptoHkdfDeinit()

◆ otPlatCryptoHkdfExpand()

◆ otPlatCryptoHkdfExtract()

◆ otPlatCryptoHkdfInit()

◆ otPlatCryptoHmacSha256Deinit()

◆ otPlatCryptoHmacSha256Finish()

◆ otPlatCryptoHmacSha256Init()

◆ otPlatCryptoHmacSha256Start()

◆ otPlatCryptoHmacSha256Update()

◆ otPlatCryptoImportKey()

◆ otPlatCryptoRandomGet()

◆ otPlatCryptoSha256Deinit()

◆ otPlatCryptoSha256Finish()

◆ otPlatCryptoSha256Init()

◆ otPlatCryptoSha256Start()

◆ otPlatCryptoSha256Update()

Crypto - Platform
Platform Abstraction