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_hash_type_t hash, 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.
|
|
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 beNULL
.
- 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 notNULL
, 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 beNULL
.
- 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 beNULL
.
- 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 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_hash_type_t |
hash,
|
||
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] 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] 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 lenght of the generated key.
- Returns
- SL_STATUS_OK if the signature is successfully verified, otherwise an appropriate error code (sl_status.h).
Enumeration Type Documentation
◆ sl_se_ecjpake_role_t
enum sl_se_ecjpake_role_t |