Key derivation#

API for key derivation and key agreement (ECDH, EC J-PAKE, HKDF, PBKDF2).

Contains key derivation functions (HKDF, PBKDF2) and key agreement functions (ECDH, ECJPAKE).

Modules#

sl_se_ecjpake_context_t

Enumerations#

enum
SL_SE_ECJPAKE_CLIENT = 0
SL_SE_ECJPAKE_SERVER
}

Roles in the EC J-PAKE exchange.

Typedefs#

Typedef sl_se_pbkdf2_prf_type_t to sl_se_hash_type_t in order to maintain backward compatibility.

Functions#

sl_status_t
sl_se_ecdh_compute_shared_secret(sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *key_in_priv, const sl_se_key_descriptor_t *key_in_pub, const sl_se_key_descriptor_t *key_out)

This function computes the shared secret with Elliptic Curve Diffie Hellman (ECDH) algorithm.

sl_status_t
sl_se_ecjpake_check(const sl_se_ecjpake_context_t *ctx)

Check if an EC J-PAKE context is ready for use.

sl_status_t
sl_se_ecjpake_derive_secret(sl_se_ecjpake_context_t *ctx, unsigned char *buf, size_t len, size_t *olen)

Derive the shared secret (TLS: Pre-Master Secret).

sl_status_t
sl_se_ecjpake_free(sl_se_ecjpake_context_t *ctx)

This clears an EC J-PAKE context and frees any embedded data structure.

sl_status_t
sl_se_ecjpake_init(sl_se_ecjpake_context_t *ctx, sl_se_command_context_t *cmd_ctx)

Initialize an EC J-PAKE context.

sl_status_t
sl_se_ecjpake_read_round_one(sl_se_ecjpake_context_t *ctx, const unsigned char *buf, size_t len)

Read and process the first round message (TLS: contents of the Client/ServerHello extension, excluding extension type and length bytes).

sl_status_t
sl_se_ecjpake_read_round_two(sl_se_ecjpake_context_t *ctx, const unsigned char *buf, size_t len)

Read and process the second round message (TLS: contents of the Client/ServerKeyExchange).

sl_status_t
sl_se_ecjpake_setup(sl_se_ecjpake_context_t *ctx, sl_se_ecjpake_role_t role, sl_se_hash_type_t hash, uint32_t curve, const unsigned char *secret, size_t len)

Set up an EC J-PAKE context for use.

sl_status_t
sl_se_ecjpake_write_round_one(sl_se_ecjpake_context_t *ctx, unsigned char *buf, size_t len, size_t *olen)

Generate and write the first round message (TLS: contents of the Client/ServerHello extension, excluding extension type and length bytes).

sl_status_t
sl_se_ecjpake_write_round_two(sl_se_ecjpake_context_t *ctx, unsigned char *buf, size_t len, size_t *olen)

Generate and write the second round message (TLS: contents of the Client/ServerKeyExchange).

sl_status_t
sl_se_derive_key_hkdf(sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *in_key, sl_se_hash_type_t hash, const unsigned char *salt, size_t salt_len, const unsigned char *info, size_t info_len, sl_se_key_descriptor_t *out_key)

Derive a pseudorandom key from the input key material using HKDF.

sl_status_t
sl_se_derive_key_pbkdf2(sl_se_command_context_t *cmd_ctx, const sl_se_key_descriptor_t *in_key, sl_se_pbkdf2_prf_type_t prf, const unsigned char *salt, size_t salt_len, uint32_t iterations, sl_se_key_descriptor_t *out_key)

Derive a pseudorandom key from the input key material using PBKDF2.

Macros#

#define
SL_SE_PRF_AES_CMAC_128 SL_SE_HASH_NONE

Defines mapping the PBKDF2 PRFs to corresponding sl_se_hash_type_t values.

#define
SL_SE_PRF_HMAC_SHA1 SL_SE_HASH_SHA1

HMAC-SHA-1.

#define
SL_SE_PRF_HMAC_SHA224 SL_SE_HASH_SHA224

HMAC-SHA-224.

#define
SL_SE_PRF_HMAC_SHA256 SL_SE_HASH_SHA256

HMAC-SHA-256.

#define
SL_SE_PRF_HMAC_SHA384 SL_SE_HASH_SHA384

HMAC-SHA-384.

#define
SL_SE_PRF_HMAC_SHA512 SL_SE_HASH_SHA512

HMAC-SHA-512.

Enumeration Documentation#

sl_se_ecjpake_role_t#

sl_se_ecjpake_role_t

Roles in the EC J-PAKE exchange.

Enumerator
SL_SE_ECJPAKE_CLIENT

Client.

SL_SE_ECJPAKE_SERVER

Server.


Definition at line 444 of file platform/security/sl_component/se_manager/inc/sl_se_manager_types.h

Typedef Documentation#

sl_se_pbkdf2_prf_type_t#

typedef sl_se_hash_type_t sl_se_pbkdf2_prf_type_t

Typedef sl_se_pbkdf2_prf_type_t to sl_se_hash_type_t in order to maintain backward compatibility.

Defines for mapping the PRF identifiers to the underlying hash enum values exists in sl_se_manager_defines.h.


Definition at line 480 of file platform/security/sl_component/se_manager/inc/sl_se_manager_types.h

Function Documentation#

sl_se_ecdh_compute_shared_secret#

sl_status_t sl_se_ecdh_compute_shared_secret (sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * key_in_priv, const sl_se_key_descriptor_t * key_in_pub, const sl_se_key_descriptor_t * key_out)

This function computes the shared secret with Elliptic Curve Diffie Hellman (ECDH) algorithm.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]key_in_priv

Our private key.

[in]key_in_pub

Their public key.

[out]key_out

Shared secret key. Montgomery curve result is one single coordinate. Other curve types result in one pair of coordinate.

Performs Elliptic Curve Diffie Hellman shared secret computation.

Note

  • P-521 Elliptic Curve based Elliptic Curve Diffie Hellman (ECDH) expects a 544 bits (68 bytes) buffer for storing private keys, and a 1088 bits (136 bytes) buffer for storing public keys and shared secret. The first 23 bits of d, Qx, Qy and shared secret are padding bits to comply word-aligned addressing. The padding bits are ignored in the computation.

This function does not implement the value-checking of the shared secret as described in RFC7748 when using Montgomery keys.

In case of using custom domain curves, key_in_priv defines the domain parameters. Moreover, key_in_pub should always contain a public key. If key_in_pub contains a private key, sl_se_export_public_key() can be used to export the public key.

Returns

  • SL_STATUS_INVALID_KEY if key_in_pub does not contain a public key when using custom domain curves, otherwise an appropriate error code (sl_status.h).


Definition at line 112 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_derivation.h

sl_se_ecjpake_check#

sl_status_t sl_se_ecjpake_check (const sl_se_ecjpake_context_t * ctx)

Check if an EC J-PAKE context is ready for use.

Parameters
[in]ctx

The EC J-PAKE context to check. This must be initialized.

Returns

  • SL_STATUS_OK when the command was executed successfully, otherwise an appropriate error code (sl_status.h).


Definition at line 131 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_derivation.h

sl_se_ecjpake_derive_secret#

sl_status_t sl_se_ecjpake_derive_secret (sl_se_ecjpake_context_t * ctx, unsigned char * buf, size_t len, size_t * olen)

Derive the shared secret (TLS: Pre-Master Secret).

Parameters
[in]ctx

The EC J-PAKE context to use. This must be initialized, set up and have performed both round one and two.

[out]buf

The buffer to write the derived secret to. This must be a writable buffer of length len bytes.

[in]len

The length of buf in bytes.

[out]olen

The address at which to store the total number of bytes written to buf. This must not be NULL.

Returns

  • SL_STATUS_OK when the command was executed successfully, otherwise an appropriate error code (sl_status.h).


Definition at line 156 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_derivation.h

sl_se_ecjpake_free#

sl_status_t sl_se_ecjpake_free (sl_se_ecjpake_context_t * ctx)

This clears an EC J-PAKE context and frees any embedded data structure.

Parameters
[in]ctx

The EC J-PAKE context to free. This may be NULL, in which case this function does nothing. If it is not NULL, it must point to an initialized EC J-PAKE context.

Returns

  • SL_STATUS_OK when the command was executed successfully, otherwise an appropriate error code (sl_status.h).


Definition at line 174 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_derivation.h

sl_se_ecjpake_init#

sl_status_t sl_se_ecjpake_init (sl_se_ecjpake_context_t * ctx, sl_se_command_context_t * cmd_ctx)

Initialize an EC J-PAKE context.

Parameters
[in]ctx

The EC J-PAKE context to initialize. This must not be NULL.

[in]cmd_ctx

Pointer to an SE command context object.

Returns

  • SL_STATUS_OK when the command was executed successfully, otherwise an appropriate error code (sl_status.h).


Definition at line 190 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_derivation.h

sl_se_ecjpake_read_round_one#

sl_status_t sl_se_ecjpake_read_round_one (sl_se_ecjpake_context_t * ctx, const unsigned char * buf, size_t len)

Read and process the first round message (TLS: contents of the Client/ServerHello extension, excluding extension type and length bytes).

Parameters
[in]ctx

The EC J-PAKE context to use. This must be initialized and set up.

[in]buf

The buffer holding the first round message. This must be a readable buffer of length len bytes.

[in]len

The length in bytes of buf.

Returns

  • SL_STATUS_OK when the command was executed successfully, otherwise an appropriate error code (sl_status.h).


Definition at line 212 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_derivation.h

sl_se_ecjpake_read_round_two#

sl_status_t sl_se_ecjpake_read_round_two (sl_se_ecjpake_context_t * ctx, const unsigned char * buf, size_t len)

Read and process the second round message (TLS: contents of the Client/ServerKeyExchange).

Parameters
[in]ctx

The EC J-PAKE context to use. This must be initialized and set up and already have performed round one.

[in]buf

The buffer holding the second round message. This must be a readable buffer of length len bytes.

[in]len

The length in bytes of buf.

Returns

  • SL_STATUS_OK when the command was executed successfully, otherwise an appropriate error code (sl_status.h).


Definition at line 236 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_derivation.h

sl_se_ecjpake_setup#

sl_status_t sl_se_ecjpake_setup (sl_se_ecjpake_context_t * ctx, sl_se_ecjpake_role_t role, sl_se_hash_type_t hash, uint32_t curve, const unsigned char * secret, size_t len)

Set up an EC J-PAKE context for use.

Parameters
[in]ctx

The EC J-PAKE context to set up. This must be initialized.

[in]role

The role of the caller. This must be either SL_SE_ECJPAKE_CLIENT or SL_SE_ECJPAKE_SERVER.

[in]hash

The identifier of the hash function to use, for example SL_SE_HASH_SHA256.

[in]curve

The identifier of the elliptic curve to use, for example SL_SE_KEY_TYPE_ECC_P256.

[in]secret

The pre-shared secret (passphrase). This must be a readable buffer of length len bytes. It need only be valid for the duration of this call.

[in]len

The length of the pre-shared secret secret.

Note

Returns

  • SL_STATUS_OK when the command was executed successfully, otherwise an appropriate error code (sl_status.h).


Definition at line 274 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_derivation.h

sl_se_ecjpake_write_round_one#

sl_status_t sl_se_ecjpake_write_round_one (sl_se_ecjpake_context_t * ctx, unsigned char * buf, size_t len, size_t * olen)

Generate and write the first round message (TLS: contents of the Client/ServerHello extension, excluding extension type and length bytes).

Parameters
[in]ctx

The EC J-PAKE context to use. This must be initialized and set up.

[out]buf

The buffer to write the contents to. This must be a writable buffer of length len bytes.

[in]len

The length of buf in bytes.

[out]olen

The address at which to store the total number of bytes written to buf. This must not be NULL.

Returns

  • SL_STATUS_OK when the command was executed successfully, otherwise an appropriate error code (sl_status.h).


Definition at line 304 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_derivation.h

sl_se_ecjpake_write_round_two#

sl_status_t sl_se_ecjpake_write_round_two (sl_se_ecjpake_context_t * ctx, unsigned char * buf, size_t len, size_t * olen)

Generate and write the second round message (TLS: contents of the Client/ServerKeyExchange).

Parameters
[in]ctx

The EC J-PAKE context to use. This must be initialized, set up, and already have performed round one.

[out]buf

The buffer to write the round two contents to. This must be a writable buffer of length len bytes.

[in]len

The size of buf in bytes.

[out]olen

The address at which to store the total number of bytes written to buf. This must not be NULL.

Returns

  • SL_STATUS_OK when the command was executed successfully, otherwise an appropriate error code (sl_status.h).


Definition at line 333 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_derivation.h

sl_se_derive_key_hkdf#

sl_status_t sl_se_derive_key_hkdf (sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * in_key, sl_se_hash_type_t hash, const unsigned char * salt, size_t salt_len, const unsigned char * info, size_t info_len, sl_se_key_descriptor_t * out_key)

Derive a pseudorandom key from the input key material using HKDF.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]in_key

Pointer to the input key material.

[in]hash

Which hashing algorithm to use.

[in]salt

An optional salt value (a non-secret random value).

[in]salt_len

The length of the salt.

[in]info

An optional context and application specific information string.

[in]info_len

The length of info.

[inout]out_key

Pointer to the generated key material. The length member of out_key is used to request a given length of the generated key.

Returns

  • SL_STATUS_OK if the signature is successfully verified, otherwise an appropriate error code (sl_status.h).


Definition at line 375 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_derivation.h

sl_se_derive_key_pbkdf2#

sl_status_t sl_se_derive_key_pbkdf2 (sl_se_command_context_t * cmd_ctx, const sl_se_key_descriptor_t * in_key, sl_se_pbkdf2_prf_type_t prf, const unsigned char * salt, size_t salt_len, uint32_t iterations, sl_se_key_descriptor_t * out_key)

Derive a pseudorandom key from the input key material using PBKDF2.

Parameters
[in]cmd_ctx

Pointer to an SE command context object.

[in]in_key

Pointer to the input key material.

[in]prf

The underlying psuedorandom function (PRF) to use in the algorithm. The most common choice of HMAC-SHA-{1, 224, 256, 384, 512} is supported on all Series-2 devices (with Vault High Security). Newer chips, EFR32xG23 and later, also support usage of AES-CMAC-PRF-128.

[in]salt

An optional salt value (a non-secret random value).

[in]salt_len

The length of the salt.

[in]iterations

The number of iterations to use. Up to 16384 iterations is supported.

[inout]out_key

Pointer to the generated key material. The length member of out_key is used to request a given length of the generated key.

Returns

  • SL_STATUS_OK if the signature is successfully verified, otherwise an appropriate error code (sl_status.h).


Definition at line 417 of file platform/security/sl_component/se_manager/inc/sl_se_manager_key_derivation.h

Macro Definition Documentation#

SL_SE_PRF_AES_CMAC_128#

#define SL_SE_PRF_AES_CMAC_128
Value:
SL_SE_HASH_NONE

Defines mapping the PBKDF2 PRFs to corresponding sl_se_hash_type_t values.

CMAC-AES-128


Definition at line 241 of file platform/security/sl_component/se_manager/inc/sl_se_manager_defines.h

SL_SE_PRF_HMAC_SHA1#

#define SL_SE_PRF_HMAC_SHA1
Value:
SL_SE_HASH_SHA1

HMAC-SHA-1.


Definition at line 242 of file platform/security/sl_component/se_manager/inc/sl_se_manager_defines.h

SL_SE_PRF_HMAC_SHA224#

#define SL_SE_PRF_HMAC_SHA224
Value:
SL_SE_HASH_SHA224

HMAC-SHA-224.


Definition at line 243 of file platform/security/sl_component/se_manager/inc/sl_se_manager_defines.h

SL_SE_PRF_HMAC_SHA256#

#define SL_SE_PRF_HMAC_SHA256
Value:
SL_SE_HASH_SHA256

HMAC-SHA-256.


Definition at line 244 of file platform/security/sl_component/se_manager/inc/sl_se_manager_defines.h

SL_SE_PRF_HMAC_SHA384#

#define SL_SE_PRF_HMAC_SHA384
Value:
SL_SE_HASH_SHA384

HMAC-SHA-384.


Definition at line 245 of file platform/security/sl_component/se_manager/inc/sl_se_manager_defines.h

SL_SE_PRF_HMAC_SHA512#

#define SL_SE_PRF_HMAC_SHA512
Value:
SL_SE_HASH_SHA512

HMAC-SHA-512.


Definition at line 246 of file platform/security/sl_component/se_manager/inc/sl_se_manager_defines.h