From dfd8d39c0aa7511654b817a7ecded22e2ef7299e Mon Sep 17 00:00:00 2001 From: Zhang Hai Peng Date: Tue, 25 Aug 2026 19:55:05 +0800 Subject: [PATCH] docs(bt): clarify Bluedroid GATT signed write API comments Correct misleading CHAR_PROP_BIT_AUTH wording and document CSRK-based signed write usage for server permissions and client write APIs. (cherry picked from commit 8d230c76509fbb7ea07ef2df3cb930ced91fe0a3) Co-authored-by: zhanghaipeng --- .../bt/host/bluedroid/api/include/api/esp_gatt_defs.h | 10 +++++----- .../bt/host/bluedroid/api/include/api/esp_gattc_api.h | 2 ++ 2 files changed, 7 insertions(+), 5 deletions(-) diff --git a/components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h b/components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h index 57736c29076..4b34bda61f3 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h +++ b/components/bt/host/bluedroid/api/include/api/esp_gatt_defs.h @@ -375,8 +375,8 @@ typedef enum { ESP_GATT_AUTH_REQ_NONE = 0, /*!< No authentication required. Corresponds to BTA_GATT_AUTH_REQ_NONE. */ ESP_GATT_AUTH_REQ_NO_MITM = 1, /*!< Unauthenticated encryption. Corresponds to BTA_GATT_AUTH_REQ_NO_MITM. */ ESP_GATT_AUTH_REQ_MITM = 2, /*!< Authenticated encryption (MITM protection). Corresponds to BTA_GATT_AUTH_REQ_MITM. */ - ESP_GATT_AUTH_REQ_SIGNED_NO_MITM = 3, /*!< Signed data, no MITM protection. Corresponds to BTA_GATT_AUTH_REQ_SIGNED_NO_MITM. */ - ESP_GATT_AUTH_REQ_SIGNED_MITM = 4, /*!< Signed data with MITM protection. Corresponds to BTA_GATT_AUTH_REQ_SIGNED_MITM. */ + ESP_GATT_AUTH_REQ_SIGNED_NO_MITM = 3, /*!< CSRK signed write, no MITM. Use with `ESP_GATT_WRITE_TYPE_NO_RSP` on a bonded, unencrypted link. */ + ESP_GATT_AUTH_REQ_SIGNED_MITM = 4, /*!< CSRK signed write with MITM. Use with `ESP_GATT_WRITE_TYPE_NO_RSP` on a bonded, unencrypted link. */ } esp_gatt_auth_req_t; @@ -410,10 +410,10 @@ typedef enum { /** @brief Permission to write to the attribute with encrypted MITM protection. Corresponds to BTA_GATT_PERM_WRITE_ENC_MITM. */ #define ESP_GATT_PERM_WRITE_ENC_MITM (1 << 6) -/** @brief Permission for signed writes to the attribute. Corresponds to BTA_GATT_PERM_WRITE_SIGNED. */ +/** @brief Signed write without link encryption (CSRK). Requires `ESP_GATT_CHAR_PROP_BIT_AUTH`. Corresponds to BTA_GATT_PERM_WRITE_SIGNED. */ #define ESP_GATT_PERM_WRITE_SIGNED (1 << 7) -/** @brief Permission for signed writes to the attribute with MITM protection. Corresponds to BTA_GATT_PERM_WRITE_SIGNED_MITM. */ +/** @brief Signed write with MITM-protected CSRK. Requires `ESP_GATT_CHAR_PROP_BIT_AUTH`. Corresponds to BTA_GATT_PERM_WRITE_SIGNED_MITM. */ #define ESP_GATT_PERM_WRITE_SIGNED_MITM (1 << 8) /** @brief Permission to read the attribute with authorization. */ @@ -463,7 +463,7 @@ typedef uint16_t esp_gatt_perm_t; ///< Type to represent GATT attribute permissi /** @brief Ability to indicate.Corresponds to BTA_GATT_CHAR_PROP_BIT_INDICATE. */ #define ESP_GATT_CHAR_PROP_BIT_INDICATE (1 << 5) -/** @brief Ability to authenticate.Corresponds to BTA_GATT_CHAR_PROP_BIT_AUTH. */ +/** @brief Authenticated Signed Writes (ATT Signed Write Command, 0xD2). Requires matching `ESP_GATT_PERM_WRITE_SIGNED`. Corresponds to BTA_GATT_CHAR_PROP_BIT_AUTH. */ #define ESP_GATT_CHAR_PROP_BIT_AUTH (1 << 6) /** @brief Has extended properties.Corresponds to BTA_GATT_CHAR_PROP_BIT_EXT_PROP. */ diff --git a/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h b/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h index 086cf211688..03d575f5fbf 100644 --- a/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h +++ b/components/bt/host/bluedroid/api/include/api/esp_gattc_api.h @@ -915,6 +915,8 @@ esp_err_t esp_ble_gattc_read_char_descr (esp_gatt_if_t gattc_if, * 3. `handle` must be greater than 0. * 4. If `auth_req` is not `ESP_GATT_AUTH_REQ_NONE`, the stack may start encryption * or SMP pairing before sending the ATT write. + * 5. `ESP_GATT_AUTH_REQ_SIGNED_*` with `ESP_GATT_WRITE_TYPE_NO_RSP` sends ATT Signed + * Write Command when bonded (CSRK) and the link is not encrypted. * * @return * - ESP_OK: Success