The pbyklib library provides a Rust implementation of the protocol required to enroll YubiKeys and TPM-based virtual
smart card (VSCs) with a Purebred instance. Purebred is a derived credential issuance system used by the U.S. Department
of Defense.
As with all Purebred apps and libraries, enrollment requires the participation of a Purebred Agent. Specifically, when enrolling a device, you will need a Purebred Agent's EDIPI and a pair of one-time password (OTP) values generated by that agent and provided in a timely manner. When provisioning user certificates to the device, user key management (UKM) 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.
The pbyk utility provides sample usage of the pbyklib crate.
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. When enrolling a virtual smart card (VSC), these steps are preceded by use of tpmvscmgr to destroy, if necessary, and create the VSC to provision.
The protocol is essentially Apple's Over-the-Air Profile Delivery and Configuration (OTA protocol) with the following three alterations:
- An additional round-trip is added before the OTA protocol is executed to provide the portal with a self-signed certificate corresponding to a freshly generated key pair. This additional step is referred to as Pre-enrollment or Phase 0 and is used to establish trust in a public key associated with the device.
- The Phase 2 response during OTA execution is encrypted using the certificate presented to the portal and verified by a Purebred Agent during Pre-enrollment.
- One or more user key management (UKM) or recover steps may be performed to deliver encrypted configuration protocols following execution of the OTA protocol.
As with other Purebred apps, information is incorporated into the app for a target environment, i.e., NIPR, SIPR, NIPR test, SIPR test, development.
Unlike other apps, a single pbyk build can target multiple environments. Target environments are represented as features
when pbyk is built. The following environment-related features are available:
| Feature | Description |
|---|---|
| dev | Development environment |
| om_nipr | Test environment for NIPR |
| nipr | NIPR production environment |
| om_sipr | Test environment for SIPR |
| sipr | SIPR production environment |
| gui | GUI support |
| vsc | Virtual smart card support |
The dev feature is the default. At least one environment-related feature must be elected when pbyk is built, else compilation fails.
Features are additive. For example, either of the following commands can be used to build a pbyk app that targets dev, om_sipr and sipr.
cargo build --features om_sipr,sipr --release
cargo build --no-default-features --features dev,om_sipr,sipr --releaseWhen more than one environment is available, the environment option must be specified. The help text for environment indicates available options, for example:
-e, --environment <ENVIRONMENT> Environment to target [possible values: dev, om-sipr, sipr]
The vsc feature is only available on Windows systems. There is also a reset_vsc feature that is not currently
supported and that may be removed.
This is a work-in-progress implementation which is at an early stage of development.
This crate requires Rust 1.65 at a minimum.
Licensed under either of:
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.