espressif/esp-nimble
1
0
Fork 0
mirror of https://github.com/espressif/esp-nimble.git synced 2026-08-14 22:17:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

host/sm: Add doxygen comments to the header file

Browse Source 
Adds missing macros, functions and structures documentation.
This commit is contained in:
Wojciech Pietraszewski
2024-03-12 09:39:31 +01:00
committed by Szymon Janc
parent cdf2520550
commit a830ac3645
1 changed files with 218 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files
nimble/host/include/host/ble_sm.h
+218 -3
View File
@@ -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 @@ 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_ */