From a830ac364550eaf53d80b7c68e25abdc09e00b02 Mon Sep 17 00:00:00 2001 From: Wojciech Pietraszewski Date: Fri, 26 Jan 2024 10:40:48 +0100 Subject: [PATCH] host/sm: Add doxygen comments to the header file Adds missing macros, functions and structures documentation. --- nimble/host/include/host/ble_sm.h | 221 +++++++++++++++++++++++++++++- 1 file changed, 218 insertions(+), 3 deletions(-) diff --git a/nimble/host/include/host/ble_sm.h b/nimble/host/include/host/ble_sm.h index 51e745f36c..503e1310a4 100644 --- a/nimble/host/include/host/ble_sm.h +++ b/nimble/host/include/host/ble_sm.h @@ -20,6 +20,13 @@ #ifndef H_BLE_SM_ #define H_BLE_SM_ +/** + * @brief Bluetooth Security Manager (SM) + * @defgroup bt_sm Bluetooth Security Manager (SM) + * @ingroup bt_host + * @{ + */ + #include #include "syscfg/syscfg.h" #include @@ -29,68 +36,213 @@ extern "C" { #endif +/** + * @defgroup ble_sm_err Security Manager (SM) Error Codes + * @{ + */ + +/** SM Error Code: Success */ #define BLE_SM_ERR_SUCCESS 0x00 + +/** SM Error Code: Passkey entry failed */ #define BLE_SM_ERR_PASSKEY 0x01 + +/** SM Error Code: Out Of Band (OOB) not available */ #define BLE_SM_ERR_OOB 0x02 + +/** SM Error Code: Authentication Requirements */ #define BLE_SM_ERR_AUTHREQ 0x03 + +/** SM Error Code: Confirm Value failed */ #define BLE_SM_ERR_CONFIRM_MISMATCH 0x04 + +/** SM Error Code: Pairing Not Supported */ #define BLE_SM_ERR_PAIR_NOT_SUPP 0x05 + +/** SM Error Code: Encryption Key Size */ #define BLE_SM_ERR_ENC_KEY_SZ 0x06 + +/** SM Error Code: Command Not Supported */ #define BLE_SM_ERR_CMD_NOT_SUPP 0x07 + +/** SM Error Code: Unspecified Reason */ #define BLE_SM_ERR_UNSPECIFIED 0x08 + +/** SM Error Code: Repeated Attempts */ #define BLE_SM_ERR_REPEATED 0x09 + +/** SM Error Code: Invalid Parameters */ #define BLE_SM_ERR_INVAL 0x0a + +/** SM Error Code: DHKey Check failed */ #define BLE_SM_ERR_DHKEY 0x0b + +/** SM Error Code: Numeric Comparison failed */ #define BLE_SM_ERR_NUMCMP 0x0c + +/** SM Error Code: Pairing in progress */ #define BLE_SM_ERR_ALREADY 0x0d + +/** SM Error Code: Cross-transport Key Derivation/Generation not allowed */ #define BLE_SM_ERR_CROSS_TRANS 0x0e + +/** SM Error Code: Key Rejected */ #define BLE_SM_ERR_KEY_REJ 0x0f + +/** SM Error Code: Out Of Boundary Code Value */ #define BLE_SM_ERR_MAX_PLUS_1 0x10 +/** @} */ + +/** + * @defgroup ble_sm_pair_alg Security Manager (SM) Pairing Algorithms + * @{ + */ + +/** SM Pairing Algorithm: Just Works */ #define BLE_SM_PAIR_ALG_JW 0 + +/** SM Pairing Algorithm: Passkey Entry */ #define BLE_SM_PAIR_ALG_PASSKEY 1 + +/** SM Pairing Algorithm: Out Of Band */ #define BLE_SM_PAIR_ALG_OOB 2 + +/** SM Pairing Algorithm: Numeric Comparison */ #define BLE_SM_PAIR_ALG_NUMCMP 3 +/** @} */ + +/** + * @defgroup ble_sm_pair_key_dist Security Manager (SM) Key Distribution Flags + * @{ + */ + +/** SM Key Distribution: Distribute Long Term Key (LTK) */ #define BLE_SM_PAIR_KEY_DIST_ENC 0x01 + +/** SM Key Distribution: Distribute Identity Resolving Key (IRK) */ #define BLE_SM_PAIR_KEY_DIST_ID 0x02 + +/** SM Key Distribution: Distribute Connection Signature Resolving Key (CSRK) */ #define BLE_SM_PAIR_KEY_DIST_SIGN 0x04 + +/** SM Key Distribution: Derive the Link Key from the LTK */ #define BLE_SM_PAIR_KEY_DIST_LINK 0x08 + +/** SM Key Distribution: Reserved For Future Use */ #define BLE_SM_PAIR_KEY_DIST_RESERVED 0xf0 +/** @} */ + +/** + * @defgroup ble_sm_io_cap Security Manager (SM) Input/Output Capabilities + * @{ + */ + +/** SM IO Capabilities: Display Only */ #define BLE_SM_IO_CAP_DISP_ONLY 0x00 + +/** SM IO Capabilities: Display Yes No */ #define BLE_SM_IO_CAP_DISP_YES_NO 0x01 + +/** SM IO Capabilities: Keyboard Only */ #define BLE_SM_IO_CAP_KEYBOARD_ONLY 0x02 + +/** SM IO Capabilities: No Input No Output */ #define BLE_SM_IO_CAP_NO_IO 0x03 + +/** SM IO Capabilities: Keyboard Display */ #define BLE_SM_IO_CAP_KEYBOARD_DISP 0x04 + +/** SM IO Capabilities: Reserved For Future Use */ #define BLE_SM_IO_CAP_RESERVED 0x05 +/** @} */ + +/** + * @defgroup ble_sm_pair_oob Security Manager (SM) Out Of Band Data (OOB) Flags + * @{ + */ + +/** SM OOB: Out Of Band Data Not Available */ #define BLE_SM_PAIR_OOB_NO 0x00 + +/** SM OOB: Out Of Band Data Available */ #define BLE_SM_PAIR_OOB_YES 0x01 + +/** SM OOB: Reserved For Future Use */ #define BLE_SM_PAIR_OOB_RESERVED 0x02 +/** @} */ + +/** + * @defgroup ble_sm_authreq Security Manager (SM) Authentication Requirements Flags + * @{ + */ + +/** SM Authentication Requirement: Bonding */ #define BLE_SM_PAIR_AUTHREQ_BOND 0x01 + +/** SM Authentication Requirement: MITM protection */ #define BLE_SM_PAIR_AUTHREQ_MITM 0x04 + +/** SM Authentication Requirement: Secure Connections */ #define BLE_SM_PAIR_AUTHREQ_SC 0x08 + +/** SM Authentication Requirement: Keypress notifications */ #define BLE_SM_PAIR_AUTHREQ_KEYPRESS 0x10 + +/** SM Authentication Requirement: Reserved For Future Use */ #define BLE_SM_PAIR_AUTHREQ_RESERVED 0xe2 +/** @} */ + +/** + * @defgroup ble_sm_pair_key_sz Security Manager (SM) Key Sizes + * @{ + */ + +/** SM Key Size: Minimum supported encryption key size in octets */ #define BLE_SM_PAIR_KEY_SZ_MIN 7 + +/** SM Key Size: Maximum supported encryption key size in octets */ #define BLE_SM_PAIR_KEY_SZ_MAX 16 -/* +/** @} */ + +/** + * @defgroup ble_sm_ioact Security Manager (SM) Key Generation Action + * @{ * The security manager asks the application to perform a key generation * action. The application passes the passkey back to SM via * ble_sm_inject_io(). */ + +/** SM IO Action: None (Just Works pairing) */ #define BLE_SM_IOACT_NONE 0 + +/** SM IO Action: Out Of Band (OOB) */ #define BLE_SM_IOACT_OOB 1 + +/** SM IO Action: Input (Passkey Entry) */ #define BLE_SM_IOACT_INPUT 2 + +/** SM IO Action: Passkey Display */ #define BLE_SM_IOACT_DISP 3 + +/** SM IO Action: Numeric Comparison */ #define BLE_SM_IOACT_NUMCMP 4 + +/** SM IO Action: Out Of Band (OOB) Secure Connections */ #define BLE_SM_IOACT_OOB_SC 5 + +/** SM IO Action: Out Of Boundary Code Value */ #define BLE_SM_IOACT_MAX_PLUS_ONE 6 +/** @} */ + +/** Represents Out Of Band (OOB) data used in Secure Connections pairing */ struct ble_sm_sc_oob_data { /** Random Number. */ uint8_t r[16]; @@ -99,19 +251,64 @@ struct ble_sm_sc_oob_data { uint8_t c[16]; }; +/** Represents Input/Output data for Security Manager used during pairing process */ struct ble_sm_io { + /** Pairing action, indicating the type of pairing method. Can be one of the + * following: + * o BLE_SM_IOACT_NONE + * o BLE_SM_IOACT_OOB + * o BLE_SM_IOACT_INPUT + * o BLE_SM_IOACT_DISP + * o BLE_SM_IOACT_NUMCMP + * o BLE_SM_IOACT_OOB_SC + */ uint8_t action; + + /** Union holding different types of pairing data. The valid field is inferred + * from the action field. */ union { + /** Passkey value between 000000 and 999999. + * Valid for the following actions: + * o BLE_SM_IOACT_INPUT + * o BLE_SM_IOACT_DISP + */ uint32_t passkey; + + /** Temporary Key random value used in Legacy Pairing. + * Valid for the following actions: + * o BLE_SM_IOACT_OOB + */ uint8_t oob[16]; + + /** Numeric Comparison acceptance indicator. + * Valid for the following actions: + * o BLE_SM_IOACT_NUMCMP + */ uint8_t numcmp_accept; + + /** Out Of Band (OOB) data used in Secure Connections. + * Valid for the following actions: + * o BLE_SM_IOACT_OOB_SC + */ struct { - struct ble_sm_sc_oob_data *local; + /** Remote Secure Connections Out Of Band (OOB) data */ struct ble_sm_sc_oob_data *remote; + /** Local Secure Connections Out Of Band (OOB) data */ + struct ble_sm_sc_oob_data *local; } oob_sc_data; }; }; +/** + * Generates Out of Band (OOB) data used during the authentication process. + * The data consists of 128-bit Random Number and 128-bit Confirm Value. + * + * @param oob_data A pointer to the structure where the generated + * OOB data will be stored. + * + * @return 0 on success; + * Non-zero on failure. + */ int ble_sm_sc_oob_generate_data(struct ble_sm_sc_oob_data *oob_data); #if MYNEWT_VAL(BLE_SM_CSIS_SIRK) @@ -132,8 +329,22 @@ int ble_sm_csis_resolve_rsi(const uint8_t *rsi, const uint8_t *sirk, #endif #if NIMBLE_BLE_SM +/** + * @brief Passes the IO data from an application to the Security Manager during the pairing + * process. + * + * It should be used after a pairing method has been established for given connection + * and once the appropriate key generation information (e.g. passkey) has been obtained. + * + * @param conn_handle The connection handle of the relevant connection. + * @param pkey A pointer to the structure where IO data is stored. + * + * @return 0 on success; + * Non-zero on failure. + */ int ble_sm_inject_io(uint16_t conn_handle, struct ble_sm_io *pkey); #else +/** This macro replaces the function to return BLE_HS_ENOTSUP when SM is disabled. */ #define ble_sm_inject_io(conn_handle, pkey) \ ((void)(conn_handle), BLE_HS_ENOTSUP) #endif @@ -142,4 +353,8 @@ int ble_sm_inject_io(uint16_t conn_handle, struct ble_sm_io *pkey); } #endif -#endif +/** + * @} + */ + +#endif /* H_BLE_SM_ */