Key derivation

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_ctxPointer to an SE command context object.
[in]key_in_privOur private key.
[in]key_in_pubTheir public key.
[out]key_outShared 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]ctxThe 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]ctxThe EC J-PAKE context to use. This must be initialized, set up and have performed both round one and two.
[out]bufThe buffer to write the derived secret to. This must be a writable buffer of length len bytes.
[in]lenThe length of buf in bytes.
[out]olenThe 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]ctxThe 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]ctxThe EC J-PAKE context to initialize. This must not be NULL.
[in]cmd_ctxPointer 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]ctxThe EC J-PAKE context to use. This must be initialized and set up.
[in]bufThe buffer holding the first round message. This must be a readable buffer of length len bytes.
[in]lenThe 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]ctxThe EC J-PAKE context to use. This must be initialized and set up and already have performed round one.
[in]bufThe buffer holding the second round message. This must be a readable buffer of length len bytes.
[in]lenThe 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]ctxThe EC J-PAKE context to set up. This must be initialized.
[in]roleThe role of the caller. This must be either SL_SE_ECJPAKE_CLIENT or SL_SE_ECJPAKE_SERVER.
[in]hashThe identifier of the hash function to use, for example SL_SE_HASH_SHA256.
[in]curveThe identifier of the elliptic curve to use, for example SL_SE_KEY_TYPE_ECC_P256.
[in]secretThe 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]lenThe 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]ctxThe EC J-PAKE context to use. This must be initialized and set up.
[out]bufThe buffer to write the contents to. This must be a writable buffer of length len bytes.
[in]lenThe length of buf in bytes.
[out]olenThe 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]ctxThe EC J-PAKE context to use. This must be initialized, set up, and already have performed round one.
[out]bufThe buffer to write the round two contents to. This must be a writable buffer of length len bytes.
[in]lenThe size of buf in bytes.
[out]olenThe 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_ctxPointer to an SE command context object.
[in]in_keyPointer to the input key material.
[in]hashWhich hashing algorithm to use.
[in]saltAn optional salt value (a non-secret random value).
[in]salt_lenThe length of the salt.
[in]infoAn optional context and application specific information string.
[in]info_lenThe length of info.
[in,out]out_keyPointer to the generated key material. The length member of out_key is used to request a given lenght 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_ctxPointer to an SE command context object.
[in]in_keyPointer to the input key material.
[in]prfThe 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]saltAn optional salt value (a non-secret random value).
[in]salt_lenThe length of the salt.
[in]iterationsThe number of iterations to use. Up to 16384 iterations is supported.
[in,out]out_keyPointer to the generated key material. The length member of out_key is used to request a given lenght 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_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

Roles in the EC J-PAKE exchange.

Enumerator
SL_SE_ECJPAKE_CLIENT 

Client.

SL_SE_ECJPAKE_SERVER 

Server.