Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Version 0.2: simplification and clarification #16

Closed
wants to merge 2 commits into from
+96 −53
Closed

Version 0.2: simplification and clarification #16

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a6ae15f
Initial draft
martinpaljak Dec 12, 2018
8bab669
Have errors under the single notification
martinpaljak Dec 12, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
149 changes: 96 additions & 53 deletions spec/apdu-service-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,12 @@
# APDU-Service specification
# APDU-over-BLE service specification v0.2

This document specifies the BLE service that transmits Command-APDUs from a BLE client device to a BLE device that also contains a Secure Element.
This document specifies a [BLE GATT](https://www.bluetooth.com/specifications/gatt/generic-attributes-overview) service that allows to transmit [APDU](https://en.wikipedia.org/wiki/Smart_card_application_protocol_data_unit)-s betweeen a BLE client device and a BLE server device that contains a Secure Element.

#### Version history
- v0.2 adds error notifications and removes multiple APDU support from the protocol

#### Requirements
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://tools.ietf.org/html/rfc2119).

## Roles
- The BLE client device (for example, a smartphone app) will implement the *GATT Client* role.
Expand All @@ -12,20 +18,22 @@ The device shall enforce Security Mode 1, Level 2 (unauthenticated pairing with

It is strongly encouraged to define an *application-level pairing* mechanism to make sure that only authorized applications may send APDU Commands to the device containing the Secure Element.

Please see [Security Considerations](./security-considerations.md) for more information on

## Client and Server requirements
Each role must support the following:

### GATT Server role
- Write characteristic value
- Read characteristic value
- Issue notifications
- Reading characteristic value
- Writing characteristic value
- Issuing notifications

### GATT Client role
- Discover primary services by UUID
- Discover characteristics by UUID
- Read characteristic value
- Write characteristic value
- Receive notifications
- Discovering primary services by UUID
- Discovering characteristics by UUID
- Reading characteristic value
- Writing characteristic value
- Receiving notifications

## Service parameters

Expand All @@ -34,79 +42,114 @@ Each role must support the following:

### Service Characteristics

| Characteristic name | Property | Length | UUID |
|-------------------------------------|---------------- |------------|----------------------------------------|
| APDU Commands | Write with ACK | 512 bytes | `8e79ecae-bb90-4967-a4a5-3f21aa9e05eb` |
| Conversation Finished | Write with ACK | 4 bytes | `8e798746-bb90-4967-a4a5-3f21aa9e05eb` |
| APDU Responses Ready | Notify with ACK | NA | `8e795e92-bb90-4967-a4a5-3f21aa9e05eb` |
| APDU Responses | Read | 512 bytes | `8e7927a7-bb90-4967-a4a5-3f21aa9e05eb` |
| Max Memory for APDU processing | Read | 4 bytes | `8e79e13b-bb90-4967-a4a5-3f21aa9e05eb` |
| Characteristic name | Property | Length | UUID |
|-------------------------------------|---------------- |--------------|----------------------------------------|
| APDU Command | Write with ACK | 1..MTU bytes | `8e79ecae-bb90-4967-a4a5-3f21aa9e05eb` |
| APDU Response Ready | Notify | 4 bytes | `8e795e92-bb90-4967-a4a5-3f21aa9e05eb` |
| APDU Response | Read | 1..MTU bytes | `8e7927a7-bb90-4967-a4a5-3f21aa9e05eb` |
| Close Communication | Write with ACK | 4 bytes | `8e798746-bb90-4967-a4a5-3f21aa9e05eb` |

#### Characteristic: APDU Commands
Used by the Client to transmit a sequence of Command APDUs. The sequence is a serialized stream of APDUs following the structure below:
#### Characteristic: APDU Command
Used by the Client to transmit a Command APDU, fragmented into messages that fit the established BLE MTU.

![APDU Command sequence](fig/command-apdu-sequence.png)
APDU is divided into packets following the structure [below](#packet).

Both the number of APDUs and the length of each APDU are encoded using two bytes, so that the resulting value is:
#### Characteristic: APDU Response Ready
Notification issued by the Server to signal that the Response APDU can be retrieved or an error code.

```value = [byte 0] + [byte 1]*256```
The payload has to be a 32-bit unsigned big endian integer, denoting:
- `0x000000000`: No error, APDU is ready for reading
- `0x000000001`: Generic SE error (no response from SE, transaction reset)
- `0x000000002`: APDU-over-BLE protocol error (packets lost, incorrect sequence, timeout)

The sequence of APDUs is then divided into packets that fit into the maximum length for this characteristic, following the structure [below](#packet).
#### Characteristic: APDU Response
Used by the Client to retrieve the Response APDU fragments corresponding to the processing of a previous Command APDU. The Client will read this characteristic only after receiving *APDU Response Ready* notification. Response APDU fragments will be encoded in the same structure as command APDUs in the figure below.

#### Characteristic: Conversation Finished
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Shouldn't this be called "Close Communication"? Conversation Finished was removed from the table

Used by the Client to notify the Server that the APDU exchange has finished so the Server can power the device down.
The payload has to be `0` coded as 32-bit unsigned integer.

#### Characteristic: APDU Responses Ready
Notification issued by the Server to signal that all the Command APDUs in the sequence have been processed, so the Response APDUs can be retrieved. The payload transmitted is irrelevant.

#### Characteristic: APDU Responses
Used by the Client to retrieve the sequence of Response APDUs corresponding to the processing of a previous sequence of Command APDUs. The Client will read this characteristic only after receiving *APDU Responses Ready* notification. Response APDUs will be encoded in the same structure as command APDUs in the figure above.

#### Characteristic: Max Memory for APDU processing
Memory, in bytes, that the Server can use to store APDU Commands. This limits the number of APDU Commands that can be sent by writing to the *APDU Commands* characteristic.
This characteristic is optional. If missing, the Server indicates that it does not have any memory limitations, so the Client does not need to limit the number of Command APDUs sent in a sequence.
Payload: memory (in bytes), coded as a 32-bit unsigned integer.

## <a name="packet"></a> Packet and payload structure
Sequences of APDU Commands and Responses may not fit into a single BLE packet, so they will have to be fragmented by the issuer and then reconstructed by the receiver. The APDU-Service will use the following packet structure:
APDU Command or APDU Response may not fit into a single BLE packet (with a default [useful payload of only 23 bytes](https://punchthrough.com/pt-blog-post/maximizing-ble-throughput-part-2-use-larger-att-mtu/) when standard MTU is used), so they will have to be fragmented by the issuer and then reconstructed by the receiver.

The APDU-Service will use the following packet structure:

![BLE packet structure](fig/ble-packet-structure.png)

which contains the following fields:
- `totn_pkt`: total number of packets in the APDU Commands/Responses sequence
- `totn_pkt`: total number of packets in the APDU Command/Response
- `pkt_nbr`: position of the packet (in the sequence)
- `data`: payload. Fragment of the APDU Commands/Responses sequence
- `data`: payload. Fragment of the APDU Command/Response

The data follows a big-endian byte order (byte 0 sent first), and little endian bit order in each byte:

![Endianess](fig/endianess.png)


The packet's length will always be the maximum size allowed by the `APDU Commands` characteristic, except for the last packet, that might be shorter.

## Packet ordering and retry policy

BLE guarantees ordered packet delivery, so it is not necessary to specify when to retry transmission, detect duplicates, etc.

## Maximum length of sequences, commands and packets (informative)
This section explains how the different frames are split in lower-layer packets, and how the maximum length of each is specified.
- APDU Sequence: frame that groups several APDU commands or responses. Its maximum length is defined by the characteristic `Max Memory for APDU processing`.
- APDU Commands packet: section of the APDU Sequence that fits in a single BLE operation. Its maximum size is the length of the `APDU Commands` write characteristic.
- BLE packet: data fragment actually transmitted by the lower layers of the BLE stack. Its maximum size is defined by the MTU size negotiated between the BLE client and server. Fragmentation, ordering and reconstruction are done transparently, so there is no need to specify them in this document.

![Sequences, commands, packets](fig/sequences-commands-packets.png)
If a client device does not for some reason send a APDU Response request, the server SHOULD re-send the notification until APDU Response characteristic is read, or until a application-specific timeout occurs.

## Sequence diagram
Interaction can be explained with this WebSequenceDiagram:


![APDU-over-BLE](https://www.websequencediagrams.com/cgi-bin/cdraw?lz=dGl0bGUgQVBEVS1vdmVyLUJMRQoKcGFydGljaXBhbnQgIk1vYmlsZSBBcHAiIGFzIENsaWVudAAVDkJMRSBQZXJpcGhlcmFsACIFU2VydmVyADwOU2VjdXJlIEVsZW1lbnQAIQZFCiAKYWx0IEJsdWV0b290aCBjb25uZWN0aW9uCgA_Bi0-AG4GOiBBZHZlcnRpc2Ugc2VydmljZQoAgQgGLT4AaQY6IEMANwYAMggAMAtDSwAcEUJvbmQAFBZlbmQKbG9vcCBNdWx0aXAAghsHcwoADwZBUERVIHRvIACBaQ4gMS4uTgCBABFXcml0ZTogIgAvBUNvbW1hbmQiIHdpdGggZnJhZ21lbnQgTgBrGm5vdGUgcmlnaHQgb2YAgk4HOgB0BXAAbwpNQVkgcG93ZXIgdXAgU0UKAIJMBQCBHQgAgmcOAIJKCVNFOgCBBwhBUERVClNFAII7ClJlc3BvbnNlABMGAIJCCAAuBTB4NjFYWCAvIDB4NkNYWCBoYW5kbGluZwpTRQAeBQAuFGVuZAoAgzkSUERVAGAJIFJlYWR5IE5vdGlmaWNhAIN3BQCCXQ4AhHAGAIJNFlJlYWQAgloIAIEzCCIAg3ASAIFKDACCcAwAgRoFYWx0IEluIGNhc2Ugb2YgZXJyb3IAhDMSAIEcBXkAgzgGAB4FIGNvZGUAhCkFZW5kAINjGUNvbnZlcnMAgVMFIEZpbmlzaGVkIgCDLDBkb3duIFNFAIVFFgo&s=rose)


```
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would move that to a separate file

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Until finalization, it is easier to keep it as such "editable link". For finalization, the images folder shall be cleaned.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agree with @sergkh

title APDU-over-BLE

participant "Mobile App" as Client
participant "BLE Peripheral" as Server
participant "Secure Element" as SE

alt Bluetooth connection
Server->Client: Advertise service
Client->Server: Connect
Server-->Client: ACK
Client->Server: Bond
Server-->Client: ACK
end
loop Multiple APDUs

loop APDU to BLE Peripheral 1..N
Client->Server: Write: "APDU Command" with fragment N
Server-->Client: ACK
end
note right of Server: BLE peripheral MAY power up SE

alt APDU to Secure Element
Server->SE: CommandAPDU
SE->Server: ResponseAPDU
Server-->>SE: 0x61XX / 0x6CXX handling
SE-->>Server: ResponseAPDU
end

Server->Client: APDU Response Ready Notification

loop APDU to Client 1..N
Client->Server: Read: "APDU Response"
Server-->Client: ResponseAPDU fragment N
end

alt In case of error
Server-->Client: Notify with error code
end
end
Client->Server: Write: "Conversation Finished"
note right of Server: BLE peripheral MAY power down SE
Server-->Client: ACK

### Commands

When sending a sequence of Command APDUs, the Client sends the different fragments in order, waiting for the ACK from the Server (sent by lower layers of the BLE stack).
```
### Command

### Responses
When sending a Command APDU, the Client sends the different fragments in order, waiting for the ACK from the Server (sent by lower layers of the BLE stack).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The "Server" is not identified in the diagram. Wouldn't it better to use the same actor names as in the sequence?


When the Server has finished processing the Command APDUs, it issues an `APDU Responses Ready` notification. Then the Client will fetch the first fragment of the sequence of Response APDUs by reading the `APDU Responses` characteristic.
### Response

Example of an exchange of Command and Response APDUs:
When the Server has finished processing the Command APDU, it issues an `APDU Response Ready` notification. Then the Client will fetch the first fragment of the sequence of Response APDUs by reading the `APDU Response` characteristic and continues reading until the full Response APDU has been read.

![Example sequence](fig/example-sequence.png)
Any time during the BLE conversation can an `Error` notification be sent and the state of the BLE Peripheral to be reset.