From d880faaefa17e1c7d46542bdf18892c70a952916 Mon Sep 17 00:00:00 2001 From: "Tony Arcieri (iqlusion)" Date: Mon, 14 Nov 2022 16:53:00 -0700 Subject: [PATCH] yubikey v0.7.0 (#444) --- CHANGELOG.md | 25 +++++++++++ Cargo.lock | 2 +- Cargo.toml | 6 +-- README.md | 75 +++++++++++++++++++++++++++----- cli/Cargo.toml | 2 +- cli/README.md | 4 +- src/lib.rs | 113 +++---------------------------------------------- 7 files changed, 103 insertions(+), 124 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 724cf8e..c5bec87 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,31 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## 0.7.0 (2022-11-14) +### Added +- Display inner PC/SC errors ([#420]) +- Support for metadata command ([#371]) +- Better `certificate::Serial` inspection ([#437]) + +### Changed +- MSRV 1.60.0 ([#423]) +- Bump `rsa` to v0.7.1 ([#440]) +- Switch from `lazy_static` to `once_cell` ([#442]) +- Switch from `subtle-encoding` to `base16ct` ([#443]) + +### Fixed +- Use `chrono` v0.4.23 or newer ([#436]) +- `Certificate::issuer` was returning the subject instead ([#437]) + +[#371]: https://github.com/iqlusioninc/yubikey.rs/pull/371 +[#420]: https://github.com/iqlusioninc/yubikey.rs/pull/420 +[#423]: https://github.com/iqlusioninc/yubikey.rs/pull/423 +[#436]: https://github.com/iqlusioninc/yubikey.rs/pull/436 +[#437]: https://github.com/iqlusioninc/yubikey.rs/pull/437 +[#440]: https://github.com/iqlusioninc/yubikey.rs/pull/440 +[#442]: https://github.com/iqlusioninc/yubikey.rs/pull/442 +[#443]: https://github.com/iqlusioninc/yubikey.rs/pull/443 + ## 0.6.0 (2022-08-10) ### Changed - 2021 edition upgrade ([#343]) diff --git a/Cargo.lock b/Cargo.lock index 226147e..4647993 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1259,7 +1259,7 @@ dependencies = [ [[package]] name = "yubikey" -version = "0.6.0" +version = "0.7.0" dependencies = [ "base16ct", "chrono", diff --git a/Cargo.toml b/Cargo.toml index 16f7f89..48fae45 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -1,6 +1,6 @@ [package] name = "yubikey" -version = "0.6.0" +version = "0.7.0" description = """ Pure Rust cross-platform host-side driver for YubiKey devices from Yubico with support for hardware-backed public-key decryption and digital signatures using @@ -11,10 +11,10 @@ authors = ["Tony Arcieri ", "Yubico AB"] license = "BSD-2-Clause" repository = "https://github.com/iqlusioninc/yubikey.rs" readme = "README.md" -categories = ["api-bindings", "cryptography", "hardware-support"] +categories = ["api-bindings", "authentication", "cryptography", "hardware-support"] keywords = ["ecdsa", "encryption", "rsa", "piv", "signature"] edition = "2021" -rust-version = "1.57" +rust-version = "1.60" [workspace] members = [".", "cli"] diff --git a/README.md b/README.md index 3c4f1af..8187bcf 100644 --- a/README.md +++ b/README.md @@ -4,16 +4,19 @@ [![crate][crate-image]][crate-link] [![Docs][docs-image]][docs-link] +[![Build Status][build-image]][build-link] +[![Safety Dance][safety-image]][safety-link] +[![Dependency Status][deps-image]][deps-link] [![2-Clause BSD Licensed][license-image]][license-link] ![MSRV][msrv-image] -[![Safety Dance][safety-image]][safety-link] -[![Build Status][build-image]][build-link] -[![dependency status][deps-image]][deps-link] Pure Rust cross-platform host-side driver for [YubiKey] devices from [Yubico] with support for public-key encryption and digital signatures using the [Personal Identity Verification (PIV)][PIV] application. +Uses the Personal Computer/Smart Card ([PC/SC]) interface with cross-platform +access provided by the [`pcsc` crate]. + [Documentation][docs-link] ## About @@ -34,9 +37,36 @@ 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 endorsed by Yubico. +## Features + +### Personal Identity Verification (PIV) + +[PIV] is a [NIST] standard for both *signing* and *encryption* +using SmartCards and SmartCard-based hardware tokens like YubiKeys. + +PIV-related functionality can be found in the [`piv`] module. + +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][yk-guide] for more information +on which devices support PIV and the available functionality. + +### Supported Algorithms +- **Authentication**: `3DES` +- **Encryption**: + - RSA: `RSA1024`, `RSA2048` + - ECC: `ECCP256`, `ECCP384` (NIST curves: P-256, P-384) +- **Signatures**: + - RSASSA-PKCS#1v1.5: `RSA1024`, `RSA2048` + - ECDSA: `ECCP256`, `ECCP384` (NIST curves: P-256, P-384) + +NOTE: RSASSA-PSS signatures and RSA-OAEP encryption may be supportable (TBD) + ## Minimum Supported Rust Version -Rust **1.57** or newer. +Rust **1.60** or newer. ## Supported YubiKeys @@ -59,6 +89,17 @@ an experimental stage and may still contain high-severity issues. USE AT YOUR OWN RISK! +## Status + +Functionality which has been successfully tested is available by default. + +Any functionality which is gated on the `untested` feature has not been +properly tested and is not known to function correctly. + +Please see the [`untested` functionality tracking issue] for current status. +We would appreciate any help testing this functionality and removing the +`untested` gating as well as writing more automated tests. + ## Testing To run the full test suite, you'll need a connected YubiKey NEO/4/5 device in @@ -68,7 +109,7 @@ Tests which run live against a YubiKey device are marked as `#[ignore]` by default in order to pass when running in a CI environment. To run these tests locally, invoke the following command: -``` +```shell cargo test -- --ignored ``` @@ -77,14 +118,14 @@ information about what is happening. If you'd like to print this logging information while running the tests, set the `RUST_LOG` environment variable to a relevant loglevel (e.g. `error`, `warn`, `info`, `debug`, `trace`): -``` +```shell RUST_LOG=info cargo test -- --ignored ``` To trace every message sent to/from the card i.e. the raw Application Protocol Data Unit (APDU) messages, use the `trace` log level: -``` +```text running 1 test [INFO yubikey::yubikey] trying to connect to reader 'Yubico YubiKey OTP+FIDO+CCID' [INFO yubikey::yubikey] connected to 'Yubico YubiKey OTP+FIDO+CCID' successfully @@ -110,6 +151,14 @@ 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][piv-tool-guide]. + +## ⚠️ Security Warning + +No security audits of this crate have ever been performed. + ## Code of Conduct We abide by the [Contributor Covenant][cc-md] and ask that you do as well. @@ -159,13 +208,13 @@ or conditions. [//]: # (badges) -[crate-image]: https://img.shields.io/crates/v/yubikey.svg +[crate-image]: https://buildstats.info/crate/yubikey [crate-link]: https://crates.io/crates/yubikey [docs-image]: https://docs.rs/yubikey/badge.svg [docs-link]: https://docs.rs/yubikey/ [license-image]: https://img.shields.io/badge/license-BSD-blue.svg [license-link]: https://github.com/iqlusioninc/yubikey.rs/blob/main/COPYING -[msrv-image]: https://img.shields.io/badge/rustc-1.57+-blue.svg +[msrv-image]: https://img.shields.io/badge/rustc-1.60+-blue.svg [safety-image]: https://img.shields.io/badge/unsafe-forbidden-success.svg [safety-link]: https://github.com/rust-secure-code/safety-dance/ [build-image]: https://github.com/iqlusioninc/yubikey.rs/workflows/CI/badge.svg?branch=main&event=push @@ -176,9 +225,12 @@ or conditions. [//]: # (general links) [YubiKey]: https://www.yubico.com/products/yubikey-hardware/ -[PIV]: https://piv.idmanagement.gov/ -[yk-guide]: https://developers.yubico.com/PIV/Introduction/YubiKey_and_PIV.html [Yubico]: https://www.yubico.com/ +[PIV]: https://piv.idmanagement.gov/ +[NIST]: https://www.nist.gov/ +[PC/SC]: https://en.wikipedia.org/wiki/PC/SC +[`pcsc` crate]: https://github.com/bluetech/pcsc-rust +[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/ @@ -187,6 +239,7 @@ or conditions. [cc-web]: https://contributor-covenant.org/ [cc-md]: https://github.com/iqlusioninc/yubikey.rs/blob/main/CODE_OF_CONDUCT.md [BSDL]: https://opensource.org/licenses/BSD-2-Clause +[`untested` functionality tracking issue]: https://github.com/iqlusioninc/yubikey.rs/issues/280 [//]: # (github issues) diff --git a/cli/Cargo.toml b/cli/Cargo.toml index 7b272a9..5b14fe0 100644 --- a/cli/Cargo.toml +++ b/cli/Cargo.toml @@ -23,4 +23,4 @@ once_cell = "1" sha2 = "0.10" termcolor = "1" x509-parser = "0.14" -yubikey = { version = "0.6", path = ".." } +yubikey = { version = "0.7", path = ".." } diff --git a/cli/README.md b/cli/README.md index c7ccbe6..bbe3465 100644 --- a/cli/README.md +++ b/cli/README.md @@ -18,7 +18,7 @@ utility with general-purpose public-key encryption and signing support. ## Minimum Supported Rust Version -Rust **1.57** or newer. +Rust **1.60** or newer. ## Supported YubiKeys @@ -84,7 +84,7 @@ or conditions. [docs-image]: https://docs.rs/yubikey-cli/badge.svg [docs-link]: https://docs.rs/yubikey-cli/ [license-image]: https://img.shields.io/badge/license-BSD-blue.svg -[rustc-image]: https://img.shields.io/badge/rustc-1.57+-blue.svg +[rustc-image]: https://img.shields.io/badge/rustc-1.60+-blue.svg [maintenance-image]: https://img.shields.io/badge/maintenance-experimental-blue.svg [safety-image]: https://img.shields.io/badge/unsafe-forbidden-success.svg [safety-link]: https://github.com/rust-secure-code/safety-dance/ diff --git a/src/lib.rs b/src/lib.rs index 1c57681..f3782c2 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,102 +1,10 @@ -//! **yubikey.rs**: pure Rust cross-platform host-side driver for [YubiKey] -//! devices from [Yubico] using the Personal Computer/Smart Card ([PC/SC]) -//! interface as provided by the [`pcsc` crate]. -//! -//! # Features -//! ## Personal Identity Verification (PIV) -//! [PIV] is a [NIST] standard for both *signing* and *encryption* -//! using SmartCards and SmartCard-based hardware tokens like YubiKeys. -//! -//! PIV-related functionality can be found in the [`piv`] module. -//! -//! 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][yk-guide] for more information -//! on which devices support PIV and the available functionality. -//! -//! # Minimum Supported Rust Version -//! Rust **1.57** or newer. -//! -//! # 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 Operating Systems -//! - Linux -//! - macOS -//! - Windows -//! -//! # Supported Algorithms -//! - **Authentication**: `3DES` -//! - **Encryption**: -//! - RSA: `RSA1024`, `RSA2048` -//! - ECC: `ECCP256`, `ECCP384` (NIST curves: P-256, P-384) -//! - **Signatures**: -//! - RSASSA-PKCS#1v1.5: `RSA1024`, `RSA2048` -//! - ECDSA: `ECCP256`, `ECCP384` (NIST curves: P-256, P-384) -//! -//! NOTE: RSASSA-PSS signatures and RSA-OAEP encryption may be supportable (TBD) -//! -//! # Status -//! Functionality which has been successfully tested is available by default. -//! -//! Any functionality which is gated on the `untested` feature has not been -//! properly tested and is not known to function correctly. -//! -//! Please see the [`untested` functionality tracking issue] for current status. -//! We would appreciate any help testing this functionality and removing the -//! `untested` gating as well as writing more automated tests. -//! -//! # 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][piv-tool-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][cc-md] and ask that you do as well. -//! -//! For more information, please see [CODE_OF_CONDUCT.md][cc-md]. -//! -//! # License -//! **yubikey.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/ -//! [`untested` functionality tracking issue]: https://github.com/iqlusioninc/yubikey.rs/issues/280 -//! [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/iqlusioninc/yubikey.rs/blob/main/CODE_OF_CONDUCT.md -//! [BSDL]: https://opensource.org/licenses/BSD-2-Clause +#![doc = include_str!("../README.md")] +#![doc( + html_logo_url = "https://raw.githubusercontent.com/iqlusioninc/yubikey.rs/main/img/logo-sq.png" +)] +#![cfg_attr(docsrs, feature(doc_cfg))] +#![forbid(unsafe_code)] +#![warn(missing_docs, rust_2018_idioms, trivial_casts, unused_qualifications)] // Adapted from yubico-piv-tool: // @@ -128,13 +36,6 @@ // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -#![cfg_attr(docsrs, feature(doc_cfg))] -#![doc( - html_logo_url = "https://raw.githubusercontent.com/iqlusioninc/yubikey.rs/main/img/logo-sq.png" -)] -#![forbid(unsafe_code)] -#![warn(missing_docs, rust_2018_idioms, trivial_casts, unused_qualifications)] - mod apdu; mod cccid; pub mod certificate;