Key derivation
Secure Engine Manager

Description

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

Data Structures

struct sl_se_ecjpake_context_t
EC J-PAKE context structure.

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.

Typedefs

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.

Enumerations

enum sl_se_ecjpake_role_t {
SL_SE_ECJPAKE_CLIENT = 0,
SL_SE_ECJPAKE_SERVER
}
Roles in the EC J-PAKE exchange.

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.

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.

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

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

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

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

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

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

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

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

Note
Currently the only values for hash/curve allowed by the standard are SL_SE_HASH_SHA256 / SL_SE_KEY_TYPE_ECC_P256 .
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 .
Returns
SL_STATUS_OK when the command was executed successfully, otherwise an appropriate error code (sl_status.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).

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

◆ 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.
[in,out] 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).

◆ 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.
[in,out] 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).

Macro Definition Documentation

◆ SL_SE_PRF_AES_CMAC_128

#define SL_SE_PRF_AES_CMAC_128 SL_SE_HASH_NONE

Defines mapping the PBKDF2 PRFs to corresponding sl_se_hash_type_t values.

CMAC-AES-128

◆ SL_SE_PRF_HMAC_SHA1

#define SL_SE_PRF_HMAC_SHA1 SL_SE_HASH_SHA1

HMAC-SHA-1.

◆ SL_SE_PRF_HMAC_SHA224

#define SL_SE_PRF_HMAC_SHA224 SL_SE_HASH_SHA224

HMAC-SHA-224.

◆ SL_SE_PRF_HMAC_SHA256

#define SL_SE_PRF_HMAC_SHA256 SL_SE_HASH_SHA256

HMAC-SHA-256.

◆ SL_SE_PRF_HMAC_SHA384

#define SL_SE_PRF_HMAC_SHA384 SL_SE_HASH_SHA384

HMAC-SHA-384.

◆ SL_SE_PRF_HMAC_SHA512

#define SL_SE_PRF_HMAC_SHA512 SL_SE_HASH_SHA512

HMAC-SHA-512.

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.

Enumeration Type Documentation

◆ sl_se_ecjpake_role_t

enum sl_se_ecjpake_role_t

Roles in the EC J-PAKE exchange.

Enumerator
SL_SE_ECJPAKE_CLIENT

Client.

SL_SE_ECJPAKE_SERVER

Server.