host/sm: Add doxygen comments to the header file
Adds missing macros, functions and structures documentation.
diff --git a/nimble/host/include/host/ble_sm.h b/nimble/host/include/host/ble_sm.h
index 51e745f..503e131 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 <inttypes.h>
#include "syscfg/syscfg.h"
#include <stdbool.h>
@@ -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 @@
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 @@
#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 @@
}
#endif
-#endif
+/**
+ * @}
+ */
+
+#endif /* H_BLE_SM_ */
