skip to content

Which ATT error does a GATT server return when a secure attribute is accessed over an unauthenticated, unencrypted or short-key link?

level: middleimportance: should knowfreq 38%

answer

  1. permissions decide the error
  2. three link problems, three codes
  3. authorization is a separate permission
  4. a rejected command gets no reply

basics

~20 s

The server sends ATT_ERROR_RSP: Insufficient Authentication (0x05) for a link not authenticated enough, Insufficient Encryption (0x0F) for an unencrypted link, Encryption Key Size Too Short (0x0C) for a short key, and Insufficient Authorization (0x08) when authorization is missing.

solid answer

~40 s

An attribute's permissions combine **access** (read, write or both), **encryption**, **authentication** and **authorization**, and a higher-layer specification defines them; ATT cannot discover them. When a request fails a check, the server answers with ATT_ERROR_RSP: **Insufficient Authentication (0x05)**, **Insufficient Encryption (0x0F)**, **Encryption Key Size Too Short (0x0C)** or, for the separate user-confirmation permission, **Insufficient Authorization (0x08)**. The specification says the client *may* then try to authenticate, encrypt, or encrypt with a longer key, and retry, so a trace shows both the failed permission and the recovery. The same permissions govern notifications and indications as well as reads and writes. Be careful reading 0x05: on an unencrypted link with no key it does not mean MITM protection is required. A rejected ATT_WRITE_CMD produces no error at all.

code

plaintext · 6 lines
plaintext
client  ATT_READ_REQ    handle 0x0012
server  ATT_ERROR_RSP   request opcode 0x0A, handle 0x0012,
                        error 0x0F (Insufficient Encryption)
client  starts encryption with the stored LTK
client  ATT_READ_REQ    handle 0x0012
server  ATT_READ_RSP    (value returned)

go deeper

for a junior

Recall that the server refuses with Insufficient Authentication, Insufficient Encryption or Encryption Key Size Too Short, and that the client may try to fix the link and retry.

for a middle

Map each link condition to its code, separate authorization from authentication, and explain how permissions combine on one attribute.

for a senior

Read an ATT trace for the cause, remember that rejected commands are silent, and know why 0x05 on an unencrypted link is ambiguous.

for a principal

Define the permission table for a product so each attribute asks for the least it needs and the evidence exists to prove it.

## Attribute permissions Every attribute on a GATT server carries a set of permissions that decide who may use it. ATT defines four kinds, and an attribute holds a combination of them: - **Access:** readable, writable, or both. - **Encryption:** an encrypted link is required, or not. - **Authentication:** an authenticated link is required, or not. - **Authorization:** the client must be authorized before access, or not. The specification says the permissions of an attribute are defined by a higher layer specification and "are not discoverable using the Attribute Protocol". An attribute can have several alternative combinations, for example read if encrypted, but write only if authenticated and encrypted. The same encryption and authentication permissions also decide whether a server may send a notification or indication. ## The error responses When the link does not satisfy a permission, the server answers the request with an **ATT_ERROR_RSP** (opcode 0x01) that names the request opcode and attribute handle in error. | Error | Code | Raised when | What the client may do | |---|---|---|---| | Insufficient Authentication | 0x05 | the link is not authenticated sufficiently | try to authenticate the link, then retry | | Insufficient Encryption | 0x0F | encryption is required and the link is not encrypted | try to encrypt the link, then retry | | Encryption Key Size Too Short | 0x0C | the link is encrypted with too short a key | try to encrypt with a longer key size | | Insufficient Authorization | 0x08 | authorization is required and missing | obtain authorization (user confirmation) | Related codes you will see beside them are Read Not Permitted (0x02) and Write Not Permitted (0x03), which say the access permission itself does not allow the operation. ## Which error in which situation GAP 10.3.1 turns the permission check into a table keyed by the link's encryption state and what the local device holds. 1. **No LTK and no STK:** the request is rejected with Insufficient Authentication, even if the attribute asks only for encryption. GAP adds a note that on a non-encrypted link this error "does not indicate that MITM protection is required". 2. **A key exists but the link is not encrypted:** Insufficient Encryption. 3. **Encrypted, but an authenticated pairing is required and only an unauthenticated one occurred:** Insufficient Authentication. 4. **Encrypted, but LE Secure Connections pairing is required and legacy pairing occurred:** Insufficient Authentication. 5. **Encrypted with a key that is too short:** Encryption Key Size Too Short. ## Authorization is a separate permission GAP 10.5 describes authorization as a confirmation by the user to continue with the procedure, and states that authentication does not necessarily provide authorization. A control point that starts a firmware update might require authorization on top of an authenticated, encrypted link. Authentication says how well the peer was verified at pairing; authorization says whether this particular action may go ahead. ## Notifications and indications The client's subscription is stored in the Client Characteristic Configuration Descriptor, and it persists across disconnection. GAP therefore requires the server, when it reconnects to send a notification with a security requirement, to initiate or request encryption first, and requires the client to check the requirement and ignore notifications that arrive before it is met (indications are confirmed and discarded). ## Designing the permission table When you write the table for a product, give each attribute the least that protects it, then check the choice against what the device can perform. An attribute that requires an authenticated link is reachable only if the pairing hardware of both ends can produce an authenticated key. Record the combination per attribute (access, encryption, authentication, authorization) so a reviewer can compare it with the error responses seen in a capture. Where the same data is reachable through two attributes, give both the same requirement, because the weaker one defines the real exposure. ## What you can and cannot see ```plaintext client ATT_READ_REQ handle 0x0012 server ATT_ERROR_RSP request opcode 0x0A, handle 0x0012, error 0x0F (Insufficient Encryption) client starts encryption with the stored LTK client ATT_READ_REQ handle 0x0012 server ATT_READ_RSP (value returned) ``` - A protocol analyser or a client log shows the error code and handle, which is the evidence for which permission failed. - An **ATT_WRITE_CMD** that the server cannot write for any reason is *ignored*: no ATT_ERROR_RSP and no write response are sent. A log with no errors therefore proves nothing about commands; test permission rules with requests, which answer. - Insufficient Authentication has more than one cause (no key, unauthenticated key, legacy where Secure Connections is required), so the code alone does not tell you which pairing change the attribute needs.

  • Where do an attribute's permissions come from, and can a client read them over ATT?
    A higher-layer specification or the application defines them, and the Attribute Protocol cannot discover them. A client learns a requirement by being refused with an error code, from the profile it implements, or from a server that publishes its requirements in the LE GATT Security Levels characteristic.
  • How does a client find out that a write command was refused because of permissions?
    It does not. ATT_WRITE_CMD gets neither an error response nor a write response; if the server cannot write the attribute for any reason, the command is ignored. Reviewers should exercise permission rules with request PDUs, which do answer, and look at server-side logs for commands.
  • Why does the specification make the server act on reconnection before sending a notification that needs security?
    The notification subscription persists across disconnection, so a bonded client reconnects already subscribed. The server must initiate or request encryption before sending, and the client must ignore notifications that arrive before the requirement is met. If the bond was lost on either side, enabling encryption fails and the data is not sent.

  • Insufficient Authentication always means the link is encrypted but not authenticated enough
  • Insufficient Encryption and Encryption Key Size Too Short are the same error
  • Authentication and authorization are the same permission
  • A client can read an attribute's permissions through ATT before trying it
  • A refused write command returns the same ATT_ERROR_RSP as a refused write request