Secure Secrets Distribution

As an additional service for sizable orders, Yubico offers the option for customers to purchase Custom Configuration for YubiKeys purchased. If Custom Configuration is purchased, Yubico will program the YubiKeys in a customer’s order to the customer's specifications, configuring everything from the behavior of the YubiKey to the secret data used to generate and validated One-Time Passwords.

For the secure transfer of YubiKey secrets, Yubico employs a PGP Public/Private Key Pair schema, using Public Encryption keys provided by customers to encrypt secret data before sending it. OpenPGP is an open standard available as free software for Windows, MacOS and Linux.

This document will outline the process of installing the necessary software to generate the PGP Public and Private key pairs, the creation of the Key Pairs themselves, and the Decryption of files received from Yubico encrypted with the provided public Key.

This document assumes the customer’s organization does not already have an OpenPGP key policy or HSM. Customers should check with their IT departments to ensure procedures are not already in place.

Setting up the OpenPGP Environment

Regardless of the platform OS (Windows, MacOS or Linux), there are best practices to consider for the computer on which the OpenPGP platform will be installed.

When generating an OpenPGP Public/Private key pair, care should be taken to ensure the Private Key is not exposed to unauthorized entities, and that both the Public and Private Keys are stored so they cannot be deleted or lost.

It is recommended to use a clean computer with a fresh install of the OpenPGP application to be the host machine for generating a key pair. Once generated, the Public key can be exported to a thumb drive or shared on a network - the Private Key should be kept only on the host computer or on a secured physical memory storage, such as a CD or secured thumb drive. Any physical memory storage holding the Private Key should be treated as a company sensitive document and secured along with other mission-critical documentation, such as in a safe.

The host machine will need to be able to read from either network storage securely or off removable drives. It is recommended that if the device is connected to a network, access is limited to internal resources only, and communication to the wider internet is prohibited.

Should the host machine be part of a regular data back-up, the backup data should be secured with the best practices recommended by the archiving solution for other sensitive and critical data.

If the OpenPGP Private Key is lost or otherwise inaccessible, customers will no longer be able to decrypt their previous YubiKey secrets files. This may impact recovery efforts is the authentication solution using the YubiKeys experiences data loss. Should the loss of the OpenPGP Private occur, it is recommended to inform Yubico with a newly generated OpenPGP Public key on the next YubiKey order to ensure the old OpenPGP Public Key is not used.

If the OpenPGP Private key is compromised, it is recommended to immediately consider and implement steps to mitigate any attacks attempting to use the YubiKey secrets for the customer’s order to compromise user verification. These steps include, but are not limited to, securing all encrypted copies of secret data provided by Yubico, monitoring YubiKey authentication and identifying out-of-character login behaviors, to a re-issuance of new YubiKeys using a different PGP key pair to all users. As all mitigation options involve significant time, effort and resources to be effective, it is highly recommended to ensure the OpenPGP Private key remains secure.

Windows: Installation

For installing OpenPGP on the Windows environment (Win7 to Win10), this document covers the open source tool Gpg4win.

1. First, download the open source windows application Gpg4win from: http://gpg4win.org/download.html.
2. Install Gpg4win selecting the default options, making sure the following components are installed:

• GnuPG
• Kleopatra
• GpgOL
• GpgEX

3. Select the location to install the Gpg4win application

4. Finish the default installation of the gpg4win application.

Windows: Creating a Public/Private Key Pair

To ensure YubiKey secrets can only be accessed by the customer who purchased the corresponding YubiKeys, Yubico requests that customers provide a Public Key which can be used to encrypt files containing secret information. The provided public key will ensure that only the customer who created the Public/Private key pair will be the only entity who can decrypt the files encrypted in such a manner.

To generate a Public/Private Key pair and provide the Public Key to Yubico, follow the steps below:

1. Launch Kleopatra (Start > All Programs > Gpg4win > Kleopatra)

2. In Kleopatra, start the process to generate a new Public/Private key pair by selecting “File > New Key Pair”.

3. In the opening page of the Certificate Creation Wizard, select the option Create a personal OpenPGP key pair

4. In the provided fields, enter your name and email address. Once the requested information has been entered, click Next. A full first and last name as well as a complete email address is not required, but very useful in identifying the owner of the key pair. 
   
   If you want to change the key size or expiration date, click Advanced Settings…. The Yubico Programming station supports RSA Keys, so limit the key material to RSA and +RSA, with key sizes up to 4096 bits. Ensure the key sizes for RSA and +RSA are identical. The lifetime of the key pair can also be set on this dialog; it is recommended to have a lifetime of at least 2 years unless security policies require a shorter time frame.
   

5. On the next page, confirm the listed parameters are correct and click Create.

6. Enter and confirm a passphrase of at least 8 characters, containing at least 1 letter, number and symbol. Record this passphrase in a safe location – files encrypted with this Public/Private Key Pair will not be able to be decrypted without this passphrase.
   

7. After successfully creating the Key Pair, click  Finish. Once created, the Key Pair will be listed in the main menu under the “All Certificates” tab.
   

Once the Public/Private Key Pair has been created, you will need to export the Public Key and send it to Yubico.

In the main menu, right click the newly created Certificate and select Export. This will create a copy of the Public Key which can be used to encrypt a file, but not decrypt it. The files encrypted with this Public Key can be decrypted with the Private Key stored on the originating computer. 

When Exporting the Public Key, it is recommended to name it with the Business or Company Name followed by the Contact Name and Date to easily identify it. Once generated, the file can be sent via email to Yubico.

DO NOT remove or delete the key pair in Kleopatra without first backing it up in a safe location. This can be done by right clicking the certificate and selecting the “Export Secret Keys” option along with the “Export” option. The file exported is your private key, do NOT compromise it by sending it over an insecure line of communication, such as email or an unsecured network. Note that the Passphrase will also need to be recorded, as the private key will not work without it.

If the certificate or secret key become lost or deleted, encrypted files sent from Yubico will not be able to be decrypted.

Windows: Validating Fingerprints

After sending a Public Key to Yubico, it is important to verify the key file received matches the one sent, and confirm it was not tampered with or replaced in transit. The simplest method to do so is to verify the fingerprint - this is normally done over a different communication channel then how the key was sent, like a telephone call.

To display the fingerprint of a key, right click the key pair in the main menu and select Details 

The Details dialog will display the Fingerprint of the key pair. Use this value to verify that the key sent to Yubico matches the one generated. 

Importing Yubico Keys for Validation

Encrypted files sent from Yubico will be “signed” with the Private Key for the programming station which the YubiKeys were configured on. By verifying the signature of the Yubico Programming station using the Yubico Public Key, the validity of the file being sent can be confirmed.

A new instance of OpenPGP may require the user to configure it to communicate with the Public Key storage server. This can be done following the steps below:

1. In Kleopatra, select the Configure Kleopatra screen (Main Menu > Settings > Configure Kleopatra) 
   

2. The Configure Kleopatra window will open to the Directory Services tab. Verify there is an entry in the OpenPGP keyserver for "hkp://keys.gnupg.net:11371". If this entry is not present, type it and click OK. NOTE: If the "hkp://keys.gnupg.net:11371" is not working for you please try “hkps://pgp.mit.edu” to look up the production keys instead.
   

3. In Kleopatra, click open the Certificate Server Certificate Lookup screen (Main Menu > File > Lookup on Server). 
   

4. In the Certificate Server Certificate Lookup screen, locate the "Find" field at the top and type in "KeyGen production@yubico.com", then click the Search button. This will display a list of all Yubico Programming Station Certificates.
   

5. Select all the servers and click Import. This will import the public key for the Yubico Programming stations, allowing you to verify the Yubico signatures.
   

When successful, seven Yubico KeyGen certificates should be imported. You can verify the fingerprints of each certificate using the following information:

Active Yubico KeyGen certificate fingerprints

• Keygen US #3 - FFE8FB5035408327E59237E2D70811785BF689D4
• Keygen US #5 - 896AD40A3DE4210CE8C788EF412C88CAD2C93633
• Keygen SE #1 - 9C65D7EFBEC6B380C6509343BCA6E8809D37E0C0

Windows: Decrypting Files Encrypted with a Public Key

When receiving files from Yubico which have been encrypted with the provided Public Key, they will need to be decrypted with the same certificate as the public Key was generated from.

1. Launch Kleopatra and select Decrypt/Verify files (Main Menu > File> Decrypt/Verify) 
   

2. In the file browser that opens, select the Encrypted file provided by Yubico.
   

3. A prompt will ask for the passphrase associated with the private key. Enter the passphrase set when creating the original certificate.
   

4. The encrypted file will be successfully decrypted, with the signature verified. Click Save All to save the secrets file in plain text.
   

Notes To Remember:

• Always store your generated certificates and passphrases in a safe location to ensure that files received from Yubico can be decrypted.
• Make sure only to send out the Public Key (Export) and NEVER the private key (Export Secret Keys).
• Make sure to only send out a public Key that corresponds to a private key you have on record.