Crypto - Platform

This module includes the platform abstraction for Crypto.

Summary

Enumerations
Anonymous Enum 17{   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 }	enum This enumeration defines the key usage flags.
otCryptoKeyAlgorithm{   OT_CRYPTO_KEY_ALG_VENDOR,   OT_CRYPTO_KEY_ALG_AES_ECB,   OT_CRYPTO_KEY_ALG_HMAC_SHA_256 }	enum This enumeration defines the key algorithms.
otCryptoKeyStorage{   OT_CRYPTO_KEY_STORAGE_VOLATILE,   OT_CRYPTO_KEY_STORAGE_PERSISTENT }	enum This enumeration defines the key storage types.
otCryptoKeyType{   OT_CRYPTO_KEY_TYPE_RAW,   OT_CRYPTO_KEY_TYPE_AES,   OT_CRYPTO_KEY_TYPE_HMAC }	enum This enumeration defines the key types.

Typedefs
otCryptoContext	typedef struct otCryptoContext
otCryptoKey	typedef struct otCryptoKey
otCryptoKeyRef	typedef uint32_t This datatype represents the key reference.

Functions
otPlatCryptoAesEncrypt(otCryptoContext *aContext, const uint8_t *aInput, uint8_t *aOutput)	otError Encrypt the given data.
otPlatCryptoAesFree(otCryptoContext *aContext)	otError Free the AES context.
otPlatCryptoAesInit(otCryptoContext *aContext)	otError Initialise the AES operation.
otPlatCryptoAesSetKey(otCryptoContext *aContext, const otCryptoKey *aKey)	otError Set the key for AES operation.
otPlatCryptoDestroyKey(otCryptoKeyRef aKeyRef)	otError Destroy a key stored in PSA ITS.
otPlatCryptoExportKey(otCryptoKeyRef aKeyRef, uint8_t *aBuffer, size_t aBufferLen, size_t *aKeyLen)	otError Export a key stored in PSA ITS.
otPlatCryptoHasKey(otCryptoKeyRef aKeyRef)	bool Check if the key ref passed has an associated key in PSA ITS.
otPlatCryptoHkdfDeinit(otCryptoContext *aContext)	otError Uninitialize the HKDF context.
otPlatCryptoHkdfExpand(otCryptoContext *aContext, const uint8_t *aInfo, uint16_t aInfoLength, uint8_t *aOutputKey, uint16_t aOutputKeyLength)	otError Perform HKDF Expand step.
otPlatCryptoHkdfExtract(otCryptoContext *aContext, const uint8_t *aSalt, uint16_t aSaltLength, const otCryptoKey *aInputKey)	otError Perform HKDF Extract step.
otPlatCryptoHkdfInit(otCryptoContext *aContext)	otError Initialise the HKDF context.
otPlatCryptoHmacSha256Deinit(otCryptoContext *aContext)	otError Uninitialize the HMAC operation.
otPlatCryptoHmacSha256Finish(otCryptoContext *aContext, uint8_t *aBuf, size_t aBufLength)	otError Complete the HMAC operation.
otPlatCryptoHmacSha256Init(otCryptoContext *aContext)	otError Initialize the HMAC operation.
otPlatCryptoHmacSha256Start(otCryptoContext *aContext, const otCryptoKey *aKey)	otError Start HMAC operation.
otPlatCryptoHmacSha256Update(otCryptoContext *aContext, const void *aBuf, uint16_t aBufLength)	otError Update the HMAC operation with new input.
otPlatCryptoImportKey(otCryptoKeyRef *aKeyRef, otCryptoKeyType aKeyType, otCryptoKeyAlgorithm aKeyAlgorithm, int aKeyUsage, otCryptoKeyStorage aKeyPersistence, const uint8_t *aKey, size_t aKeyLen)	otError Import a key into PSA ITS.
otPlatCryptoInit(void)	void Initialize the Crypto module.
otPlatCryptoRandomDeinit(void)	void Deinitialize cryptographically-secure pseudorandom number generator (CSPRNG).
otPlatCryptoRandomGet(uint8_t *aBuffer, uint16_t aSize)	otError Fills a given buffer with cryptographically secure random bytes.
otPlatCryptoRandomInit(void)	void Initialize cryptographically-secure pseudorandom number generator (CSPRNG).
otPlatCryptoSha256Deinit(otCryptoContext *aContext)	otError Uninitialize the SHA-256 operation.
otPlatCryptoSha256Finish(otCryptoContext *aContext, uint8_t *aHash, uint16_t aHashSize)	otError Finish SHA-256 operation.
otPlatCryptoSha256Init(otCryptoContext *aContext)	otError Initialise the SHA-256 operation.
otPlatCryptoSha256Start(otCryptoContext *aContext)	otError Start SHA-256 operation.
otPlatCryptoSha256Update(otCryptoContext *aContext, const void *aBuf, uint16_t aBufLength)	otError Update SHA-256 operation with new input.

Structs
otCryptoContext	This structure stores the context object for platform APIs.
otCryptoKey	This structure represents the Key Material required for Crypto operations.

Enumerations

Anonymous Enum 17

 Anonymous Enum 17

This enumeration defines the key usage flags.

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

otCryptoKeyAlgorithm

 otCryptoKeyAlgorithm

This enumeration defines the key algorithms.

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

otCryptoKeyStorage

 otCryptoKeyStorage

This enumeration defines the key storage types.

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

otCryptoKeyType

 otCryptoKeyType

This enumeration defines the key types.

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

Typedefs

otCryptoContext

struct otCryptoContext otCryptoContext

otCryptoKey

struct otCryptoKey otCryptoKey

otCryptoKeyRef

uint32_t otCryptoKeyRef

This datatype represents the key reference.

Functions

otPlatCryptoAesEncrypt

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

Encrypt the given data.

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

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

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

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

otPlatCryptoAesSetKey

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

Set the key for AES operation.

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

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

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

otPlatCryptoExportKey

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

Export a key stored in PSA ITS.

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

Details
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

otPlatCryptoHasKey

bool otPlatCryptoHasKey(
  otCryptoKeyRef aKeyRef
)

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

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

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

otPlatCryptoHkdfDeinit

otError otPlatCryptoHkdfDeinit(
  otCryptoContext *aContext
)

Uninitialize the HKDF context.

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

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

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

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

Details
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

otPlatCryptoHmacSha256Deinit

otError otPlatCryptoHmacSha256Deinit(
  otCryptoContext *aContext
)

Uninitialize the HMAC operation.

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

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

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

Details
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

otPlatCryptoHmacSha256Start

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

Start HMAC operation.

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

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

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.

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

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

otPlatCryptoInit

void otPlatCryptoInit(
  void
)

Initialize the Crypto module.

otPlatCryptoRandomDeinit

void otPlatCryptoRandomDeinit(
  void
)

Deinitialize cryptographically-secure pseudorandom number generator (CSPRNG).

otPlatCryptoRandomGet

otError otPlatCryptoRandomGet(
  uint8_t *aBuffer,
  uint16_t aSize
)

Fills a given buffer with cryptographically secure random bytes.

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

otPlatCryptoRandomInit

void otPlatCryptoRandomInit(
  void
)

Initialize cryptographically-secure pseudorandom number generator (CSPRNG).

otPlatCryptoSha256Deinit

otError otPlatCryptoSha256Deinit(
  otCryptoContext *aContext
)

Uninitialize the SHA-256 operation.

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

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

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

Details
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

otPlatCryptoSha256Start

otError otPlatCryptoSha256Start(
  otCryptoContext *aContext
)

Start SHA-256 operation.

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

Details
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

Resources

OpenThread API Reference topics originate from the source code, available on GitHub. For more information, or to contribute to our documentation, refer to Resources.