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.

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: Status 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 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

Roles in the EC J-PAKE exchange.

Enumerator
SL_SE_ECJPAKE_CLIENT	Client.
SL_SE_ECJPAKE_SERVER	Server.

Key derivation Secure Element Manager

Description

Data Structures

Functions

Enumerations

Function Documentation

◆ sl_se_ecdh_compute_shared_secret()

◆ sl_se_ecjpake_check()

◆ sl_se_ecjpake_derive_secret()

◆ sl_se_ecjpake_free()

◆ sl_se_ecjpake_init()

◆ sl_se_ecjpake_read_round_one()

◆ sl_se_ecjpake_read_round_two()

◆ sl_se_ecjpake_setup()

◆ sl_se_ecjpake_write_round_one()

◆ sl_se_ecjpake_write_round_two()

◆ sl_se_derive_key_hkdf()

◆ sl_se_derive_key_pbkdf2()

Enumeration Type Documentation

◆ sl_se_ecjpake_role_t

Key derivation
Secure Element Manager