Secure Channel Specifics
Yubico Secure Channel Technical Description
Introduction to Yubico Secure Channel
Yubico has implemented a subset of the (GlobalPlatform Secure Channel Protocol 03) Secure channel specification: specifically, only the most secure implementation including command and response message authentication code (MAC) and encryption.
At the highest level, implementing a secure channel consists of providing overhearing and tampering resistance to information being sent between an external service, like a Credential Management Solution (CMS) and a smart card. Overhearing resistance is accomplished by the AES encryption of all commands being sent and received by use of a unique, private symmetric AES key. Tamper resistance is included by sending a securely encrypted MAC of both the commands and associated responses using an AES key unique to each session. 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, with the plain text of the communication 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 and sits between the input of APDU commands sent into the secure element and the applications on the YubiKey. As such, any command which 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), as they do not support communication over the CCID channel.
Transport Keys and Session Keys
| Key | Usage | Creation |
|---|---|---|
Static Secure Channel
Encryption Key
(Key-ENC)
|
Generate session key
for Decryption/
Encryption (AES)
|
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)
|
Imported from
Trusted source
|
Data Encryption Key
(Key-DEK)
|
Sensitive Data Decryption
(AES) used for encryption
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 keys as defined in the SCP03 specifications; 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 keys:
- Secure Channel Encryption Key (KEY-ENC)
- Secure Channel Message Authentication Code Key (Key-MAC)
- Data Encryption Key (Key-DEK)
The transport key sets used for establishing the secure channels 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. In order to import new transport key sets, a secure channel must be established with the security domain. This has to be done with a previously loaded transport key set or the default transport key set.
The Secure Channel Encryption Key is used when initializing a session to generate the Session Secure Channel Encryption Key to be used during that session. Likewise, the Secure Channel MAC Key is used to generate the Session Secure Channel MAC key for Command and Session Secure Channel MAC Key for Response. The Data Encryption Key is only used when importing new transport key sets; the keys to be imported 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 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 GP SCP03 spec, 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 which can be verified to ensure the data was not tampered 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 has been 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 end the session, removing any authorizations granted previously.
To begin, the client will identify the function they wish to communicate with and send 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 will select the Transport key set on the YubiKey to be used, as well as generating a unique challenge. This challenge will be used by the client to derive the session keys which will be utilized going forward. The Initialize Update command is sent from the client, which includes the challenge and Transport Key set identifier, to the YubiKey’s CCID function they want to establish a secure channel with. |
|---|---|
| Step 2: | The YubiKey, upon receiving an Initialize Update command when a client is starting a session with any CCID facing function, will direct communication between a client and the YubiKey to the Secure Channel function for the remainder of the session. The Secure Channel Function will use the Transport Key Identifier to select the Transport Key set in memory to use. The YubiKey will generate a card challenge and use it, along with the challenge provided from the client, to derive the Session keys for Encryption and MAC using the selected Transport Key set. The YubiKey will then generate 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: | The client, upon receiving the response from the YubiKey, 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, the External Authenticate command must be run next.
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 will define the session security settings - the YubiKey only supports the strictest option, with both commands and responses encrypted and have 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, confirming that the client has the same session keys and a secure channel has been created. At that point, 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. At this point, 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). It is important to note that any APDU delivering instructions or data (such as a key or certificate) to a YubiKey is considered a Command APDU. Sending an unencrypted command will end the current session and will remove any authorizations. |
|---|---|
| Step 2: | A command MAC is created using the Session MAC key (S-MAC) using the encrypted APDU along 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 being communicated with is returned. |
| Step 5: | The response is encrypted with the S-ENC key, then has a MAC chain value 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. |
To get in touch with Yubico Support, click here.
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 as 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 3 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 once connected to the YubiKey, allowing for a YubiKeys to be shipped with a default key set, then have the key set be changed to a random set of keys at initialization, ensuring 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 to values derived from details specific to the hardware and a BMK. This means these keys can be distributed with locked down key sets, ensuring 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, limiting access to just that CMS. As with other custom configuration options, these keys can be overwritten or deleted by the customer; they are not “baked into” the YubiKey firmware.
Batch Master Key (BMK) Generation
Each custom order with diversified keys has a unique BMK, which 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 YubiHSM2 can be used to generate a random AES key with the GET PSEUDO RANDOM command, e.g. get random 0 32. For more information, see this command in the HSM 2 Commands reference guide.
Before every order with Key Diversification, the customer will generate and provide the BMK to Yubico by secure means. After the YubiKeys have been programmed using the BMK provided, the BMK on the Yubico programming station is destroyed, leaving the customer with the only extant BMK. The customer must maintain and securely archive their BMK if required for 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 on the next line:
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 to generate a 32-byte key value and 24-byte key value respectively, the first one with a counter value set to 01 and the second one with a counter value set to 02.
The Key Length in the KDF input filed is expressed in hexadecimal value. It is:
0100for a 256-bit key,00C0for a 192-bit Key (e.g. PIV Admin Key),0080for a 128-bit key (e.g. ISD Keys & Interfaces Management Key) and0040for a 64-bit code (e.g. the PUK).
Labels for Key Diversification
The KDF function of separating keys uses the following labels as input. Note that these are example values, keeping 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 table below.
| 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. In the HTML version of this guide, you may need to scroll horizontally to see the full line.
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 GlobalPlatform 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 can 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 elected not to attribute any specific meaning to 40 of those bytes. Only the first two bytes are meaningful.
Example Command
To retrieve the value (scroll horizontally if necessary):
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.
To get in touch with Yubico Support, click here.
Yubico SCP03 Developer Guidance
This section describes how Secure Channel Protocol 3 works in the YubiKey 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, and
- 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; 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.
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, 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 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’ed 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 to be 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 smartcards supporting the GlobalPlatform secure channel protocols.
Examples
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
Gpshell is a C library and tool for interacting with the secure channel protocols.
Examples
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
References
- https://globalplatform.org/specs-library/card-specification-v2-3-1/
- https://globalplatform.org/specs-library/secure-channel-protocol-03-amendment-d-v1-2/
- https://github.com/martinpaljak/GlobalPlatformPro/
- https://sourceforge.net/projects/globalplatform/
- https://sourceforge.net/p/globalplatform/wiki/GPShell/
To get in touch with Yubico Support, click here.
To get in touch with Yubico Support, click here.