1_intro2_command_line3_gui4_miscellaneous5_known_issues

Introduction

The pbyk utility is a provides a command line interface and/or GUI interface to enroll YubiKeys with a Purebred instance. On Windows systems, support for enrolling trusted platform module (TPM)-based virtual smart cards (VSCs) is also available. Purebred is a derived credential issuance system used by the U.S. Department of Defense.

As with all Purebred apps, enrollment requires the participation of a Purebred Agent. Specifically, when enrolling the device, you will need a Purebred Agent's EDIPI and a pair of one-time password values generated by that agent and provided in a timely manner. When provisioning user certificates to the device, user key management (UKM) one-time passwords (OTPs) are required. These can be obtained by authenticating to the target Purebred instance using the (simulated) CAC credentials from which derived credentials will be created.

This documentation focuses on the use of the pbyk utility and does not cover obtaining OTP values from the Purebred portal.

Using pbyk from the command line

The features provided by pbyk will vary with how the utility was built and the platform. Some builds may target different environments. Some may provide only a command-line interface, while others provide a graphical user interface (GUI) and a command line interface. This chapter addresses usage of the command line interface.

Usage

As noted above, the available options depend on how the utility was compiled. The example below is from a Windows build that provides virtual smart card (VSC) support and that targets the development, SIPR and O&M SIPR environments and that provides a GUI. The supported environments are evident in the description for the --environment argument and the availability of the GUI is evident by the presence of a --interactive argument. The --interactive argument can be used to exercise the utility
from a command line.

Usage instructions as shown by invoking the app with the --help argument are below. The remainder of this chapter discusses use of the tool from a command line. The next chapter discusses using the tool via its GUI.

Usage: pbyk [OPTIONS]

Options:
  -h, --help     Print help (see more with '--help')
  -V, --version  Print version

Arguments:
  -a, --agent-edipi <AGENT_EDIPI>  EDIPI of Purebred Agent who provided the pre_enroll_otp or enroll_otp value
  -s, --serial <SERIAL>            Serial number of YubiKey or virtual smart card (VSC) to provision (available devices can be listed using list_yubikeys or list_vscs); this is not required if only one YubiKey or VSC is present
  -e, --environment <ENVIRONMENT>  Environment to target [possible values: dev, om-sipr, sipr]

Actions:
  -1, --pre-enroll-otp <PRE_ENROLL_OTP>
          Pre-enrollment OTP provided by Purebred Agent identified by agent_edipi
  -2, --enroll-otp <ENROLL_OTP>
          Enrollment OTP provided by Purebred Agent identified by agent_edipi
  -3, --ukm-otp <UKM_OTP>
          OTP generated by user associated with the device on the Purebred portal
  -4, --recover-otp <RECOVER_OTP>
          OTP generated by user associated with the device on the Purebred portal

Diagnostics:
  -p, --portal-status-check  Connect to status interface on portal to affirm network connectivity
  -k, --scep-check           Connect to status interface on CA to affirm network connectivity

Utilities:
  -y, --list-yubikeys  Lists available YubiKey devices, if any
  -v, --list-vscs      Lists available virtual smart card (VSC) devices, if any
  -r, --reset-device   Resets the indicated device to a default state using a management key expected by Purebred applications
  -i, --interactive    Run pbyk as command line app

Logging:
  -l, --logging-config <LOGGING_CONFIG>
          Full path and filename of YAML-formatted configuration file for log4rs logging mechanism. See https://docs.rs/log4rs/latest/log4rs/ for details
  -c, --log-to-console
          Log output to the console

Though the usage instructions above include --interactive, the commands provided in this chapter were prepared using a build that did not provide a GUI so no --interactive argument is required.

Purebred Workflow

The Purebred workflow consists of four steps: pre-enroll, enroll, user key management and recovery. When enrolling a YubiKey, these steps are preceded by a device reset operation. The reset step is necessary to prepare the device for enrollment by clearing previous contents and establishing usage of a particular management key. When enrolling a VSC, these steps are typically preceded by VSC creation (and deletion, as necessary). See chapter 4 for details on creating and deleting VSCs.

The following sections demonstrate enrolling a YubiKey device with the serial number 15995762 and a VSC with the name "Microsoft Virtual Smart Card 0" with the cooperation of a Purebred Agent whose EDIPI is 5533442211. The steps are the same for YubiKeys and VSCs, with only the serial number value varying. For YubiKeys, the serial number of the device is used. For VSCs, the name of the device is used.

Reset

The first step is to list available YubiKeys and/or VSCs. If you already know your device's serial number or if only one device is present, this can be skipped (the serial number argument is only needed when more than one device is available).

$ pbyk -y
Name: Yubico YubiKey OTP+FIDO+CCID; Serial: 15995762

> pbyk -v
Name: Microsoft Virtual Smart Card 1
Name: Microsoft Virtual Smart Card 0

Next, reset the YubiKey so that it uses the expected management key.

$ pbyk -s 15995762 -r
Starting reset of YubiKey with serial number 15995762. Use Ctrl+C to cancel.
Enter new PIN; PINs must contain 6 to 8 ASCII characters: 
Re-enter new PIN: 
Enter new PIN Unlock Key (PUK); PUKs must be 6 to 8 bytes in length: 
Re-enter new PIN Unlock Key (PUK):

A limited form of reset is provided for VSCs. For a reset comparable to that provided for Yubikeys, use the tpmvscmgr utility. Section 4 provides some instructions for using tpmvscmgr to create or destroy VSCs. The reset support provided by pbyk only temporarily removes certificates associated with a VSC from the user's CAPI store to enable re-execution of the Purebred workflow. Keys corresponding to those certificates are not deleted from the VSC and may be re-registered with CAPI by the operating system. No PIN entry is required because the VSC itself is not being reset or recreated.

>pbyk -s "Microsoft Virtual Smart Card 0" -r
Starting reset of VSC with serial number Microsoft Virtual Smart Card 0. This may take a few seconds.

Pre-enroll

The next two steps, Pre-enroll and Enroll, require Purebred Agent participation. The agent should provide their EDIPI and a Pre-enrollment OTP. Pre-enrollment must be completed within three minutes of generating the Pre-enrollment OTP.

$ pbyk -s 15995762 -a 5533442211 -1 74517780
Enter PIN: 
Pre-enroll completed successfully: 07E7730D014D55AFA800609C962E9FF40B61A5AD70E07AAC95E9F6911C4B48E1

When enrolling a VSC, PIN entry is not performed directly using pbyk. Instead, a PIN entry dialog is displayed by the Windows virtual smart card system.

Pre-enrollment of a VSC is as shown above, but with the VSC name used as the serial number.

> pbyk -s "Microsoft Virtual Smart Card 0" -a 5533442211 -1 05041153
Pre-enroll completed successfully: 27E2751C3BD47AC24B6328179E081240FC586738

Enroll

Next, the Purebred Agent will affirm the hash value displayed during pre-enrollment to establish trust in the device and will provide an Enrollment OTP. As with Pre-enrollment, the Enrollment operation must be completed within three minutes of generating the Enrollment OTP.

$ pbyk -s 15995762 -a 5533442211 -2 63999319
Enter PIN: 
Enroll completed successfully

Enrollment of a VSC is as shown above, but with the VSC name used as the serial number. As with pre-enrollment, the Windows virtual smart card system will prompt for the VSC PIN.

> pbyk -s "Microsoft Virtual Smart Card 0" -a 5533442211 -2 30800612 -e dev
Enroll completed successfully

User key management

Provisioning user keys does not require Purebred Agent co-operation but does require a UKM OTP. To generate a UKM OTP, browse to the My Devices tab on the Purebred portal and click the Generate OTP link for the target device to obtain a UKM OTP for your device. Provide the value to pbyk as shown below. The UKM process must be completed within three minutes of generating the OTP value.

$ pbyk -s 15995762 -3 38979363
Enter PIN: 
UKM completed successfully

Provisioning user keys to a VSC is as shown above, but with the VSC name used as the serial number. As with pre-enrollment and enrollment, the Windows virtual smart card system will prompt for the VSC PIN. Note, key generation in a virtual smart card is relatively slow. The UKM step may take several minutes.

> pbyk -s 15995762 -3 26727573
UKM completed successfully

Recover

The Recover operation is optional and follows the same steps as described for UKM. After obtaining a UKM OTP complete the Recover operation as shown below. The recovery process must be completed within three minutes of generating the OTP value.

$ pbyk -s 15995762 -4 30468894
Enter PIN: 
Recover completed successfully

Recovering user keys to a VSC is as shown above, but with the VSC name used as the serial number. As with pre-enrollment and enrollment, the Windows virtual smart card system will prompt for the VSC PIN. In some cases, installation of a recovered key into a VSC will fail, in which case a prompt will be displayed to the user and the key will be installed as a software credential.

> pbyk -s 15995762 -4 69550720
Recover completed successfully

Using pbyk as a desktop application

The features provided by pbyk will vary with how the utility was built. Some builds may target different environments. Some may provide only a command-line interface, while others provide a graphical user interface (GUI) and a command line interface. This chapter addresses usage via the GUI.

By default, when pbyk is launched in GUI mode, it will create a file named log.yaml in the .pbyk folder in the user's home directory. This logging configuration file will be used to generate a log file adjacent to the configuration file. The configuration file can be customized. It will only be automatically created if absent.

Purebred Workflow

The Purebred workflow consists of four steps: pre-enroll, enroll, user key management and recovery. When enrolling a YubiKey, these steps are preceded by a device reset operation. The reset step is necessary to prepare the device for enrollment by clearing previous contents and establishing usage of a particular management key. When enrolling a VSC, these steps are preceded by VSC creation (and deletion, as necessary). See chapter 4 for details on creating and deleting VSCs.

The following sections demonstrate enrolling a YubiKey device with the serial number 15995762 and a VSC with the name "Microsoft Virtual Smart Card 0" with the cooperation of a Purebred Agent whose EDIPI is 5533442211. The steps are the same for YubiKeys and VSCs, with only the serial number value varying. For YubiKeys, the serial number of the device is used. For VSCs, the name of the device is used.

Reset

The reset feature can be accessed in one of two ways depending on the state of the device. For devices that have not been enrolled with Purebred previously, and thus have a different management key installed, simply launching the pbyk app will display an alert like the one shown below.

For devices that have been enrolled with Purebred previously, launching the app then clicking the DISA logo five times within five seconds will display the same alert.

When the 'Yes' button is clicked, the app will display a form like the one shown below, which can be used to complete the reset process.

A limited form of reset is provided for VSCs. For a reset comparable to that provided for Yubikeys, use the tpmvscmgr utility. Section 4 provides some instructions for using tpmvscmgr to create or destroy VSCs. The reset support provided by pbyk only temporarily removes certificates associated with a VSC from the user's CAPI store to enable re-execution of the Purebred workflow. Keys corresponding to those certificates are not deleted from the VSC and may be re-registered with CAPI by the operating system. When resetting a VSC, the same steps as used for Yubikeys apply, with the exception that no PIN or PUK values need to be provided, as shown below.

Pre-enroll

The next two steps require Purebred Agent participation. The agent should provide their EDIPI and a Pre-enrollment OTP. Pre-enrollment must be completed within three minutes of generating the Pre-enrollment OTP. To complete Pre-enrollment, provide the requested information as shown in the screenshot below then click the Pre-enroll button. In this example, the YubiKey with serial number 15995762 is being enrolled in the Development environment with the assistance of a Purebred Agent whose EDIPI is 5533442211.

The YubiKey Serial Number field is a drop list and will feature multiple options when multiple YubiKeys and/or VSCs are available. When a different device is changed, the form displayed by the app may change to match the state of the newly selected device.

When pre-enrolling a VSC, the process is similar except there is no PIN field, as the Windows virtual smart card system will prompt the user for the PIN directly.

Enroll

Next, the Purebred Agent will affirm the hash value displayed following pre-enrollment to establish trust in the device and will provide an Enrollment OTP. As with Pre-enrollment, the Enrollment operation must be completed within three minutes of generating the Enrollment OTP.

The YubiKey Serial Number field is a read-only text box and will feature the value selected on the Pre-enroll view.

When enrolling a VSC, the process is similar except there is no PIN field, as the Windows virtual smart card system will prompt the user for the PIN directly.

User key management

Provisioning user keys does not require Purebred Agent co-operation but does require a UKM OTP. To generate a UKM OTP, browse to the My Devices tab on the Purebred portal and click the Generate OTP link for the target device to obtain a UKM OTP for your device. Provide the value to pbyk as shown below. The UKM process must be completed within three minutes of generating the OTP value.

The YubiKey Serial Number field is a drop list and will feature multiple options when multiple YubiKeys are available. When a different device is changed, the form displayed by the app may change to match the state of the newly selected device.

When provisioning user keys to a VSC, the process is similar except there is no PIN field, as the Windows virtual smart card system will prompt the user for the PIN directly. Note, key generation in a virtual smart card is relatively slow. The UKM step may take several minutes.

Recover

The Recover operation is optional and follows the same steps as described for UKM. After obtaining a UKM OTP complete the Recover operation as shown below taking care to click the Recover Old Decryption Keys checkbox before clicking the User Key Management button. The recovery process must be completed within three minutes of generating the OTP value.

The YubiKey Serial Number field is a drop list and will feature multiple options when multiple YubiKeys are available. When a different device is changed, the form displayed by the app may change to match the state of the newly selected device.

When recovering keys to a VSC, the process is similar except there is no PIN field, as the Windows virtual smart card system will prompt the user for the PIN directly. In some cases, installation of a recovered key into a VSC will fail, in which case a prompt will be displayed to the user and the key will be installed as a software credential.

Using command-line interface

In some cases, using the command-line interface may be more convenient even when a GUI is available. To exercise the command-line interface using a pbyk instance that provides a GUI simply add --interactive when launching the application along with other appropriate arguments. The following shows the commands given in the command line chapter with the additional argument.

$ ./pbyk -iy
Name: Yubico YubiKey OTP+FIDO+CCID; Serial: 15995762
$ ./pbyk -s 15995762 -ir
Starting reset of YubiKey with serial number 15995762. Use Ctrl+C to cancel.
Enter new PIN; PINs must contain 6 to 8 ASCII characters: 
Re-enter new PIN: 
Enter new PIN Unlock Key (PUK); PUKs must be 6 to 8 bytes in length: 
Re-enter new PIN Unlock Key (PUK): 
$ ./pbyk -s 15995762 -a 5533442211 -e dev -i1 22735141
Enter PIN for YubiKey with serial number 15995762: 
Pre-enroll completed successfully: BF8FD6C91095CC4B02925EE299D3FD6A57F3F965
$ ./pbyk -s 15995762 -a 5533442211 -e dev -i -2 93638350
Enter PIN for YubiKey with serial number 15995762: 
Enroll completed successfully
$ ./pbyk -s 15995762 -e dev -i -3 19475568
Enter PIN for YubiKey with serial number 15995762: 
UKM completed successfully
$ ./pbyk -s 15995762 -e dev -i -4 41537238
Enter PIN for YubiKey with serial number 15995762: 
Recover completed successfully

Provisioning a VSC in this fashion is similar, with the VSC name used as the serial number value.

Miscellaneous topics

Resetting a YubiKey with yubico-piv-tool

The pbyk reset-yubikey feature performs the equivalent of the following yubico-piv-tool commands to lock then reset a YubiKey.

  yubico-piv-tool -a verify-pin -P 32165498
  yubico-piv-tool -a verify-pin -P 32165498
  yubico-piv-tool -a verify-pin -P 32165498
  yubico-piv-tool -a change-puk -P 12345679 -N 32165498
  yubico-piv-tool -a change-puk -P 12345679 -N 32165498
  yubico-piv-tool -a change-puk -P 12345679 -N 32165498
  yubico-piv-tool -a reset
  yubico-piv-tool -a set-chuid
  yubico-piv-tool -a set-ccc
  yubico-piv-tool -a set-mgm-key -n 020203040506070801020304050607080102030405060708
  yubico-piv-tool -a change-puk -P 12345678 -N 12345678
  yubico-piv-tool -a change-pin -P 123456 -N 77777777

The reset_yubikey function is intended to perform the equivalent steps.

The caller is assumed to have enforced PIN and PUK requirements. If either the PIN or PUK fails to satisfy requirements (as described here), then the attempt to set the PIN or PUK will fail.

Managing virtual smart cards with tpmvscmgr

Windows provides the tpmvscmgr utility to create and destroy virtual smarts. The commands below will destroy the first virtual smart card on a system, then create new one using the default PIN value and a random administrator key. The "/attestation AIK_AND_CERT" portion of this command is required when creating VSCs for use with Purebred where attestations are to be used. Where attestations are not available, pbyk will attempt to perform enrollment without attestations. Use of a non-default PIN value is recommended.

TpmVscMgr destroy /instance root\smartcardreader\0000
TpmVscMgr create /name MyVSC /pin default /adminkey random /generate /attestation AIK_AND_CERT

Sample logging configuration

The pbyk utility uses the log4rs crate for logging support. YAML is used to define a logging configuration. See https://docs.rs/log4rs/latest/log4rs/ for a description of the YAML format. The snip below provides a sample that outputs pbyk and pbyklib information at the debug level. Several dependencies are listed and configured at the error level. The volume of logging information can be controlled be adjusting the level for the various components used by pbyk.

refresh_rate: 30 seconds
appenders:
  stdout:
    kind: console
    encoder:
      pattern: "{d} {l} {t} - {m}{n}"
  pbyk:
    kind: rolling_file
    path: "./pbyk.log"
    encoder:
      pattern: "{d} {l} {t} - {m}{n}"
    # The policy which handles rotation of the log file. Required.
    policy:
      # Identifies which policy is to be used. If no kind is specified, it will
      # default to "compound".
      kind: compound

      # The remainder of the configuration is passed along to the policy's
      # deserializer, and will vary based on the kind of policy.
      trigger:
        kind: size
        limit: 100 mb

      roller:
        kind: delete      
root:
  appenders:
    - pbyk
    - stdout
loggers:
  # turn dependencies on at desired level to see additional log output
  reqwest:
    level: error
  rustls:
    level: error
  certval:
    level: error
  yubikey:
    level: error
  pbyklib:
    level: debug
  pbyk:
    level: debug

Source code

The pbyk utility is written in the Rust programming language. The source code for the application is available here.

Additional resources

Additional information on the Purebred process can be found on the DoD Cyber Exchange site. Contact information for various support resources can be found here.

Known Issues

General

  • NIPR and O&M NIPR builds are not presently supported owing to lack of support for BER decoding in the cms crate used by pbyk and the current NIPR CA's usage of BER encoding when returning CA certificates during SCEP processing. The next NIPR CA update should enable these features to be used.
  • GUI support is not presently provided for Linux

GUI mode

  • Copy and Paste does not work on macOS (see Dioxus issue 1691)
  • Console window may remain visible when run in GUI mode except on Windows
  • State information is only saved when an action is performed, not when app is closed
  • YubiKey reset capability is not available on macOS on x86_64 hardware

Windows

  • When the VSC feature is used, the app takes several seconds to close
  • On Windows 11, elevated permissions are required to generate attestations. On Windows 10, attestations are available without elevated permissions. On Windows 11, use of elevated permissions (or not) should remain constant throughout enrollment. For example, enrolling with elevation then performing UKM without will not work. A device must be deleted on the portal to remove attestation expectation once it has been established.
  • The VSC state information maintained in the .pbyk folder in the user's home directory will grow without bound across multiple reset generations. The file can be manually deleted when a VSC is destroyed and recreated as a mitigation.