Crate yubikey_piv

YubiKey PIV: Personal Identity Verification support for Yubico devices using the Personal Computer/Smart Card (PC/SC) interface as provided by the pcsc crate.

PIV is a NIST standard for both signing and encryption using SmartCards and SmartCard-based hardware tokens like YubiKeys.

This library natively implements the protocol used to manage and utilize PIV encryption and signing keys which can be generated, imported, and stored on YubiKey devices.

See Yubico's guide to PIV-enabled YubiKeys for more information on which devices support PIV and the available functionality.

Minimum Supported Rust Version

Rust 1.44+

Supported YubiKeys

• YubiKey 4 series
• YubiKey 5 series

NOTE: Nano and USB-C variants of the above are also supported. Pre-YK4 YubiKey NEO series is NOT supported.

Supported Algorithms

• Authentication: 3DES
• Encryption: RSA1024, RSA2048, ECCP256, ECCP384
• Signatures:
  • RSASSA-PKCS#1v1.5: RSA1024, RSA2048
  • ECDSA: ECCP256, ECCP384

NOTE: RSASSA-PSS signatures and RSA-OAEP encryption may be supportable (TBD)

Status

This is a work-in-progress effort, and while much of the library-level code from upstream yubico-piv-tool has been translated into Rust presenting a safe interface, much of it is still untested.

Please see the project's README.md for a complete status.

History

This library is a Rust translation of the yubico-piv-tool utility by Yubico, which was originally written in C. It was mechanically translated from C into Rust using Corrode, and then subsequently heavily refactored into safer, more idiomatic Rust.

For more information on yubico-piv-tool and background information on how the YubiKey implementation of PIV works in general, see the Yubico PIV Tool Command Line Guide.

Security Warning

No security audits of this crate have ever been performed. Presently it is in an experimental stage and may still contain high-severity issues.

USE AT YOUR OWN RISK!

Code of Conduct

We abide by the Contributor Covenant and ask that you do as well.

For more information, please see CODE_OF_CONDUCT.md.

License

yubikey-piv.rs is a fork of and originally a mechanical translation from Yubico's yubico-piv-tool, a C library/CLI program. The original library was licensed under a 2-Clause BSD License, which this library inherits as a derived work.

Re-exports

pub use self::error::Error;

pub use self::key::Key;

pub use self::mgm::MgmKey;

pub use self::readers::Readers;

pub use self::yubikey::Serial;

pub use self::yubikey::YubiKey;

Modules

cccid	Cardholder Capability Container (CCC) ID Support
certificate	YubiKey Certificates
chuid	Cardholder Unique Identifier (CHUID) Support
config	YubiKey Configuration Values
error	Error types
key	PIV cryptographic keys stored in a YubiKey.
mgm	Management Key (MGM) for authenticating to the YubiKey management applet
mscmap	MS Container Map Records
msroots	msroots: PKCS#7 formatted certificate store for enterprise trusted roots.
policy	Enums representing key policies.
readers	Support for enumerating available readers
settings	Configuration setting values parsed from the environment and config file: /etc/yubico/yubikeypiv.conf
yubikey	YubiKey-related types and communication support

Type Definitions

ObjectId

Object identifiers