PutKeySet Method

PutKeySet(StaticKeys)

Put the given key set onto the YubiKey.

C#

public void PutKeySet(StaticKeys newKeySet)

Parameters

Type	Name	Description
StaticKeys	newKeySet	The keys and KeyVersion Number of the set that will be loaded onto the YubiKey.

Exceptions

Type	Condition
System.ArgumentNullException	The newKeySet argument is null.
Yubico.YubiKey.Scp03.SecureChannelException	The new key set's checksum failed to verify, or some other error described in the exception message.

Remarks

See the User's Manual entry on SCP03.

On each YubiKey that supports SCP03, there is space for three sets of keys. Each set contains three keys: "ENC", "MAC", and "DEK" (Channel Encryption, Channel MAC, and Data Encryption).

   slot 1:   ENC   MAC   DEK
   slot 2:   ENC   MAC   DEK
   slot 3:   ENC   MAC   DEK

Each key is 16 bytes. YubiKeys do not support any other key size.

Note that the standard allows changing one key in a key set. However, YubiKeys only allow calling this command with all three keys. That is, with a YubiKey, it is possible only to set or change all three keys of a set.

Standard YubiKeys are manufactured with one key set, and each key in that set is the default value.

   slot 1:   ENC(default)  MAC(default)  DEK(default)
   slot 2:   --empty--
   slot 3:   --empty--

The default value is 0x40 41 42 ... 4F.

The key sets are not specified using a "slot number", rather, each key set is given a Key Version Number (KVN). Each key in the set is given a Key Identifier (KeyId). The YubiKey allows only 1, 2, and 3 as the KeyIds, and SDK users never need to worry about them. If the YubiKey contains the default key, the KVN is 255 (0xFF).

   slot 1: KVN=0xff  KeyId=1:ENC(default)  KeyId=2:MAC(default)  KeyId=3:DEK(default)
   slot 2:   --empty--
   slot 3:   --empty--

It is possible to use this method to replace or add a key set. However, if the YubiKey contains only the initial, default keys, then it is only possible to replace that set. For example, suppose you have a YubiKey with the default keys and you try to set the keys in slot 2. The YubiKey will not allow that and will return an error.

When you replace the initial, default keys, you must specify the KVN of the new keys. For the YubiKey, in this situation, the KVN must be 1. If you supply any other values for the KVN, the YubiKey will return an error. Hence, after replacing the initial, default keys, your three sets of keys will be the following:

   slot 1: KVN=1  newENC  newMAC  newDEK
   slot 2:   --empty--
   slot 3:   --empty--

In order to add or change any key set, you must supply one of the existing key sets in order to build the SCP03 command and to encrypt and authenticate the new keys. When replacing the initial, default keys, you only have the choice to supply the keys with the KVN of 0xFF.

Once you have replaced the original key set, you can use that set to add a second set to slot 2. It's KVN must be 2.

   slot 1: KVN=1  ENC  MAC  DEK
   slot 2: KVN=2  ENC  MAC  DEK
   slot 3:   --empty--

You can use either key set to add a set to slot 3. You can use a key set to replace itself.