This document describes all APDUs part of the Keycard protocol. Any implementation must fully implement this specification except for items explicitly marked as optional or conditional. The Keycard applet is a full implementation of this specification. The Keycard SDK provides both low-level methods to send each of the APDUs described here as well as convenience methods and classes to simplify integration.
APDUs (Application Protocol Data Units) are the standard command/response messages used to communicate with smart cards, defined by ISO 7816-4: the host sends a command APDU, the card executes it and returns a response APDU. They are Keycard's native API — every SDK ultimately speaks APDUs to the card.
This documentation reflects version 4.0 of the applet.
0x0400 and a
SecureChannel v2 with 0x0400 or above.
Pages for commands that no longer exist are kept, marked
Removed in 4.0, and describe the 3.x behaviour.Every genuine Keycard holds a persistent secp256k1 key pair — the authentikey — loaded together with a 98-byte certificate at production time. The certificate is the concatenation of:
| Field | Size |
|---|---|
| Authentikey public key, compressed | 33 bytes |
CA signature r | 32 bytes |
CA signature s | 32 bytes |
Recovery id v | 1 byte |
r, s and v are a CA ECDSA signature over the compressed public key. Because the recovery id is included, the client recovers the CA public key from the certificate itself and checks it against the anchors it trusts — no CA key needs to be transmitted. The certificate carries no serial number and no expiry.
Since 4.0 the certificate is returned in the SELECT response and is used by the secure channel handshake to authenticate the card. The applet refuses every command — SELECT included — if no valid certificate has been loaded, so cards where the identity has not been provisioned are simply unusable.
The certificate is verified once, at the first connection, and then again on every handshake through the signature the card produces over the key exchange transcript. Clients that have already pinned a card's public key may accept it directly instead of checking the CA anchor.
Known CA anchors (compressed secp256k1 public keys, 33 bytes):
| CA | Public key |
|---|---|
| Keycard production | 029a9b9ee1e7a71bdf45b3f9c58c99866ff1294d2c1e304e228a86e10c3343501c |
| Keycard test cards | 025877220aaae6e54a6f974602d5995c0fe24a3ea7ddabd8644bec795b9da00743 |
The Keycard protocol can be implemented by different devices which might have very different capabilities, different user interaction and connection types. For this reason some features not strictly related to signing transactions are optional. Each device reports its capabilities as response to the SELECT command. The optional capabilities are described below
The Secure Channel protocol defined in this document provides both passive and active MITM protection and PFS. Some devices however might have inherently secure connections to the client (for example Bluetooth based devices can use pairing and encrypted communication). To avoid overhead, devices using inherently secure connections can avoid implementing the secure channel defined here.
Devices not implementing the Secure Channel capability do not implement the OPEN SECURE CHANNEL and SECURED APDU commands.
Key management is the ability to generate, remove, backup and restore keys. Some devices might have internal key management and not allow the client to take part in this process.
Devices not implementing the Key management capability do not implement the LOAD KEY, GENERATE KEY, GENERATE MNEMONIC, REMOVE KEY commands.
Credentials management is the ability to authenticate the user and manipulate PIN and PUK. Some devices, especially those with screen and buttons, might want to handle this completely internally without client intervention.
Devices not implementing the Credentials management capability do not implement the INIT, VERIFY PIN, UNBLOCK PIN and CHANGE PIN commands.
The NDEF capability is the ability to set a custom NDEF record on the NFC interface. The NDEF record is used, for example, by mobile phones to decide the action to perform when a card is tapped to the device and no application using NFC is open. Customizing the NDEF record allow setting a default client or link to launch. Obviously, not all devices have a NFC interface and even those who do might not provide a way to customize the NDEF response.
Devices not implementing the NDEF capability do not support P1 = 0x01 (SET NDEF DATA) in the STORE DATA command.
The factory reset capability is the ability to bring the card back to its uninitialized state, deleting all secrets. Devices not implementing it do not implement the FACTORY RESET command.