Secure_Link
GENERAL_API

APIs for Secure link configuration and usage.

Data Structures

struct sl_wfx_set_securelink_mac_key_req_body_t
Set the Secure Link MAC key.
struct sl_wfx_set_securelink_mac_key_cnf_body_t
Confirmation for the Secure Link MAC key setting.
struct sl_wfx_securelink_exchange_pub_keys_req_body_t
Exchange Secure Link Public Keys.
struct sl_wfx_securelink_exchange_pub_keys_cnf_body_t
Confirmation for exchange of Secure Link Public Keys.
struct sl_wfx_securelink_exchange_pub_keys_ind_body_t
Indication for exchange of Secure Link Public Keys.
struct sl_wfx_securelink_configure_req_body_t
Configure Secure Link Layer.
struct sl_wfx_securelink_configure_cnf_body_t
Confirmation of Secure Link Layer configuration sl_wfx_securelink_configure_req_body_t .

Macros

#define SL_WFX_SESSION_KEY_PROTECTION_DISABLE_MAGIC 0xfa21e603
Magic word used to disable Session Key protection.

Enumerations

enum sl_wfx_secure_link_state_t {
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
enum sl_wfx_securelink_mac_key_dest_t {
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
enum sl_wfx_secure_link_session_key_alg_t {
SECURE_LINK_CURVE25519 = 0x01 ,
SECURE_LINK_KDF = 0x02
}
Session Key computation algorithms.

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

Data Structure Documentation

◆ sl_wfx_set_securelink_mac_key_req_body_t

struct 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

Definition at line 569 of file sl_wfx_general_api.h .

Data Fields
uint8_t key_value[32] Secure Link MAC Key value.
uint8_t otp_or_ram Key destination - OTP or RAM (see enum sl_wfx_securelink_mac_key_dest_t)

◆ sl_wfx_set_securelink_mac_key_cnf_body_t

struct sl_wfx_set_securelink_mac_key_cnf_body_t

Confirmation for the Secure Link MAC key setting.

Definition at line 582 of file sl_wfx_general_api.h .

Data Fields
uint32_t status Key upload status (see enum sl_wfx_status_t)

◆ sl_wfx_securelink_exchange_pub_keys_req_body_t

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

Definition at line 610 of file sl_wfx_general_api.h .

Data Fields
uint32_t algorithm Choice of the cryptographic algorithm used in the session key computation (see enum sl_wfx_secure_link_session_key_alg_t)
uint8_t host_pub_key[32] Host Public Key.
uint8_t host_pub_key_mac[64] Host Public Key MAC.

◆ sl_wfx_securelink_exchange_pub_keys_cnf_body_t

struct sl_wfx_securelink_exchange_pub_keys_cnf_body_t

Confirmation for exchange of Secure Link Public Keys.

Definition at line 624 of file sl_wfx_general_api.h .

Data Fields
uint32_t status Request status (see enum sl_wfx_status_t)

◆ sl_wfx_securelink_exchange_pub_keys_ind_body_t

struct sl_wfx_securelink_exchange_pub_keys_ind_body_t

Indication for exchange of Secure Link Public Keys.

Definition at line 638 of file sl_wfx_general_api.h .

Data Fields
uint8_t ncp_pub_key[32] Device Public Key.
uint8_t ncp_pub_key_mac[64] Device Public Key MAC.
uint32_t status Request status (see enum sl_wfx_status_t)

◆ sl_wfx_securelink_configure_req_body_t

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

Definition at line 673 of file sl_wfx_general_api.h .

Data Fields
uint32_t disable_session_key_protection Force the firmware to authorize the use of the same session key during a complete power cycle, even very long. NOT RECOMMENDED.
uint8_t encr_bmp[32] Encryption bitmap.

◆ sl_wfx_securelink_configure_cnf_body_t

struct 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

Definition at line 690 of file sl_wfx_general_api.h .

Data Fields
uint8_t encr_bmp[32] Encryption bitmap.
uint32_t status Request status (see enum sl_wfx_status_t)

Enumeration Type Documentation

◆ sl_wfx_secure_link_session_key_alg_t

enum sl_wfx_secure_link_session_key_alg_t

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)

Definition at line 598 of file sl_wfx_general_api.h .

◆ sl_wfx_secure_link_state_t

enum sl_wfx_secure_link_state_t

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

Definition at line 544 of file sl_wfx_general_api.h .

◆ sl_wfx_securelink_mac_key_dest_t

enum 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

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.

Definition at line 554 of file sl_wfx_general_api.h .