Crypto - Platform

This module includes the platform abstraction for Crypto.

Summary

Enumerations
anonymous 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
} 		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
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)
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.
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.
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.

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

 anonymous enum

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.

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.

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

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.