Secure_Link

APIs for Secure link configuration and usage. More...

Classes
struct	sl_wfx_set_securemink_mac_key_req_body_s
	Set the Secure Link MAC key. More...
struct	sl_wfx_set_securelink_mac_key_req_s
struct	sl_wfx_set_securelink_mac_key_cnf_body_s
	Confirmation for the Secure Link MAC key setting. More...
struct	sl_wfx_set_securelink_mac_key_cnf_s
struct	sl_wfx_securelink_exchange_pub_keys_req_body_s
	Exchange Secure Link Public Keys. More...
struct	sl_wfx_securelink_exchange_pub_keys_req_s
struct	sl_wfx_securelink_exchange_pub_keys_cnf_body_s
	Confirmation for exchange of Secure Link Public Keys. More...
struct	sl_wfx_securelink_exchange_pub_keys_cnf_s
struct	sl_wfx_securelink_exchange_pub_keys_ind_body_s
	Indication for exchange of Secure Link Public Keys. More...
struct	sl_wfx_securelink_exchange_pub_keys_ind_s
struct	sl_wfx_securelink_configure_req_body_s
	Configure Secure Link Layer. More...
struct	sl_wfx_securelink_configure_req_s
struct	sl_wfx_securelink_configure_cnf_body_s
	Confirmation of Secure Link Layer configuration sl_wfx_securelink_configure_req_body_t. More...
struct	sl_wfx_securelink_configure_cnf_s

Macros
#define	SL_WFX_KEY_VALUE_SIZE   32
#define	SL_WFX_HOST_PUB_KEY_SIZE   32
#define	SL_WFX_HOST_PUB_KEY_MAC_SIZE   64
#define	SL_WFX_NCP_PUB_KEY_SIZE   32
#define	SL_WFX_NCP_PUB_KEY_MAC_SIZE   64
#define	SL_WFX_SESSION_KEY_PROTECTION_DISABLE_MAGIC   0xfa21e603
	Magic word used to disable Session Key protection.
#define	SL_WFX_ENCR_BMP_SIZE   32

Typedefs
typedef enum sl_wfx_secure_link_state_e	sl_wfx_secure_link_state_t
	*Secure Link' device state
typedef enum sl_wfx_securelink_mac_key_dest_e	sl_wfx_securelink_mac_key_dest_t
	destination of the Secure Link MAC key, used by request message sl_wfx_set_securelink_mac_key_req_body_t
typedef struct sl_wfx_set_securemink_mac_key_req_body_s	sl_wfx_set_securelink_mac_key_req_body_t
	Set the Secure Link MAC key. More...
typedef struct sl_wfx_set_securelink_mac_key_req_s	sl_wfx_set_securelink_mac_key_req_t
typedef struct sl_wfx_set_securelink_mac_key_cnf_body_s	sl_wfx_set_securelink_mac_key_cnf_body_t
	Confirmation for the Secure Link MAC key setting.
typedef struct sl_wfx_set_securelink_mac_key_cnf_s	sl_wfx_set_securelink_mac_key_cnf_t
typedef enum sl_wfx_secure_link_session_key_alg_e	sl_wfx_secure_link_session_key_alg_t
	Session Key computation algorithms.
typedef struct sl_wfx_securelink_exchange_pub_keys_req_body_s	sl_wfx_securelink_exchange_pub_keys_req_body_t
	Exchange Secure Link Public Keys. More...
typedef struct sl_wfx_securelink_exchange_pub_keys_req_s	sl_wfx_securelink_exchange_pub_keys_req_t
typedef struct sl_wfx_securelink_exchange_pub_keys_cnf_body_s	sl_wfx_securelink_exchange_pub_keys_cnf_body_t
	Confirmation for exchange of Secure Link Public Keys.
typedef struct sl_wfx_securelink_exchange_pub_keys_cnf_s	sl_wfx_securelink_exchange_pub_keys_cnf_t
typedef struct sl_wfx_securelink_exchange_pub_keys_ind_body_s	sl_wfx_securelink_exchange_pub_keys_ind_body_t
	Indication for exchange of Secure Link Public Keys.
typedef struct sl_wfx_securelink_exchange_pub_keys_ind_s	sl_wfx_securelink_exchange_pub_keys_ind_t
typedef struct sl_wfx_securelink_configure_req_body_s	sl_wfx_securelink_configure_req_body_t
	Configure Secure Link Layer. More...
typedef struct sl_wfx_securelink_configure_req_s	sl_wfx_securelink_configure_req_t
typedef struct sl_wfx_securelink_configure_cnf_body_s	sl_wfx_securelink_configure_cnf_body_t
	Confirmation of Secure Link Layer configuration sl_wfx_securelink_configure_req_body_t. More...
typedef struct sl_wfx_securelink_configure_cnf_s	sl_wfx_securelink_configure_cnf_t

Enumerations
enum	sl_wfx_secure_link_state_e { SECURE_LINK_NA_MODE = 0x0 , SECURE_LINK_UNTRUSTED_MODE = 0x1 , SECURE_LINK_TRUSTED_MODE = 0x2 , SECURE_LINK_TRUSTED_ACTIVE_ENFORCED = 0x3 }
	*Secure Link' device state More...
enum	sl_wfx_securelink_mac_key_dest_e { SECURE_LINK_MAC_KEY_DEST_OTP = 0x78 , SECURE_LINK_MAC_KEY_DEST_RAM = 0x87 }
	destination of the Secure Link MAC key, used by request message sl_wfx_set_securelink_mac_key_req_body_t More...
enum	sl_wfx_secure_link_session_key_alg_e { SECURE_LINK_CURVE25519 = 0x01 , SECURE_LINK_KDF = 0x02 }
	Session Key computation algorithms. More...

Detailed Description

APIs for Secure link configuration and usage.

WFX family of product have the ability to encrypt the SDIO or SPI link.

Link to more detailed documentation about the Secure Link feature : SecureLink

Typedef Documentation

sl_wfx_securelink_configure_cnf_body_t

typedef struct sl_wfx_securelink_configure_cnf_body_s sl_wfx_securelink_configure_cnf_body_t

Confirmation of Secure Link Layer configuration sl_wfx_securelink_configure_req_body_t.

Returns

HI_STATUS_SUCCESS

Note

The host driver should wait for this confirmation to update its local bitmap with the returned value

sl_wfx_securelink_configure_req_body_t

typedef struct sl_wfx_securelink_configure_req_body_s sl_wfx_securelink_configure_req_body_t

Configure Secure Link Layer.

This API can be used to:

• Set/update the Secure Link encryption bitmap
• Disable Session Key Protection

About the Session Key protection: SecureLink underlying encryption algorithm is AES CCM. This algorithm is using an internal Nonce counter incremented each time a message is encrypted/decrypted. This counter is not supposed to go beyond a given limit to guarantee AES CCM security properties. This is why Host Driver is responsible for renegotiating the session key once the message counter is approaching the limit. Disabling the Session Key protection will disable the check performed by the firmware that the Nonce counter is crossing the limit, allowing Host Driver to use the same session key during the same power cycle, even during a very long time. This behavior is not recommended.

To disable the protection, a given magic word (SL_WFX_SESSION_KEY_PROTECTION_DISABLE_MAGIC) must be provided as DisableSessionKeyProtection parameter value. Any other value will let the protection set.

Note

When SecureLink is activated, SL Configure API must be called right after the key exchange. Issuing another command instead will result in an error.

It is not recommended to call this API a second time during the same power cycle.

sl_wfx_securelink_exchange_pub_keys_req_body_t

typedef struct sl_wfx_securelink_exchange_pub_keys_req_body_s sl_wfx_securelink_exchange_pub_keys_req_body_t

Exchange Secure Link Public Keys.

This API is used by the Host to send its curve25519 public key to Device, and get back Device public key in the confirmation message. Once keys are exchanged and authenticated (using their respective MAC), each peer computes the Secure Link session key that will be used to encrypt/decrypt future Host<->Device messages.

sl_wfx_set_securelink_mac_key_req_body_t

typedef struct sl_wfx_set_securemink_mac_key_req_body_s sl_wfx_set_securelink_mac_key_req_body_t

Set the Secure Link MAC key.

This API can be used for Trusted Eval devices in two contexts:

• to set a temporary SecureLink MAC key in RAM.
• to permanently burn the SecureLink MAC key in OTP memory. In that case, the OTP SecureLink mode will switch to Trusted Enforced mode

Enumeration Type Documentation

sl_wfx_secure_link_session_key_alg_e

enum sl_wfx_secure_link_session_key_alg_e

Session Key computation algorithms.

Enumerator
SECURE_LINK_CURVE25519	Session key is computed using curve25519 algorithm.
SECURE_LINK_KDF	Session key is computed using KDF algorithm (not available yet)

sl_wfx_secure_link_state_e

enum sl_wfx_secure_link_state_e

*Secure Link' device state

Enumerator
SECURE_LINK_NA_MODE	Reserved.
SECURE_LINK_UNTRUSTED_MODE	Untrusted mode - SecureLink not available.
SECURE_LINK_TRUSTED_MODE	Trusted (Evaluation) mode.
SECURE_LINK_TRUSTED_ACTIVE_ENFORCED	Trusted (Enforced) mode.

sl_wfx_securelink_mac_key_dest_e

enum sl_wfx_securelink_mac_key_dest_e

destination of the Secure Link MAC key, used by request message sl_wfx_set_securelink_mac_key_req_body_t

Enumerator
SECURE_LINK_MAC_KEY_DEST_OTP	Key will be stored in OTP.
SECURE_LINK_MAC_KEY_DEST_RAM	Key will be stored in RAM.