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 (Win10 to Win11), 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

4. Select the location to install the Gpg4win application
5. Finish the default installation of the Gpg4win application.

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 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. Open Kleopatra
2. In Kleopatra, start the process to generate a new Public/Private key pair by selecting File > New Key Pair.
3. Add your name and e-mail address to the respective fields, check the box next to Protect the generated key with a passphrase, and then click Advanced Settings...
4. Under Key Material, select RSA, change the dropdown to 4,096 bits, and then click OK. 
5. Click OK again.
6. When the pinentry-qt window appears, enter the passphrase to protect using the private key of your new key pair, enter it again in the Repeat field, and then click OK.
7. Once the Success message appears, click OK.

Export your public key and send to Yubico

1. 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. 
   

    Note: 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.

2. Create a new email addressed to address specified in your order form, attach the exported public key, and send it.

 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
    Export Secret Keys, along with the “Export” option. The file exported is your
    private key, so 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.

Validating Fingerprints

After sending your 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 of 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, open 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 hkps://keyserver.ubuntu.com. If this entry is not present, enter it and click OK.

  NOTE:  If the Ubuntu keyserver (hkps://keyserver.ubuntu.com) is not working for
            you, try either the GnuPG keyserver (hkps://keys.gnupg.net) or the 
            MIT keyserver (hkps://pgp.mit.edu) to look up the production keys.

3. In Kleopatra, click Lookup on Server. 
4. In the Lookup on Server - Kleopatra window, locate the Find field at the top and type in KeyGen production@yubico.com and then click the Search button. This will display a list of all active Yubico Programming Station Certificates.
   
5. Hold the Ctrl key on your keyboard, select all of the Yubico production servers, and then click Import. This will import the public key for the Yubico Programming stations, allowing you to verify the Yubico signatures. When successful, four Yubico KeyGen certificates should be imported (two from the US, two from Sweden). You can verify the fingerprints of each certificate using the following information:
   
   
   • Keygen US #3 - FFE8FB5035408327E59237E2D70811785BF689D4
   • Keygen US #5 - 896AD40A3DE4210CE8C788EF412C88CAD2C93633
   • Keygen SE #1 - 9C65D7EFBEC6B380C6509343BCA6E8809D37E0C0
   • Keygen SE #3 - 74CC67DA1F743A25DCAB9F7E394BAD7145106C6F

    Note: The certificate fingerprint is not the same as the Key-ID shown in the 
             Certificates list. To verify each fingerprint, you will need to right 
             click on each certificate and select Properties - the fingerprint will
             be displayed in the OpenPGP Certificate - Kleopatra window.

6. Finally, you'll need to right-click on each of the four imported certificates (one at a time) and select Certify.

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. 

2. In the Select One or More Files to Decrypt and/or Verify window, select the encrypted file provided by Yubico and then click Open.

3. In the pinentry-qt window that appears, enter the passphrase used when you created the public/private key pair and click OK.

4. Click Save All to save the secrets file in plaintext.
   

Additional notes

• 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 and NEVER the private key.
• Make sure to only send out a public key that corresponds to a private key you have on record.