Modules#

otCryptoKey

otCryptoContext

otPlatCryptoSha256Hash

otPlatCryptoEcdsaKeyPair

otPlatCryptoEcdsaPublicKey

otPlatCryptoEcdsaSignature

Crypto - Platform#

This module includes the platform abstraction for Crypto.

Enumerations#

enum
OT_CRYPTO_KEY_TYPE_RAW
OT_CRYPTO_KEY_TYPE_AES
OT_CRYPTO_KEY_TYPE_HMAC
OT_CRYPTO_KEY_TYPE_ECDSA
}

This enumeration defines the key types.

enum
OT_CRYPTO_KEY_ALG_VENDOR
OT_CRYPTO_KEY_ALG_AES_ECB
OT_CRYPTO_KEY_ALG_HMAC_SHA_256
OT_CRYPTO_KEY_ALG_ECDSA
}

This enumeration defines the key algorithms.

enum
@12 {
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
}

This enumeration defines the key usage flags.

enum
OT_CRYPTO_KEY_STORAGE_VOLATILE
OT_CRYPTO_KEY_STORAGE_PERSISTENT
}

This enumeration defines the key storage types.

Typedefs#

typedef uint32_t

This datatype represents the key reference.

typedef struct otCryptoKey
typedef struct otPlatCryptoSha256Hash

This structure represents a SHA-256 hash.

Functions#

void

Initialize the Crypto module.

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

Import a key into PSA ITS.

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

Export a key stored in PSA ITS.

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.

otPlatCryptoHmacSha256Init(otCryptoContext *aContext)

Initialize the HMAC operation.

otPlatCryptoHmacSha256Deinit(otCryptoContext *aContext)

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

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

Complete the HMAC operation.

otPlatCryptoAesInit(otCryptoContext *aContext)

Initialise the AES operation.

otPlatCryptoAesSetKey(otCryptoContext *aContext, const otCryptoKey *aKey)

Set the key for AES operation.

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

Encrypt the given data.

otPlatCryptoAesFree(otCryptoContext *aContext)

Free the AES context.

otPlatCryptoHkdfInit(otCryptoContext *aContext)

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

otPlatCryptoHkdfDeinit(otCryptoContext *aContext)

Uninitialize the HKDF context.

otPlatCryptoSha256Init(otCryptoContext *aContext)

Initialise the SHA-256 operation.

otPlatCryptoSha256Deinit(otCryptoContext *aContext)

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

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

Finish SHA-256 operation.

void

Initialize cryptographically-secure pseudorandom number generator (CSPRNG).

void

Deinitialize cryptographically-secure pseudorandom number generator (CSPRNG).

otPlatCryptoRandomGet(uint8_t *aBuffer, uint16_t aSize)

Fills a given buffer with cryptographically secure random bytes.

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.

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.

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

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

otPlatCryptoEcdsaExportPublicKey(otCryptoKeyRef aKeyRef, otPlatCryptoEcdsaPublicKey *aPublicKey)

Get the associated public key from the key reference passed.

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

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

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

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

Macros#

#define

Length of SHA256 hash (in bytes).

#define

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

#define

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

#define

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

#define

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

Enumeration Documentation#

otCryptoKeyType#

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.

OT_CRYPTO_KEY_TYPE_ECDSA

Key Type: ECDSA.


Definition at line 61 of file include/openthread/platform/crypto.h

otCryptoKeyAlgorithm#

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.

OT_CRYPTO_KEY_ALG_ECDSA

Key Algorithm: ECDSA.


Definition at line 73 of file include/openthread/platform/crypto.h

@12#

@12

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: Sign Hash.

OT_CRYPTO_KEY_USAGE_VERIFY_HASH

Key Usage: Verify Hash.


Definition at line 85 of file include/openthread/platform/crypto.h

otCryptoKeyStorage#

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.


Definition at line 99 of file include/openthread/platform/crypto.h

Typedef Documentation#

otCryptoKeyRef#

typedef uint32_t otCryptoKeyRef

This datatype represents the key reference.


Definition at line 109 of file include/openthread/platform/crypto.h

otCryptoKey#

typedef struct otCryptoKey otCryptoKey

Definition at line 122 of file include/openthread/platform/crypto.h

otCryptoContext#

typedef struct otCryptoContext otCryptoContext

Definition at line 134 of file include/openthread/platform/crypto.h

otPlatCryptoSha256Hash#

typedef struct otPlatCryptoSha256Hash otPlatCryptoSha256Hash

This structure represents a SHA-256 hash.


Definition at line 158 of file include/openthread/platform/crypto.h

otPlatCryptoEcdsaKeyPair#

typedef struct otPlatCryptoEcdsaKeyPair otPlatCryptoEcdsaKeyPair

Definition at line 178 of file include/openthread/platform/crypto.h

otPlatCryptoEcdsaPublicKey#

typedef struct otPlatCryptoEcdsaPublicKey otPlatCryptoEcdsaPublicKey

Definition at line 200 of file include/openthread/platform/crypto.h

otPlatCryptoEcdsaSignature#

typedef struct otPlatCryptoEcdsaSignature otPlatCryptoEcdsaSignature

Definition at line 223 of file include/openthread/platform/crypto.h

Variable Documentation#

OT_TOOL_PACKED_END#

OT_TOOL_PACKED_BEGIN struct otPlatCryptoEcdsaSignature OT_TOOL_PACKED_END

Definition at line 152 of file include/openthread/platform/crypto.h

Function Documentation#

otPlatCryptoInit#

void otPlatCryptoInit (void)

Initialize the Crypto module.

Parameters
N/A

Definition at line 235 of file include/openthread/platform/crypto.h

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
[inout]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.

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.


Definition at line 261 of file include/openthread/platform/crypto.h

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.

Note

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


Definition at line 284 of file include/openthread/platform/crypto.h

otPlatCryptoDestroyKey#

otError otPlatCryptoDestroyKey (otCryptoKeyRef aKeyRef)

Destroy a key stored in PSA ITS.

Parameters
[in]aKeyRef

The key ref to be destroyed

Note

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


Definition at line 297 of file include/openthread/platform/crypto.h

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.

Note

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


Definition at line 310 of file include/openthread/platform/crypto.h

otPlatCryptoHmacSha256Init#

otError otPlatCryptoHmacSha256Init (otCryptoContext *aContext)

Initialize the HMAC operation.

Parameters
[in]aContext

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


Definition at line 325 of file include/openthread/platform/crypto.h

otPlatCryptoHmacSha256Deinit#

otError otPlatCryptoHmacSha256Deinit (otCryptoContext *aContext)

Uninitialize the HMAC operation.

Parameters
[in]aContext

Context for HMAC operation.


Definition at line 337 of file include/openthread/platform/crypto.h

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


Definition at line 350 of file include/openthread/platform/crypto.h

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.


Definition at line 364 of file include/openthread/platform/crypto.h

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.


Definition at line 378 of file include/openthread/platform/crypto.h

otPlatCryptoAesInit#

otError otPlatCryptoAesInit (otCryptoContext *aContext)

Initialise the AES operation.

Parameters
[in]aContext

Context for AES operation.

Note

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


Definition at line 394 of file include/openthread/platform/crypto.h

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.


Definition at line 407 of file include/openthread/platform/crypto.h

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.


Definition at line 421 of file include/openthread/platform/crypto.h

otPlatCryptoAesFree#

otError otPlatCryptoAesFree (otCryptoContext *aContext)

Free the AES context.

Parameters
[in]aContext

Context for AES operation.


Definition at line 433 of file include/openthread/platform/crypto.h

otPlatCryptoHkdfInit#

otError otPlatCryptoHkdfInit (otCryptoContext *aContext)

Initialise the HKDF context.

Parameters
[in]aContext

Context for HKDF operation.

Note

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


Definition at line 448 of file include/openthread/platform/crypto.h

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.


Definition at line 464 of file include/openthread/platform/crypto.h

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.


Definition at line 482 of file include/openthread/platform/crypto.h

otPlatCryptoHkdfDeinit#

otError otPlatCryptoHkdfDeinit (otCryptoContext *aContext)

Uninitialize the HKDF context.

Parameters
[in]aContext

Context for HKDF operation.


Definition at line 497 of file include/openthread/platform/crypto.h

otPlatCryptoSha256Init#

otError otPlatCryptoSha256Init (otCryptoContext *aContext)

Initialise the SHA-256 operation.

Parameters
[in]aContext

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


Definition at line 512 of file include/openthread/platform/crypto.h

otPlatCryptoSha256Deinit#

otError otPlatCryptoSha256Deinit (otCryptoContext *aContext)

Uninitialize the SHA-256 operation.

Parameters
[in]aContext

Context for SHA-256 operation.


Definition at line 524 of file include/openthread/platform/crypto.h

otPlatCryptoSha256Start#

otError otPlatCryptoSha256Start (otCryptoContext *aContext)

Start SHA-256 operation.

Parameters
[in]aContext

Context for SHA-256 operation.


Definition at line 536 of file include/openthread/platform/crypto.h

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.


Definition at line 550 of file include/openthread/platform/crypto.h

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.


Definition at line 564 of file include/openthread/platform/crypto.h

otPlatCryptoRandomInit#

void otPlatCryptoRandomInit (void)

Initialize cryptographically-secure pseudorandom number generator (CSPRNG).

Parameters
N/A

Definition at line 570 of file include/openthread/platform/crypto.h

otPlatCryptoRandomDeinit#

void otPlatCryptoRandomDeinit (void)

Deinitialize cryptographically-secure pseudorandom number generator (CSPRNG).

Parameters
N/A

Definition at line 576 of file include/openthread/platform/crypto.h

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


Definition at line 588 of file include/openthread/platform/crypto.h

otPlatCryptoEcdsaGenerateKey#

otError otPlatCryptoEcdsaGenerateKey (otPlatCryptoEcdsaKeyPair *aKeyPair)