Crypto - Platform

This module includes the platform abstraction for Crypto.

Summary

Enumerations
Anonymous Enum 11{   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,   OT_CRYPTO_KEY_USAGE_VERIFY_HASH = 1 << 4 }	enum Defines the key usage flags.
otCryptoKeyAlgorithm{   OT_CRYPTO_KEY_ALG_VENDOR,   OT_CRYPTO_KEY_ALG_AES_ECB,   OT_CRYPTO_KEY_ALG_HMAC_SHA_256,   OT_CRYPTO_KEY_ALG_ECDSA }	enum Defines the key algorithms.
otCryptoKeyStorage{   OT_CRYPTO_KEY_STORAGE_VOLATILE,   OT_CRYPTO_KEY_STORAGE_PERSISTENT }	enum Defines the key storage types.
otCryptoKeyType{   OT_CRYPTO_KEY_TYPE_RAW,   OT_CRYPTO_KEY_TYPE_AES,   OT_CRYPTO_KEY_TYPE_HMAC,   OT_CRYPTO_KEY_TYPE_ECDSA }	enum Defines the key types.

Typedefs
otCryptoContext	typedef struct otCryptoContext
otCryptoKey	typedef struct otCryptoKey
otCryptoKeyRef	typedef uint32_t This datatype represents the key reference.
otPlatCryptoEcdsaKeyPair	typedef struct otPlatCryptoEcdsaKeyPair
otPlatCryptoEcdsaPublicKey	typedef struct otPlatCryptoEcdsaPublicKey
otPlatCryptoEcdsaSignature	typedef struct otPlatCryptoEcdsaSignature
otPlatCryptoSha256Hash	typedef struct otPlatCryptoSha256Hash Represents a SHA-256 hash.

Variables
OT_TOOL_PACKED_END	OT_TOOL_PACKED_BEGIN struct otPlatCryptoSha256Hash

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.
otPlatCryptoEcdsaExportPublicKey(otCryptoKeyRef aKeyRef, otPlatCryptoEcdsaPublicKey *aPublicKey)	otError Get the associated public key from the key reference passed.
otPlatCryptoEcdsaGenerateAndImportKey(otCryptoKeyRef aKeyRef)	otError Generate and import a new ECDSA key-pair at reference passed.
otPlatCryptoEcdsaGenerateKey(otPlatCryptoEcdsaKeyPair *aKeyPair)	otError Generate and populate the output buffer with a new ECDSA key-pair.
otPlatCryptoEcdsaGetPublicKey(const otPlatCryptoEcdsaKeyPair *aKeyPair, otPlatCryptoEcdsaPublicKey *aPublicKey)	otError Get the associated public key from the input context.
otPlatCryptoEcdsaSign(const otPlatCryptoEcdsaKeyPair *aKeyPair, const otPlatCryptoSha256Hash *aHash, otPlatCryptoEcdsaSignature *aSignature)	otError Calculate the ECDSA signature for a hashed message using the private key from the input context.
otPlatCryptoEcdsaSignUsingKeyRef(otCryptoKeyRef aKeyRef, const otPlatCryptoSha256Hash *aHash, otPlatCryptoEcdsaSignature *aSignature)	otError Calculate the ECDSA signature for a hashed message using the Key reference passed.
otPlatCryptoEcdsaVerify(const otPlatCryptoEcdsaPublicKey *aPublicKey, const otPlatCryptoSha256Hash *aHash, const otPlatCryptoEcdsaSignature *aSignature)	otError Use the key from the input context to verify the ECDSA signature of a hashed message.
otPlatCryptoEcdsaVerifyUsingKeyRef(otCryptoKeyRef aKeyRef, const otPlatCryptoSha256Hash *aHash, const otPlatCryptoEcdsaSignature *aSignature)	otError Use the keyref to verify the ECDSA signature of a hashed message.
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.
otPlatCryptoPbkdf2GenerateKey(const uint8_t *aPassword, uint16_t aPasswordLen, const uint8_t *aSalt, uint16_t aSaltLen, uint32_t aIterationCounter, uint16_t aKeyLen, uint8_t *aKey)	otError Perform PKCS#5 PBKDF2 using CMAC (AES-CMAC-PRF-128).
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.

Macros
OT_CRYPTO_ECDSA_MAX_DER_SIZE 125	Max buffer size (in bytes) for representing the EDCSA key-pair in DER format.
OT_CRYPTO_ECDSA_PUBLIC_KEY_SIZE 64	Buffer size (in bytes) for representing the EDCSA public key.
OT_CRYPTO_ECDSA_SIGNATURE_SIZE 64	Buffer size (in bytes) for representing the EDCSA signature.
OT_CRYPTO_PBDKF2_MAX_SALT_SIZE 30	Max PBKDF2 SALT length: salt prefix (6) + extended panid (8) + network name (16)
OT_CRYPTO_SHA256_HASH_SIZE 32	Length of SHA256 hash (in bytes).

Structs
otCryptoContext	Stores the context object for platform APIs.
otCryptoKey	Represents the Key Material required for Crypto operations.
otPlatCryptoEcdsaKeyPair	Represents an ECDSA key pair (public and private keys).
otPlatCryptoEcdsaPublicKey	Represents a ECDSA public key.
otPlatCryptoEcdsaSignature	Represents an ECDSA signature.
otPlatCryptoSha256Hash	Represents a SHA-256 hash.

Enumerations

Anonymous Enum 11

 Anonymous Enum 11

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: Sign Hash.
OT_CRYPTO_KEY_USAGE_VERIFY_HASH	Key Usage: Verify Hash.

otCryptoKeyAlgorithm

 otCryptoKeyAlgorithm

Defines the key algorithms.

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

otCryptoKeyStorage

 otCryptoKeyStorage

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

Defines the key types.

Properties
OT_CRYPTO_KEY_TYPE_AES	Key Type: AES.
OT_CRYPTO_KEY_TYPE_ECDSA	Key Type: ECDSA.
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.

otPlatCryptoEcdsaKeyPair

struct otPlatCryptoEcdsaKeyPair otPlatCryptoEcdsaKeyPair

otPlatCryptoEcdsaPublicKey

struct otPlatCryptoEcdsaPublicKey otPlatCryptoEcdsaPublicKey

otPlatCryptoEcdsaSignature

struct otPlatCryptoEcdsaSignature otPlatCryptoEcdsaSignature

otPlatCryptoSha256Hash

struct otPlatCryptoSha256Hash otPlatCryptoSha256Hash

Represents a SHA-256 hash.

Variables

OT_TOOL_PACKED_END

OT_TOOL_PACKED_BEGIN struct otPlatCryptoSha256Hash OT_TOOL_PACKED_END

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.

otPlatCryptoEcdsaExportPublicKey

otError otPlatCryptoEcdsaExportPublicKey(
  otCryptoKeyRef aKeyRef,
  otPlatCryptoEcdsaPublicKey *aPublicKey
)

Get the associated public key from the key reference passed.

The public key is stored differently depending on the crypto backend library being used (OPENTHREAD_CONFIG_CRYPTO_LIB).

This API must make sure to return the public key as a byte sequence representation of an uncompressed curve point (RFC 6605 - sec 4)

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

Details
Parameters	[in] aKeyRef Key Reference to the slot where the key-pair is stored. [out] aPublicKey A pointer to an ECDSA public key structure to store the public key.
Return Values	OT_ERROR_NONE Public key was retrieved successfully, and aBuffer is updated. OT_ERROR_PARSE The key-pair DER format could not be parsed (invalid format). OT_ERROR_INVALID_ARGS The aContext is NULL.

otPlatCryptoEcdsaGenerateAndImportKey

otError otPlatCryptoEcdsaGenerateAndImportKey(
  otCryptoKeyRef aKeyRef
)

Generate and import a new ECDSA key-pair at reference passed.

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

Details
Parameters	[in] aKeyRef Key Reference to the slot where the key-pair is stored.
Return Values	OT_ERROR_NONE A new key-pair was generated successfully. OT_ERROR_NO_BUFS Failed to allocate buffer for key generation. OT_ERROR_NOT_CAPABLE Feature not supported. OT_ERROR_FAILED Failed to generate key-pair.

otPlatCryptoEcdsaGenerateKey

otError otPlatCryptoEcdsaGenerateKey(
  otPlatCryptoEcdsaKeyPair *aKeyPair
)

Generate and populate the output buffer with a new ECDSA key-pair.

Details
Parameters	[out] aKeyPair A pointer to an ECDSA key-pair structure to store the generated key-pair.
Return Values	OT_ERROR_NONE A new key-pair was generated successfully. OT_ERROR_NO_BUFS Failed to allocate buffer for key generation. OT_ERROR_NOT_CAPABLE Feature not supported. OT_ERROR_FAILED Failed to generate key-pair.

otPlatCryptoEcdsaGetPublicKey

otError otPlatCryptoEcdsaGetPublicKey(
  const otPlatCryptoEcdsaKeyPair *aKeyPair,
  otPlatCryptoEcdsaPublicKey *aPublicKey
)

Get the associated public key from the input context.

Details
Parameters	[in] aKeyPair A pointer to an ECDSA key-pair structure where the key-pair is stored. [out] aPublicKey A pointer to an ECDSA public key structure to store the public key.
Return Values	OT_ERROR_NONE Public key was retrieved successfully, and aBuffer is updated. OT_ERROR_PARSE The key-pair DER format could not be parsed (invalid format). OT_ERROR_INVALID_ARGS The aContext is NULL.

otPlatCryptoEcdsaSign

otError otPlatCryptoEcdsaSign(
  const otPlatCryptoEcdsaKeyPair *aKeyPair,
  const otPlatCryptoSha256Hash *aHash,
  otPlatCryptoEcdsaSignature *aSignature
)

Calculate the ECDSA signature for a hashed message using the private key from the input context.

Uses the deterministic digital signature generation procedure from RFC 6979.

Details
Parameters	[in] aKeyPair A pointer to an ECDSA key-pair structure where the key-pair is stored. [in] aHash A pointer to a SHA-256 hash structure where the hash value for signature calculation is stored. [out] aSignature A pointer to an ECDSA signature structure to output the calculated signature.
Return Values	OT_ERROR_NONE The signature was calculated successfully, aSignature was updated. OT_ERROR_PARSE The key-pair DER format could not be parsed (invalid format). OT_ERROR_NO_BUFS Failed to allocate buffer for signature calculation. OT_ERROR_INVALID_ARGS The aContext is NULL.

otPlatCryptoEcdsaSignUsingKeyRef

otError otPlatCryptoEcdsaSignUsingKeyRef(
  otCryptoKeyRef aKeyRef,
  const otPlatCryptoSha256Hash *aHash,
  otPlatCryptoEcdsaSignature *aSignature
)

Calculate the ECDSA signature for a hashed message using the Key reference passed.

Uses the deterministic digital signature generation procedure from RFC 6979.

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

Details
Parameters	[in] aKeyRef Key Reference to the slot where the key-pair is stored. [in] aHash A pointer to a SHA-256 hash structure where the hash value for signature calculation is stored. [out] aSignature A pointer to an ECDSA signature structure to output the calculated signature.
Return Values	OT_ERROR_NONE The signature was calculated successfully, aSignature was updated. OT_ERROR_PARSE The key-pair DER format could not be parsed (invalid format). OT_ERROR_NO_BUFS Failed to allocate buffer for signature calculation. OT_ERROR_INVALID_ARGS The aContext is NULL.

otPlatCryptoEcdsaVerify

otError otPlatCryptoEcdsaVerify(
  const otPlatCryptoEcdsaPublicKey *aPublicKey,
  const otPlatCryptoSha256Hash *aHash,
  const otPlatCryptoEcdsaSignature *aSignature
)

Use the key from the input context to verify the ECDSA signature of a hashed message.

Details
Parameters	[in] aPublicKey A pointer to an ECDSA public key structure where the public key for signature verification is stored. [in] aHash A pointer to a SHA-256 hash structure where the hash value for signature verification is stored. [in] aSignature A pointer to an ECDSA signature structure where the signature value to be verified is stored.
Return Values	OT_ERROR_NONE The signature was verified successfully. OT_ERROR_SECURITY The signature is invalid. OT_ERROR_INVALID_ARGS The key or hash is invalid. OT_ERROR_NO_BUFS Failed to allocate buffer for signature verification.

otPlatCryptoEcdsaVerifyUsingKeyRef

otError otPlatCryptoEcdsaVerifyUsingKeyRef(
  otCryptoKeyRef aKeyRef,
  const otPlatCryptoSha256Hash *aHash,
  const otPlatCryptoEcdsaSignature *aSignature
)

Use the keyref to verify the ECDSA signature of a hashed message.

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

Details
Parameters	[in] aKeyRef Key Reference to the slot where the key-pair is stored. [in] aHash A pointer to a SHA-256 hash structure where the hash value for signature verification is stored. [in] aSignature A pointer to an ECDSA signature structure where the signature value to be verified is stored.
Return Values	OT_ERROR_NONE The signature was verified successfully. OT_ERROR_SECURITY The signature is invalid. OT_ERROR_INVALID_ARGS The key or hash is invalid. OT_ERROR_NO_BUFS Failed to allocate buffer for signature verification.

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

otPlatCryptoPbkdf2GenerateKey

otError otPlatCryptoPbkdf2GenerateKey(
  const uint8_t *aPassword,
  uint16_t aPasswordLen,
  const uint8_t *aSalt,
  uint16_t aSaltLen,
  uint32_t aIterationCounter,
  uint16_t aKeyLen,
  uint8_t *aKey
)

Perform PKCS#5 PBKDF2 using CMAC (AES-CMAC-PRF-128).

Details
Parameters	[in] aPassword Password to use when generating key. [in] aPasswordLen Length of password. [in] aSalt Salt to use when generating key. [in] aSaltLen Length of salt. [in] aIterationCounter Iteration count. [in] aKeyLen Length of generated key in bytes. [out] aKey A pointer to the generated key.
Return Values	OT_ERROR_NONE A new key-pair was generated successfully. OT_ERROR_NO_BUFS Failed to allocate buffer for key generation. OT_ERROR_NOT_CAPABLE Feature not supported. OT_ERROR_FAILED Failed to generate key.

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

Macros

OT_CRYPTO_ECDSA_MAX_DER_SIZE

 OT_CRYPTO_ECDSA_MAX_DER_SIZE 125

Max buffer size (in bytes) for representing the EDCSA key-pair in DER format.

OT_CRYPTO_ECDSA_PUBLIC_KEY_SIZE

 OT_CRYPTO_ECDSA_PUBLIC_KEY_SIZE 64

Buffer size (in bytes) for representing the EDCSA public key.

OT_CRYPTO_ECDSA_SIGNATURE_SIZE

 OT_CRYPTO_ECDSA_SIGNATURE_SIZE 64

Buffer size (in bytes) for representing the EDCSA signature.

OT_CRYPTO_PBDKF2_MAX_SALT_SIZE

 OT_CRYPTO_PBDKF2_MAX_SALT_SIZE 30

Max PBKDF2 SALT length: salt prefix (6) + extended panid (8) + network name (16)

OT_CRYPTO_SHA256_HASH_SIZE

 OT_CRYPTO_SHA256_HASH_SIZE 32

Length of SHA256 hash (in bytes).

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.