Import Smart Card Certificates onto your YubiKey

Before your smart card certificates can be provisioned to your iOS Keychain with Yubico Authenticator, you must first import those certificates onto a YubiKey from your host computer. This can be done through either of the following tools:

  • YubiKey Manager GUI
  • YubiKey Manager CLI

The GUI (graphical user interface) tool allows you to configure PIV functionality by clicking through a series of screens, whereas the CLI (command line interface) tool allows you to configure the same functionality through commands in a terminal. Both versions of the tool are supported for Windows, Linux, and macOS.

Follow the steps detailed below to import your smart card certificates onto your YubiKey using your preferred version of YubiKey Manager.

If you already have your smart card certificate stored on your YubiKey, skip to the next section: Smart Card Certificate Provisioning.

YubiKey Manager GUI

To use the GUI version of YubiKey Manager to import your certificate, follow the steps below:

  1. If you haven’t already, download the appropriate version of the YubiKey Manager GUI tool onto your host computer. Click on the downloaded file and follow the prompts to complete the installation.

  2. Open the YubiKey Manager GUI tool and plug your YubiKey into your computer.

  3. On the homepage of the YubiKey Manager, click on the Applications drop-down menu and select PIV.

  4. Select Configure Certificates under the Certificates section.

    _images/gui-configure-certificates.png

  5. The YubiKey has 24 total PIV slots, four of which are accessible via the YubiKey Manager tool (9a, 9c, 9d, and 9e). Technically, all of these accessible slots can be used to hold an X.509 certificate for authentication, but slot 9a is intended to be used for this purpose. For more information on PIV application slots, check out the slot documentation.

    Select an empty slot and click Import.

    _images/gui-import.png

  6. Navigate to the certificate file on your computer and select it to begin the import process.

    Remember, the public certificate AND its private key must be imported onto your YubiKey. While the YubiKey can store any X.509 certificate of the PEM, DER, and PKCS12 format, we recommend using the PKCS12 file type (which have .pfx or .p12 file extensions) because the public certificate and private key are stored in a single file.

  7. When prompted, enter the certificate’s password and click OK.

    Note

    If you do not know your certificate’s password, check with your admin (if applicable) or the certificate provider.

  8. Next, enter the PIV application management key and click OK.

    Note

    If you have not changed the management key using YubiKey Manager, the default managment key will be sufficient. If your YubiKey is managed by your organization, reach out to your admin for your management key.

    _images/gui-management-key.png

  9. If the import was successful, the slot will display the issuer, subject name, and expiration date of the imported certificate.

    _images/gui-imported.png

  10. Repeat this process to import additional smart card certificates as needed.

YubiKey Manager CLI

If you prefer to use the command line version of the YubiKey Manager tool (ykman) to import your certificate, follow the steps below:

  1. Install ykman onto your host computer.

  2. ykman can be run within a command prompt, terminal, or PowerShell. Please see the ykman documentation for more information on configuring your system to do this.

  3. Once your system has been configured, open a command prompt, terminal, or PowerShell.

  4. Plug your YubiKey into your computer.

  5. The YubiKey has 24 total PIV slots, four of which are accessible via the YubiKey Manager tool (9a, 9c, 9d, and 9e). Technically, all of these accessible slots can be used to hold an X.509 certificate for authentication, but slot 9a is intended to be used for this purpose. For more information on PIV application slots, check out the slot documentation.

    Enter ykman piv info to check if any slots on your YubiKey are already occupied.

  6. Once you have identified an appropriate empty slot, navigate to the folder containing your smart card certificate.

  7. Enter ykman piv certificates import <slot> <filename> to import your certificate onto your YubiKey. <slot> refers to the slot number (e.g. 9a), and <filename> refers to the name of your certificate file (e.g. certificate.p12).

    Remember, the public certificate AND its private key must be imported onto your YubiKey. While the YubiKey can store any X.509 certificate of the PEM, DER, and PKCS12 format, we recommend using the PKCS12 file type (which have .pfx or .p12 file extensions) because the public certificate and private key are stored in a single file.

  8. When prompted, enter your certificate’s password and your PIV application management key.

    Note

    If you do not know your certificate’s password, check with your admin (if applicable) or the certificate provider. If you have not changed the management key using YubiKey Manager, the default managment key will be sufficient. If your YubiKey is managed by your organization, reach out to your admin for your management key.

  9. Enter ykman piv info again to verify that the certificate import was successful. You will see the slot number listed along with the certificate algorithm, subject DN, issuer DN, serial number, fingerprint, and the time period the certificate is valid for.

    Note

    For more information on ykman PIV commands, please see the ykman documentation.

    _images/manager-cli.png

  10. Repeat this process to import additional smart card certificates as needed.

Next Steps

Now that you have imported your smart card certificate onto your YubiKey, you may provision the certificate to your iOS Keychain through the Yubico Authenticator application on your iOS device.

To file a support ticket with Yubico, click Support.