Skip to content

Commit

Permalink
host/sm: Add doxygen comments to the header file
Browse files Browse the repository at this point in the history 
Adds missing macros, functions and structures documentation.
  • Loading branch information
@wpiet @sjanc
wpiet authored and sjanc committed Mar 12, 2024
1 parent cdf2520 commit a830ac3
Showing 1 changed file with 218 additions and 3 deletions.
221 changes: 218 additions & 3 deletions nimble/host/include/host/ble_sm.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Expand All @@ -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];
Expand All @@ -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)
Expand All @@ -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
Expand All @@ -142,4 +353,8 @@ int ble_sm_inject_io(uint16_t conn_handle, struct ble_sm_io *pkey);
}
#endif

#endif
/**
* @}
*/

#endif /* H_BLE_SM_ */

0 comments on commit a830ac3

Please sign in to comment.