Secure Channel Protocol (SCP03 and SCP11)
Yubico Secure Channel Technical Description
Introduction
Yubico has implemented a subset of the (GlobalPlatform Secure Channel Protocol 03) specification, specifically, the most secure implementation including command and response message authentication code (MAC) and encryption. This is available in YubKey firmware 5.3.0 and later.
Yubico has implemented a subset of the (GlobalPlatform Secure Channel Protocol 11) specification, specifically, the most secure implementation including command and response message authentication code (MAC) and encryption. This is available in YubKey firmware 5.7.0 and later.
At the highest level, implementing a secure channel consists of providing overhearing and tampering resistance to information sent between an external service, like a Credential Management Solution (CMS) and a smart card. Overhearing resistance is provided by using a unique, private symmetric AES key to apply AES encryption on all commands sent and received. Tamper resistance is provided by using an AES key, unique to each session, to send a securely encrypted MAC of both the commands and associated responses. Since these protections are applied to the data at the endpoints of the communication channel, a standard CCID interface can be used without modification, supporting native flows in Windows, Linux, and other systems.
On the YubiKey, all of the secure channel operations occur within the secure cryptographic processor. The plain text of the communication is never exposed to outside observers.
Flow when Initializing a Secure Channel on a YubiKey
YubiKey Secure Channel Support
The YubiKey Secure Channel implementation is separate from the rest of the functionality on the YubiKey. It is only active when a secure channel is established. It sits between the input of APDU commands sent into the secure element and the applications on the YubiKey. As such, any command that can be sent as an APDU over CCID can use secure channel, regardless if it is for PIV, OTP or other supported functions. The only exceptions are the FIDO protocols (U2F/WebAuthn), because they do not support communication over the CCID channel.
The SCP11 addition is compatible with existing SCP03 setups, however the long lived encryption keys are symmetric when using SCP03 (AES-128) and asymmetric when using SCP11 (ECC P-256).
Transport Keys and Session Keys
| Key | Usage | Creation |
|---|---|---|
Static Secure Channel
Encryption Key
(Key-ENC)
|
Generate session key
for Decryption/
Encryption
(AES-128)
|
Imported from
Trusted source
|
Static Secure Channel
Message Authentication
Code Key (Key-MAC)
|
Generate session key for
Secure Channel
authentication and Secure
Channel MAC Verification
and Generation (AES-128)
|
Imported from
Trusted source
|
Data Encryption Key
(Key-DEK)
|
Sensitive Data Decryption
(AES-128) used to
encrypt other Transport
key sets on import
|
Imported from
Trusted source
|
Session Secure Channel
Encryption Key (S-ENC)
|
Used for data
confidentiality
|
Dynamically
Created Per
Session
|
Secure Channel Message
Authentication Code
Key for Command (S-MAC)
|
Used for data and
protocol integrity
|
Dynamically
Created Per
Session
|
Secure Channel Message
Authentication Code
Key for Response
(S-RMAC)
|
User for data and
protocol integrity
|
Dynamically
Created Per
Session
|
The Yubico Secure Channel uses two types of AES-128 or ECC P-256 keys as defined in the SCP03 or SCP11 specifications, respectively; these are organized in the static, externally sourced and imported transport keys, and the dynamic, internally generated session keys. The YubiKey can hold up to 3 transport key sets, and generates unique session keys for each session.
Transport Keys
A Transport Key set is made of 3 AES-128 or ECC P-256 keys:
- Secure Channel Encryption Key (KEY-ENC)
- Secure Channel Message Authentication Code Key (Key-MAC)
- Data Encryption Key (Key-DEK)
Transport key sets are used for establishing the secure channels and are protected in the SCP03 security domain in the secure element. A transport key set contains three long-lived keys, imported from an external source. When a session is established, the session keys are derived from the long-lived transport key set.
The YubiKey security domain can store three concurrent long-lived transport key sets. To import new transport key sets, establish a secure channel with the security domain. Do this with either a previously loaded transport key set or the default transport key set.
When initializing a session, the Secure Channel Encryption Key is used to generate the Session Secure Channel Encryption Key for use during that session. Similarly, the Secure Channel MAC Key is used to generate the Session Secure Channel MAC key for the Command and Session Secure Channel MAC Key for Response. The Data Encryption Key is only used when importing new transport key sets; the imported keys must be encrypted with a known Data Encryption key.
The Transport keys are imported from a CMS or HSM over an established secure channel. YubiKeys are shipped with either default values for the transport keys, or values derived from a Batch Master Key set at programming. Transport keys can and should be rotated on a regular basis depending on the threat model for the organization. Once overwritten on a YubiKey, Transport keys cannot be restored, so they should be archived, on the CMS if necessary.
Session Keys
The Session Key set is made of 3 AES-128 or ECC P-256 keys:
- Session Secure Channel Encryption Key (S-ENC)
- Secure Channel Message Authentication Code Key for Command (S-MAC)
- Secure Channel Message Authentication Code Key for Response (S-RMAC)
Session keys are all dynamically generated at the start of each session, using the Secure Channel Encryption and MAC Transport Keys, as well as the challenge sent from the client at the session start. For more details, refer to the GlobalPlaftorm Secure Channel Protocol (SCP) 03 specification, section 4.1.5.
Every command sent over a secure channel between a client or CMS and a YubiKey is encrypted with the Session Secure Channel Encryption Key. Further, each command from the client has a MAC generated from the contents of the encrypted command APDU and the Session MAC key for Command. This MAC value is used to verify the authenticity of the command sent. Each command MAC value is based off the previous command MAC, enabling a chain that can be verified to ensure the data was not tampered with in transit, nor is a command being replayed.
The Response MAC is generated using the encrypted response APDU from the YubiKey and the Session MAC key for Response. Each Response MAC also includes a value derived from the original command MAC sent from the client, providing a verification that the data included in the response corresponds to the last command sent.
Establishing a Secure Channel
A client connecting to any CCID function on the YubiKey can establish a secure channel at the start of a session. Once a session is started with a secure channel, all communication to and from the YubiKey over that session must be encrypted. Sending a command in plain text will not be accepted and immediately ends the session and removes any previously granted authorizations.
The AID to access the Secure Channel functionality on the YubiKey is A000000308. The EXTERNAL_AUTHENTICATE command with security level C-DECRYPTION, R-ENCRYPTION, CMAC and R-MAC is the only supported option.
To begin, the client identifies the function they wish to communicate with and sends the Initialize Update command.
YubiKey Secure Channel Initialize Update Flow
| Step 1: | When a client starts the process of establishing a secure channel with the YubiKey, it selects the Transport key set on the YubiKey to be used, and generates a unique challenge. This challenge is used by the client to derive the session keys that are used going forward. The |
|---|---|
| Step 2: | When the YubiKey receives an The Secure Channel Function uses the Transport Key Identifier to select the Transport Key set in memory to use. The YubiKey derives the Session keys for Encryption and MAC by generating a card challenge, then using that plus the challenge provided from the client and the selected Transport Key set. The YubiKey then generates a command MAC from the previously internally generated card challenge using the Session Command MAC key (S-MAC). The card challenge from the YubiKey and associated MAC are sent back to the client. |
| Step 3: | When the client receives the response from the YubiKey, it derives the session keys using the transport key set, the original challenge, and the card challenge from the YubiKey. The client then verifies the MAC using the session keys it had generated. Upon a successful verification, the client can be confident that the YubiKey has generated matching session keys. However, at this point, the YubiKey does not know if the client has the correct key set. |
To authorize the YubiKey to accept commands from the client, run the External Authenticate command. Security level C-DECRYPTION, R-ENCRYPTION, CMAC and R-MAC is the only supported option.
YubiKey Secure Channel External Authenticate flow
| Step 1: | The External Authenticate flow starts with the client receiving the card challenge from the YubiKey created during the Initialize Update command. From that point, the client defines the session security settings - the YubiKey only supports the strictest option, with both commands and responses encrypted and associated MACs generated. As with the Initialize Update flow, the client creates a challenge and encrypts it with the session encryption key. However, a MAC value from the previous challenge is also created and appended to the challenge, creating a chain of commands to be tracked. The Challenge and MAC chain value are then used to create a command MAC using the S-MAC key, and both are sent to the YubiKey. |
|---|---|
| Step 2: | The YubiKey receives the External Authenticate command, and verifies the Challenge using the MAC value and S-MAC key. The MAC Chain is then verified, confirms that the client has the same session keys and that a secure channel has been created. Then the challenge is decrypted using the S-ENC key and a response is created. In addition, the challenge from the client is used to create a new MAC chain value, which is appended to the response. |
| Step 3: | The response and MAC Chain value are used to generate a response MAC using the S-RMAC key. Then the response and associated MAC are sent from the YubiKey back to the client. Then the response MAC is verified using the S-RMAC key, the MAC Chain value is verified against the command sent previously, and the response is decrypted. |
At this point, a secure channel has been established between the client and the YubiKey.
Communicating Over Secure Channel
Communicating Over Secure Channel Flow
When Command APDU is sent over an established secure channel, the Yubico Secure Channel follows an encrypt then MAC approach.
| Step 1: | The command APDU is first encrypted using the Session Encryption Key (S-ENC). Sending an unencrypted command ends the current session and removes any authorizations. Important Any APDU delivering instructions or data, such as a key or certificate, to a YubiKey is considered a Command APDU. |
|---|---|
| Step 2: | A command MAC is created using the Session MAC key (S-MAC), the encrypted APDU, with a MAC chain value created from the previous Command MAC. This is sent to the YubiKey. |
| Step 3: | The YubiKey verifies the command MAC, then verifies the MAC Chain links to the previous command sent. |
| Step 4: | With the MAC values verified, the command is decrypted and passed to the YubiKey functionality. A response from the function called in the communication is returned. |
| Step 5: | The response is encrypted with the S-ENC key, then a MAC chain value is derived from the command appended to it. The response and chain MAC value are used with the Session Response MAC key to generate a response MAC. The Response and Response MAC are sent back to the client. |
| Step 6: | The client performs the same operations, verifying the response MAC, verifying the MAC chain, then decrypting the response. The Response APDU are passed to the client. |
Yubico Secure Channel Key Diversification and Programming
Introduction
The term key diversification refers to the process of deriving a secure channel static transport key set from a Batch Master Key (BMK), the YubiKey identifier (part of serial number), and additional metadata.
Benefits and Usage
Key diversification enables simplified and secured distribution of secure channel transport key sets because only the Batch Master Key must be shared with the CMS system to derive the YubiKey transport key sets.
Hence, the secure channel transport key sets can be pre-programmed by Yubico, assuming that Yubico has access to the BMK of the CMS vendor.
Another option is for the CMS system to generate the secure channel transport key sets based on the YubiKey serial number, the BMK, and additional metadata. The CMS can then use the initial secure channel transport key set for writing additional secure channel transport key sets to the YubiKeys.
SCP03 Key Diversification
Secure Channel and Security Domains
The YubiKey supports up to three secure channel transport key sets. This is to enable more granular control over the establishment of a secure channel to a specific device. The keys in each of these key sets can be overwritten when connected to the YubiKey. This allows for YubiKeys to be shipped with a default key set, then have the key set be changed to a random set of keys at initialization. .This in turn, ensures that only the CMS server has the actual keys.
Key Diversification Option
When purchasing YubiKeys from Yubico, there is an option to custom-configure the transport keys from the default values to values derived from details specific to the hardware and a BMK. This means these keys can be distributed with locked down key sets, and that ensures they cannot be connected to remotely by third parties. The BMK is generated and owned by the customer, who in turn can provide it to Yubico and their CMS deployment. The CMS can then use the BMK to establish a secure channel to a customer’s YubiKeys, and set new transport keys during initialization. This limits access to just that CMS. As with other custom configuration options, these keys can be overwritten or deleted by the customer; the keys are not “baked into” the YubiKey firmware.
Batch Master Key (BMK) Generation
Each custom order with diversified keys has a unique BMK. This is used when Yubico programs the keys. A BMK is a 32-bit AES key that Yubico recommends the customer generate in a secure manner approved by their own internal security department. The YubiHSM 2 can be used to generate a random AES key with the GET PSEUDO RANDOM command, for example: get random 0 32.
For more information, see the YubiHSM 2 User Guide, Command Reference for the GET PSEUDO RANDOM command.
Before every order with key diversification, the customer must generate and provide the BMK to Yubico by a secure means. After the YubiKeys are programmed using the BMK provided, the BMK on the Yubico programming station is destroyed. This ensures the customer has the only extant BMK. The customer must maintain and securely archive their BMK for use with future orders.
Key Diversification Function (KDF)
The diversification function used is the AES-CMAC-KDF Counter Mode derivation algorithm specified in NIST SP800-108.
Scroll horizontally to see the diversified key in this code sample:
AES CMAC of [ Counter (1 byte) || Label (4 bytes) || 00 ||
Context (10 bytes) || Key Length in bits (2 Bytes) ]
Note
AES256 and 3DES keys require two rounds of KDF. They are used to generate a 32-byte key value and 24-byte key value respectively. The first KDF has a counter value set to 01 and the second SDK has a counter value set to 02.
The Key Length in the KDF input field is expressed in hexadecimal value. It is:
0100for a 256-bit key00C0for a 192-bit Key (PIV Admin Key)0080for a 128-bit key (ISD Keys & Interfaces Management Key)0040for a 64-bit code (the PUK)
Labels for Key Diversification
The KDF function of separating keys uses the following labels as input. Note that these are example values, using: Yubikey 5 Series implementation with ISD Keys as 16-byte values, YubiKey Interfaces Management Key as a 16-byte value, the PIV Admin Key as a 24-byte value, and the PUK as an 8-byte value.
| Factory Key Codes | Key Length in bits | KDF Label |
|---|---|---|
| Issuer Security Domain DAK (Authentication Key) | ‘0080’ | ‘00000001’ |
| Issuer Security Domain DMK (MAC Key ) | ‘0080’ | ‘00000002’ |
| Issuer Security Domain DEK (Encryption Key) | ‘0080’ | ‘00000003’ |
| PIV Application Administrative Key | ‘00C0’ | ‘00000004’ |
| PIV Application PUK | ‘0040’ | ‘00000007’ |
| Capabilities Lock Code (YubiKey Interfaces Management Key) | ‘0080’ | ‘00000010’ |
In general the Key Length should be derived from the listed values:
| Key Size | Key Length in Bits |
|---|---|
| 32 Bytes | ‘0100’ |
| 24 Bytes | ‘00C0’ |
| 20 Bytes | ‘00A0’ |
| 16 Bytes | ‘0080’ |
| 8 Bytes | ‘0040’ |
Context for Key Diversification
The value of the Context field in the KDF input data is the Issuer Context and is equal to the first 10 bytes of the value returned from the Global Platform INITIALIZE UPDATE command.
PUK Generation from Diversified Value
We use the trailing 8 bytes of the diversified value and generate the PUK using the pseudocode below. Scroll horizontally to see the full line, if needed.
for (int i = 0; i < 8; i++) { diversifiedVal[i] = (byte)
(0x30 + ((diversifiedVal[i] & 0x7F) % 10));}
Global Platform: CPLC Data
Description
Although this format is officially deprecated and not part of the Global Platform specification, some organizations need support for the information stored in the so-called CPLC (Card Production Life Cycle).
This consists of a static set of bytes that can be retrieved with a GET DATA command (INS 0xca) and TAG 0x9f7f after selecting the SD application.
The response is 42 bytes that can be parsed into different fields with different meanings. However, Yubico does not attribute any specific meaning to 40 of those bytes. Only the first two bytes are meaningful.
Example Command
To retrieve the value use the command: Scroll horizontally, if needed.
opensc-tool -c default -s '00a4040008a000000151000000' -s '00ca9f7f'
Relevant Output
40 90 73 F9 53 94 C0 01 23 D8 E9 F0 68 3A 48 9A @.s.S...#...h:H.
76 30 4C D8 F6 CC 41 66 61 0F C4 F5 8C DE D6 93 v0L...Afa.......
77 32 09 82 1B EA 0C 78 3D 8B w2.....x=.
Of those 42 bytes, only the first two (40 90) are meant to signify an Infineon SLE 78 chipset, the rest are random bytes generated when the SD application is (re)initialized.
Yubico SCP03 Developer Guidance
This section describes how Secure Channel Protocol 3 (SCP03) works in the YubiKey. It is intended for developers integrating support for it.
Introduction
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:
- C-MAC
- C-ENC
- R-MAC
- R-ENC
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. It does set up a mutually authenticated and encrypted channel between the YubiKey and the host. Unencrypted commands sent over the secure channel end the session and revokes any previously issued authorizations.
For more details on SCP03, refer to the Global Platform SCP03 specifications.
Key Sets
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. Manipulating the individual keys within the set, is not allowed.
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 and the value 404142434445464748494a4b4c4d4e4f for all three keys. These keys 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 (for example, 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, send the delete instruction with p2=1.
Sessions
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’d in its entirety. If the data exceeds the capacity of a single message, it is chunked for transport.
CPLC
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 ascribed to any of the fields.
Software
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
GlobalPlatformPro is a Java library and tool for interacting with smart cards supporting the Global Platform secure channel protocols.
Examples
Some of the following examples are long lines of code. Scroll horizontally, as needed.
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
Gpshell is a C library and tool for interacting with the secure channel protocols.
Examples
Gpshell works with scripts. The following code is an example of opening a channel with the YubiKey. Scroll horizontally to see the last line of code in its entirety, as needed.
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