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
otCryptoKey typedef
struct otCryptoKey
otCryptoKeyRef typedef
uint32_t
This datatype represents the key reference.
otPlatCryptoEcdsaKeyPair typedef
otPlatCryptoEcdsaPublicKey typedef
otPlatCryptoEcdsaSignature typedef
otPlatCryptoSha256Hash typedef
Represents a SHA-256 hash.

Variables
OT_TOOL_PACKED_END

Functions
otPlatCryptoAesEncrypt(otCryptoContext *aContext, const uint8_t *aInput, uint8_t *aOutput)
Encrypt the given data.
otPlatCryptoAesFree(otCryptoContext *aContext)
Free the AES context.
otPlatCryptoAesInit(otCryptoContext *aContext)
Initialise the AES operation.
otPlatCryptoAesSetKey(otCryptoContext *aContext, const otCryptoKey *aKey)
Set the key for AES operation.
otPlatCryptoDestroyKey(otCryptoKeyRef aKeyRef)
Destroy a key stored in PSA ITS.
otPlatCryptoEcdsaExportPublicKey(otCryptoKeyRef aKeyRef, otPlatCryptoEcdsaPublicKey *aPublicKey)
Get the associated public key from the key reference passed.
otPlatCryptoEcdsaGenerateAndImportKey(otCryptoKeyRef aKeyRef)
Generate and import a new ECDSA key-pair at reference passed.
otPlatCryptoEcdsaGenerateKey(otPlatCryptoEcdsaKeyPair *aKeyPair)
Generate and populate the output buffer with a new ECDSA key-pair.
otPlatCryptoEcdsaGetPublicKey(const otPlatCryptoEcdsaKeyPair *aKeyPair, otPlatCryptoEcdsaPublicKey *aPublicKey)
Get the associated public key from the input context.
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.
otPlatCryptoEcdsaSignUsingKeyRef(otCryptoKeyRef aKeyRef, const otPlatCryptoSha256Hash *aHash, otPlatCryptoEcdsaSignature *aSignature)
Calculate the ECDSA signature for a hashed message using the Key reference passed.
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.
otPlatCryptoEcdsaVerifyUsingKeyRef(otCryptoKeyRef aKeyRef, const otPlatCryptoSha256Hash *aHash, const otPlatCryptoEcdsaSignature *aSignature)
Use the keyref to verify the ECDSA signature of a hashed message.
otPlatCryptoExportKey(otCryptoKeyRef aKeyRef, uint8_t *aBuffer, size_t aBufferLen, size_t *aKeyLen)
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)
Uninitialize the HKDF context.
otPlatCryptoHkdfExpand(otCryptoContext *aContext, const uint8_t *aInfo, uint16_t aInfoLength, uint8_t *aOutputKey, uint16_t aOutputKeyLength)
Perform HKDF Expand step.
otPlatCryptoHkdfExtract(otCryptoContext *aContext, const uint8_t *aSalt, uint16_t aSaltLength, const otCryptoKey *aInputKey)
Perform HKDF Extract step.
otPlatCryptoHkdfInit(otCryptoContext *aContext)
Initialise the HKDF context.
otPlatCryptoHmacSha256Deinit(otCryptoContext *aContext)
Uninitialize the HMAC operation.
otPlatCryptoHmacSha256Finish(otCryptoContext *aContext, uint8_t *aBuf, size_t aBufLength)
Complete the HMAC operation.
otPlatCryptoHmacSha256Init(otCryptoContext *aContext)
Initialize the HMAC operation.
otPlatCryptoHmacSha256Start(otCryptoContext *aContext, const otCryptoKey *aKey)
Start HMAC operation.
otPlatCryptoHmacSha256Update(otCryptoContext *aContext, const void *aBuf, uint16_t aBufLength)
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)
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)
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)
Fills a given buffer with cryptographically secure random bytes.
otPlatCryptoRandomInit(void)
void
Initialize cryptographically-secure pseudorandom number generator (CSPRNG).
otPlatCryptoSha256Deinit(otCryptoContext *aContext)
Uninitialize the SHA-256 operation.
otPlatCryptoSha256Finish(otCryptoContext *aContext, uint8_t *aHash, uint16_t aHashSize)
Finish SHA-256 operation.
otPlatCryptoSha256Init(otCryptoContext *aContext)
Initialise the SHA-256 operation.
otPlatCryptoSha256Start(otCryptoContext *aContext)
Start SHA-256 operation.
otPlatCryptoSha256Update(otCryptoContext *aContext, const void *aBuf, uint16_t aBufLength)
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.

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.

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)

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.