Yubico SCP03 Developer Guidance
This section describes how Secure Channel Protocol 3 works in the YubiKey for developers integrating support for it.
SCP03 is a protocol from Global Platform for mutual authentication and encrypted transport using smart cards. The protocol allows for the following modes of encryption and authentication of data:
- R-MAC, and
The YubiKey implements this with all of them turned on; turning anything off is not an option.
Authenticating with SCP03 does not assign any specific permissions in the YubiKey; what it does is set up a mutually authenticated and encrypted channel between the YubiKey and the host. Unencrypted commands sent over the secure channel will end the session, revoking any previously issued authorizations.
For more details on SCP03, refer to the Global Platform SCP03 specifications.
A key set contains three long-lived keys, the encryption key (Key-ENC), the mac key (Key-MAC), and the data encryption key (Key-DEK). When a session is established, the session encryption key is derived from the ENC key, while the session mac keys are derived from the MAC key. Any new key sets transported over the session are encrypted with the DEK.
The YubiKey only allows putting or deleting a whole key set at a time, not manipulating the individual keys within the set.
Each key set is identified by the key version defined when the set is imported into the YubiKey. Each individual key also has an id, but that serves solely to identify the specific key within the set - ENC, MAC or DEK. The key version number is required for addressing the correct set. 255 is the factory default version and therefore that version number is reserved. When importing a key set, the version is set to a value in the range 1-254.
The YubiKey can store up to three key sets at a time. By default there is one key set installed with key version 255 having the value
404142434445464748494a4b4c4d4e4f for all three keys, which are known as the test keys. When a new key set is installed, it replaces the default key set. The YubiKey supports only AES-128 for all three keys.
When authentication with a key set fails repeatedly (i.e., 32 times in a row) that key set is deleted. When the last key set is deleted, the security domain is automatically reset with the default key set installed. To delete the last key set on purpose and force a reset, the delete instruction is sent with
The session is established only within the scope of the currently selected applet. When a new applet is selected, the session is terminated. To manage SCP03 keys, a session needs to be established with the AID
a000000151000000 - the Issuer Security Domain.
When a large amount of data is to be transported over the session, it is encrypted and mac’ed in its entirety. If the data exceeds the capacity of a single message, it is chunked for transport.
The security domain contains an entry called CPLC which identifies a specific device. On a YubiKey, this entry is filled with random data on first boot. No significance is to be ascribed to any of the fields.
Yubico has conformed to the Global Platform Open Standard, and as such, has developed the SCP03 support on the YubiKey to be compatible with open source offerings.
GlobalPlatformPro is a Java library and tool for interacting with smartcards supporting the GlobalPlatform secure channel protocols.
Some of the following examples are long lines of code; for those, you might have to scroll horizontally.
Open a channel with the security domain and print information
$ java -jar tool/target/gp.jar --mode mac --mode enc --mode rmac --mode renc --debug --info
Open a channel with the security domain and install a new key set
$ java -jar tool/target/gp.jar --mode mac --mode enc --mode rmac --mode renc --debug --lock 000102030405060708090a0b0c0d0e0f
Open a channel with the PIV applet and verify the PIN over the channel
$ java -jar tool/target/gp.jar --mode mac --mode enc --mode rmac --mode renc --debug --sdaid a000000308000010000100 -s 0020008008313233343536ffff
Gpshell is a C library and tool for interacting with the secure channel protocols.
Gpshell works with scripts; here is an example of opening a channel with the YubiKey. To see the last line of code in its entirety, scroll horizontally.
enable_trace mode_211 establish_context card_connect select -AID a000000151 open_sc -enc_key 404142434445464748494a4b4c4d4e4f -mac_key 404142434445464748494a4b4c4d4e4f -kek_key 404142434445464748494a4b4c4d4e4f -security 51 -scp 3 -scpimpl 96