james/yubikey.rs
Public Access
1
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

Document project status in README.md and lib.rs

Browse Source 
This commit adds quite a bit of documentation about the current status
of the project, including links to GitHub issues for the different Rust
modules which map to specific pieces of functionality.

The intent is to track the current status of the project in the
README.md as that's more up-to-date than the docs.rs documentation
(which depends on a crate release to get updated).
This commit is contained in:
Tony Arcieri
2019-11-25 13:42:22 -08:00
parent eb399cbecc
commit cf8f3c88cf
4 changed files with 145 additions and 56 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+77 -26
View File
@@ -10,7 +10,7 @@
[![Build Status][build-image]][build-link] [![Build Status][build-image]][build-link]
[![Gitter Chat][gitter-image]][gitter-link] [![Gitter Chat][gitter-image]][gitter-link]
Pure Rust host-side YubiKey [Personal Identity Verification (PIV)][1] driver Pure Rust host-side YubiKey [Personal Identity Verification (PIV)][PIV] driver
with general-purpose public-key encryption and signing support. with general-purpose public-key encryption and signing support.
[Documentation][docs-link] [Documentation][docs-link]
@@ -22,21 +22,29 @@ to store a number of RSA (2048/1024) and ECC (NIST P-256/P-384) private keys
with configurable access control policies. Both the signing (RSASSA/ECDSA) and with configurable access control policies. Both the signing (RSASSA/ECDSA) and
encryption (PKCS#1v1.5/ECIES) use cases are supported for either key type. encryption (PKCS#1v1.5/ECIES) use cases are supported for either key type.
See [Yubico's guide to PIV-enabled YubiKeys][2] for more information See [Yubico's guide to PIV-enabled YubiKeys][yk-guide] for more information
on which devices support PIV and the available functionality. on which devices support PIV and the available functionality.
If you've been wanting to use Rust to sign and/or encrypt stuff using a If you've been wanting to use Rust to sign and/or encrypt stuff using a
private key generated and stored on a Yubikey (with option PIN-based access), private key generated and stored on a Yubikey (with option PIN-based access),
this is the crate you've been after! this is the crate you've been after!
One small problem, it's not done yet... 😫 Note that while this project started as a fork of a [Yubico] project,
this fork is **NOT** an official Yubico project and is in no way supported or
But it might be close? endorsed by Yubico.
## Minimum Supported Rust Version ## Minimum Supported Rust Version
- Rust **1.39+** - Rust **1.39+**
## Supported YubiKeys
- [YubiKey NEO] series (may be dropped in the future, see [#18])
- [YubiKey 4] series
- [YubiKey 5] series
NOTE: Nano and USB-C variants of the above are also supported
## Security Warning ## Security Warning
No security audits of this crate have ever been performed. Presently it is in No security audits of this crate have ever been performed. Presently it is in
@@ -44,16 +52,36 @@ an experimental stage and may still contain high-severity issues.
USE AT YOUR OWN RISK! USE AT YOUR OWN RISK!
## History ## Status
This library is a Rust translation of the [yubico-piv-tool][3] utility by This project is a largely incomplete work-in-progress. So far the only
Yubico, which was originally written in C. It was mechanically translated functionality which has actually been tested is connecting to Yubikeys.
from C into Rust using [Corrode][4], and then subsequently heavily
refactored into safer, more idiomatic Rust.
Note that while this project started as a fork of a [Yubico][5] project, If you're interested helping test functionality, the table below documents
this fork is **NOT** an official Yubico project and is in no way supported or the current status of the project and relevant GitHub issues for various
endorsed by Yubico. functions of the YubiKey:
| | Module | Issue | Description |
|----|---------------|-------|-------------|
| 🚧 | `yubikey` | [#20] | Core functionality: auth, keys, PIN/PUK, encrypt, sign, attest |
| ⚠️ | `cccid` | [#21] | Cardholder Capability Container (CCC) IDs |
| ⚠️ | `certificate` | [#22] | Certificates for stored keys |
| ⚠️ | `chuid` | [#23] | Cardholder Unique Identifier (CHUID) |
| ⚠️ | `config` | [#24] | Support for reading on-key configuration |
| ⚠️ | `container` | [#25] | MS Container Map Records |
| ⚠️ | `key` | [#26] | Crypto key management: list, generate, import |
| ⚠️ | `mgm` | [#26] | Management Key (MGM) support: set, get, derive
| ⚠️ | `msroots` | [#28] | `msroots` file: PKCS#7 formatted certificate store for enterprise trusted roots |
Legend:
| | Description |
|----|------------------------------------|
| 🚧 | Testing and validation in progress |
| ⚠️ | Untested support |
NOTE: Commands marked ⚠️ have not been properly tested and may contain bugs or
not work at all.
## Testing ## Testing
@@ -96,17 +124,24 @@ test connect ... ok
APDU messages labeled `>>>` are being sent to the YubiKey's internal SmartCard, APDU messages labeled `>>>` are being sent to the YubiKey's internal SmartCard,
and ones labeled `<<<` are the responses. and ones labeled `<<<` are the responses.
## 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.
## Code of Conduct ## Code of Conduct
We abide by the [Contributor Covenant][6] and ask that you do as well. We abide by the [Contributor Covenant][cc-md] and ask that you do as well.
For more information, please see [CODE_OF_CONDUCT.md][7]. For more information, please see [CODE_OF_CONDUCT.md][cc-md].
## License ## License
**yubikey-piv.rs** is a fork of and originally a mechanical translation from **yubikey-piv.rs** is a fork of and originally a mechanical translation from
Yubico's [`yubico-piv-tool`][3], a C library/CLI program. The original library Yubico's [yubico-piv-tool], a C library/CLI program. The original library
was licensed under a [2-Clause BSD License][8], which this library inherits was licensed under a [2-Clause BSD License][BSDL], which this library inherits
as a derived work. as a derived work.
Copyright (c) 2014-2019 Yubico AB, Tony Arcieri Copyright (c) 2014-2019 Yubico AB, Tony Arcieri
@@ -140,7 +175,7 @@ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Unless you explicitly state otherwise, any contribution intentionally Unless you explicitly state otherwise, any contribution intentionally
submitted for inclusion in the work by you shall be licensed under the submitted for inclusion in the work by you shall be licensed under the
[2-Clause BSD License][8] as shown above, without any additional terms [2-Clause BSD License][BSDL] as shown above, without any additional terms
or conditions. or conditions.
[//]: # (badges) [//]: # (badges)
@@ -159,11 +194,27 @@ or conditions.
[//]: # (general links) [//]: # (general links)
[1]: https://piv.idmanagement.gov/ [PIV]: https://piv.idmanagement.gov/
[2]: https://developers.yubico.com/PIV/Introduction/YubiKey_and_PIV.html [yk-guide]: https://developers.yubico.com/PIV/Introduction/YubiKey_and_PIV.html
[3]: https://github.com/Yubico/yubico-piv-tool/ [Yubico]: https://www.yubico.com/
[4]: https://github.com/jameysharp/corrode [YubiKey NEO]: https://support.yubico.com/support/solutions/articles/15000006494-yubikey-neo
[5]: https://www.yubico.com/ [YubiKey 4]: https://support.yubico.com/support/solutions/articles/15000006486-yubikey-4
[6]: https://contributor-covenant.org/ [YubiKey 5]: https://www.yubico.com/products/yubikey-5-overview/
[7]: https://github.com/tarcieri/yubikey-piv.rs/blob/develop/CODE_OF_CONDUCT.md [yubico-piv-tool]: https://github.com/Yubico/yubico-piv-tool/
[8]: https://opensource.org/licenses/BSD-2-Clause [Corrode]: https://github.com/jameysharp/corrode
[cc-web]: https://contributor-covenant.org/
[cc-md]: https://github.com/tarcieri/yubikey-piv.rs/blob/develop/CODE_OF_CONDUCT.md
[BSDL]: https://opensource.org/licenses/BSD-2-Clause
[//]: # (github issues)
[#18]: https://github.com/tarcieri/yubikey-piv.rs/issues/18
[#20]: https://github.com/tarcieri/yubikey-piv.rs/issues/20
[#21]: https://github.com/tarcieri/yubikey-piv.rs/issues/21
[#22]: https://github.com/tarcieri/yubikey-piv.rs/issues/22
[#23]: https://github.com/tarcieri/yubikey-piv.rs/issues/23
[#24]: https://github.com/tarcieri/yubikey-piv.rs/issues/24
[#25]: https://github.com/tarcieri/yubikey-piv.rs/issues/25
[#26]: https://github.com/tarcieri/yubikey-piv.rs/issues/26
[#27]: https://github.com/tarcieri/yubikey-piv.rs/issues/27
[#28]: https://github.com/tarcieri/yubikey-piv.rs/issues/28
src/apdu.rs
+1 -2
View File
@@ -39,8 +39,7 @@ const APDU_DATA_MAX: usize = 0xFF;
/// Application Protocol Data Unit (APDU). /// Application Protocol Data Unit (APDU).
/// ///
/// These messages are packets used to communicate with the YubiKey using the /// These messages are packets used to communicate with the YubiKey.
/// Chip Card Interface Device (CCID) protocol.
#[derive(Clone)] #[derive(Clone)]
pub(crate) struct APDU { pub(crate) struct APDU {
/// Instruction class: indicates the type of command (e.g. inter-industry or proprietary) /// Instruction class: indicates the type of command (e.g. inter-industry or proprietary)
src/container.rs
+2 -2
View File
@@ -1,4 +1,4 @@
//! PIV container records. //! MS Container Map Records
//! //!
//! These appear(?) to be defined in Microsoft's Smart Card Minidriver Specification: //! These appear(?) to be defined in Microsoft's Smart Card Minidriver Specification:
//! <https://docs.microsoft.com/en-us/previous-versions/windows/hardware/design/dn631754(v=vs.85)> //! <https://docs.microsoft.com/en-us/previous-versions/windows/hardware/design/dn631754(v=vs.85)>
@@ -40,7 +40,7 @@ use std::{
fmt::{self, Debug}, fmt::{self, Debug},
}; };
/// MS Container Map(?) records /// MS Container Map(?) Records
#[derive(Copy, Clone)] #[derive(Copy, Clone)]
pub struct Container { pub struct Container {
/// Container name /// Container name
src/lib.rs
+65 -26
View File
@@ -1,18 +1,30 @@
//! [YubiKey][1] PIV: [Personal Identity Verification][2] support for //! [YubiKey] PIV: [Personal Identity Verification][PIV] support for
//! [Yubico][3] devices using the Personal Computer/Smart Card ([PC/SC][4]) //! [Yubico] devices using the Personal Computer/Smart Card ([PC/SC])
//! interface as provided by the [`pcsc` crate][5]. //! interface as provided by the [`pcsc` crate].
//! //!
//! **PIV** is a [NIST][6] standard for both *signing* and *encryption* //! **PIV** is a [NIST] standard for both *signing* and *encryption*
//! using SmartCards and SmartCard-based hardware tokens like YubiKeys. //! using SmartCards and SmartCard-based hardware tokens like YubiKeys.
//! //!
//! This library natively implements the CCID protocol used to manage and //! This library natively implements the protocol used to manage and
//! utilize PIV encryption and signing keys which can be generated, imported, //! utilize PIV encryption and signing keys which can be generated, imported,
//! and stored on YubiKey devices. //! and stored on YubiKey devices.
//! //!
//! See [Yubico's guide to PIV-enabled YubiKeys][7] for more information //! See [Yubico's guide to PIV-enabled YubiKeys][yk-guide] for more information
//! on which devices support PIV and the available functionality. //! on which devices support PIV and the available functionality.
//! //!
//! Supported algorithms: //! ## Minimum Supported Rust Version
//!
//! Rust 1.39+
//!
//! ## Supported YubiKeys
//!
//! - [YubiKey NEO] series
//! - [YubiKey 4] series
//! - [YubiKey 5] series
//!
//! NOTE: Nano and USB-C variants of the above are also supported
//!
//! ## Supported Algorithms
//! //!
//! - **Authentication**: `3DES` //! - **Authentication**: `3DES`
//! - **Encryption**: `RSA1024`, `RSA2048`, `ECCP256`, `ECCP384` //! - **Encryption**: `RSA1024`, `RSA2048`, `ECCP256`, `ECCP384`
@@ -20,36 +32,63 @@
//! - RSASSA-PKCS#1v1.5: `RSA1024`, `RSA2048` //! - RSASSA-PKCS#1v1.5: `RSA1024`, `RSA2048`
//! - ECDSA: `ECCP256`, `ECCP384` //! - ECDSA: `ECCP256`, `ECCP384`
//! //!
//! NOTE: RSASSA-PSS signatures and RSA-OAEP encryption may be supportable (TBD)
//!
//! ## Status //! ## Status
//! //!
//! This library is a work-in-progress translation and is not yet usable. //! This is a work-in-progress effort, and while much of the library-level
//! Check back later for updates. //! code from upstream [yubico-piv-tool] has been translated into Rust
//! presenting a safe interface, much of it is still untested.
//! //!
//! ## Minimum Supported Rust Version //! Please see the project's README.md for a complete status.
//!
//! Rust 1.39+
//! //!
//! ## History //! ## History
//! //!
//! This library is a Rust translation of the [yubico-piv-tool][8] utility by //! This library is a Rust translation of the [yubico-piv-tool] utility by
//! Yubico, which was originally written in C. It was mechanically translated //! Yubico, which was originally written in C. It was mechanically translated
//! from C into Rust using [Corrode][9], and then subsequently heavily //! from C into Rust using [Corrode], and then subsequently heavily
//! refactored into safer, more idiomatic Rust. //! refactored into safer, more idiomatic Rust.
//! //!
//! For more information on `yubico-piv-tool` and background information on how //! For more information on [yubico-piv-tool] and background information on how
//! the YubiKey implementation of PIV works in general, see the //! the YubiKey implementation of PIV works in general, see the
//! [Yubico PIV Tool Command Line Guide][10]. //! [Yubico PIV Tool Command Line Guide][piv-tool-guide].
//! //!
//! [1]: https://www.yubico.com/products/yubikey-hardware/ //! ## Security Warning
//! [2]: https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-73-4.pdf //!
//! [3]: https://www.yubico.com/ //! No security audits of this crate have ever been performed. Presently it is in
//! [4]: https://en.wikipedia.org/wiki/PC/SC //! an experimental stage and may still contain high-severity issues.
//! [5]: https://github.com/bluetech/pcsc-rust //!
//! [6]: https://www.nist.gov/ //! USE AT YOUR OWN RISK!
//! [7]: https://developers.yubico.com/PIV/Introduction/YubiKey_and_PIV.html //!
//! [8]: https://github.com/Yubico/yubico-piv-tool/ //! ## Code of Conduct
//! [9]: https://github.com/jameysharp/corrode //!
//! [10]: https://www.yubico.com/wp-content/uploads/2016/05/Yubico_PIV_Tool_Command_Line_Guide_en.pdf //! We abide by the [Contributor Covenant][cc-md] and ask that you do as well.
//!
//! For more information, please see [CODE_OF_CONDUCT.md][cc-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][BSDL], which this library inherits
//! as a derived work.
//!
//! [YubiKey]: https://www.yubico.com/products/yubikey-hardware/
//! [PIV]: https://nvlpubs.nist.gov/nistpubs/SpecialPublications/NIST.SP.800-73-4.pdf
//! [Yubico]: https://www.yubico.com/
//! [PC/SC]: https://en.wikipedia.org/wiki/PC/SC
//! [`pcsc` crate]: https://github.com/bluetech/pcsc-rust
//! [NIST]: https://www.nist.gov/
//! [yk-guide]: https://developers.yubico.com/PIV/Introduction/YubiKey_and_PIV.html
//! [YubiKey NEO]: https://support.yubico.com/support/solutions/articles/15000006494-yubikey-neo
//! [YubiKey 4]: https://support.yubico.com/support/solutions/articles/15000006486-yubikey-4
//! [YubiKey 5]: https://www.yubico.com/products/yubikey-5-overview/
//! [yubico-piv-tool]: https://github.com/Yubico/yubico-piv-tool/
//! [Corrode]: https://github.com/jameysharp/corrode
//! [piv-tool-guide]: https://www.yubico.com/wp-content/uploads/2016/05/Yubico_PIV_Tool_Command_Line_Guide_en.pdf
//! [cc-web]: https://contributor-covenant.org/
//! [cc-md]: https://github.com/tarcieri/yubikey-piv.rs/blob/develop/CODE_OF_CONDUCT.md
//! [BSDL]: https://opensource.org/licenses/BSD-2-Clause
// Adapted from yubico-piv-tool: // Adapted from yubico-piv-tool:
// <https://github.com/Yubico/yubico-piv-tool/> // <https://github.com/Yubico/yubico-piv-tool/>