yubikey v0.6.0 (#403)

Bumps [p384](https://github.com/RustCrypto/elliptic-curves) from 0.10.0 to 0.11.2.
- [Release notes](https://github.com/RustCrypto/elliptic-curves/releases)
- [Commits](https://github.com/RustCrypto/elliptic-curves/compare/p384/v0.10.0...p384/v0.11.2)

---
updated-dependencies:
- dependency-name: p384
  dependency-type: direct:production
  update-type: version-update:semver-minor
...

Signed-off-by: dependabot[bot] <support@github.com>

Signed-off-by: dependabot[bot] <support@github.com>
Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>

.cargo/audit.toml

@@ -0,0 +1,5 @@
+[advisories]
+ignore = [
+    "RUSTSEC-2020-0071", # time
+    "RUSTSEC-2020-0159", # chrono
+] 

.github/workflows/ci.yml

@@ -36,13 +36,13 @@ jobs:
             toolchain: stable
             deps: true
           - platform: ubuntu-latest
-            toolchain: 1.46.0 # MSRV
+            toolchain: 1.57.0 # MSRV
             deps: sudo apt-get install libpcsclite-dev
           - platform: windows-latest
-            toolchain: 1.46.0 # MSRV
+            toolchain: 1.57.0 # MSRV
             deps: true
           - platform: macos-latest
-            toolchain: 1.46.0 # MSRV
+            toolchain: 1.57.0 # MSRV
             deps: true
     runs-on: ${{ matrix.platform }}
     steps:
@@ -82,7 +82,8 @@ jobs:
       - uses: actions-rs/toolchain@v1
         with:
           profile: minimal
-          toolchain: 1.46.0 # MSRV
+          toolchain: 1.57.0 # MSRV
           components: clippy
+          override: true
       - run: sudo apt-get install libpcsclite-dev
-      - run: cargo clippy --all --exclude crypto_box --all-features -- -D warnings
+      - run: cargo clippy --all --all-features -- -D warnings

.github/workflows/security_audit.yml

@@ -42,4 +42,4 @@ jobs:
         uses: actions-rs/cargo@v1
         with:
           command: audit
-          args: --deny-warnings --ignore RUSTSEC-2019-0031 # spin
+          args: --deny warnings --ignore RUSTSEC-2019-0031 # spin

CHANGELOG.md

@@ -4,7 +4,114 @@ 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.2.0 (2021-01-30)
+## 0.6.0 (2022-08-10)
+### Changed
+- 2021 edition upgrade ([#343])
+- RustCrypto crate upgrades; MSRV 1.57 ([#378])
+  - `des` v0.8
+  - `elliptic-curve` v0.12
+  - `hmac` v0.12
+  - `num-bigint-dig` v0.8
+  - `pbkdf2` v0.11
+  - `p256` v0.11
+  - `p384` v0.11
+  - `rsa` v0.6
+  - `sha1` v0.10 (replacing `sha-1`)
+  - `sha2` v0.10
+- Bump `uuid` to v1.0 ([#376])
+- Bump `der-parser` to v8.0 ([#402])
+- Bump `x509-parser` to v0.14 ([#402])
+
+[#343]: https://github.com/iqlusioninc/yubikey.rs/pull/343
+[#376]: https://github.com/iqlusioninc/yubikey.rs/pull/376
+[#378]: https://github.com/iqlusioninc/yubikey.rs/pull/378
+[#402]: https://github.com/iqlusioninc/yubikey.rs/pull/402
+
+## 0.5.0 (2021-11-21)
+### Changed
+- Update `rsa` dependency to 0.5 ([#315])
+- Update `pbkdf2` dependency to 0.9 ([#315])
+- Update `x509-parser` dependency to 0.12 ([#315], [#322])
+- Update `nom` to v7.0 ([#322])
+
+[#315]: https://github.com/iqlusioninc/yubikey.rs/pull/315
+[#322]: https://github.com/iqlusioninc/yubikey.rs/pull/322
+
+## 0.4.2 (2021-07-13)
+### Added
+- Make `yubikey::Buffer` a pub type ([#290])
+
+### Changed
+- Have `YubiKey::block_puk` take `&mut self` as argument ([#289])
+
+[#289]: https://github.com/iqlusioninc/yubikey.rs/pull/289
+[#290]: https://github.com/iqlusioninc/yubikey.rs/pull/290
+
+## 0.4.1 (2021-07-12)
+### Changed
+- Rename `SettingValue` to `Setting` ([#286])
+- Rename `Ccc` to `CccId` ([#287])
+
+[#286]: https://github.com/iqlusioninc/yubikey.rs/pull/286
+[#287]: https://github.com/iqlusioninc/yubikey.rs/pull/287
+
+## 0.4.0 (2021-07-12) [YANKED]
+### Added
+- `Result` alias ([#271])
+
+### Changed
+- Renamed crate from `yubikey-piv` => `yubikey` ([#267])
+- Renamed the following:
+    - `APDU` => `Apdu` ([#269])
+    - `CCC` => `Ccc` ([#269])
+    - `CHUID` => `ChuId` ([#269])
+    - `Ccc::cccid` => `Ccc::card_id` ([#270])
+    - `key` => `piv` ([#277])
+    - `readers` => `reader` ([#278])
+    - `readers::Readers` => `reader::Context` ([#278])
+- Bumped the following dependencies:
+  - `rsa` => v0.4 ([#246])
+  - `des` => v0.7 ([#251])
+  - `elliptic-curve` => v0.10 ([#268])
+  - `hmac` => v0.11 ([#251])
+  - `pbkdf2` => v0.8 ([#251])
+  - `p256` => v0.9 ([#268])
+  - `p384` => v0.8 ([#268])
+- MSRV 1.51+ ([#268])
+- Flatten API ([#274])
+- Replace `getrandom` with `rand_core` ([#276])
+
+### Fixed
+- Potential local DoS in TLV parser ([#279])
+
+[#246]: https://github.com/iqlusioninc/yubikey.rs/pull/246
+[#251]: https://github.com/iqlusioninc/yubikey.rs/pull/251
+[#267]: https://github.com/iqlusioninc/yubikey.rs/pull/267
+[#268]: https://github.com/iqlusioninc/yubikey.rs/pull/268
+[#269]: https://github.com/iqlusioninc/yubikey.rs/pull/269
+[#270]: https://github.com/iqlusioninc/yubikey.rs/pull/270
+[#271]: https://github.com/iqlusioninc/yubikey.rs/pull/271
+[#274]: https://github.com/iqlusioninc/yubikey.rs/pull/274
+[#276]: https://github.com/iqlusioninc/yubikey.rs/pull/276
+[#277]: https://github.com/iqlusioninc/yubikey.rs/pull/277
+[#278]: https://github.com/iqlusioninc/yubikey.rs/pull/278
+[#279]: https://github.com/iqlusioninc/yubikey.rs/pull/279
+
+## yubikey-piv 0.3.0 (2021-03-22)
+### Added
+- Typed structs for PIN-protected and admin metadata ([#223])
+- `MgmKey::set_default`/`MgmKey::set_manual` methods ([#224])
+
+### Changed
+- Have `Transaction::set_mgm_key` take touch requirement as bool ([#224])
+
+### Removed
+- `MgmKey::set` method ([#224])
+
+[#223]: https://github.com/iqlusioninc/yubikey.rs/pull/223
+[#224]: https://github.com/iqlusioninc/yubikey.rs/pull/224
+
+## yubikey-piv 0.2.0 (2021-01-30)
 ### Changed
 - Bump `der-parser` to v5.0 ([#194])
 - Improve self-signed certificates ([#207])
@@ -13,12 +120,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Bump MSRV to 1.46+ ([#208])
 - Bump `pbkdf2` dependency to v0.7 ([#219])
 
-[#194]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/194
+[#194]: https://github.com/iqlusioninc/yubikey.rs/pull/194
-[#207]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/207
+[#207]: https://github.com/iqlusioninc/yubikey.rs/pull/207
-[#208]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/208
+[#208]: https://github.com/iqlusioninc/yubikey.rs/pull/208
-[#219]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/219
+[#219]: https://github.com/iqlusioninc/yubikey.rs/pull/219
 
-## 0.1.0 (2020-10-19)
+## yubikey-piv 0.1.0 (2020-10-19)
 ### Added
 - `Certificate::generate_self_signed` ([#80])
 - `YubiKey::open_by_serial` ([#69])
@@ -43,24 +150,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Removed
 - YubiKey NEO support ([#63])
 
-[#177]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/177
+[#177]: https://github.com/iqlusioninc/yubikey.rs/pull/177
-[#175]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/175
+[#175]: https://github.com/iqlusioninc/yubikey.rs/pull/175
-[#128]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/128
+[#128]: https://github.com/iqlusioninc/yubikey.rs/pull/128
-[#82]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/82
+[#82]: https://github.com/iqlusioninc/yubikey.rs/pull/82
-[#73]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/73
+[#73]: https://github.com/iqlusioninc/yubikey.rs/pull/73
-[#88]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/88
+[#88]: https://github.com/iqlusioninc/yubikey.rs/pull/88
-[#80]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/80
+[#80]: https://github.com/iqlusioninc/yubikey.rs/pull/80
-[#69]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/69
+[#69]: https://github.com/iqlusioninc/yubikey.rs/pull/69
-[#68]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/68
+[#68]: https://github.com/iqlusioninc/yubikey.rs/pull/68
-[#67]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/67
+[#67]: https://github.com/iqlusioninc/yubikey.rs/pull/67
-[#65]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/65
+[#65]: https://github.com/iqlusioninc/yubikey.rs/pull/65
-[#64]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/64
+[#64]: https://github.com/iqlusioninc/yubikey.rs/pull/64
-[#63]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/63
+[#63]: https://github.com/iqlusioninc/yubikey.rs/pull/63
-[#62]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/62
+[#62]: https://github.com/iqlusioninc/yubikey.rs/pull/62
-[#61]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/61
+[#61]: https://github.com/iqlusioninc/yubikey.rs/pull/61
-[#60]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/60
+[#60]: https://github.com/iqlusioninc/yubikey.rs/pull/60
 
-## 0.0.3 (2019-12-02)
+## yubikey-piv 0.0.3 (2019-12-02)
 ### Added
 - Initial `Readers` enumerator for detecting YubiKeys ([#51])
 - Certificate parsing ([#45])
@@ -76,19 +183,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `Ins` (APDU instruction codes) enum ([#33])
 - Factor `Response` into `apdu` module; improved debugging ([#32])
 
-[#51]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/51
+[#51]: https://github.com/iqlusioninc/yubikey.rs/pull/51
-[#45]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/45
+[#45]: https://github.com/iqlusioninc/yubikey.rs/pull/45
-[#44]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/44
+[#44]: https://github.com/iqlusioninc/yubikey.rs/pull/44
-[#43]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/43
+[#43]: https://github.com/iqlusioninc/yubikey.rs/pull/43
-[#42]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/42
+[#42]: https://github.com/iqlusioninc/yubikey.rs/pull/42
-[#39]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/39
+[#39]: https://github.com/iqlusioninc/yubikey.rs/pull/39
-[#37]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/37
+[#37]: https://github.com/iqlusioninc/yubikey.rs/pull/37
-[#36]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/36
+[#36]: https://github.com/iqlusioninc/yubikey.rs/pull/36
-[#34]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/34
+[#34]: https://github.com/iqlusioninc/yubikey.rs/pull/34
-[#33]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/33
+[#33]: https://github.com/iqlusioninc/yubikey.rs/pull/33
-[#32]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/32
+[#32]: https://github.com/iqlusioninc/yubikey.rs/pull/32
 
-## 0.0.2 (2019-11-25)
+## yubikey-piv 0.0.2 (2019-11-25)
 ### Added
 - `untested` Cargo feature to mark untested functionality ([#30])
 - Initial connect test and docs ([#19])
@@ -103,16 +210,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Use `log` crate for logging ([#7])
 - Replace `ErrorKind::Ok` with `Result` ([#6])
 
-[#30]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/30
+[#30]: https://github.com/iqlusioninc/yubikey.rs/pull/30
-[#19]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/19
+[#19]: https://github.com/iqlusioninc/yubikey.rs/pull/19
-[#17]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/17
+[#17]: https://github.com/iqlusioninc/yubikey.rs/pull/17
-[#15]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/15
+[#15]: https://github.com/iqlusioninc/yubikey.rs/pull/15
-[#13]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/13
+[#13]: https://github.com/iqlusioninc/yubikey.rs/pull/13
-[#10]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/10
+[#10]: https://github.com/iqlusioninc/yubikey.rs/pull/10
-[#9]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/9
+[#9]: https://github.com/iqlusioninc/yubikey.rs/pull/9
-[#8]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/8
+[#8]: https://github.com/iqlusioninc/yubikey.rs/pull/8
-[#7]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/7
+[#7]: https://github.com/iqlusioninc/yubikey.rs/pull/7
-[#6]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/6
+[#6]: https://github.com/iqlusioninc/yubikey.rs/pull/6
 
-## 0.0.1 (2019-11-18)
+## yubikey-piv 0.0.1 (2019-11-18)
 - Initial release

COPYING

@@ -1,4 +1,4 @@
-Copyright (c) 2014-2019 Yubico AB, Tony Arcieri
+Copyright (c) 2014-2021 Yubico AB, Tony Arcieri
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without

Cargo.toml

@@ -1,56 +1,54 @@
 [package]
-name    = "yubikey-piv"
+name = "yubikey"
-version = "0.2.0" # Also update html_root_url in lib.rs when bumping this
+version = "0.6.0"
 description = """
-Pure Rust host-side driver for the YubiKey Personal Identity Verification (PIV)
+Pure Rust cross-platform host-side driver for YubiKey devices from Yubico with
-application providing general-purpose public-key signing and encryption
+support for hardware-backed public-key decryption and digital signatures using
-with hardware-backed private keys for RSA (2048/1024) and ECC (P-256/P-384)
+the Personal Identity Verification (PIV) application. Supports RSA (1024/2048)
-algorithms (e.g, PKCS#1v1.5, ECDSA)
+or ECC (NIST P-256/P-384) algorithms e.g, PKCS#1v1.5, ECDSA
 """
 authors = ["Tony Arcieri <tony@iqlusion.io>", "Yubico AB"]
-edition    = "2018"
 license = "BSD-2-Clause"
-repository = "https://github.com/iqlusioninc/yubikey-piv.rs"
+repository = "https://github.com/iqlusioninc/yubikey.rs"
 readme = "README.md"
 categories = ["api-bindings", "cryptography", "hardware-support"]
-keywords   = ["ecdsa", "rsa", "piv", "pcsc", "yubikey"]
+keywords = ["ecdsa", "encryption", "rsa", "piv", "signature"]
+edition = "2021"
+rust-version = "1.57"
 
 [workspace]
 members = [".", "cli"]
 
-[badges]
-maintenance = { status = "experimental" }
-
 [dependencies]
 chrono = "0.4"
 cookie-factory = "0.3"
-der-parser = "5"
+der-parser = "8"
-des = "0.6"
+des = "0.8"
-elliptic-curve = "0.8"
+elliptic-curve = "0.12"
-getrandom = "0.1"
+hmac = "0.12"
-hmac = "0.10"
 log = "0.4"
-nom = "6"
+nom = "7"
-num-bigint = { version = "0.6", features = ["rand"], package = "num-bigint-dig" }
+num-bigint-dig = { version = "0.8", features = ["rand"] }
 num-traits = "0.2"
 num-integer = "0.1"
-pbkdf2 = { version = "0.7", default-features = false }
+pbkdf2 = { version = "0.11", default-features = false }
-p256 = "0.7"
+p256 = "0.11"
-p384 = "0.6"
+p384 = "0.11"
 pcsc = "2"
-rsa = "0.3"
+rand_core = { version = "0.6", features = ["std"] }
-secrecy = "0.7"
+rsa = "0.6"
-sha-1 = "0.9"
+secrecy = "0.8"
-sha2 = "0.9"
+sha1 = "0.10"
+sha2 = "0.10"
 subtle = "2"
 subtle-encoding = "0.5"
+uuid = { version = "1.0", features = ["v4"] }
 x509 = "0.2"
-x509-parser = "0.9"
+x509-parser = "0.14"
 zeroize = "1"
 
 [dev-dependencies]
-env_logger = "0.8"
+env_logger = "0.9"
-ring = "0.16.18"
 lazy_static = "1"
 
 [features]
@@ -58,3 +56,4 @@ untested = []
 
 [package.metadata.docs.rs]
 all-features = true
+rustdoc-args = ["--cfg", "docsrs"]

README.md

@@ -1,18 +1,18 @@
-<img src="https://raw.githubusercontent.com/iqlusioninc/yubikey-piv.rs/main/img/logo.png" width="150" height="110">
+<img src="https://raw.githubusercontent.com/iqlusioninc/yubikey.rs/main/img/logo.png" width="150" height="110">
 
-# yubikey-piv.rs
+# yubikey.rs
 
 [![crate][crate-image]][crate-link]
 [![Docs][docs-image]][docs-link]
 [![2-Clause BSD Licensed][license-image]][license-link]
-![Rust Version][rustc-image]
+![MSRV][msrv-image]
-![Maintenance Status: Experimental][maintenance-image]
 [![Safety Dance][safety-image]][safety-link]
 [![Build Status][build-image]][build-link]
-[![Gitter Chat][gitter-image]][gitter-link]
+[![dependency status][deps-image]][deps-link]
 
-Pure Rust host-side YubiKey [Personal Identity Verification (PIV)][PIV] driver
+Pure Rust cross-platform host-side driver for [YubiKey] devices from [Yubico]
-with general-purpose public-key encryption and signing support.
+with support for public-key encryption and digital signatures using the
+[Personal Identity Verification (PIV)][PIV] application.
 
 [Documentation][docs-link]
 
@@ -26,8 +26,8 @@ encryption (PKCS#1v1.5/ECIES) use cases are supported for either key type.
 See [Yubico's guide to PIV-enabled YubiKeys][yk-guide] for more information
 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 data 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!
 
 Note that while this project started as a fork of a [Yubico] project,
@@ -36,7 +36,7 @@ endorsed by Yubico.
 
 ## Minimum Supported Rust Version
 
-- Rust **1.46** or newer
+Rust **1.57** or newer.
 
 ## Supported YubiKeys
 
@@ -46,6 +46,12 @@ endorsed by Yubico.
 NOTE: Nano and USB-C variants of the above are also supported.
       Pre-YK4 [YubiKey NEO] series is **NOT** supported (see [#18]).
 
+## Supported Operating Systems
+
+- Linux
+- macOS
+- Windows
+
 ## Security Warning
 
 No security audits of this crate have ever been performed. Presently it is in
@@ -53,41 +59,6 @@ an experimental stage and may still contain high-severity issues.
 
 USE AT YOUR OWN RISK!
 
-## Status
-
-This project is a largely incomplete work-in-progress. So far the only
-functionality which has actually been tested is connecting to Yubikeys.
-
-If you're interested helping test functionality, the table below documents
-the current status of the project and relevant GitHub issues for various
-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 |
-| 🚧 | `key`         | [#26] | Crypto key management: list, generate, import |
-| 🚧 | `mgm`         | [#26] | Management Key (MGM) support: set, get, derive |
-| ⚠️ | `mscmap`      | [#25] | MS Container Map Records |
-| ⚠️ | `msroots`     | [#28] | `msroots` file: PKCS#7 formatted certificate store for enterprise trusted roots |
-
-Legend:
-
-|    | Description                        |
-|----|------------------------------------|
-| ✅ | Working                            |
-| 🚧 | Testing and validation in progress |
-| ⚠️ | Untested support                   |
-
-NOTE: Commands marked ⚠️ are disabled by default as they have have not been properly tested and may contain bugs or
-not work at all. USE AT YOUR OWN RISK!
-
-Enable the `untested` feature in your `Cargo.toml` to enable features marked ⚠️
-above.
-
 ## Testing
 
 To run the full test suite, you'll need a connected YubiKey NEO/4/5 device in
@@ -115,17 +86,17 @@ Application Protocol Data Unit (APDU) messages, use the `trace` log level:
 
 ```
 running 1 test
-[INFO  yubikey_piv::yubikey] trying to connect to reader 'Yubico YubiKey OTP+FIDO+CCID'
+[INFO  yubikey::yubikey] trying to connect to reader 'Yubico YubiKey OTP+FIDO+CCID'
-[INFO  yubikey_piv::yubikey] connected to 'Yubico YubiKey OTP+FIDO+CCID' successfully
+[INFO  yubikey::yubikey] connected to 'Yubico YubiKey OTP+FIDO+CCID' successfully
-[TRACE yubikey_piv::apdu] >>> APDU { cla: 0, ins: SelectApplication, p1: 4, p2: 0, data: [160, 0, 0, 3, 8] }
+[TRACE yubikey::apdu] >>> Apdu { cla: 0, ins: SelectApplication, p1: 4, p2: 0, data: [160, 0, 0, 3, 8] }
-[TRACE yubikey_piv::transaction] >>> [0, 164, 4, 0, 5, 160, 0, 0, 3, 8]
+[TRACE yubikey::transaction] >>> [0, 164, 4, 0, 5, 160, 0, 0, 3, 8]
-[TRACE yubikey_piv::apdu] <<< Response { status_words: Success, data: [97, 17, 79, 6, 0, 0, 16, 0, 1, 0, 121, 7, 79, 5, 160, 0, 0, 3, 8] }
+[TRACE yubikey::apdu] <<< Response { status_words: Success, data: [97, 17, 79, 6, 0, 0, 16, 0, 1, 0, 121, 7, 79, 5, 160, 0, 0, 3, 8] }
-[TRACE yubikey_piv::apdu] >>> APDU { cla: 0, ins: GetVersion, p1: 0, p2: 0, data: [] }
+[TRACE yubikey::apdu] >>> Apdu { cla: 0, ins: GetVersion, p1: 0, p2: 0, data: [] }
-[TRACE yubikey_piv::transaction] >>> [0, 253, 0, 0, 0]
+[TRACE yubikey::transaction] >>> [0, 253, 0, 0, 0]
-[TRACE yubikey_piv::apdu] <<< Response { status_words: Success, data: [5, 1, 2] }
+[TRACE yubikey::apdu] <<< Response { status_words: Success, data: [5, 1, 2] }
-[TRACE yubikey_piv::apdu] >>> APDU { cla: 0, ins: GetSerial, p1: 0, p2: 0, data: [] }
+[TRACE yubikey::apdu] >>> Apdu { cla: 0, ins: GetSerial, p1: 0, p2: 0, data: [] }
-[TRACE yubikey_piv::transaction] >>> [0, 248, 0, 0, 0]
+[TRACE yubikey::transaction] >>> [0, 248, 0, 0, 0]
-[TRACE yubikey_piv::apdu] <<< Response { status_words: Success, data: [0, 115, 0, 178] }
+[TRACE yubikey::apdu] <<< Response { status_words: Success, data: [0, 115, 0, 178] }
 test connect ... ok
 ```
 
@@ -147,12 +118,12 @@ 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
+**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.
 
-Copyright (c) 2014-2020 Yubico AB, Tony Arcieri
+Copyright (c) 2014-2021 Yubico AB, Tony Arcieri
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
@@ -188,23 +159,23 @@ or conditions.
 
 [//]: # (badges)
 
-[crate-image]: https://img.shields.io/crates/v/yubikey-piv.svg
+[crate-image]: https://img.shields.io/crates/v/yubikey.svg
-[crate-link]: https://crates.io/crates/yubikey-piv
+[crate-link]: https://crates.io/crates/yubikey
-[docs-image]: https://docs.rs/yubikey-piv/badge.svg
+[docs-image]: https://docs.rs/yubikey/badge.svg
-[docs-link]: https://docs.rs/yubikey-piv/
+[docs-link]: https://docs.rs/yubikey/
 [license-image]: https://img.shields.io/badge/license-BSD-blue.svg
-[license-link]: https://github.com/iqlusioninc/yubikey-piv.rs/blob/main/COPYING
+[license-link]: https://github.com/iqlusioninc/yubikey.rs/blob/main/COPYING
-[rustc-image]: https://img.shields.io/badge/rustc-1.46+-blue.svg
+[msrv-image]: https://img.shields.io/badge/rustc-1.57+-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/
-[build-image]: https://github.com/iqlusioninc/yubikey-piv.rs/workflows/CI/badge.svg?branch=main&event=push
+[build-image]: https://github.com/iqlusioninc/yubikey.rs/workflows/CI/badge.svg?branch=main&event=push
-[build-link]: https://github.com/iqlusioninc/yubikey-piv.rs/actions
+[build-link]: https://github.com/iqlusioninc/yubikey.rs/actions
-[gitter-image]: https://badges.gitter.im/badge.svg
+[deps-image]: https://deps.rs/repo/github/iqlusioninc/yubikey.rs/status.svg
-[gitter-link]: https://gitter.im/iqlusioninc/community
+[deps-link]: https://deps.rs/repo/github/iqlusioninc/yubikey.rs
 
 [//]: # (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/
@@ -214,18 +185,18 @@ or conditions.
 [yubico-piv-tool]: https://github.com/Yubico/yubico-piv-tool/
 [Corrode]: https://github.com/jameysharp/corrode
 [cc-web]: https://contributor-covenant.org/
-[cc-md]: https://github.com/iqlusioninc/yubikey-piv.rs/blob/main/CODE_OF_CONDUCT.md
+[cc-md]: https://github.com/iqlusioninc/yubikey.rs/blob/main/CODE_OF_CONDUCT.md
 [BSDL]: https://opensource.org/licenses/BSD-2-Clause
 
 [//]: # (github issues)
 
-[#18]: https://github.com/iqlusioninc/yubikey-piv.rs/issues/18
+[#18]: https://github.com/iqlusioninc/yubikey.rs/issues/18
-[#20]: https://github.com/iqlusioninc/yubikey-piv.rs/issues/20
+[#20]: https://github.com/iqlusioninc/yubikey.rs/issues/20
-[#21]: https://github.com/iqlusioninc/yubikey-piv.rs/issues/21
+[#21]: https://github.com/iqlusioninc/yubikey.rs/issues/21
-[#22]: https://github.com/iqlusioninc/yubikey-piv.rs/issues/22
+[#22]: https://github.com/iqlusioninc/yubikey.rs/issues/22
-[#23]: https://github.com/iqlusioninc/yubikey-piv.rs/issues/23
+[#23]: https://github.com/iqlusioninc/yubikey.rs/issues/23
-[#24]: https://github.com/iqlusioninc/yubikey-piv.rs/issues/24
+[#24]: https://github.com/iqlusioninc/yubikey.rs/issues/24
-[#25]: https://github.com/iqlusioninc/yubikey-piv.rs/issues/25
+[#25]: https://github.com/iqlusioninc/yubikey.rs/issues/25
-[#26]: https://github.com/iqlusioninc/yubikey-piv.rs/issues/26
+[#26]: https://github.com/iqlusioninc/yubikey.rs/issues/26
-[#27]: https://github.com/iqlusioninc/yubikey-piv.rs/issues/27
+[#27]: https://github.com/iqlusioninc/yubikey.rs/issues/27
-[#28]: https://github.com/iqlusioninc/yubikey-piv.rs/issues/28
+[#28]: https://github.com/iqlusioninc/yubikey.rs/issues/28

cli/CHANGELOG.md

@@ -4,22 +4,49 @@ 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.5.0 (2021-11-21)
+### Changed
+- Bump `yubikey` dependency to v0.5 ([#327])
+
+[#327]: https://github.com/iqlusioninc/yubikey.rs/pull/327
+ 
+## 0.4.0 (2021-07-12)
+### Changed
+- Switch to renamed `yubikey` crate ([#283])
+- Bump MSRV to 1.51+ ([#283])
+
+[#283]: https://github.com/iqlusioninc/yubikey.rs/pull/283
+
+## 0.3.0 (2021-03-22)
+### Changed
+- Bump `yubikey-piv` dependency to v0.3 ([#240])
+
+[#240]: https://github.com/iqlusioninc/yubikey.rs/pull/240
+
+## 0.2.0 (2021-01-30)
+### Changed
+- Bump MSRV to 1.46+ ([#208])
+- Bump `yubikey-piv` dependency to v0.2 ([#220])
+
+[#208]: https://github.com/iqlusioninc/yubikey.rs/pull/208
+[#220]: https://github.com/iqlusioninc/yubikey.rs/pull/220
+
 ## 0.1.0 (2020-10-19)
 ### Added
 - `status` command ([#72], [#74])
 
 ### Changed
-- Bump `yubikey-piv` to v0.1.0 ([#180])
+- Bump `yubikey-piv` to v0.1 ([#180])
 - Bump `x509-parser` to v0.8 ([#181])
 - Bump `sha2` to v0.9 ([#182])
 - Rename `list` command to `readers`; improve usage ([#71])
 
-[#182]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/182
+[#182]: https://github.com/iqlusioninc/yubikey.rs/pull/182
-[#181]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/181
+[#181]: https://github.com/iqlusioninc/yubikey.rs/pull/181
-[#180]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/180
+[#180]: https://github.com/iqlusioninc/yubikey.rs/pull/180
-[#74]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/74
+[#74]: https://github.com/iqlusioninc/yubikey.rs/pull/74
-[#72]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/72
+[#72]: https://github.com/iqlusioninc/yubikey.rs/pull/72
-[#71]: https://github.com/iqlusioninc/yubikey-piv.rs/pull/71
+[#71]: https://github.com/iqlusioninc/yubikey.rs/pull/71
 
 ## 0.0.1 (2019-12-02)
 - Initial release

cli/Cargo.toml

@@ -1,25 +1,26 @@
 [package]
 name = "yubikey-cli"
-version = "0.1.0"
+version = "0.6.0-pre"
 description = """
 Command-line interface for performing encryption and signing using RSA/ECC keys
 stored on YubiKey devices.
 """
 authors = ["Tony Arcieri <tony@iqlusion.io>"]
-edition    = "2018"
 license = "BSD-2-Clause"
-repository = "https://github.com/iqlusioninc/yubikey-piv.rs"
+repository = "https://github.com/iqlusioninc/yubikey.rs"
 readme = "README.md"
 categories = ["command-line-utilities", "cryptography", "hardware-support"]
 keywords = ["ecdsa", "rsa", "piv", "pcsc", "yubikey"]
+edition = "2021"
+rust-version = "1.56"
 
 [dependencies]
-gumdrop = "0.8"
+clap = { version = "3", features = ["derive"] }
-env_logger = "0.8"
+env_logger = "0.9"
 lazy_static = "1"
 log = "0.4"
 sha2 = "0.9"
 subtle-encoding = "0.5"
 termcolor = "1"
-x509-parser = "0.9"
+x509-parser = "0.12"
-yubikey-piv = { version = "0.2", path = ".." }
+yubikey = { version = "0.6", path = ".." }

cli/README.md

@@ -1,4 +1,4 @@
-<img src="https://raw.githubusercontent.com/iqlusioninc/yubikey-piv.rs/main/img/logo.png" width="150" height="110">
+<img src="https://raw.githubusercontent.com/iqlusioninc/yubikey.rs/main/img/logo.png" width="150" height="110">
 
 # yubikey-cli.rs
 
@@ -18,7 +18,7 @@ utility with general-purpose public-key encryption and signing support.
 
 ## Minimum Supported Rust Version
 
-- Rust **1.39+**
+Rust **1.51** or newer.
 
 ## Supported YubiKeys
 
@@ -47,7 +47,7 @@ For more information, please see [CODE_OF_CONDUCT.md][cc-md].
 
 ## License
 
-Copyright (c) 2014-2019 Yubico AB, Tony Arcieri
+Copyright (c) 2014-2021 Yubico AB, Tony Arcieri
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
@@ -92,8 +92,8 @@ or conditions.
 [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/
-[build-image]: https://github.com/iqlusioninc/yubikey-piv.rs/workflows/CI/badge.svg?branch=main&event=push
+[build-image]: https://github.com/iqlusioninc/yubikey.rs/workflows/CI/badge.svg?branch=main&event=push
-[build-link]: https://github.com/iqlusioninc/yubikey-piv.rs/actions
+[build-link]: https://github.com/iqlusioninc/yubikey.rs/actions
 [gitter-image]: https://badges.gitter.im/badge.svg
 [gitter-link]: https://gitter.im/iqlusioninc/community
 

cli/src/bin/yubikey/main.rs

@@ -8,9 +8,9 @@
     unused_qualifications
 )]
 
-use gumdrop::Options;
+use clap::Parser;
 use yubikey_cli::commands::YubiKeyCli;
 
 fn main() {
-    YubiKeyCli::parse_args_default_or_exit().run();
+    YubiKeyCli::parse().run()
 }

cli/src/commands.rs

@@ -4,62 +4,25 @@ pub mod readers;
 pub mod status;
 
 use self::{readers::ReadersCmd, status::StatusCmd};
-use crate::terminal::{self, STDOUT};
+use crate::terminal;
-use gumdrop::Options;
+use clap::Parser;
-use std::{
+use std::{env, process::exit};
-    env,
+use termcolor::ColorChoice;
-    io::{self, Write},
+use yubikey::{Serial, YubiKey};
-    process::exit,
-};
-use termcolor::{ColorChoice, ColorSpec, WriteColor};
-use yubikey_piv::{Serial, YubiKey};
 
 /// The `yubikey` CLI utility
-#[derive(Debug, Options)]
+#[derive(Debug, Parser)]
 pub struct YubiKeyCli {
-    /// Obtain help about the current command
+    /// Serial number of the YubiKey to connect to
-    #[options(short = "h", help = "print help message")]
+    #[clap(short = 's', long = "serial")]
-    pub help: bool,
-
-    /// Specify the serial number of the YubiKey to connect to
-    #[options(
-        short = "s",
-        long = "serial",
-        help = "serial number of the YubiKey to connect to"
-    )]
     pub serial: Option<Serial>,
 
     /// Subcommand to execute.
-    #[options(command)]
+    #[clap(subcommand)]
-    pub command: Option<Commands>,
+    pub command: Commands,
 }
 
 impl YubiKeyCli {
-    /// Print usage information
-    pub fn print_usage() -> Result<(), io::Error> {
-        let mut stdout = STDOUT.lock();
-        stdout.reset()?;
-
-        let mut bold = ColorSpec::new();
-        bold.set_bold(true);
-
-        stdout.set_color(&bold)?;
-        writeln!(
-            stdout,
-            "{} {}",
-            env!("CARGO_PKG_NAME"),
-            env!("CARGO_PKG_VERSION")
-        )?;
-        stdout.reset()?;
-
-        writeln!(stdout, "{}", env!("CARGO_PKG_AUTHORS"))?;
-        writeln!(stdout, "{}", env!("CARGO_PKG_DESCRIPTION").trim())?;
-        writeln!(stdout)?;
-        writeln!(stdout, "{}", Commands::usage())?;
-
-        Ok(())
-    }
-
     /// Run the underlying command type or print usage info and exit
     pub fn run(&self) {
         // TODO(tarcieri): make this more configurable
@@ -70,10 +33,7 @@ impl YubiKeyCli {
             env_logger::builder().format_timestamp(None).init();
         }
 
-        match &self.command {
+        self.command.run(self.yubikey_init())
-            Some(cmd) => cmd.run(self.yubikey_init()),
-            None => Self::print_usage().unwrap(),
-        }
     }
 
     /// Initialize the YubiKey client driver
@@ -92,22 +52,18 @@ impl YubiKeyCli {
 }
 
 /// Subcommands of this application
-#[derive(Debug, Options)]
+#[derive(Debug, Parser)]
 pub enum Commands {
-    /// `help` subcommand
-    #[options(help = "show help for a command")]
-    Help(HelpOpts),
-
     /// `version` subcommand
-    #[options(help = "display version information")]
+    #[clap(about = "display version information")]
     Version(VersionOpts),
 
     /// `readers` subcommand
-    #[options(help = "list detected readers")]
+    #[clap(about = "list detected readers")]
     Readers(ReadersCmd),
 
     /// `status` subcommand
-    #[options(help = "show yubikey status")]
+    #[clap(about = "show yubikey status")]
     Status(StatusCmd),
 }
 
@@ -115,7 +71,6 @@ impl Commands {
     /// Run the given command
     pub fn run(&self, yubikey: YubiKey) {
         match self {
-            Commands::Help(help) => help.run(),
             Commands::Version(version) => version.run(),
             Commands::Readers(list) => list.run(),
             Commands::Status(status) => status.run(yubikey),
@@ -123,28 +78,8 @@ impl Commands {
     }
 }
 
-/// Help options
-#[derive(Debug, Options)]
-pub struct HelpOpts {
-    #[options(free, help = "subcommand to get help for")]
-    free: Vec<String>,
-}
-
-impl HelpOpts {
-    fn run(&self) {
-        if let Some(command) = self.free.first() {
-            if let Some(usage) = Commands::command_usage(command) {
-                println!("{}", usage);
-                exit(1);
-            }
-        }
-
-        println!("{}", Commands::usage());
-    }
-}
-
 /// Version options
-#[derive(Debug, Options)]
+#[derive(Debug, Parser)]
 pub struct VersionOpts {}
 
 impl VersionOpts {

cli/src/commands/readers.rs

@@ -1,22 +1,22 @@
 //! List detected readers
 
 use crate::terminal::STDOUT;
-use gumdrop::Options;
+use clap::Parser;
 use std::{
     io::{self, Write},
     process::exit,
 };
 use termcolor::{ColorSpec, StandardStreamLock, WriteColor};
-use yubikey_piv::{Readers, Serial};
+use yubikey::{Context, Serial};
 
 /// The `readers` subcommand
-#[derive(Debug, Options)]
+#[derive(Debug, Parser)]
 pub struct ReadersCmd {}
 
 impl ReadersCmd {
     /// Run the `readers` subcommand
     pub fn run(&self) {
-        let mut readers = Readers::open().unwrap_or_else(|e| {
+        let mut readers = Context::open().unwrap_or_else(|e| {
             status_err!("couldn't open PC/SC context: {}", e);
             exit(1);
         });
@@ -53,7 +53,7 @@ impl ReadersCmd {
         index: usize,
         name: &str,
         serial: Serial,
-    ) -> Result<(), io::Error> {
+    ) -> io::Result<()> {
         stream.set_color(ColorSpec::new().set_bold(true))?;
         write!(stream, "{:>3}:", index)?;
         stream.reset()?;

cli/src/commands/status.rs

@@ -1,18 +1,16 @@
 //! Print device status
 
-use crate::terminal::STDOUT;
+use crate::terminal::{print_cert_info, STDOUT};
-use gumdrop::Options;
+use clap::Parser;
 use std::io::{self, Write};
 use termcolor::{ColorSpec, StandardStreamLock, WriteColor};
-use yubikey_piv::{key::*, YubiKey};
+use yubikey::{piv::*, YubiKey};
-
-use crate::print_cert_info;
 
 // String to use for `None`
 const NONE_STR: &str = "<none>";
 
 /// The `status` subcommand
-#[derive(Debug, Options)]
+#[derive(Debug, Parser)]
 pub struct StatusCmd {}
 
 impl StatusCmd {
@@ -51,7 +49,7 @@ impl StatusCmd {
         stream: &mut StandardStreamLock<'_>,
         name: &str,
         value: impl ToString,
-    ) -> Result<(), io::Error> {
+    ) -> io::Result<()> {
         stream.set_color(ColorSpec::new().set_bold(true))?;
         write!(stream, "{:>12}:", name)?;
         stream.reset()?;

cli/src/lib.rs

@@ -1,92 +1,13 @@
-//! `yubikey` command-line utility
+//! `yubikey` command-line utility.
+//!
+//! The goal of this tool is to provide functionality similar to `yubico-piv-tool`
+//! but implemented in pure Rust.
+//!
+//! It also serves as a demonstration/example of how to use the `yubikey` crate.
 
 #![forbid(unsafe_code)]
-#![warn(
+#![warn(missing_docs, rust_2018_idioms, unused_qualifications)]
-    missing_docs,
-    rust_2018_idioms,
-    unused_lifetimes,
-    unused_qualifications
-)]
 
 #[macro_use]
 pub mod terminal;
-
 pub mod commands;
-
-use log::debug;
-use sha2::{Digest, Sha256};
-use std::io::{self, Write};
-use std::str;
-use subtle_encoding::hex;
-use termcolor::{ColorSpec, StandardStreamLock, WriteColor};
-use x509_parser::parse_x509_certificate;
-use yubikey_piv::{certificate::Certificate, key::*, YubiKey};
-
-///Write information about certificate found in slot a la yubico-piv-tool output.
-pub fn print_cert_info(
-    yubikey: &mut YubiKey,
-    slot: SlotId,
-    stream: &mut StandardStreamLock<'_>,
-) -> Result<(), io::Error> {
-    let cert = match Certificate::read(yubikey, slot) {
-        Ok(c) => c,
-        Err(e) => {
-            debug!("error reading certificate in slot {:?}: {}", slot, e);
-            return Ok(());
-        }
-    };
-    let buf = cert.into_buffer();
-
-    if !buf.is_empty() {
-        let fingerprint = Sha256::digest(&buf);
-        let slot_id: u8 = slot.into();
-        print_cert_attr(stream, "Slot", format!("{:x}", slot_id))?;
-        match parse_x509_certificate(&buf) {
-            Ok((_rem, cert)) => {
-                print_cert_attr(
-                    stream,
-                    "Algorithm",
-                    cert.tbs_certificate.subject_pki.algorithm.algorithm,
-                )?;
-
-                print_cert_attr(stream, "Subject", cert.tbs_certificate.subject)?;
-                print_cert_attr(stream, "Issuer", cert.tbs_certificate.issuer)?;
-                print_cert_attr(
-                    stream,
-                    "Fingerprint",
-                    str::from_utf8(hex::encode(fingerprint).as_slice()).unwrap(),
-                )?;
-                print_cert_attr(
-                    stream,
-                    "Not Before",
-                    cert.tbs_certificate.validity.not_before.to_rfc2822(),
-                )?;
-                print_cert_attr(
-                    stream,
-                    "Not After",
-                    cert.tbs_certificate.validity.not_after.to_rfc2822(),
-                )?;
-            }
-            _ => {
-                println!("Failed to parse certificate");
-                return Ok(());
-            }
-        };
-    }
-
-    Ok(())
-}
-
-/// Print a status attribute
-fn print_cert_attr(
-    stream: &mut StandardStreamLock<'_>,
-    name: &str,
-    value: impl ToString,
-) -> Result<(), io::Error> {
-    stream.set_color(ColorSpec::new().set_bold(true))?;
-    write!(stream, "{:>12}:", name)?;
-    stream.reset()?;
-    writeln!(stream, " {}", value.to_string())?;
-    stream.flush()?;
-    Ok(())
-}

cli/src/terminal.rs

@@ -1,9 +1,17 @@
 //! Status messages
 
 use lazy_static::lazy_static;
-use std::io::{self, Write};
+use log::debug;
-use std::sync::Mutex;
+use sha2::{Digest, Sha256};
-use termcolor::{Color, ColorChoice, ColorSpec, StandardStream, WriteColor};
+use std::{
+    io::{self, Write},
+    str,
+    sync::Mutex,
+};
+use subtle_encoding::hex;
+use termcolor::{Color, ColorChoice, ColorSpec, StandardStream, StandardStreamLock, WriteColor};
+use x509_parser::parse_x509_certificate;
+use yubikey::{certificate::Certificate, piv::*, YubiKey};
 
 /// Print a success status message (in green if colors are enabled)
 #[macro_export]
@@ -143,7 +151,7 @@ impl Status {
     }
 
     /// Print the given message
-    fn print(self, stream: &StandardStream, msg: impl AsRef<str>) -> Result<(), io::Error> {
+    fn print(self, stream: &StandardStream, msg: impl AsRef<str>) -> io::Result<()> {
         let mut s = stream.lock();
         s.reset()?;
         s.set_color(ColorSpec::new().set_fg(self.color).set_bold(self.bold))?;
@@ -163,3 +171,72 @@ impl Status {
         Ok(())
     }
 }
+
+/// Write information about certificate found in slot a la yubico-piv-tool output.
+pub fn print_cert_info(
+    yubikey: &mut YubiKey,
+    slot: SlotId,
+    stream: &mut StandardStreamLock<'_>,
+) -> io::Result<()> {
+    let cert = match Certificate::read(yubikey, slot) {
+        Ok(c) => c,
+        Err(e) => {
+            debug!("error reading certificate in slot {:?}: {}", slot, e);
+            return Ok(());
+        }
+    };
+    let buf = cert.into_buffer();
+
+    if !buf.is_empty() {
+        let fingerprint = Sha256::digest(&buf);
+        let slot_id: u8 = slot.into();
+        print_cert_attr(stream, "Slot", format!("{:x}", slot_id))?;
+        match parse_x509_certificate(&buf) {
+            Ok((_rem, cert)) => {
+                print_cert_attr(
+                    stream,
+                    "Algorithm",
+                    cert.tbs_certificate.subject_pki.algorithm.algorithm,
+                )?;
+
+                print_cert_attr(stream, "Subject", cert.tbs_certificate.subject)?;
+                print_cert_attr(stream, "Issuer", cert.tbs_certificate.issuer)?;
+                print_cert_attr(
+                    stream,
+                    "Fingerprint",
+                    str::from_utf8(hex::encode(fingerprint).as_slice()).unwrap(),
+                )?;
+                print_cert_attr(
+                    stream,
+                    "Not Before",
+                    cert.tbs_certificate.validity.not_before.to_rfc2822(),
+                )?;
+                print_cert_attr(
+                    stream,
+                    "Not After",
+                    cert.tbs_certificate.validity.not_after.to_rfc2822(),
+                )?;
+            }
+            _ => {
+                println!("Failed to parse certificate");
+                return Ok(());
+            }
+        };
+    }
+
+    Ok(())
+}
+
+/// Print a status attribute
+fn print_cert_attr(
+    stream: &mut StandardStreamLock<'_>,
+    name: &str,
+    value: impl ToString,
+) -> io::Result<()> {
+    stream.set_color(ColorSpec::new().set_bold(true))?;
+    write!(stream, "{:>12}:", name)?;
+    stream.reset()?;
+    writeln!(stream, " {}", value.to_string())?;
+    stream.flush()?;
+    Ok(())
+}

src/apdu.rs

@@ -30,7 +30,7 @@
 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-use crate::{error::Error, transaction::Transaction, Buffer};
+use crate::{transaction::Transaction, Buffer, Result};
 use log::trace;
 use zeroize::{Zeroize, Zeroizing};
 
@@ -41,7 +41,7 @@ const APDU_DATA_MAX: usize = 0xFF;
 ///
 /// These messages are packets used to communicate with the YubiKey.
 #[derive(Clone, Debug, Eq, PartialEq)]
-pub(crate) struct APDU {
+pub(crate) struct Apdu {
     /// Instruction class: indicates the type of command (e.g. inter-industry or proprietary)
     cla: u8,
 
@@ -58,7 +58,7 @@ pub(crate) struct APDU {
     data: Vec<u8>,
 }
 
-impl APDU {
+impl Apdu {
     /// Create a new APDU with the given instruction code
     pub fn new(ins: impl Into<Ins>) -> Self {
         Self {
@@ -109,7 +109,7 @@ impl APDU {
     }
 
     /// Transmit this APDU using the given card transaction
-    pub fn transmit(&self, txn: &Transaction<'_>, recv_len: usize) -> Result<Response, Error> {
+    pub fn transmit(&self, txn: &Transaction<'_>, recv_len: usize) -> Result<Response> {
         trace!(">>> {:?}", self);
         let response = Response::from(txn.transmit(&self.to_bytes(), recv_len)?);
         trace!("<<< {:?}", &response);
@@ -129,13 +129,13 @@ impl APDU {
     }
 }
 
-impl Drop for APDU {
+impl Drop for Apdu {
     fn drop(&mut self) {
         self.zeroize();
     }
 }
 
-impl Zeroize for APDU {
+impl Zeroize for Apdu {
     fn zeroize(&mut self) {
         // Only `data` may contain secrets
         self.data.zeroize();

src/cccid.rs

@@ -30,17 +30,14 @@
 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-use crate::{error::Error, yubikey::YubiKey};
+use crate::{Error, Result, YubiKey};
-use getrandom::getrandom;
+use rand_core::{OsRng, RngCore};
-use std::fmt::{self, Debug, Display};
+use std::{
+    fmt::{self, Debug, Display},
+    str,
+};
 use subtle_encoding::hex;
 
-/// CCCID size
-pub const CCCID_SIZE: usize = 14;
-
-/// CCC size
-pub const CCC_SIZE: usize = 51;
-
 /// CCCID offset
 const CCC_ID_OFFS: usize = 9;
 
@@ -62,33 +59,39 @@ const CCC_TMPL: &[u8] = &[
     0x00, 0xfe, 0x00,
 ];
 
-/// Cardholder Capability Container (CCC) Identifier Card ID
+/// Cardholder Capability Container (CCC) Identifier Card ID.
-#[derive(Copy, Clone, Debug, Eq, PartialEq)]
+#[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)]
-pub struct CardId(pub [u8; CCCID_SIZE]);
+pub struct CardId(pub [u8; Self::BYTE_SIZE]);
 
 impl CardId {
+    /// CCCID size in bytes
+    pub const BYTE_SIZE: usize = 14;
+
     /// Generate a random CCC Card ID
-    pub fn generate() -> Result<Self, Error> {
+    pub fn generate() -> Self {
-        let mut id = [0u8; CCCID_SIZE];
+        let mut id = [0u8; Self::BYTE_SIZE];
-        getrandom(&mut id).map_err(|_| Error::RandomnessError)?;
+        OsRng.fill_bytes(&mut id);
-        Ok(Self(id))
+        Self(id)
     }
 }
 
-/// Cardholder Capability Container (CCC) Identifier
+/// Cardholder Capability Container (CCC) Identifier.
-#[derive(Copy, Clone)]
+#[derive(Copy, Clone, Debug, Eq, PartialEq)]
-pub struct CCC(pub [u8; CCC_SIZE]);
+pub struct CccId(pub [u8; Self::BYTE_SIZE]);
+
+impl CccId {
+    /// CCC size in bytes
+    pub const BYTE_SIZE: usize = 51;
 
-impl CCC {
     /// Return CardId component of CCC
-    pub fn cccid(&self) -> Result<CardId, Error> {
+    pub fn card_id(&self) -> Result<CardId> {
-        let mut cccid = [0u8; CCCID_SIZE];
+        let mut cccid = [0u8; CardId::BYTE_SIZE];
-        cccid.copy_from_slice(&self.0[CCC_ID_OFFS..(CCC_ID_OFFS + CCCID_SIZE)]);
+        cccid.copy_from_slice(&self.0[CCC_ID_OFFS..(CCC_ID_OFFS + CardId::BYTE_SIZE)]);
         Ok(CardId(cccid))
     }
 
     /// Get Cardholder Capability Container (CCC) ID
-    pub fn get(yubikey: &mut YubiKey) -> Result<Self, Error> {
+    pub fn get(yubikey: &mut YubiKey) -> Result<Self> {
         let txn = yubikey.begin_transaction()?;
         let response = txn.fetch_object(OBJ_CAPABILITY)?;
 
@@ -96,14 +99,13 @@ impl CCC {
             return Err(Error::GenericError);
         }
 
-        let mut ccc = [0u8; CCC_SIZE];
+        Ok(Self(response[..Self::BYTE_SIZE].try_into().unwrap()))
-        ccc.copy_from_slice(&response[0..CCC_SIZE]);
-        Ok(Self(ccc))
     }
 
-    /// Get Cardholder Capability Container (CCC) ID
+    /// Set Cardholder Capability Container (CCC) ID
     #[cfg(feature = "untested")]
-    pub fn set(&self, yubikey: &mut YubiKey) -> Result<(), Error> {
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
+    pub fn set(&self, yubikey: &mut YubiKey) -> Result<()> {
         let mut buf = CCC_TMPL.to_vec();
         buf[0..self.0.len()].copy_from_slice(&self.0);
 
@@ -112,18 +114,8 @@ impl CCC {
     }
 }
 
-impl Debug for CCC {
+impl Display for CccId {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        write!(f, "CCC({:?})", &self.0[..])
+        f.write_str(str::from_utf8(&hex::encode(&self.0[..])).unwrap())
-    }
-}
-
-impl Display for CCC {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        write!(
-            f,
-            "{}",
-            String::from_utf8(hex::encode(&self.0[..])).unwrap()
-        )
     }
 }

src/certificate.rs

@@ -1,4 +1,4 @@
-//! YubiKey Certificates
+//! X.509 certificate support.
 
 // Adapted from yubico-piv-tool:
 // <https://github.com/Yubico/yubico-piv-tool/>
@@ -31,8 +31,9 @@
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 use crate::{
-    error::Error,
+    consts::CB_OBJ_MAX,
-    key::{sign_data, AlgorithmId, SlotId},
+    error::{Error, Result},
+    piv::{sign_data, AlgorithmId, SlotId},
     serialization::*,
     transaction::Transaction,
     yubikey::YubiKey,
@@ -41,20 +42,16 @@ use crate::{
 use chrono::{DateTime, Utc};
 use elliptic_curve::sec1::EncodedPoint as EcPublicKey;
 use log::error;
-use num_bigint::BigUint;
+use num_bigint_dig::BigUint;
 use p256::NistP256;
 use p384::NistP384;
-use rsa::{PublicKeyParts, RSAPublicKey};
+use rsa::{PublicKeyParts, RsaPublicKey};
 use sha2::{Digest, Sha256};
-use std::convert::TryFrom;
+use std::{fmt, ops::DerefMut};
-use std::fmt;
-use std::ops::DerefMut;
 use x509::{der::Oid, RelativeDistinguishedName};
 use x509_parser::{parse_x509_certificate, x509::SubjectPublicKeyInfo};
 use zeroize::Zeroizing;
 
-use crate::CB_OBJ_MAX;
-
 // TODO: Make these der_parser::oid::Oid constants when it has const fn support.
 const OID_RSA_ENCRYPTION: &str = "1.2.840.113549.1.1.1";
 const OID_EC_PUBLIC_KEY: &str = "1.2.840.10045.2.1";
@@ -82,13 +79,13 @@ impl From<[u8; 20]> for Serial {
 }
 
 impl TryFrom<&[u8]> for Serial {
-    type Error = ();
+    type Error = Error;
 
-    fn try_from(bytes: &[u8]) -> Result<Serial, ()> {
+    fn try_from(bytes: &[u8]) -> Result<Serial> {
         if bytes.len() <= 20 {
-            Ok(Serial(BigUint::from_bytes_be(&bytes)))
+            Ok(Serial(BigUint::from_bytes_be(bytes)))
         } else {
-            Err(())
+            Err(Error::ParseError)
         }
     }
 }
@@ -112,7 +109,7 @@ pub enum CertInfo {
 impl TryFrom<u8> for CertInfo {
     type Error = Error;
 
-    fn try_from(value: u8) -> Result<Self, Self::Error> {
+    fn try_from(value: u8) -> Result<Self> {
         match value {
             0x00 => Ok(CertInfo::Uncompressed),
             0x01 => Ok(CertInfo::Gzip),
@@ -173,7 +170,7 @@ pub enum PublicKeyInfo {
         algorithm: AlgorithmId,
 
         /// Public key
-        pubkey: RSAPublicKey,
+        pubkey: RsaPublicKey,
     },
 
     /// EC P-256 keys
@@ -190,10 +187,10 @@ impl fmt::Debug for PublicKeyInfo {
 }
 
 impl PublicKeyInfo {
-    fn parse(subject_pki: &SubjectPublicKeyInfo<'_>) -> Result<Self, Error> {
+    fn parse(subject_pki: &SubjectPublicKeyInfo<'_>) -> Result<Self> {
         match subject_pki.algorithm.algorithm.to_string().as_str() {
             OID_RSA_ENCRYPTION => {
-                let pubkey = read_pki::rsa_pubkey(subject_pki.subject_public_key.data)?;
+                let pubkey = read_pki::rsa_pubkey(&subject_pki.subject_public_key.data)?;
 
                 Ok(PublicKeyInfo::Rsa {
                     algorithm: match pubkey.n().bits() {
@@ -213,10 +210,10 @@ impl PublicKeyInfo {
                     .ok_or(Error::InvalidObject)?;
 
                 match read_pki::ec_parameters(algorithm_parameters)? {
-                    AlgorithmId::EccP256 => EcPublicKey::from_bytes(key_bytes)
+                    AlgorithmId::EccP256 => EcPublicKey::<NistP256>::from_bytes(key_bytes)
                         .map(PublicKeyInfo::EcP256)
                         .map_err(|_| Error::InvalidObject),
-                    AlgorithmId::EccP384 => EcPublicKey::from_bytes(key_bytes)
+                    AlgorithmId::EccP384 => EcPublicKey::<NistP384>::from_bytes(key_bytes)
                         .map(PublicKeyInfo::EcP384)
                         .map_err(|_| Error::InvalidObject),
                     _ => Err(Error::AlgorithmError),
@@ -321,6 +318,7 @@ impl x509::AlgorithmIdentifier for SignatureId {
 #[derive(Clone, Debug)]
 pub struct Certificate {
     serial: Serial,
+    #[allow(dead_code)]
     issuer: String,
     subject: String,
     subject_pki: PublicKeyInfo,
@@ -330,7 +328,7 @@ pub struct Certificate {
 impl<'a> TryFrom<&'a [u8]> for Certificate {
     type Error = Error;
 
-    fn try_from(bytes: &'a [u8]) -> Result<Self, Error> {
+    fn try_from(bytes: &'a [u8]) -> Result<Self> {
         Self::from_bytes(bytes.to_vec())
     }
 }
@@ -350,7 +348,7 @@ impl Certificate {
         subject: &[RelativeDistinguishedName<'_>],
         subject_pki: PublicKeyInfo,
         extensions: &[x509::Extension<'_, O>],
-    ) -> Result<Self, Error> {
+    ) -> Result<Self> {
         let serial = serial.into();
 
         let mut tbs_cert = Buffer::new(Vec::with_capacity(CB_OBJ_MAX));
@@ -365,12 +363,12 @@ impl Certificate {
                 &serial.to_bytes(),
                 &signature_algorithm,
                 // Issuer and subject are the same in self-signed certificates.
-                &subject,
+                subject,
                 Utc::now(),
                 not_after,
-                &subject,
+                subject,
                 &subject_pki,
-                &extensions,
+                extensions,
             ),
             tbs_cert.deref_mut(),
         )
@@ -453,7 +451,7 @@ impl Certificate {
     }
 
     /// Read a certificate from the given slot in the YubiKey
-    pub fn read(yubikey: &mut YubiKey, slot: SlotId) -> Result<Self, Error> {
+    pub fn read(yubikey: &mut YubiKey, slot: SlotId) -> Result<Self> {
         let txn = yubikey.begin_transaction()?;
         let buf = read_certificate(&txn, slot)?;
 
@@ -465,25 +463,21 @@ impl Certificate {
     }
 
     /// Write this certificate into the YubiKey in the given slot
-    pub fn write(
+    pub fn write(&self, yubikey: &mut YubiKey, slot: SlotId, certinfo: CertInfo) -> Result<()> {
-        &self,
-        yubikey: &mut YubiKey,
-        slot: SlotId,
-        certinfo: CertInfo,
-    ) -> Result<(), Error> {
         let txn = yubikey.begin_transaction()?;
         write_certificate(&txn, slot, Some(&self.data), certinfo)
     }
 
     /// Delete a certificate located at the given slot of the given YubiKey
     #[cfg(feature = "untested")]
-    pub fn delete(yubikey: &mut YubiKey, slot: SlotId) -> Result<(), Error> {
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
+    pub fn delete(yubikey: &mut YubiKey, slot: SlotId) -> Result<()> {
         let txn = yubikey.begin_transaction()?;
         write_certificate(&txn, slot, None, CertInfo::Uncompressed)
     }
 
     /// Initialize a local certificate struct from the given bytebuffer
-    pub fn from_bytes(cert: impl Into<Buffer>) -> Result<Self, Error> {
+    pub fn from_bytes(cert: impl Into<Buffer>) -> Result<Self> {
         let cert = cert.into();
 
         if cert.is_empty() {
@@ -544,7 +538,7 @@ impl AsRef<[u8]> for Certificate {
 }
 
 /// Read certificate
-pub(crate) fn read_certificate(txn: &Transaction<'_>, slot: SlotId) -> Result<Buffer, Error> {
+pub(crate) fn read_certificate(txn: &Transaction<'_>, slot: SlotId) -> Result<Buffer> {
     let object_id = slot.object_id();
 
     let buf = match txn.fetch_object(object_id) {
@@ -572,7 +566,7 @@ pub(crate) fn write_certificate(
     slot: SlotId,
     data: Option<&[u8]>,
     certinfo: CertInfo,
-) -> Result<(), Error> {
+) -> Result<()> {
     let object_id = slot.object_id();
 
     if data.is_none() {
@@ -593,16 +587,16 @@ pub(crate) fn write_certificate(
 
 mod read_pki {
     use der_parser::{
+        asn1_rs::Any,
         ber::BerObjectContent,
-        der::{parse_der_integer, DerObject},
+        der::{parse_der_integer, parse_der_sequence_defined_g, DerObject},
         error::BerError,
-        *,
     };
-    use nom::{combinator, IResult};
+    use nom::{combinator, sequence::pair, IResult};
-    use rsa::{BigUint, RSAPublicKey};
+    use rsa::{BigUint, RsaPublicKey};
 
     use super::{OID_NIST_P256, OID_NIST_P384};
-    use crate::{error::Error, key::AlgorithmId};
+    use crate::{piv::AlgorithmId, Error, Result};
 
     /// From [RFC 8017](https://tools.ietf.org/html/rfc8017#appendix-A.1.1):
     /// ```text
@@ -611,21 +605,18 @@ mod read_pki {
     ///     publicExponent    INTEGER   -- e
     /// }
     /// ```
-    pub(super) fn rsa_pubkey(encoded: &[u8]) -> Result<RSAPublicKey, Error> {
+    pub(super) fn rsa_pubkey(encoded: &[u8]) -> Result<RsaPublicKey> {
-        fn parse_rsa_pubkey(i: &[u8]) -> IResult<&[u8], DerObject<'_>, BerError> {
+        fn parse_rsa_pubkey(i: &[u8]) -> IResult<&[u8], (DerObject<'_>, DerObject<'_>), BerError> {
-            parse_der_sequence_defined!(i, parse_der_integer >> parse_der_integer)
+            parse_der_sequence_defined_g(|i, _| pair(parse_der_integer, parse_der_integer)(i))(i)
         }
 
         fn rsa_pubkey_parts(i: &[u8]) -> IResult<&[u8], (BigUint, BigUint), BerError> {
-            combinator::map(parse_rsa_pubkey, |object| {
+            combinator::map(parse_rsa_pubkey, |(modulus, public_exponent)| {
-                let seq = object.as_sequence().expect("is DER sequence");
+                let n = match modulus.content {
-                assert_eq!(seq.len(), 2);
-
-                let n = match seq[0].content {
                     BerObjectContent::Integer(s) => BigUint::from_bytes_be(s),
                     _ => panic!("expected DER integer"),
                 };
-                let e = match seq[1].content {
+                let e = match public_exponent.content {
                     BerObjectContent::Integer(s) => BigUint::from_bytes_be(s),
                     _ => panic!("expected DER integer"),
                 };
@@ -639,7 +630,7 @@ mod read_pki {
             _ => return Err(Error::InvalidObject),
         };
 
-        RSAPublicKey::new(n, e).map_err(|_| Error::InvalidObject)
+        RsaPublicKey::new(n, e).map_err(|_| Error::InvalidObject)
     }
 
     /// From [RFC 5480](https://tools.ietf.org/html/rfc5480#section-2.1.1):
@@ -650,8 +641,8 @@ mod read_pki {
     ///   -- specifiedCurve  SpecifiedECDomain
     /// }
     /// ```
-    pub(super) fn ec_parameters(parameters: &DerObject<'_>) -> Result<AlgorithmId, Error> {
+    pub(super) fn ec_parameters(parameters: &Any<'_>) -> Result<AlgorithmId> {
-        let curve_oid = parameters.as_oid_val().map_err(|_| Error::InvalidObject)?;
+        let curve_oid = parameters.as_oid().map_err(|_| Error::InvalidObject)?;
 
         match curve_oid.to_string().as_str() {
             OID_NIST_P256 => Ok(AlgorithmId::EccP256),
@@ -663,7 +654,7 @@ mod read_pki {
 
 mod write_pki {
     use cookie_factory::{SerializeFn, WriteContext};
-    use rsa::{BigUint, PublicKeyParts, RSAPublicKey};
+    use rsa::{BigUint, PublicKeyParts, RsaPublicKey};
     use std::io::Write;
     use x509::der::write::{der_integer, der_sequence};
 
@@ -680,7 +671,7 @@ mod write_pki {
     /// }
     /// ```
     pub(super) fn rsa_pubkey<'a, W: Write + 'a>(
-        pubkey: &'a RSAPublicKey,
+        pubkey: &'a RsaPublicKey,
     ) -> impl SerializeFn<W> + 'a {
         der_sequence((
             der_integer_biguint(pubkey.n()),

src/chuid.rs

@@ -30,22 +30,13 @@
 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-use crate::{error::Error, yubikey::YubiKey};
+use crate::{Error, Result, YubiKey};
-use getrandom::getrandom;
+use std::{
-use std::fmt::{self, Debug, Display};
+    fmt::{self, Debug, Display},
+    str,
+};
 use subtle_encoding::hex;
-
+use uuid::Uuid;
-/// CHUID size
-pub const CHUID_SIZE: usize = 59;
-
-/// CARDID size
-pub const CARDID_SIZE: usize = 16;
-
-/// FASC-N component size
-pub const FASCN_SIZE: usize = 25;
-
-/// Expiration size
-pub const EXPIRATION_SIZE: usize = 8;
 
 /// FASC-N offset
 const CHUID_FASCN_OFFS: usize = 2;
@@ -81,50 +72,42 @@ const CHUID_TMPL: &[u8] = &[
     0x30, 0x33, 0x30, 0x30, 0x31, 0x30, 0x31, 0x3e, 0x00, 0xfe, 0x00,
 ];
 
-/// Cardholder Unique Identifier (CHUID) Card UUID/GUID value
+/// Cardholder Unique Identifier (CHUID).
 #[derive(Copy, Clone, Debug)]
-pub struct Uuid(pub [u8; CARDID_SIZE]);
+pub struct ChuId(pub [u8; Self::BYTE_SIZE]);
 
-impl Uuid {
+impl ChuId {
-    /// Generate a random Cardholder Unique Identifier (CHUID) UUID
+    /// CHUID size in bytes
-    pub fn generate() -> Result<Self, Error> {
+    pub const BYTE_SIZE: usize = 59;
-        let mut id = [0u8; CARDID_SIZE];
-        getrandom(&mut id).map_err(|_| Error::RandomnessError)?;
-        Ok(Self(id))
-    }
-}
 
-/// Cardholder Unique Identifier (CHUID)
+    /// FASC-N component size
-#[derive(Copy, Clone)]
+    pub const FASCN_SIZE: usize = 25;
-pub struct CHUID(pub [u8; CHUID_SIZE]);
+
+    /// Expiration size
+    pub const EXPIRATION_SIZE: usize = 8;
 
-impl CHUID {
     /// Return FASC-N component of CHUID
-    pub fn fascn(&self) -> Result<[u8; FASCN_SIZE], Error> {
+    pub fn fascn(&self) -> [u8; Self::FASCN_SIZE] {
-        let mut fascn = [0u8; FASCN_SIZE];
+        self.0[CHUID_FASCN_OFFS..(CHUID_FASCN_OFFS + Self::FASCN_SIZE)]
-        fascn.copy_from_slice(&self.0[CHUID_FASCN_OFFS..(CHUID_FASCN_OFFS + FASCN_SIZE)]);
+            .try_into()
-        Ok(fascn)
+            .unwrap()
     }
 
     /// Return Card UUID/GUID component of CHUID
-    pub fn uuid(&self) -> Result<[u8; CARDID_SIZE], Error> {
+    pub fn uuid(&self) -> Uuid {
-        let mut uuid = [0u8; CARDID_SIZE];
+        Uuid::from_slice(&self.0[CHUID_GUID_OFFS..(CHUID_GUID_OFFS + 16)]).unwrap()
-        uuid.copy_from_slice(&self.0[CHUID_GUID_OFFS..(CHUID_GUID_OFFS + CARDID_SIZE)]);
-        Ok(uuid)
     }
 
     /// Return expiration date component of CHUID
     // TODO(tarcieri): parse expiration?
-    pub fn expiration(&self) -> Result<[u8; EXPIRATION_SIZE], Error> {
+    pub fn expiration(&self) -> [u8; Self::EXPIRATION_SIZE] {
-        let mut expiration = [0u8; EXPIRATION_SIZE];
+        self.0[CHUID_EXPIRATION_OFFS..(CHUID_EXPIRATION_OFFS + Self::EXPIRATION_SIZE)]
-        expiration.copy_from_slice(
+            .try_into()
-            &self.0[CHUID_EXPIRATION_OFFS..(CHUID_EXPIRATION_OFFS + EXPIRATION_SIZE)],
+            .unwrap()
-        );
-        Ok(expiration)
     }
 
     /// Get Cardholder Unique Identifier (CHUID)
-    pub fn get(yubikey: &mut YubiKey) -> Result<CHUID, Error> {
+    pub fn get(yubikey: &mut YubiKey) -> Result<ChuId> {
         let txn = yubikey.begin_transaction()?;
         let response = txn.fetch_object(OBJ_CHUID)?;
 
@@ -132,36 +115,23 @@ impl CHUID {
             return Err(Error::GenericError);
         }
 
-        let mut chuid = [0u8; CHUID_SIZE];
+        Ok(ChuId(response[..Self::BYTE_SIZE].try_into().unwrap()))
-        chuid.copy_from_slice(&response[0..CHUID_SIZE]);
-        let retval = CHUID { 0: chuid };
-        Ok(retval)
     }
 
     /// Set Cardholder Unique Identifier (CHUID)
     #[cfg(feature = "untested")]
-
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
-    pub fn set(&self, yubikey: &mut YubiKey) -> Result<(), Error> {
+    pub fn set(&self, yubikey: &mut YubiKey) -> Result<()> {
         let mut buf = CHUID_TMPL.to_vec();
-        buf[0..self.0.len()].copy_from_slice(&self.0);
+        buf[..Self::BYTE_SIZE].copy_from_slice(&self.0);
 
         let txn = yubikey.begin_transaction()?;
         txn.save_object(OBJ_CHUID, &buf)
     }
 }
 
-impl Display for CHUID {
+impl Display for ChuId {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        write!(
+        f.write_str(str::from_utf8(&hex::encode(&self.0[..])).unwrap())
-            f,
-            "{}",
-            String::from_utf8(hex::encode(&self.0[..])).unwrap()
-        )
-    }
-}
-
-impl Debug for CHUID {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        write!(f, "CHUID({:?})", &self.0[..])
     }
 }

src/config.rs

@@ -31,56 +31,60 @@
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 use crate::{
-    error::Error,
+    consts::{
-    metadata,
+        TAG_ADMIN_FLAGS_1, TAG_ADMIN_SALT, TAG_ADMIN_TIMESTAMP, TAG_PROTECTED_FLAGS_1,
+        TAG_PROTECTED_MGM,
+    },
+    metadata::{AdminData, ProtectedData},
     mgm::{MgmType, ADMIN_FLAGS_1_PROTECTED_MGM},
     yubikey::{YubiKey, ADMIN_FLAGS_1_PUK_BLOCKED},
-    TAG_ADMIN, TAG_ADMIN_FLAGS_1, TAG_ADMIN_SALT, TAG_ADMIN_TIMESTAMP, TAG_PROTECTED,
+    Result,
-    TAG_PROTECTED_FLAGS_1, TAG_PROTECTED_MGM,
 };
 use log::error;
-use std::{
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
-    convert::TryInto,
-    time::{Duration, SystemTime, UNIX_EPOCH},
-};
 
 const CB_ADMIN_TIMESTAMP: usize = 0x04;
 const PROTECTED_FLAGS_1_PUK_NOBLOCK: u8 = 0x01;
 
-/// Config
+/// YubiKey configuration.
 #[derive(Copy, Clone, Debug)]
 pub struct Config {
     /// Protected data available
-    protected_data_available: bool,
+    pub protected_data_available: bool,
 
     /// PUK blocked
-    puk_blocked: bool,
+    pub puk_blocked: bool,
 
     /// No block on upgrade
-    puk_noblock_on_upgrade: bool,
+    pub puk_noblock_on_upgrade: bool,
 
     /// PIN last changed
-    pin_last_changed: Option<SystemTime>,
+    pub pin_last_changed: Option<SystemTime>,
 
     /// MGM type
-    mgm_type: MgmType,
+    pub mgm_type: MgmType,
 }
 
-impl Config {
+impl Default for Config {
-    /// Get YubiKey config
+    fn default() -> Config {
-    pub fn get(yubikey: &mut YubiKey) -> Result<Config, Error> {
+        Config {
-        let mut config = Config {
             protected_data_available: false,
             puk_blocked: false,
             puk_noblock_on_upgrade: false,
             pin_last_changed: None,
             mgm_type: MgmType::Manual,
-        };
+        }
+    }
+}
 
+impl Config {
+    /// Get YubiKey config.
+    pub(crate) fn get(yubikey: &mut YubiKey) -> Result<Config> {
+        let mut config = Self::default();
         let txn = yubikey.begin_transaction()?;
 
-        if let Ok(data) = metadata::read(&txn, TAG_ADMIN) {
+        if let Ok(admin_data) = AdminData::read(&txn) {
-            if let Ok(item) = metadata::get_item(&data, TAG_ADMIN_FLAGS_1) {
+            if let Ok(item) = admin_data.get_item(TAG_ADMIN_FLAGS_1) {
                 if item.is_empty() {
                     error!("empty response for admin flags metadata item! ignoring");
                 } else {
@@ -94,7 +98,7 @@ impl Config {
                 }
             }
 
-            if metadata::get_item(&data, TAG_ADMIN_SALT).is_ok() {
+            if admin_data.get_item(TAG_ADMIN_SALT).is_ok() {
                 if config.mgm_type != MgmType::Manual {
                     error!("conflicting types of MGM key administration configured");
                 } else {
@@ -102,7 +106,7 @@ impl Config {
                 }
             }
 
-            if let Ok(item) = metadata::get_item(&data, TAG_ADMIN_TIMESTAMP) {
+            if let Ok(item) = admin_data.get_item(TAG_ADMIN_TIMESTAMP) {
                 if item.len() != CB_ADMIN_TIMESTAMP {
                     error!("pin timestamp in admin metadata is an invalid size");
                 } else {
@@ -117,10 +121,10 @@ impl Config {
             }
         }
 
-        if let Ok(data) = metadata::read(&txn, TAG_PROTECTED) {
+        if let Ok(protected_data) = ProtectedData::read(&txn) {
             config.protected_data_available = true;
 
-            if let Ok(item) = metadata::get_item(&data, TAG_PROTECTED_FLAGS_1) {
+            if let Ok(item) = protected_data.get_item(TAG_PROTECTED_FLAGS_1) {
                 if item.is_empty() {
                     error!("empty response for protected flags metadata item! ignoring");
                 } else if item[0] & PROTECTED_FLAGS_1_PUK_NOBLOCK != 0 {
@@ -128,11 +132,9 @@ impl Config {
                 }
             }
 
-            if metadata::get_item(&data, TAG_PROTECTED_MGM).is_ok() {
+            if protected_data.get_item(TAG_PROTECTED_MGM).is_ok() {
                 if config.mgm_type != MgmType::Protected {
-                    error!(
+                    error!("conflicting MGM key types: protected MGM exists");
-                        "conflicting types of mgm key administration configured: protected MGM exists"
-                    );
                 }
 
                 // Always favor protected MGM

src/consts.rs

@@ -0,0 +1,20 @@
+//! Miscellaneous constant values
+
+/// YubiKey max buffer size
+pub(crate) const CB_BUF_MAX: usize = 3072;
+
+/// YubiKey max object size
+pub(crate) const CB_OBJ_MAX: usize = CB_BUF_MAX - 9;
+
+pub(crate) const CB_OBJ_TAG_MIN: usize = 2; // 1 byte tag + 1 byte len
+#[cfg(feature = "untested")]
+pub(crate) const CB_OBJ_TAG_MAX: usize = CB_OBJ_TAG_MIN + 2; // 1 byte tag + 3 bytes len
+
+// Admin tags
+pub(crate) const TAG_ADMIN_FLAGS_1: u8 = 0x81;
+pub(crate) const TAG_ADMIN_SALT: u8 = 0x82;
+pub(crate) const TAG_ADMIN_TIMESTAMP: u8 = 0x83;
+
+// Protected tags
+pub(crate) const TAG_PROTECTED_FLAGS_1: u8 = 0x81;
+pub(crate) const TAG_PROTECTED_MGM: u8 = 0x89;

src/error.rs

@@ -32,65 +32,66 @@
 
 use std::fmt::{self, Display};
 
-/// Kinds of errors
+/// Result type with [`Error`].
+pub type Result<T> = core::result::Result<T, Error>;
+
+/// Kinds of errors.
 #[derive(Clone, Copy, Debug, Eq, PartialEq)]
+#[non_exhaustive]
 pub enum Error {
+    /// Algorithm error
+    AlgorithmError,
+
+    /// Applet error
+    AppletError,
+
+    /// Argument error
+    ArgumentError,
+
+    /// Authentication error
+    AuthenticationError,
+
+    /// Generic error
+    GenericError,
+
+    /// Invalid object
+    InvalidObject,
+
+    /// Key error
+    KeyError,
+
     /// Memory error
     MemoryError,
 
+    /// Not supported
+    NotSupported,
+
+    /// Not found
+    NotFound,
+
+    /// Parse error
+    ParseError,
+
     /// PCSC error
     PcscError {
         /// Original PC/SC error
         inner: Option<pcsc::Error>,
     },
 
+    /// PIN locked
+    PinLocked,
+
+    /// Range error
+    RangeError,
+
     /// Size error
     SizeError,
 
-    /// Applet error
-    AppletError,
-
-    /// Authentication error
-    AuthenticationError,
-
-    /// Randomness error
-    RandomnessError,
-
-    /// Generic error
-    GenericError,
-
-    /// Key error
-    KeyError,
-
-    /// Parse error
-    ParseError,
-
     /// Wrong PIN
     WrongPin {
         /// Number of tries remaining
         tries: u8,
     },
-
-    /// Invalid object
-    InvalidObject,
-
-    /// Algorithm error
-    AlgorithmError,
-
-    /// PIN locked
-    PinLocked,
-
-    /// Argument error
-    ArgumentError,
-
-    /// Range error
-    RangeError,
-
-    /// Not supported
-    NotSupported,
-
-    /// Not found
-    NotFound,
 }
 
 impl Error {
@@ -98,48 +99,46 @@ impl Error {
     ///
     /// These names map to the legacy names from the Yubico C library, to
     /// assist in web searches for relevant information for these errors.
-    pub fn name(self) -> &'static str {
+    pub fn name(self) -> Option<&'static str> {
-        match self {
+        Some(match self {
-            Error::MemoryError => "YKPIV_MEMORY_ERROR",
-            Error::PcscError { .. } => "YKPIV_PCSC_ERROR",
-            Error::SizeError => "YKPIV_SIZE_ERROR",
-            Error::AppletError => "YKPIV_APPLET_ERROR",
-            Error::AuthenticationError => "YKPIV_AUTHENTICATION_ERROR",
-            Error::RandomnessError => "YKPIV_RANDOMNESS_ERROR",
-            Error::GenericError => "YKPIV_GENERIC_ERROR",
-            Error::KeyError => "YKPIV_KEY_ERROR",
-            Error::ParseError => "YKPIV_PARSE_ERROR",
-            Error::WrongPin { .. } => "YKPIV_WRONG_PIN",
-            Error::InvalidObject => "YKPIV_INVALID_OBJECT",
             Error::AlgorithmError => "YKPIV_ALGORITHM_ERROR",
-            Error::PinLocked => "YKPIV_PIN_LOCKED",
+            Error::AppletError => "YKPIV_APPLET_ERROR",
             Error::ArgumentError => "YKPIV_ARGUMENT_ERROR",
-            Error::RangeError => "YKPIV_RANGE_ERROR",
+            Error::AuthenticationError => "YKPIV_AUTHENTICATION_ERROR",
+            Error::GenericError => "YKPIV_GENERIC_ERROR",
+            Error::InvalidObject => "YKPIV_INVALID_OBJECT",
+            Error::KeyError => "YKPIV_KEY_ERROR",
+            Error::MemoryError => "YKPIV_MEMORY_ERROR",
             Error::NotSupported => "YKPIV_NOT_SUPPORTED",
-            Error::NotFound => "<not found>",
+            Error::ParseError => "YKPIV_PARSE_ERROR",
-        }
+            Error::PcscError { .. } => "YKPIV_PCSC_ERROR",
+            Error::PinLocked => "YKPIV_PIN_LOCKED",
+            Error::RangeError => "YKPIV_RANGE_ERROR",
+            Error::SizeError => "YKPIV_SIZE_ERROR",
+            Error::WrongPin { .. } => "YKPIV_WRONG_PIN",
+            _ => return None,
+        })
     }
 
     /// Error message
     pub fn msg(self) -> &'static str {
         match self {
-            Error::MemoryError => "memory error",
-            Error::PcscError { .. } => "PCSC error",
-            Error::SizeError => "size error",
-            Error::AppletError => "applet error",
-            Error::AuthenticationError => "authentication error",
-            Error::RandomnessError => "randomness error",
-            Error::GenericError => "generic error",
-            Error::KeyError => "key error",
-            Error::ParseError => "parse error",
-            Error::WrongPin { .. } => "wrong pin",
-            Error::InvalidObject => "invalid object",
             Error::AlgorithmError => "algorithm error",
-            Error::PinLocked => "PIN locked",
+            Error::AppletError => "applet error",
             Error::ArgumentError => "argument error",
-            Error::RangeError => "range error",
+            Error::AuthenticationError => "authentication error",
+            Error::GenericError => "generic error",
+            Error::InvalidObject => "invalid object",
+            Error::KeyError => "key error",
+            Error::MemoryError => "memory error",
             Error::NotSupported => "not supported",
             Error::NotFound => "not found",
+            Error::ParseError => "parse error",
+            Error::PcscError { .. } => "PC/SC error",
+            Error::PinLocked => "PIN locked",
+            Error::RangeError => "range error",
+            Error::SizeError => "size error",
+            Error::WrongPin { .. } => "wrong pin",
         }
     }
 }
@@ -159,10 +158,8 @@ impl From<pcsc::Error> for Error {
 impl std::error::Error for Error {
     fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
         match self {
-            #[allow(trivial_casts)] // why doesn't this work without the cast???
+            #[allow(trivial_casts)]
-            Error::PcscError { inner } => inner
+            Error::PcscError { inner } => inner.as_ref().map(|err| err as &_),
-                .as_ref()
-                .map(|err| err as &(dyn std::error::Error + 'static)),
             _ => None,
         }
     }

src/lib.rs

@@ -1,10 +1,14 @@
-//! [YubiKey] PIV: [Personal Identity Verification][PIV] support for
+//! **yubikey.rs**: pure Rust cross-platform host-side driver for [YubiKey]
-//! [Yubico] devices using the Personal Computer/Smart Card ([PC/SC])
+//! devices from [Yubico] 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*
+//! # 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.
@@ -12,38 +16,43 @@
 //! 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
+//! # Minimum Supported Rust Version
-//!
+//! Rust **1.57** or newer.
-//! Rust 1.44+
-//!
-//! ## Supported YubiKeys
 //!
+//! # 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
+//! # Supported Operating Systems
+//! - Linux
+//! - macOS
+//! - Windows
 //!
+//! # Supported Algorithms
 //! - **Authentication**: `3DES`
-//! - **Encryption**: `RSA1024`, `RSA2048`, `ECCP256`, `ECCP384`
+//! - **Encryption**:
+//!   - RSA: `RSA1024`, `RSA2048`
+//!   - ECC: `ECCP256`, `ECCP384` (NIST curves: P-256, P-384)
 //! - **Signatures**:
 //!   - RSASSA-PKCS#1v1.5: `RSA1024`, `RSA2048`
-//!   - ECDSA: `ECCP256`, `ECCP384`
+//!   - ECDSA: `ECCP256`, `ECCP384` (NIST curves: P-256, P-384)
 //!
 //! NOTE: RSASSA-PSS signatures and RSA-OAEP encryption may be supportable (TBD)
 //!
-//! ## Status
+//! # Status
+//! Functionality which has been successfully tested is available by default.
 //!
-//! This is a work-in-progress effort, and while much of the library-level
+//! Any functionality which is gated on the `untested` feature has not been
-//! code from upstream [yubico-piv-tool] has been translated into Rust
+//! properly tested and is not known to function correctly.
-//! presenting a safe interface, much of it is still untested.
 //!
-//! Please see the [project's README.md for a complete status][status].
+//! Please see the [`untested` functionality tracking issue] for current status.
-//!
+//! We would appreciate any help testing this functionality and removing the
-//! ## History
+//! `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
@@ -53,25 +62,23 @@
 //! the YubiKey implementation of PIV works in general, see the
 //! [Yubico PIV Tool Command Line Guide][piv-tool-guide].
 //!
-//! ## Security Warning
+//! # 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
+//! # 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
+//! # License
+//! **yubikey.rs** is a fork of and originally a mechanical translation from
+//! Yubico's [yubico-piv-tool], a C library/CLI program.
 //!
-//! **yubikey-piv.rs** is a fork of and originally a mechanical translation from
+//! The original library was licensed under a [2-Clause BSD License][BSDL],
-//! Yubico's [yubico-piv-tool], a C library/CLI program. The original library
+//! which this library inherits as a derived work.
-//! 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
@@ -83,12 +90,12 @@
 //! [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/
-//! [status]: https://github.com/iqlusioninc/yubikey-piv.rs#status
+//! [`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-piv.rs/blob/main/CODE_OF_CONDUCT.md
+//! [cc-md]: https://github.com/iqlusioninc/yubikey.rs/blob/main/CODE_OF_CONDUCT.md
 //! [BSDL]: https://opensource.org/licenses/BSD-2-Clause
 
 // Adapted from yubico-piv-tool:
@@ -121,78 +128,55 @@
 // (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-piv.rs/main/img/logo.png",
+    html_logo_url = "https://raw.githubusercontent.com/iqlusioninc/yubikey.rs/main/img/logo.png"
-    html_root_url = "https://docs.rs/yubikey-piv/0.1.0"
 )]
 #![forbid(unsafe_code)]
-#![warn(
+#![warn(missing_docs, rust_2018_idioms, trivial_casts, unused_qualifications)]
-    missing_docs,
-    rust_2018_idioms,
-    trivial_casts,
-    trivial_numeric_casts,
-    unused_lifetimes,
-    unused_qualifications
-)]
 
 mod apdu;
-pub mod cccid;
+mod cccid;
 pub mod certificate;
-pub mod chuid;
+mod chuid;
-pub mod config;
+mod config;
-pub mod error;
+mod consts;
-pub mod key;
+mod error;
 mod metadata;
-pub mod mgm;
+mod mgm;
 #[cfg(feature = "untested")]
-pub mod mscmap;
+mod mscmap;
 #[cfg(feature = "untested")]
-pub mod msroots;
+mod msroots;
-pub mod policy;
+pub mod piv;
-pub mod readers;
+mod policy;
+pub mod reader;
 mod serialization;
-pub mod settings;
+mod setting;
 mod transaction;
-pub mod yubikey;
+mod yubikey;
 
-pub use self::{
+pub use crate::{
-    error::Error,
+    cccid::{CardId, CccId},
-    key::Key,
+    certificate::Certificate,
-    mgm::MgmKey,
+    chuid::ChuId,
-    readers::Readers,
+    config::Config,
-    yubikey::{Serial, YubiKey},
+    error::{Error, Result},
+    mgm::{MgmKey, MgmType},
+    piv::Key,
+    policy::{PinPolicy, TouchPolicy},
+    reader::Context,
+    setting::{Setting, SettingSource},
+    yubikey::{CachedPin, Serial, Version, YubiKey},
 };
 
-/// Object identifiers
+#[cfg(feature = "untested")]
+pub use crate::{mscmap::MsContainer, msroots::MsRoots};
+
+pub use uuid::Uuid;
+
+/// Object identifiers: handles to particular objects stored on a YubiKey.
 pub type ObjectId = u32;
 
 /// Buffer type (self-zeroizing byte vector)
-pub(crate) type Buffer = zeroize::Zeroizing<Vec<u8>>;
+pub type Buffer = zeroize::Zeroizing<Vec<u8>>;
-
-/// YubiKey max buffer size
-pub(crate) const CB_BUF_MAX: usize = 3072;
-
-/// YubiKey max object size
-pub(crate) const CB_OBJ_MAX: usize = CB_BUF_MAX - 9;
-pub(crate) const CB_OBJ_TAG_MIN: usize = 2; // 1 byte tag + 1 byte len
-#[cfg(feature = "untested")]
-pub(crate) const CB_OBJ_TAG_MAX: usize = CB_OBJ_TAG_MIN + 2; // 1 byte tag + 3 bytes len
-
-pub(crate) const TAG_ADMIN: u8 = 0x80;
-pub(crate) const TAG_ADMIN_FLAGS_1: u8 = 0x81;
-pub(crate) const TAG_ADMIN_SALT: u8 = 0x82;
-pub(crate) const TAG_ADMIN_TIMESTAMP: u8 = 0x83;
-pub(crate) const TAG_PROTECTED: u8 = 0x88;
-pub(crate) const TAG_PROTECTED_FLAGS_1: u8 = 0x81;
-pub(crate) const TAG_PROTECTED_MGM: u8 = 0x89;
-
-/// PIV Applet ID
-pub(crate) const PIV_AID: [u8; 5] = [0xa0, 0x00, 0x00, 0x03, 0x08];
-
-/// MGMT Applet ID.
-/// <https://developers.yubico.com/PIV/Introduction/Admin_access.html>
-#[cfg(feature = "untested")]
-pub(crate) const MGMT_AID: [u8; 8] = [0xa0, 0x00, 0x00, 0x05, 0x27, 0x47, 0x11, 0x17];
-
-/// YubiKey OTP Applet ID. Needed to query serial on YK4.
-pub(crate) const YK_AID: [u8; 8] = [0xa0, 0x00, 0x00, 0x05, 0x27, 0x20, 0x01, 0x01];

src/metadata.rs

@@ -30,21 +30,91 @@
 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-use crate::{
+use std::marker::PhantomData;
-    error::Error, serialization::*, transaction::Transaction, Buffer, TAG_ADMIN, TAG_PROTECTED,
-};
-
-#[cfg(feature = "untested")]
-use crate::{CB_OBJ_MAX, CB_OBJ_TAG_MAX};
-
-#[cfg(feature = "untested")]
 use zeroize::Zeroizing;
 
+use crate::{serialization::*, transaction::Transaction, Buffer, Error, Result};
+
+#[cfg(feature = "untested")]
+use crate::consts::{CB_OBJ_MAX, CB_OBJ_TAG_MAX};
+
+#[cfg(feature = "untested")]
+use std::iter;
+
+const TAG_ADMIN: u8 = 0x80;
+const TAG_PROTECTED: u8 = 0x88;
 pub const OBJ_ADMIN_DATA: u32 = 0x005f_ff00;
 pub const OBJ_PRINTED: u32 = 0x005f_c109;
 
+pub(crate) trait MetadataType: private::Sealed {}
+
+/// A type variable corresponding to PIN-protected metadata.
+pub(crate) enum Protected {}
+impl MetadataType for Protected {}
+
+/// A type variable corresponding to administrative metadata.
+pub(crate) enum Admin {}
+impl MetadataType for Admin {}
+
+/// Metadata stored in a YubiKey.
+pub(crate) struct Metadata<T: MetadataType> {
+    inner: Buffer,
+    _marker: PhantomData<T>,
+}
+
+/// PIN-protected metadata stored in a YubiKey.
+pub(crate) type ProtectedData = Metadata<Protected>;
+/// Administrative metadata stored in a YubiKey.
+pub(crate) type AdminData = Metadata<Admin>;
+
+impl<T: MetadataType> Default for Metadata<T> {
+    fn default() -> Self {
+        Metadata {
+            inner: Zeroizing::new(vec![]),
+            _marker: PhantomData::default(),
+        }
+    }
+}
+
+impl<T: MetadataType> Metadata<T> {
+    /// Read metadata
+    pub(crate) fn read(txn: &Transaction<'_>) -> Result<Self> {
+        let data = txn.fetch_object(T::obj_id())?;
+        Ok(Metadata {
+            inner: Tlv::parse_single(data, T::tag())?,
+            _marker: PhantomData::default(),
+        })
+    }
+
+    /// Write metadata
+    #[cfg(feature = "untested")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
+    pub(crate) fn write(&self, txn: &Transaction<'_>) -> Result<()> {
+        if self.inner.len() > CB_OBJ_MAX - CB_OBJ_TAG_MAX {
+            return Err(Error::GenericError);
+        }
+
+        if self.inner.is_empty() {
+            return Self::delete(txn);
+        }
+
+        let mut buf = Zeroizing::new(vec![0u8; CB_OBJ_MAX]);
+        let len = Tlv::write(&mut buf, T::tag(), &self.inner)?;
+
+        txn.save_object(T::obj_id(), &buf[..len])
+    }
+
+    /// Delete metadata
+    #[cfg(feature = "untested")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
+    pub(crate) fn delete(txn: &Transaction<'_>) -> Result<()> {
+        txn.save_object(T::obj_id(), &[])
+    }
+
     /// Get metadata item
-pub(crate) fn get_item(mut data: &[u8], tag: u8) -> Result<&[u8], Error> {
+    pub(crate) fn get_item(&self, tag: u8) -> Result<&[u8]> {
+        let mut data = &self.inner[..];
+
         while !data.is_empty() {
             let (remaining, tlv) = Tlv::parse(data)?;
             data = remaining;
@@ -60,25 +130,19 @@ pub(crate) fn get_item(mut data: &[u8], tag: u8) -> Result<&[u8], Error> {
 
     /// Set metadata item
     #[cfg(feature = "untested")]
-pub(crate) fn set_item(
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
-    data: &mut [u8],
+    pub(crate) fn set_item(&mut self, tag: u8, item: &[u8]) -> Result<()> {
-    pcb_data: &mut usize,
-    cb_data_max: usize,
-    tag: u8,
-    p_item: &[u8],
-) -> Result<(), Error> {
         let mut cb_temp: usize = 0;
         let mut tag_temp: u8 = 0;
         let mut cb_len: usize = 0;
-    let cb_item = p_item.len();
 
         let mut offset = 0;
 
-    while offset < *pcb_data {
+        while offset < self.inner.len() {
-        tag_temp = data[offset];
+            tag_temp = self.inner[offset];
             offset += 1;
 
-        cb_len = get_length(&data[offset..], &mut cb_temp);
+            cb_len = get_length(&self.inner[offset..], &mut cb_temp);
             offset += cb_len;
 
             if tag_temp == tag {
@@ -89,13 +153,16 @@ pub(crate) fn set_item(
         }
 
         if tag_temp != tag {
-        if cb_item == 0 {
+            if item.is_empty() {
                 // We've been asked to delete an existing item that isn't in the blob
                 return Ok(());
             }
 
             // We did not find an existing tag, append
-        *pcb_data += Tlv::write(&mut data[*pcb_data..], tag, p_item)?;
+            assert_eq!(offset, self.inner.len());
+            self.inner
+                .extend(iter::repeat(0).take(1 + get_length_size(item.len()) + item.len()));
+            Tlv::write(&mut self.inner[offset..], tag, item)?;
 
             return Ok(());
         }
@@ -103,80 +170,50 @@ pub(crate) fn set_item(
         // Found tag
 
         // Check length, if it matches, overwrite
-    if cb_temp == cb_item {
+        if cb_temp == item.len() {
-        data[offset..offset + cb_item].copy_from_slice(p_item);
+            self.inner[offset..offset + item.len()].copy_from_slice(item);
             return Ok(());
         }
 
         // Length doesn't match, expand/shrink to fit
         let next_offset = offset + cb_temp;
         // Must be signed to have negative offsets
-    let cb_moved: isize = (cb_item as isize - cb_temp as isize)
+        let cb_moved: isize = (item.len() as isize - cb_temp as isize)
-        + if cb_item != 0 {
+            + if item.is_empty() {
-            get_length_size(cb_item) as isize
-        } else {
                 // For tag, if deleting
                 -1
+            } else {
+                get_length_size(item.len()) as isize
             }
             // Accounts for different length encoding
             - cb_len as isize;
 
         // If length would cause buffer overflow, return error
-    if (*pcb_data as isize + cb_moved) as usize > cb_data_max {
+        if (self.inner.len() as isize + cb_moved) as usize > CB_OBJ_MAX {
             return Err(Error::GenericError);
         }
 
         // Move remaining data
-    data.copy_within(
+        let orig_len = self.inner.len();
-        next_offset..*pcb_data,
+        if cb_moved > 0 {
+            self.inner.extend(iter::repeat(0).take(cb_moved as usize));
+        }
+        self.inner.copy_within(
+            next_offset..orig_len,
             (next_offset as isize + cb_moved) as usize,
         );
-    *pcb_data = (*pcb_data as isize + cb_moved) as usize;
+        self.inner
+            .resize((orig_len as isize + cb_moved) as usize, 0);
 
         // Re-encode item and insert
-    if cb_item != 0 {
+        if !item.is_empty() {
             offset -= cb_len;
-        offset += set_length(&mut data[offset..], cb_item)?;
+            offset += set_length(&mut self.inner[offset..], item.len())?;
-        data[offset..offset + cb_item].copy_from_slice(p_item);
+            self.inner[offset..offset + item.len()].copy_from_slice(item);
         }
 
         Ok(())
     }
-
-/// Read metadata
-pub(crate) fn read(txn: &Transaction<'_>, tag: u8) -> Result<Buffer, Error> {
-    let obj_id = match tag {
-        TAG_ADMIN => OBJ_ADMIN_DATA,
-        TAG_PROTECTED => OBJ_PRINTED,
-        _ => return Err(Error::InvalidObject),
-    };
-
-    let data = txn.fetch_object(obj_id)?;
-    Tlv::parse_single(data, tag)
-}
-
-/// Write metadata
-#[cfg(feature = "untested")]
-pub(crate) fn write(txn: &Transaction<'_>, tag: u8, data: &[u8]) -> Result<(), Error> {
-    if data.len() > CB_OBJ_MAX - CB_OBJ_TAG_MAX {
-        return Err(Error::GenericError);
-    }
-
-    let obj_id = match tag {
-        TAG_ADMIN => OBJ_ADMIN_DATA,
-        TAG_PROTECTED => OBJ_PRINTED,
-        _ => return Err(Error::InvalidObject),
-    };
-
-    if data.is_empty() {
-        // Deleting metadata
-        return txn.save_object(obj_id, &[]);
-    }
-
-    let mut buf = Zeroizing::new(vec![0u8; CB_OBJ_MAX]);
-    let len = Tlv::write(&mut buf, tag, data)?;
-
-    txn.save_object(obj_id, &buf[..len])
 }
 
 /// Get the size of a length tag for the given length
@@ -190,3 +227,27 @@ fn get_length_size(length: usize) -> usize {
         3
     }
 }
+
+mod private {
+    use super::*;
+    pub trait Sealed {
+        fn tag() -> u8;
+        fn obj_id() -> u32;
+    }
+    impl Sealed for Protected {
+        fn tag() -> u8 {
+            TAG_PROTECTED
+        }
+        fn obj_id() -> u32 {
+            OBJ_PRINTED
+        }
+    }
+    impl Sealed for Admin {
+        fn tag() -> u8 {
+            TAG_ADMIN
+        }
+        fn obj_id() -> u32 {
+            OBJ_ADMIN_DATA
+        }
+    }
+}

src/mgm.rs

@@ -30,38 +30,29 @@
 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-use crate::error::Error;
+use crate::{Error, Result};
-use getrandom::getrandom;
 use log::error;
-use std::convert::{TryFrom, TryInto};
+use rand_core::{OsRng, RngCore};
 use zeroize::{Zeroize, Zeroizing};
 
 #[cfg(feature = "untested")]
 use crate::{
-    metadata, yubikey::YubiKey, CB_BUF_MAX, CB_OBJ_MAX, TAG_ADMIN, TAG_ADMIN_FLAGS_1,
+    consts::{TAG_ADMIN_FLAGS_1, TAG_ADMIN_SALT, TAG_PROTECTED_MGM},
-    TAG_ADMIN_SALT, TAG_PROTECTED, TAG_PROTECTED_MGM,
+    metadata::{AdminData, ProtectedData},
+    yubikey::YubiKey,
 };
 use des::{
-    cipher::{generic_array::GenericArray, BlockCipher, NewBlockCipher},
+    cipher::{generic_array::GenericArray, BlockDecrypt, BlockEncrypt, KeyInit},
     TdesEde3,
 };
 #[cfg(feature = "untested")]
-use hmac::Hmac;
+use {hmac::Hmac, pbkdf2::pbkdf2, sha1::Sha1};
-#[cfg(feature = "untested")]
-use pbkdf2::pbkdf2;
-#[cfg(feature = "untested")]
-use sha1::Sha1;
 
 pub(crate) const ADMIN_FLAGS_1_PROTECTED_MGM: u8 = 0x02;
 
 #[cfg(feature = "untested")]
 const CB_ADMIN_SALT: usize = 16;
 
-/// Default MGM key configured on all YubiKeys
-const DEFAULT_MGM_KEY: [u8; DES_LEN_3DES] = [
-    1, 2, 3, 4, 5, 6, 7, 8, 1, 2, 3, 4, 5, 6, 7, 8, 1, 2, 3, 4, 5, 6, 7, 8,
-];
-
 /// Size of a DES key
 const DES_LEN_DES: usize = 8;
 
@@ -72,7 +63,7 @@ pub(crate) const DES_LEN_3DES: usize = DES_LEN_DES * 3;
 #[cfg(feature = "untested")]
 const ITER_MGM_PBKDF2: u32 = 10000;
 
-/// Management Key (MGM) key types (manual/derived/protected)
+/// Management Key (MGM) key types (manual/derived/protected).
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub enum MgmType {
     /// Manual
@@ -96,27 +87,23 @@ pub struct MgmKey([u8; DES_LEN_3DES]);
 
 impl MgmKey {
     /// Generate a random MGM key
-    pub fn generate() -> Result<Self, Error> {
+    pub fn generate() -> Self {
         let mut key_bytes = [0u8; DES_LEN_3DES];
-
+        OsRng.fill_bytes(&mut key_bytes);
-        if getrandom(&mut key_bytes).is_err() {
+        Self(key_bytes)
-            return Err(Error::RandomnessError);
-        }
-
-        MgmKey::new(key_bytes)
     }
 
     /// Create an MGM key from byte slice.
     ///
     /// Returns an error if the slice is the wrong size or the key is weak.
-    pub fn from_bytes(bytes: impl AsRef<[u8]>) -> Result<Self, Error> {
+    pub fn from_bytes(bytes: impl AsRef<[u8]>) -> Result<Self> {
         bytes.as_ref().try_into()
     }
 
     /// Create an MGM key from the given byte array.
     ///
     /// Returns an error if the key is weak.
-    pub fn new(key_bytes: [u8; DES_LEN_3DES]) -> Result<Self, Error> {
+    pub fn new(key_bytes: [u8; DES_LEN_3DES]) -> Result<Self> {
         if is_weak_key(&key_bytes) {
             error!(
                 "blacklisting key '{:?}' since it's weak (with odd parity)",
@@ -126,17 +113,18 @@ impl MgmKey {
             return Err(Error::KeyError);
         }
 
-        Ok(MgmKey(key_bytes))
+        Ok(Self(key_bytes))
     }
 
     /// Get derived management key (MGM)
     #[cfg(feature = "untested")]
-    pub fn get_derived(yubikey: &mut YubiKey, pin: &[u8]) -> Result<Self, Error> {
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
+    pub fn get_derived(yubikey: &mut YubiKey, pin: &[u8]) -> Result<Self> {
         let txn = yubikey.begin_transaction()?;
 
         // recover management key
-        let data = metadata::read(&txn, TAG_ADMIN)?;
+        let admin_data = AdminData::read(&txn)?;
-        let salt = metadata::get_item(&data, TAG_ADMIN_SALT)?;
+        let salt = admin_data.get_item(TAG_ADMIN_SALT)?;
 
         if salt.len() != CB_ADMIN_SALT {
             error!(
@@ -149,22 +137,22 @@ impl MgmKey {
         }
 
         let mut mgm = [0u8; DES_LEN_3DES];
-        pbkdf2::<Hmac<Sha1>>(pin, &salt, ITER_MGM_PBKDF2, &mut mgm);
+        pbkdf2::<Hmac<Sha1>>(pin, salt, ITER_MGM_PBKDF2, &mut mgm);
-
         MgmKey::from_bytes(mgm)
     }
 
     /// Get protected management key (MGM)
     #[cfg(feature = "untested")]
-    pub fn get_protected(yubikey: &mut YubiKey) -> Result<Self, Error> {
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
+    pub fn get_protected(yubikey: &mut YubiKey) -> Result<Self> {
         let txn = yubikey.begin_transaction()?;
 
-        let data = metadata::read(&txn, TAG_PROTECTED).map_err(|e| {
+        let protected_data = ProtectedData::read(&txn).map_err(|e| {
             error!("could not read protected data (err: {:?})", e);
             e
         })?;
 
-        let item = metadata::get_item(&data, TAG_PROTECTED_MGM).map_err(|e| {
+        let item = protected_data.get_item(TAG_PROTECTED_MGM).map_err(|e| {
             error!("could not read protected MGM from metadata (err: {:?})", e);
             e
         })?;
@@ -182,21 +170,87 @@ impl MgmKey {
         MgmKey::from_bytes(item)
     }
 
-    /// Set the management key (MGM)
+    /// Resets the management key for the given YubiKey to the default value.
+    ///
+    /// This will wipe any metadata related to derived and PIN-protected management keys.
     #[cfg(feature = "untested")]
-    pub fn set(&self, yubikey: &mut YubiKey, touch: Option<u8>) -> Result<(), Error> {
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
-        let txn = yubikey.begin_transaction()?;
+    pub fn set_default(yubikey: &mut YubiKey) -> Result<()> {
-        txn.set_mgm_key(&self, touch)
+        MgmKey::default().set_manual(yubikey, false)
     }
 
-    /// Set protected management key (MGM)
+    /// Configures the given YubiKey to use this management key.
+    ///
+    /// The management key must be stored by the user, and provided when performing key
+    /// management operations.
+    ///
+    /// This will wipe any metadata related to derived and PIN-protected management keys.
     #[cfg(feature = "untested")]
-    pub fn set_protected(&self, yubikey: &mut YubiKey) -> Result<(), Error> {
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
-        let mut data = Zeroizing::new(vec![0u8; CB_BUF_MAX]);
+    pub fn set_manual(&self, yubikey: &mut YubiKey, require_touch: bool) -> Result<()> {
-
         let txn = yubikey.begin_transaction()?;
 
-        txn.set_mgm_key(self, None).map_err(|e| {
+        txn.set_mgm_key(self, require_touch).map_err(|e| {
+            // Log a warning, since the device mgm key is corrupt or we're in a state
+            // where we can't set the mgm key.
+            error!("could not set new derived mgm key, err = {}", e);
+            e
+        })?;
+
+        // After this point, we've set the mgm key, so the function should succeed,
+        // regardless of being able to set the metadata.
+
+        if let Ok(mut admin_data) = AdminData::read(&txn) {
+            // Clear the protected mgm key bit.
+            if let Ok(item) = admin_data.get_item(TAG_ADMIN_FLAGS_1) {
+                let mut flags_1 = [0u8; 1];
+                if item.len() == flags_1.len() {
+                    flags_1.copy_from_slice(item);
+                    flags_1[0] &= !ADMIN_FLAGS_1_PROTECTED_MGM;
+
+                    if let Err(e) = admin_data.set_item(TAG_ADMIN_FLAGS_1, &flags_1) {
+                        error!("could not set admin flags item, err = {}", e);
+                    }
+                } else {
+                    error!(
+                        "admin data flags are an incorrect size: {} (expected {})",
+                        item.len(),
+                        flags_1.len()
+                    );
+                }
+            }
+
+            // Remove any existing salt for a derived mgm key.
+            if let Err(e) = admin_data.set_item(TAG_ADMIN_SALT, &[]) {
+                error!("could not unset derived mgm salt (err = {})", e)
+            }
+
+            if let Err(e) = admin_data.write(&txn) {
+                error!("could not write admin data, err = {}", e);
+            }
+        }
+
+        // Clear any prior mgm key from protected data.
+        if let Ok(mut protected_data) = ProtectedData::read(&txn) {
+            if let Err(e) = protected_data.set_item(TAG_PROTECTED_MGM, &[]) {
+                error!("could not clear protected mgm item, err = {:?}", e);
+            } else if let Err(e) = protected_data.write(&txn) {
+                error!("could not write protected data, err = {:?}", e);
+            }
+        }
+
+        Ok(())
+    }
+
+    /// Configures the given YubiKey to use this as a PIN-protected management key.
+    ///
+    /// This enables key management operations to be performed with access to the PIN.
+    #[cfg(feature = "untested")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
+    pub fn set_protected(&self, yubikey: &mut YubiKey) -> Result<()> {
+        let txn = yubikey.begin_transaction()?;
+
+        txn.set_mgm_key(self, false).map_err(|e| {
             // log a warning, since the device mgm key is corrupt or we're in
             // a state where we can't set the mgm key
             error!("could not set new derived mgm key, err = {}", e);
@@ -206,39 +260,25 @@ impl MgmKey {
         // after this point, we've set the mgm key, so the function should
         // succeed, regardless of being able to set the metadata
 
-        // set the new mgm key in protected data
+        // Fetch the current protected data, or start a blank metadata blob.
-        let buffer = match metadata::read(&txn, TAG_PROTECTED) {
+        let mut protected_data = ProtectedData::read(&txn).unwrap_or_default();
-            Ok(b) => b,
-            Err(_) => {
-                // set current metadata blob size to zero, we'll add to the blank blob
-                Zeroizing::new(vec![])
-            }
-        };
-        let mut cb_data = buffer.len();
-        data[..cb_data].copy_from_slice(&buffer);
 
-        if let Err(e) = metadata::set_item(
+        // Set the new mgm key in protected data.
-            data.as_mut_slice(),
+        if let Err(e) = protected_data.set_item(TAG_PROTECTED_MGM, self.as_ref()) {
-            &mut cb_data,
-            CB_OBJ_MAX,
-            TAG_PROTECTED_MGM,
-            self.as_ref(),
-        ) {
             error!("could not set protected mgm item, err = {:?}", e);
         } else {
-            metadata::write(&txn, TAG_PROTECTED, &data).map_err(|e| {
+            protected_data.write(&txn).map_err(|e| {
                 error!("could not write protected data, err = {:?}", e);
                 e
             })?;
         }
 
         // set the protected mgm flag in admin data
-        cb_data = data.len();
 
         let mut flags_1 = [0u8; 1];
 
-        if let Ok(buffer) = metadata::read(&txn, TAG_ADMIN) {
+        let mut admin_data = if let Ok(mut admin_data) = AdminData::read(&txn) {
-            if let Ok(item) = metadata::get_item(&buffer, TAG_ADMIN_FLAGS_1) {
+            if let Ok(item) = admin_data.get_item(TAG_ADMIN_FLAGS_1) {
                 if item.len() == flags_1.len() {
                     flags_1.copy_from_slice(item);
                 } else {
@@ -254,26 +294,20 @@ impl MgmKey {
             }
 
             // remove any existing salt
-            if let Err(e) =
+            if let Err(e) = admin_data.set_item(TAG_ADMIN_SALT, &[]) {
-                metadata::set_item(&mut data, &mut cb_data, CB_OBJ_MAX, TAG_ADMIN_SALT, &[])
-            {
                 error!("could not unset derived mgm salt (err = {})", e)
             }
+
+            admin_data
         } else {
-            cb_data = 0;
+            AdminData::default()
-        }
+        };
 
         flags_1[0] |= ADMIN_FLAGS_1_PROTECTED_MGM;
 
-        if let Err(e) = metadata::set_item(
+        if let Err(e) = admin_data.set_item(TAG_ADMIN_FLAGS_1, &flags_1) {
-            data.as_mut_slice(),
-            &mut cb_data,
-            CB_OBJ_MAX,
-            TAG_ADMIN_FLAGS_1,
-            &flags_1,
-        ) {
             error!("could not set admin flags item, err = {}", e);
-        } else if let Err(e) = metadata::write(&txn, TAG_ADMIN, &data[..cb_data]) {
+        } else if let Err(e) = admin_data.write(&txn) {
             error!("could not write admin data, err = {}", e);
         }
 
@@ -281,7 +315,6 @@ impl MgmKey {
     }
 
     /// Encrypt with 3DES key
-    #[allow(clippy::trivially_copy_pass_by_ref)]
     pub(crate) fn encrypt(&self, input: &[u8; DES_LEN_DES]) -> [u8; DES_LEN_DES] {
         let mut output = input.to_owned();
         TdesEde3::new(GenericArray::from_slice(&self.0))
@@ -290,7 +323,6 @@ impl MgmKey {
     }
 
     /// Decrypt with 3DES key
-    #[allow(clippy::trivially_copy_pass_by_ref)]
     pub(crate) fn decrypt(&self, input: &[u8; DES_LEN_DES]) -> [u8; DES_LEN_DES] {
         let mut output = input.to_owned();
         TdesEde3::new(GenericArray::from_slice(&self.0))
@@ -305,9 +337,12 @@ impl AsRef<[u8; DES_LEN_3DES]> for MgmKey {
     }
 }
 
+/// Default MGM key configured on all YubiKeys
 impl Default for MgmKey {
     fn default() -> Self {
-        MgmKey(DEFAULT_MGM_KEY)
+        MgmKey([
+            1, 2, 3, 4, 5, 6, 7, 8, 1, 2, 3, 4, 5, 6, 7, 8, 1, 2, 3, 4, 5, 6, 7, 8,
+        ])
     }
 }
 
@@ -320,7 +355,7 @@ impl Drop for MgmKey {
 impl<'a> TryFrom<&'a [u8]> for MgmKey {
     type Error = Error;
 
-    fn try_from(key_bytes: &'a [u8]) -> Result<Self, Error> {
+    fn try_from(key_bytes: &'a [u8]) -> Result<Self> {
         Self::new(key_bytes.try_into().map_err(|_| Error::SizeError)?)
     }
 }

src/mscmap.rs

@@ -1,7 +1,4 @@
-//! MS Container Map Records
+//! MS Container Map Records.
-//!
-//! 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)>
 
 // Adapted from yubico-piv-tool:
 // <https://github.com/Yubico/yubico-piv-tool/>
@@ -33,54 +30,57 @@
 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-use crate::{error::Error, key::SlotId, serialization::*, yubikey::YubiKey, CB_OBJ_MAX};
+use crate::{consts::CB_OBJ_MAX, piv::SlotId, serialization::*, Error, Result, YubiKey};
 use log::error;
-use std::{
-    convert::{TryFrom, TryInto},
-    fmt::{self, Debug},
-};
-
-/// Container name length
-const CONTAINER_NAME_LEN: usize = 40;
-
-/// Container record length: 27 = 80 + 1 + 1 + 2 + 1 + 1 + 1 + 20
-const CONTAINER_REC_LEN: usize = (2 * CONTAINER_NAME_LEN) + 27;
 
 const OBJ_MSCMAP: u32 = 0x005f_ff10;
 
 const TAG_MSCMAP: u8 = 0x81;
 
-/// MS Container Map(?) Records
+/// MS Container Map records.
-#[derive(Copy, Clone)]
+///
-pub struct Container {
+/// Defined in Microsoft's Smart Card Minidriver Specification:
-    /// Container name
+/// <https://docs.microsoft.com/en-us/previous-versions/windows/hardware/design/dn631754(v=vs.85)>
-    pub name: [u16; CONTAINER_NAME_LEN],
+#[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
+#[derive(Clone, Debug)]
+pub struct MsContainer {
+    /// Container name.
+    pub name: [u16; Self::NAME_LEN],
 
-    /// Card slot
+    /// Card slot.
     pub slot: SlotId,
 
-    /// Key spec
+    /// Key spec.
     pub key_spec: u8,
 
-    /// Key size in bits
+    /// Key size in bits.
     pub key_size_bits: u16,
 
-    /// Flags
+    /// Flags.
     pub flags: u8,
 
-    /// PIN ID
+    /// PIN ID.
     pub pin_id: u8,
 
-    /// Associated ECHD(?) container (typo of "ecdh" perhaps?)
+    /// Associated ECHD container.
     pub associated_echd_container: u8,
 
-    /// Cert fingerprint
+    /// Cert fingerprint.
-    pub cert_fingerprint: [u8; 20],
+    pub cert_fingerprint: [u8; Self::CERT_FINGERPRINT_LEN],
 }
 
-impl Container {
+impl MsContainer {
-    /// Read MS Container Map records
+    /// Container name length in UTF-16 chars.
-    pub fn read_mscmap(yubikey: &mut YubiKey) -> Result<Vec<Self>, Error> {
+    const NAME_LEN: usize = 40;
+
+    /// Container record length: 27 = 80 + 1 + 1 + 2 + 1 + 1 + 1 + 20
+    const REC_LEN: usize = (2 * Self::NAME_LEN) + 27;
+
+    /// Length of a certificate fingerprint.
+    const CERT_FINGERPRINT_LEN: usize = 20;
+
+    /// Read MS Container Map records.
+    pub fn read_mscmap(yubikey: &mut YubiKey) -> Result<Vec<Self>> {
         let txn = yubikey.begin_transaction()?;
         let response = txn.fetch_object(OBJ_MSCMAP)?;
         let mut containers = vec![];
@@ -98,17 +98,17 @@ impl Container {
             return Err(Error::InvalidObject);
         }
 
-        for chunk in tlv.value.chunks_exact(CONTAINER_REC_LEN) {
+        for chunk in tlv.value.chunks_exact(Self::REC_LEN) {
-            containers.push(Container::new(chunk)?);
+            containers.push(MsContainer::new(chunk)?);
         }
 
         Ok(containers)
     }
 
     /// Write MS Container Map records.
-    pub fn write_mscmap(yubikey: &mut YubiKey, containers: &[Self]) -> Result<(), Error> {
+    pub fn write_mscmap(yubikey: &mut YubiKey, containers: &[Self]) -> Result<()> {
         let n_containers = containers.len();
-        let data_len = n_containers * CONTAINER_REC_LEN;
+        let data_len = n_containers * Self::REC_LEN;
 
         let txn = yubikey.begin_transaction()?;
 
@@ -118,7 +118,7 @@ impl Container {
 
         let mut buf = [0u8; CB_OBJ_MAX];
         let offset = Tlv::write_as(&mut buf, TAG_MSCMAP, data_len, |buf| {
-            for (i, chunk) in buf.chunks_exact_mut(CONTAINER_REC_LEN).enumerate() {
+            for (i, chunk) in buf.chunks_exact_mut(Self::REC_LEN).enumerate() {
                 chunk.copy_from_slice(&containers[i].to_bytes());
             }
         })?;
@@ -126,19 +126,19 @@ impl Container {
         txn.save_object(OBJ_MSCMAP, &buf[..offset])
     }
 
-    /// Parse a container record from a byte slice
+    /// Parse a container record from a byte slice.
-    pub fn new(bytes: &[u8]) -> Result<Self, Error> {
+    pub fn new(bytes: &[u8]) -> Result<Self> {
-        if bytes.len() != CONTAINER_REC_LEN {
+        if bytes.len() != Self::REC_LEN {
             error!(
                 "couldn't parse PIV container: expected {}-bytes, got {}-bytes",
-                CONTAINER_REC_LEN,
+                Self::REC_LEN,
                 bytes.len()
             );
             return Err(Error::ParseError);
         }
 
-        let mut name = [0u16; CONTAINER_NAME_LEN];
+        let mut name = [0u16; Self::NAME_LEN];
-        let name_bytes_len = CONTAINER_NAME_LEN * 2;
+        let name_bytes_len = Self::NAME_LEN * 2;
 
         for (i, chunk) in bytes[..name_bytes_len].chunks_exact(2).enumerate() {
             name[i] = u16::from_le_bytes(chunk.try_into().unwrap());
@@ -147,7 +147,7 @@ impl Container {
         let mut cert_fingerprint = [0u8; 20];
         cert_fingerprint.copy_from_slice(&bytes[(bytes.len() - 20)..]);
 
-        Ok(Container {
+        Ok(Self {
             name,
             slot: bytes[name_bytes_len].try_into()?,
             key_spec: bytes[name_bytes_len + 1],
@@ -163,16 +163,17 @@ impl Container {
         })
     }
 
-    /// Parse the container name as a UTF-16 string
+    /// Parse the container name as a UTF-16 string.
-    pub fn parse_name(&self) -> Result<String, Error> {
+    pub fn parse_name(&self) -> Result<String> {
         String::from_utf16(&self.name).map_err(|_| Error::ParseError)
     }
 
-    /// Serialize a container record as a byte size
+    /// Serialize a container record as a byte size.
-    pub fn to_bytes(&self) -> [u8; CONTAINER_REC_LEN] {
+    pub fn to_bytes(&self) -> [u8; Self::REC_LEN] {
-        let mut bytes = Vec::with_capacity(CONTAINER_REC_LEN);
+        // TODO(tarcieri): use array instead of `Vec`
+        let mut bytes = Vec::with_capacity(Self::REC_LEN);
 
-        for i in 0..CONTAINER_NAME_LEN {
+        for i in 0..Self::NAME_LEN {
             bytes.extend_from_slice(&self.name[i].to_le_bytes());
         }
 
@@ -183,36 +184,14 @@ impl Container {
         bytes.push(self.pin_id);
         bytes.push(self.associated_echd_container);
         bytes.extend_from_slice(&self.cert_fingerprint);
-
+        bytes.as_slice().try_into().unwrap()
-        // TODO(tarcieri): use TryInto here when const generics are available
-        let mut result = [0u8; CONTAINER_REC_LEN];
-        result.copy_from_slice(&bytes);
-        result
     }
 }
 
-impl Debug for Container {
+impl<'a> TryFrom<&'a [u8]> for MsContainer {
-    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
-        write!(
-            f,
-            "PivContainer {{ name: {:?}, slot: {:?}, key_spec: {}, key_size_bits: {}, \
-             flags: {}, pin_id: {}, associated_echd_container: {}, cert_fingerprint: {:?} }}",
-            &self.name[..],
-            self.slot,
-            self.key_spec,
-            self.key_size_bits,
-            self.flags,
-            self.pin_id,
-            self.associated_echd_container,
-            &self.cert_fingerprint[..]
-        )
-    }
-}
-
-impl<'a> TryFrom<&'a [u8]> for Container {
     type Error = Error;
 
-    fn try_from(bytes: &'a [u8]) -> Result<Self, Error> {
+    fn try_from(bytes: &'a [u8]) -> Result<Self> {
         Self::new(bytes)
     }
 }

src/msroots.rs

@@ -1,11 +1,4 @@
-//! `msroots`: PKCS#7 formatted certificate store for enterprise trusted roots.
+//! PKCS#7 formatted certificate store for enterprise trusted roots.
-//!
-//! This `msroots` file contains a bag of certificates with empty content and
-//! an empty signature, allowing an enterprise root certificate truststore to
-//! be written to and read from a YubiKey.
-//!
-//! For more information, see:
-//! <https://docs.microsoft.com/en-us/windows-hardware/drivers/smartcard/developer-guidelines#-interoperability-with-msroots>
 
 // Adapted from yubico-piv-tool:
 // <https://github.com/Yubico/yubico-piv-tool/>
@@ -37,8 +30,11 @@
 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-use crate::{error::Error, serialization::*, yubikey::YubiKey};
+use crate::{
-use crate::{CB_OBJ_MAX, CB_OBJ_TAG_MAX};
+    consts::{CB_OBJ_MAX, CB_OBJ_TAG_MAX},
+    serialization::*,
+    Error, Result, YubiKey,
+};
 use log::error;
 
 const OBJ_MSROOTS1: u32 = 0x005f_ff11;
@@ -53,17 +49,25 @@ const OBJ_MSROOTS5: u32 = 0x005f_ff15;
 const TAG_MSROOTS_END: u8 = 0x82;
 const TAG_MSROOTS_MID: u8 = 0x83;
 
-/// `msroots` file: PKCS#7-formatted certificate store for enterprise trust roots
+/// PKCS#7-formatted certificate store for enterprise trust roots.
+///
+/// The `msroots` file contains a bag of certificates with empty content and
+/// an empty signature, allowing an enterprise root certificate truststore to
+/// be written to and read from a YubiKey.
+///
+/// For more information, see:
+/// <https://docs.microsoft.com/en-us/windows-hardware/drivers/smartcard/developer-guidelines#-interoperability-with-msroots>
+#[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
 pub struct MsRoots(Vec<u8>);
 
 impl MsRoots {
     /// Initialize a local certificate struct from the given bytebuffer
-    pub fn new(msroots: impl AsRef<[u8]>) -> Result<Self, Error> {
+    pub fn new(msroots: impl AsRef<[u8]>) -> Result<Self> {
         Ok(MsRoots(msroots.as_ref().into()))
     }
 
     /// Read `msroots` file from YubiKey
-    pub fn read(yubikey: &mut YubiKey) -> Result<Option<Self>, Error> {
+    pub fn read(yubikey: &mut YubiKey) -> Result<Option<Self>> {
         let txn = yubikey.begin_transaction()?;
 
         // allocate first page
@@ -100,14 +104,14 @@ impl MsRoots {
     }
 
     /// Write `msroots` file to YubiKey
-    pub fn write(&self, yubikey: &mut YubiKey) -> Result<(), Error> {
+    pub fn write(&self, yubikey: &mut YubiKey) -> Result<()> {
         let mut buf = [0u8; CB_OBJ_MAX];
         let mut offset: usize;
         let mut data_offset: usize = 0;
         let mut data_chunk: usize;
         let data = &self.0;
         let data_len = data.len();
-        let n_objs: usize;
+
         let txn = yubikey.begin_transaction()?;
 
         if data_len == 0 {
@@ -115,7 +119,7 @@ impl MsRoots {
         }
 
         // Calculate number of objects required to store blob
-        n_objs = (data_len / (CB_OBJ_MAX - CB_OBJ_TAG_MAX)) + 1;
+        let n_objs: usize = (data_len / (CB_OBJ_MAX - CB_OBJ_TAG_MAX)) + 1;
 
         if n_objs > 5 {
             return Err(Error::SizeError);

src/piv.rs

@@ -1,11 +1,16 @@
-//! PIV cryptographic keys stored in a YubiKey.
+//! Personal Identity Verification (PIV) cryptographic keys stored in a YubiKey.
+//!
+//! Support for public-key cryptography using keys stored within the PIV
+//! slots of a YubiKey.
 //!
 //! Supported algorithms:
 //!
-//! - **Encryption**: `RSA1024`, `RSA2048`, `ECCP256`, `ECCP384`
+//! - **Encryption**:
+//!   - RSA: `RSA1024`, `RSA2048`
+//!   - ECC: `ECCP256`, `ECCP384` (NIST curves: P-256, P-384)
 //! - **Signatures**:
 //!   - RSASSA-PKCS#1v1.5: `RSA1024`, `RSA2048`
-//!   - ECDSA: `ECCP256`, `ECCP384`
+//!   - ECDSA: `ECCP256`, `ECCP384` (NIST curves: P-256, P-384)
 
 // Adapted from yubico-piv-tool:
 // <https://github.com/Yubico/yubico-piv-tool/>
@@ -39,32 +44,32 @@
 
 use crate::{
     apdu::{Ins, StatusWords},
-    certificate::{self, Certificate},
+    certificate::{self, Certificate, PublicKeyInfo},
-    error::Error,
+    error::{Error, Result},
-    serialization::*,
-    settings,
-    yubikey::YubiKey,
-    ObjectId,
-};
-use log::debug;
-use std::convert::TryFrom;
-
-#[cfg(feature = "untested")]
-use crate::CB_OBJ_MAX;
-use crate::{
-    certificate::PublicKeyInfo,
     policy::{PinPolicy, TouchPolicy},
-    Buffer,
+    serialization::*,
+    setting,
+    yubikey::YubiKey,
+    Buffer, ObjectId,
 };
 use elliptic_curve::sec1::EncodedPoint as EcPublicKey;
-use log::{error, warn};
+use log::{debug, error, warn};
+use p256::NistP256;
+use p384::NistP384;
+use rsa::{BigUint, RsaPublicKey};
+use std::{
+    fmt::{Display, Formatter},
+    str::FromStr,
+};
+
 #[cfg(feature = "untested")]
-use num_bigint::traits::ModInverse;
+use {
-#[cfg(feature = "untested")]
+    crate::consts::CB_OBJ_MAX,
-use num_integer::Integer;
+    num_bigint_dig::traits::ModInverse,
-#[cfg(feature = "untested")]
+    num_integer::Integer,
-use num_traits::{FromPrimitive, One};
+    num_traits::{FromPrimitive, One},
-use rsa::{BigUint, RSAPublicKey};
+};
+
 #[cfg(feature = "untested")]
 use zeroize::Zeroizing;
 
@@ -83,7 +88,7 @@ const KEYDATA_RSA_EXP: u64 = 65537;
 
 /// Slot identifiers.
 /// <https://developers.yubico.com/PIV/Introduction/Certificate_slots.html>
-#[derive(Clone, Copy, Debug, PartialEq)]
+#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq, Ord, PartialOrd)]
 pub enum SlotId {
     /// This certificate and its associated private key is used to authenticate the card
     /// and the cardholder. This slot is used for things like system login. The end user
@@ -126,7 +131,7 @@ pub enum SlotId {
 impl TryFrom<u8> for SlotId {
     type Error = Error;
 
-    fn try_from(value: u8) -> Result<Self, Self::Error> {
+    fn try_from(value: u8) -> Result<Self> {
         match value {
             0x9a => Ok(SlotId::Authentication),
             0x9c => Ok(SlotId::Signature),
@@ -151,17 +156,26 @@ impl From<SlotId> for u8 {
     }
 }
 
-impl TryFrom<String> for SlotId {
+impl Display for SlotId {
-    type Error = Error;
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        match self {
+            SlotId::Retired(r) => write!(f, "{:?}", r),
+            _ => write!(f, "{:?}", self),
+        }
+    }
+}
 
-    fn try_from(s: String) -> Result<SlotId, Error> {
+impl FromStr for SlotId {
-        match s.as_ref() {
+    type Err = Error;
+
+    fn from_str(s: &str) -> Result<SlotId> {
+        match s {
             "9a" => Ok(SlotId::Authentication),
             "9c" => Ok(SlotId::Signature),
             "9d" => Ok(SlotId::KeyManagement),
             "9e" => Ok(SlotId::CardAuthentication),
             "f9" => Ok(SlotId::Attestation),
-            _ => RetiredSlotId::try_from(s).map(SlotId::Retired),
+            _ => s.parse().map(SlotId::Retired),
         }
     }
 }
@@ -182,7 +196,7 @@ impl SlotId {
 
 /// Retired slot IDs.
 #[allow(missing_docs)]
-#[derive(Clone, Copy, Debug, PartialEq)]
+#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
 pub enum RetiredSlotId {
     R1,
     R2,
@@ -209,7 +223,7 @@ pub enum RetiredSlotId {
 impl TryFrom<u8> for RetiredSlotId {
     type Error = Error;
 
-    fn try_from(value: u8) -> Result<Self, Self::Error> {
+    fn try_from(value: u8) -> Result<Self> {
         match value {
             0x82 => Ok(RetiredSlotId::R1),
             0x83 => Ok(RetiredSlotId::R2),
@@ -236,11 +250,11 @@ impl TryFrom<u8> for RetiredSlotId {
     }
 }
 
-impl TryFrom<String> for RetiredSlotId {
+impl FromStr for RetiredSlotId {
-    type Error = Error;
+    type Err = Error;
 
-    fn try_from(value: String) -> Result<Self, Self::Error> {
+    fn from_str(value: &str) -> Result<Self> {
-        match value.as_ref() {
+        match value {
             "82" => Ok(RetiredSlotId::R1),
             "83" => Ok(RetiredSlotId::R2),
             "84" => Ok(RetiredSlotId::R3),
@@ -293,6 +307,12 @@ impl From<RetiredSlotId> for u8 {
     }
 }
 
+impl Display for RetiredSlotId {
+    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
+        write!(f, "{:?}", self)
+    }
+}
+
 impl RetiredSlotId {
     /// Returns the [`ObjectId`] that corresponds to a given [`RetiredSlotId`].
     pub(crate) fn object_id(self) -> ObjectId {
@@ -354,10 +374,13 @@ pub const SLOTS: [SlotId; 24] = [
 pub enum AlgorithmId {
     /// 1024-bit RSA.
     Rsa1024,
+
     /// 2048-bit RSA.
     Rsa2048,
+
     /// ECDSA with the NIST P256 curve.
     EccP256,
+
     /// ECDSA with the NIST P384 curve.
     EccP384,
 }
@@ -365,7 +388,7 @@ pub enum AlgorithmId {
 impl TryFrom<u8> for AlgorithmId {
     type Error = Error;
 
-    fn try_from(value: u8) -> Result<Self, Self::Error> {
+    fn try_from(value: u8) -> Result<Self> {
         match value {
             0x06 => Ok(AlgorithmId::Rsa1024),
             0x07 => Ok(AlgorithmId::Rsa2048),
@@ -389,11 +412,12 @@ impl From<AlgorithmId> for u8 {
 
 impl AlgorithmId {
     /// Writes the `AlgorithmId` in the format the YubiKey expects during key generation.
-    pub(crate) fn write(self, buf: &mut [u8]) -> Result<usize, Error> {
+    pub(crate) fn write(self, buf: &mut [u8]) -> Result<usize> {
         Tlv::write(buf, 0x80, &[self.into()])
     }
 
     #[cfg(feature = "untested")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
     fn get_elem_len(self) -> usize {
         match self {
             AlgorithmId::Rsa1024 => 64,
@@ -404,6 +428,7 @@ impl AlgorithmId {
     }
 
     #[cfg(feature = "untested")]
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
     fn get_param_tag(self) -> u8 {
         match self {
             AlgorithmId::Rsa1024 | AlgorithmId::Rsa2048 => 0x01,
@@ -424,7 +449,7 @@ pub struct Key {
 
 impl Key {
     /// List Personal Identity Verification (PIV) keys stored in a YubiKey
-    pub fn list(yubikey: &mut YubiKey) -> Result<Vec<Self>, Error> {
+    pub fn list(yubikey: &mut YubiKey) -> Result<Vec<Self>> {
         let mut keys = vec![];
         let txn = yubikey.begin_transaction()?;
 
@@ -457,15 +482,14 @@ impl Key {
     }
 }
 
-/// Generate key
+/// Generate new key.
-#[allow(clippy::cognitive_complexity)]
 pub fn generate(
     yubikey: &mut YubiKey,
     slot: SlotId,
     algorithm: AlgorithmId,
     pin_policy: PinPolicy,
     touch_policy: TouchPolicy,
-) -> Result<PublicKeyInfo, Error> {
+) -> Result<PublicKeyInfo> {
     // Keygen messages
     // TODO(tarcieri): extract these into an I18N-handling type?
     const SZ_SETTING_ROCA: &str = "Enable_Unsafe_Keygen_ROCA";
@@ -477,7 +501,7 @@ pub fn generate(
     const SZ_ROCA_BLOCK_ADMIN: &str = "was blocked due to an administrator configuration setting.";
     const SZ_ROCA_DEFAULT: &str = "was permitted by default, but is not recommended.  The default behavior will change in a future Yubico release.";
 
-    let setting_roca: settings::BoolValue;
+    let setting_roca: setting::Setting;
 
     match algorithm {
         AlgorithmId::Rsa1024 | AlgorithmId::Rsa2048 => {
@@ -485,17 +509,17 @@ pub fn generate(
                 && (yubikey.version.minor < 3
                     || yubikey.version.minor == 3 && (yubikey.version.patch < 5))
             {
-                setting_roca = settings::BoolValue::get(SZ_SETTING_ROCA, true);
+                setting_roca = setting::Setting::get(SZ_SETTING_ROCA, true);
 
                 let psz_msg = match setting_roca.source {
-                    settings::Source::User => {
+                    setting::SettingSource::User => {
                         if setting_roca.value {
                             SZ_ROCA_ALLOW_USER
                         } else {
                             SZ_ROCA_BLOCK_USER
                         }
                     }
-                    settings::Source::Admin => {
+                    setting::SettingSource::Admin => {
                         if setting_roca.value {
                             SZ_ROCA_ALLOW_ADMIN
                         } else {
@@ -620,7 +644,7 @@ pub fn generate(
 
             Ok(PublicKeyInfo::Rsa {
                 algorithm,
-                pubkey: RSAPublicKey::new(
+                pubkey: RsaPublicKey::new(
                     BigUint::from_bytes_be(&modulus),
                     BigUint::from_bytes_be(&exp),
                 )
@@ -653,10 +677,14 @@ pub fn generate(
 
             let point = tlv.value.to_vec();
 
-            if let AlgorithmId::EccP256 = algorithm {
+            match algorithm {
-                EcPublicKey::from_bytes(point).map(PublicKeyInfo::EcP256)
+                AlgorithmId::EccP256 => {
-            } else {
+                    EcPublicKey::<NistP256>::from_bytes(point).map(PublicKeyInfo::EcP256)
-                EcPublicKey::from_bytes(point).map(PublicKeyInfo::EcP384)
+                }
+                AlgorithmId::EccP384 => {
+                    EcPublicKey::<NistP384>::from_bytes(point).map(PublicKeyInfo::EcP384)
+                }
+                _ => return Err(Error::AlgorithmError),
             }
             .map_err(|_| Error::InvalidObject)
         }
@@ -664,6 +692,7 @@ pub fn generate(
 }
 
 #[cfg(feature = "untested")]
+#[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
 fn write_key(
     yubikey: &mut YubiKey,
     slot: SlotId,
@@ -671,7 +700,7 @@ fn write_key(
     pin_policy: PinPolicy,
     touch_policy: TouchPolicy,
     algorithm: AlgorithmId,
-) -> Result<(), Error> {
+) -> Result<()> {
     let mut key_data = Buffer::new(vec![0u8; KEYDATA_LEN]);
     let templ = [0, Ins::ImportKey.code(), algorithm.into(), slot.into()];
     let mut offset = 0;
@@ -712,6 +741,7 @@ fn write_key(
 
 /// The key data that makes up an RSA key.
 #[cfg(feature = "untested")]
+#[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
 pub struct RsaKeyData {
     /// The secret prime `p`.
     p: Buffer,
@@ -773,6 +803,7 @@ impl RsaKeyData {
 ///
 /// Errors if `algorithm` isn't `AlgorithmId::Rsa1024` or `AlgorithmId::Rsa2048`.
 #[cfg(feature = "untested")]
+#[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
 pub fn import_rsa_key(
     yubikey: &mut YubiKey,
     slot: SlotId,
@@ -780,7 +811,7 @@ pub fn import_rsa_key(
     key_data: RsaKeyData,
     touch_policy: TouchPolicy,
     pin_policy: PinPolicy,
-) -> Result<(), Error> {
+) -> Result<()> {
     match algorithm {
         AlgorithmId::Rsa1024 | AlgorithmId::Rsa2048 => (),
         _ => return Err(Error::AlgorithmError),
@@ -807,6 +838,7 @@ pub fn import_rsa_key(
 ///
 /// Errors if `algorithm` isn't `AlgorithmId::EccP256` or ` AlgorithmId::EccP384`.
 #[cfg(feature = "untested")]
+#[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
 pub fn import_ecc_key(
     yubikey: &mut YubiKey,
     slot: SlotId,
@@ -814,7 +846,7 @@ pub fn import_ecc_key(
     key_data: &[u8],
     touch_policy: TouchPolicy,
     pin_policy: PinPolicy,
-) -> Result<(), Error> {
+) -> Result<()> {
     match algorithm {
         AlgorithmId::EccP256 | AlgorithmId::EccP384 => (),
         _ => return Err(Error::AlgorithmError),
@@ -832,9 +864,11 @@ pub fn import_ecc_key(
 }
 
 /// Generate an attestation certificate for a stored key.
+///
 /// <https://developers.yubico.com/PIV/Introduction/PIV_attestation.html>
 #[cfg(feature = "untested")]
-pub fn attest(yubikey: &mut YubiKey, key: SlotId) -> Result<Buffer, Error> {
+#[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
+pub fn attest(yubikey: &mut YubiKey, key: SlotId) -> Result<Buffer> {
     let templ = [0, Ins::Attest.code(), key.into(), 0];
     let txn = yubikey.begin_transaction()?;
     let response = txn.transfer_data(&templ, &[], CB_OBJ_MAX)?;
@@ -854,27 +888,28 @@ pub fn attest(yubikey: &mut YubiKey, key: SlotId) -> Result<Buffer, Error> {
     Ok(Buffer::new(response.data().into()))
 }
 
-/// Sign data using a PIV key
+/// Sign data using a PIV key.
 pub fn sign_data(
     yubikey: &mut YubiKey,
     raw_in: &[u8],
     algorithm: AlgorithmId,
     key: SlotId,
-) -> Result<Buffer, Error> {
+) -> Result<Buffer> {
     let txn = yubikey.begin_transaction()?;
 
     // don't attempt to reselect in crypt operations to avoid problems with PIN_ALWAYS
     txn.authenticated_command(raw_in, algorithm, key, false)
 }
 
-/// Decrypt data using a PIV key
+/// Decrypt data using a PIV key.
 #[cfg(feature = "untested")]
+#[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
 pub fn decrypt_data(
     yubikey: &mut YubiKey,
     input: &[u8],
     algorithm: AlgorithmId,
     key: SlotId,
-) -> Result<Buffer, Error> {
+) -> Result<Buffer> {
     let txn = yubikey.begin_transaction()?;
 
     // don't attempt to reselect in crypt operations to avoid problems with PIN_ALWAYS

src/policy.rs

@@ -1,10 +1,11 @@
 //! Enums representing key policies.
 
-use crate::{error::Error, serialization::Tlv};
+use crate::{serialization::Tlv, Result};
 
 /// Specifies how often the PIN needs to be entered for access to the credential in a
-/// given slot. This policy must be set upon key generation or importation, and cannot be
+/// given slot.
-/// changed later.
+///
+/// This policy must be set when keys are generated or imported, and cannot be changed later.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub enum PinPolicy {
     /// Use the default PIN policy for the slot. See the slot's documentation for details.
@@ -37,7 +38,7 @@ impl From<PinPolicy> for u8 {
 impl PinPolicy {
     /// Writes the `PinPolicy` in the format the YubiKey expects during key generation or
     /// importation.
-    pub(crate) fn write(self, buf: &mut [u8]) -> Result<usize, Error> {
+    pub(crate) fn write(self, buf: &mut [u8]) -> Result<usize> {
         match self {
             PinPolicy::Default => Ok(0),
             _ => Tlv::write(buf, 0xaa, &[self.into()]),
@@ -46,8 +47,9 @@ impl PinPolicy {
 }
 
 /// Specifies under what conditions a physical touch on the metal contact is required, in
-/// addition to the [`PinPolicy`]. This policy must be set upon key generation or
+/// addition to the [`PinPolicy`].
-/// importation, and cannot be changed later.
+///
+/// This policy must be set when keys are generated or imported, and cannot be changed later.
 #[derive(Clone, Copy, Debug, PartialEq)]
 pub enum TouchPolicy {
     /// Use the default touch policy for the slot.
@@ -81,7 +83,7 @@ impl From<TouchPolicy> for u8 {
 impl TouchPolicy {
     /// Writes the `TouchPolicy` in the format the YubiKey expects during key generation
     /// or importation.
-    pub(crate) fn write(self, buf: &mut [u8]) -> Result<usize, Error> {
+    pub(crate) fn write(self, buf: &mut [u8]) -> Result<usize> {
         match self {
             TouchPolicy::Default => Ok(0),
             _ => Tlv::write(buf, 0xab, &[self.into()]),

src/reader.rs

@@ -1,9 +1,8 @@
-//! Support for enumerating available readers
+//! Support for enumerating available PC/SC card readers.
 
-use crate::{error::Error, yubikey::YubiKey};
+use crate::{Result, YubiKey};
 use std::{
     borrow::Cow,
-    convert::TryInto,
     ffi::CStr,
     sync::{Arc, Mutex},
 };
@@ -11,8 +10,8 @@ use std::{
 /// Iterator over connected readers
 pub type Iter<'ctx> = std::vec::IntoIter<Reader<'ctx>>;
 
-/// Enumeration support for available readers
+/// PC/SC reader context: used to enumerate available PC/SC [`Reader`]s.
-pub struct Readers {
+pub struct Context {
     /// PC/SC context
     ctx: Arc<Mutex<pcsc::Context>>,
 
@@ -20,10 +19,10 @@ pub struct Readers {
     reader_names: Vec<u8>,
 }
 
-impl Readers {
+impl Context {
     /// Open a PC/SC context, which can be used to enumerate available PC/SC
     /// readers (which can be used to connect to YubiKeys).
-    pub fn open() -> Result<Self, Error> {
+    pub fn open() -> Result<Self> {
         let ctx = pcsc::Context::establish(pcsc::Scope::System)?;
         let reader_names = vec![0u8; ctx.list_readers_len()?];
         Ok(Self {
@@ -32,8 +31,8 @@ impl Readers {
         })
     }
 
-    /// Iterate over the available readers
+    /// Iterate over the available readers.
-    pub fn iter(&mut self) -> Result<Iter<'_>, Error> {
+    pub fn iter(&mut self) -> Result<Iter<'_>> {
         let Self { ctx, reader_names } = self;
 
         let reader_cstrs: Vec<_> = {
@@ -45,6 +44,7 @@ impl Readers {
             c.list_readers(reader_names)?.collect()
         };
 
+        #[allow(clippy::needless_collect)]
         let readers: Vec<_> = reader_cstrs
             .iter()
             .map(|name| Reader::new(name, Arc::clone(ctx)))
@@ -54,7 +54,7 @@ impl Readers {
     }
 }
 
-/// An individual connected reader
+/// An individual connected PC/SC card reader.
 pub struct Reader<'ctx> {
     /// Name of this reader
     name: &'ctx CStr,
@@ -64,25 +64,25 @@ pub struct Reader<'ctx> {
 }
 
 impl<'ctx> Reader<'ctx> {
-    /// Create a new reader from its name and context
+    /// Create a new reader from its name and context.
     fn new(name: &'ctx CStr, ctx: Arc<Mutex<pcsc::Context>>) -> Self {
         // TODO(tarcieri): open devices, determine they're YubiKeys, get serial?
         Self { name, ctx }
     }
 
-    /// Get this reader's name
+    /// Get this reader's name.
     pub fn name(&self) -> Cow<'_, str> {
         // TODO(tarcieri): is lossy ok here? try to avoid lossiness?
         self.name.to_string_lossy()
     }
 
-    /// Open a connection to this reader, returning a `YubiKey` if successful
+    /// Open a connection to this reader, returning a `YubiKey` if successful.
-    pub fn open(&self) -> Result<YubiKey, Error> {
+    pub fn open(&self) -> Result<YubiKey> {
         self.try_into()
     }
 
-    /// Connect to this reader, returning its `pcsc::Card`
+    /// Connect to this reader, returning its `pcsc::Card`.
-    pub(crate) fn connect(&self) -> Result<pcsc::Card, Error> {
+    pub(crate) fn connect(&self) -> Result<pcsc::Card> {
         let ctx = self.ctx.lock().unwrap();
         Ok(ctx.connect(self.name, pcsc::ShareMode::Shared, pcsc::Protocols::T1)?)
     }

src/serialization.rs

@@ -30,7 +30,7 @@
 // (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-use crate::{error::Error, Buffer, ObjectId, CB_OBJ_TAG_MIN};
+use crate::{consts::CB_OBJ_TAG_MIN, Buffer, Error, ObjectId, Result};
 
 pub const OBJ_DISCOVERY: u32 = 0x7e;
 
@@ -44,24 +44,27 @@ pub(crate) struct Tlv<'a> {
 
 impl<'a> Tlv<'a> {
     /// Parses a `Tlv` from a buffer, returning the remainder of the buffer.
-    pub(crate) fn parse(buffer: &'a [u8]) -> Result<(&'a [u8], Self), Error> {
+    pub(crate) fn parse(buffer: &'a [u8]) -> Result<(&'a [u8], Self)> {
         if buffer.len() < CB_OBJ_TAG_MIN || !has_valid_length(&buffer[1..], buffer.len() - 1) {
             return Err(Error::SizeError);
         }
 
         let tag = buffer[0];
-
         let mut len = 0;
         let offset = 1 + get_length(&buffer[1..], &mut len);
+        let buffer = buffer.get(offset..).ok_or(Error::SizeError)?;
 
-        let (value, buffer) = buffer[offset..].split_at(len);
+        if buffer.len() >= len {
-
+            let (value, buffer) = buffer.split_at(len);
             Ok((buffer, Tlv { tag, value }))
+        } else {
+            Err(Error::SizeError)
+        }
     }
 
     /// Takes a [`Buffer`] containing a single `Tlv` with the given tag, and returns a
     /// `Buffer` containing only the value part of the `Tlv`.
-    pub(crate) fn parse_single(mut buffer: Buffer, tag: u8) -> Result<Buffer, Error> {
+    pub(crate) fn parse_single(mut buffer: Buffer, tag: u8) -> Result<Buffer> {
         if buffer.len() < CB_OBJ_TAG_MIN || !has_valid_length(&buffer[1..], buffer.len() - 1) {
             return Err(Error::SizeError);
         }
@@ -79,7 +82,7 @@ impl<'a> Tlv<'a> {
     }
 
     /// Writes a TLV to the given buffer.
-    pub(crate) fn write(buffer: &mut [u8], tag: u8, value: &[u8]) -> Result<usize, Error> {
+    pub(crate) fn write(buffer: &mut [u8], tag: u8, value: &[u8]) -> Result<usize> {
         if buffer.len() < CB_OBJ_TAG_MIN {
             return Err(Error::SizeError);
         }
@@ -103,7 +106,7 @@ impl<'a> Tlv<'a> {
         tag: u8,
         length: usize,
         value: Gen,
-    ) -> Result<usize, Error>
+    ) -> Result<usize>
     where
         Gen: FnOnce(&mut [u8]),
     {
@@ -124,7 +127,7 @@ impl<'a> Tlv<'a> {
 }
 
 /// Set length
-pub(crate) fn set_length(buffer: &mut [u8], length: usize) -> Result<usize, Error> {
+pub(crate) fn set_length(buffer: &mut [u8], length: usize) -> Result<usize> {
     if length < 0x80 {
         if buffer.is_empty() {
             Err(Error::SizeError)

src/setting.rs

@@ -0,0 +1,132 @@
+//! Configuration setting values parsed from the environment and config file:
+//! `/etc/yubico/yubikeypiv.conf`
+
+// Adapted from yubico-piv-tool:
+// <https://github.com/Yubico/yubico-piv-tool/>
+//
+// Copyright (c) 2014-2016 Yubico AB
+// All rights reserved.
+//
+// Redistribution and use in source and binary forms, with or without
+// modification, are permitted provided that the following conditions are
+// met:
+//
+//   * Redistributions of source code must retain the above copyright
+//     notice, this list of conditions and the following disclaimer.
+//
+//   * Redistributions in binary form must reproduce the above
+//     copyright notice, this list of conditions and the following
+//     disclaimer in the documentation and/or other materials provided
+//     with the distribution.
+//
+// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+/// Default location of the YubiKey PIV configuration file
+pub const DEFAULT_CONFIG_FILE: &str = "/etc/yubico/yubikeypiv.conf";
+
+use std::{
+    env,
+    fs::File,
+    io::{BufRead, BufReader},
+};
+
+/// Source of how a setting was configured.
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum SettingSource {
+    /// User-specified setting: sourced via `YUBIKEY_PIV_*` environment vars.
+    User,
+
+    /// Admin-specified setting: sourced via the `/etc/yubico/yubikeypiv.conf`
+    /// configuration file.
+    Admin,
+
+    /// Default setting.
+    Default,
+}
+
+impl Default for SettingSource {
+    fn default() -> Self {
+        Self::Default
+    }
+}
+
+/// Setting booleans: configuration values sourced from a file or the environment.
+///
+/// These can be configured globally in `/etc/yubico/yubikeypiv.conf` by a
+/// system administrator, or by the local user via `YUBIKEY_PIV_*` environment
+/// variables.
+#[derive(Copy, Clone, Debug, Default)]
+pub struct Setting {
+    /// Boolean value
+    pub value: bool,
+
+    /// Source of the configuration setting (user, admin, or default)
+    pub source: SettingSource,
+}
+
+impl Setting {
+    /// Get a setting by name.
+    pub fn get(key: &str, default: bool) -> Self {
+        Self::from_file(key)
+            .or_else(|| Self::from_env(key))
+            .unwrap_or(Self {
+                value: default,
+                source: SettingSource::Default,
+            })
+    }
+
+    /// Get a boolean config value from the provided config file
+    fn from_file(key: &str) -> Option<Self> {
+        if let Ok(file) = File::open(DEFAULT_CONFIG_FILE) {
+            for line in BufReader::new(file).lines() {
+                let line = match line {
+                    Ok(line) => line,
+                    _ => continue,
+                };
+
+                if line.starts_with('#') || line.starts_with('\r') || line.starts_with('\n') {
+                    continue;
+                }
+
+                let (name, value) = {
+                    let mut parts = line.splitn(2, '=');
+                    let name = parts.next();
+                    let value = parts.next();
+                    match (name, value, parts.next()) {
+                        (Some(name), Some(value), None) => (name.trim(), value.trim()),
+                        _ => continue,
+                    }
+                };
+
+                if name == key {
+                    return Some(Setting {
+                        source: SettingSource::Admin,
+                        value: value == "1" || value == "true",
+                    });
+                }
+            }
+        }
+
+        None
+    }
+
+    /// Get a setting boolean from an environment variable
+    fn from_env(key: &str) -> Option<Self> {
+        env::var(format!("YUBIKEY_PIV_{}", key))
+            .ok()
+            .map(|value| Setting {
+                source: SettingSource::User,
+                value: value == "1" || value == "true",
+            })
+    }
+}

src/settings.rs

@@ -1,138 +0,0 @@
-//! Configuration setting values parsed from the environment and config file:
-//! `/etc/yubico/yubikeypiv.conf`
-
-// Adapted from yubico-piv-tool:
-// <https://github.com/Yubico/yubico-piv-tool/>
-//
-// Copyright (c) 2014-2016 Yubico AB
-// All rights reserved.
-//
-// Redistribution and use in source and binary forms, with or without
-// modification, are permitted provided that the following conditions are
-// met:
-//
-//   * Redistributions of source code must retain the above copyright
-//     notice, this list of conditions and the following disclaimer.
-//
-//   * Redistributions in binary form must reproduce the above
-//     copyright notice, this list of conditions and the following
-//     disclaimer in the documentation and/or other materials provided
-//     with the distribution.
-//
-// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
-// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
-// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
-// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
-// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
-// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
-// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
-// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
-// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
-// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
-// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-
-/// Default location of the YubiKey PIV configuration file
-pub const DEFAULT_CONFIG_FILE: &str = "/etc/yubico/yubikeypiv.conf";
-
-use std::{
-    env,
-    fs::File,
-    io::{BufRead, BufReader},
-};
-
-/// Source of how a setting was configured
-#[derive(Clone, Copy, Debug, Eq, PartialEq)]
-pub enum Source {
-    /// User-specified setting
-    User,
-
-    /// Admin-specified setting
-    Admin,
-
-    /// Default setting
-    Default,
-}
-
-/// Setting booleans
-#[derive(Copy, Clone, Debug)]
-pub struct BoolValue {
-    /// Boolean value
-    pub value: bool,
-
-    /// Source of the configuration setting (user/admin/default)
-    pub source: Source,
-}
-
-impl BoolValue {
-    /// Get a [`BoolValue`] value
-    pub fn get(key: &str, def: bool) -> Self {
-        let mut setting = get_setting_from_file(key);
-
-        if setting.source == Source::Default {
-            setting = get_setting_from_env(key);
-        }
-
-        if setting.source == Source::Default {
-            setting.value = def;
-        }
-
-        setting
-    }
-}
-
-/// Get a boolean config value
-fn get_setting_from_file(key: &str) -> BoolValue {
-    let mut setting: BoolValue = BoolValue {
-        value: false,
-        source: Source::Default,
-    };
-
-    let file = match File::open(DEFAULT_CONFIG_FILE) {
-        Ok(f) => f,
-        Err(_) => return setting,
-    };
-
-    for line in BufReader::new(file).lines() {
-        let line = match line {
-            Ok(line) => line,
-            _ => continue,
-        };
-
-        if line.starts_with('#') || line.starts_with('\r') || line.starts_with('\n') {
-            continue;
-        }
-
-        let (name, value) = {
-            let mut parts = line.splitn(1, '=');
-            let name = parts.next();
-            let value = parts.next();
-            match (name, value, parts.next()) {
-                (Some(name), Some(value), None) => (name.trim(), value.trim()),
-                _ => continue,
-            }
-        };
-
-        if name == key {
-            setting.source = Source::Admin;
-            setting.value = value == "1" || value == "true";
-            break;
-        }
-    }
-
-    setting
-}
-
-/// Get a setting boolean from an environment variable
-fn get_setting_from_env(key: &str) -> BoolValue {
-    let mut setting: BoolValue = BoolValue {
-        value: false,
-        source: Source::Default,
-    };
-
-    if let Ok(value) = env::var(format!("YUBIKEY_PIV_{}", key)) {
-        setting.source = Source::User;
-        setting.value = value == "1" || value == "true";
-    }
-
-    setting
-}

src/transaction.rs

@@ -2,20 +2,26 @@
 
 use crate::{
     apdu::Response,
-    apdu::{Ins, StatusWords, APDU},
+    apdu::{Apdu, Ins, StatusWords},
-    error::Error,
+    consts::{CB_BUF_MAX, CB_OBJ_MAX},
-    key::{AlgorithmId, SlotId},
+    error::{Error, Result},
+    piv::{AlgorithmId, SlotId},
     serialization::*,
     yubikey::*,
-    Buffer, ObjectId, CB_BUF_MAX, CB_OBJ_MAX, PIV_AID, YK_AID,
+    Buffer, ObjectId,
 };
 use log::{error, trace};
-use std::convert::TryInto;
 use zeroize::Zeroizing;
 
 #[cfg(feature = "untested")]
 use crate::mgm::{MgmKey, DES_LEN_3DES};
 
+/// PIV Applet ID
+const PIV_AID: [u8; 5] = [0xa0, 0x00, 0x00, 0x03, 0x08];
+
+/// YubiKey OTP Applet ID. Needed to query serial on YK4.
+const YK_AID: [u8; 8] = [0xa0, 0x00, 0x00, 0x05, 0x27, 0x20, 0x01, 0x01];
+
 const CB_PIN_MAX: usize = 8;
 
 #[cfg(feature = "untested")]
@@ -32,7 +38,7 @@ pub(crate) struct Transaction<'tx> {
 
 impl<'tx> Transaction<'tx> {
     /// Create a new transaction with the given card.
-    pub fn new(card: &'tx mut pcsc::Card) -> Result<Self, Error> {
+    pub fn new(card: &'tx mut pcsc::Card) -> Result<Self> {
         Ok(Transaction {
             inner: card.transaction()?,
         })
@@ -45,7 +51,7 @@ impl<'tx> Transaction<'tx> {
     /// single APDU messages at a time. For larger messages that need to be
     /// split into multiple APDUs, use the [`Transaction::transfer_data`]
     /// method instead.
-    pub fn transmit(&self, send_buffer: &[u8], recv_len: usize) -> Result<Vec<u8>, Error> {
+    pub fn transmit(&self, send_buffer: &[u8], recv_len: usize) -> Result<Vec<u8>> {
         trace!(">>> {:?}", send_buffer);
 
         let mut recv_buffer = vec![0u8; recv_len];
@@ -60,8 +66,8 @@ impl<'tx> Transaction<'tx> {
     }
 
     /// Select application.
-    pub fn select_application(&self) -> Result<(), Error> {
+    pub fn select_application(&self) -> Result<()> {
-        let response = APDU::new(Ins::SelectApplication)
+        let response = Apdu::new(Ins::SelectApplication)
             .p1(0x04)
             .data(&PIV_AID)
             .transmit(self, 0xFF)
@@ -82,9 +88,9 @@ impl<'tx> Transaction<'tx> {
     }
 
     /// Get the version of the PIV application installed on the YubiKey.
-    pub fn get_version(&self) -> Result<Version, Error> {
+    pub fn get_version(&self) -> Result<Version> {
         // get version from device
-        let response = APDU::new(Ins::GetVersion).transmit(self, 261)?;
+        let response = Apdu::new(Ins::GetVersion).transmit(self, 261)?;
 
         if !response.is_success() {
             return Err(Error::GenericError);
@@ -98,10 +104,10 @@ impl<'tx> Transaction<'tx> {
     }
 
     /// Get YubiKey device serial number.
-    pub fn get_serial(&self, version: Version) -> Result<Serial, Error> {
+    pub fn get_serial(&self, version: Version) -> Result<Serial> {
         let response = if version.major < 5 {
             // YK4 requires switching to the yk applet to retrieve the serial
-            let sw = APDU::new(Ins::SelectApplication)
+            let sw = Apdu::new(Ins::SelectApplication)
                 .p1(0x04)
                 .data(&YK_AID)
                 .transmit(self, 0xFF)?
@@ -112,7 +118,7 @@ impl<'tx> Transaction<'tx> {
                 return Err(Error::GenericError);
             }
 
-            let resp = APDU::new(0x01).p1(0x10).transmit(self, 0xFF)?;
+            let resp = Apdu::new(0x01).p1(0x10).transmit(self, 0xFF)?;
 
             if !resp.is_success() {
                 error!(
@@ -123,7 +129,7 @@ impl<'tx> Transaction<'tx> {
             }
 
             // reselect the PIV applet
-            let sw = APDU::new(Ins::SelectApplication)
+            let sw = Apdu::new(Ins::SelectApplication)
                 .p1(0x04)
                 .data(&PIV_AID)
                 .transmit(self, 0xFF)?
@@ -137,7 +143,7 @@ impl<'tx> Transaction<'tx> {
             resp
         } else {
             // YK5 implements getting the serial as a PIV applet command (0xf8)
-            let resp = APDU::new(Ins::GetSerial).transmit(self, 0xFF)?;
+            let resp = Apdu::new(Ins::GetSerial).transmit(self, 0xFF)?;
 
             if !resp.is_success() {
                 error!(
@@ -157,12 +163,12 @@ impl<'tx> Transaction<'tx> {
     }
 
     /// Verify device PIN.
-    pub fn verify_pin(&self, pin: &[u8]) -> Result<(), Error> {
+    pub fn verify_pin(&self, pin: &[u8]) -> Result<()> {
         if pin.len() > CB_PIN_MAX {
             return Err(Error::SizeError);
         }
 
-        let mut query = APDU::new(Ins::Verify);
+        let mut query = Apdu::new(Ins::Verify);
         query.params(0x00, 0x80);
 
         // Empty pin means we are querying the number of retries. We set no data in this
@@ -191,7 +197,7 @@ impl<'tx> Transaction<'tx> {
         action: ChangeRefAction,
         current_pin: &[u8],
         new_pin: &[u8],
-    ) -> Result<(), Error> {
+    ) -> Result<()> {
         if current_pin.len() > CB_PIN_MAX || new_pin.len() > CB_PIN_MAX {
             return Err(Error::SizeError);
         }
@@ -229,14 +235,8 @@ impl<'tx> Transaction<'tx> {
 
     /// Set the management key (MGM).
     #[cfg(feature = "untested")]
-    pub fn set_mgm_key(&self, new_key: &MgmKey, touch: Option<u8>) -> Result<(), Error> {
+    pub fn set_mgm_key(&self, new_key: &MgmKey, require_touch: bool) -> Result<()> {
-        let p2 = match touch.unwrap_or_default() {
+        let p2 = if require_touch { 0xfe } else { 0xff };
-            0 => 0xff,
-            1 => 0xfe,
-            _ => {
-                return Err(Error::GenericError);
-            }
-        };
 
         let mut data = [0u8; DES_LEN_3DES + 3];
         data[0] = ALGO_3DES;
@@ -244,7 +244,7 @@ impl<'tx> Transaction<'tx> {
         data[2] = DES_LEN_3DES as u8;
         data[3..3 + DES_LEN_3DES].copy_from_slice(new_key.as_ref());
 
-        let status_words = APDU::new(Ins::SetMgmKey)
+        let status_words = Apdu::new(Ins::SetMgmKey)
             .params(0xff, p2)
             .data(&data)
             .transmit(self, 261)?
@@ -269,7 +269,7 @@ impl<'tx> Transaction<'tx> {
         algorithm: AlgorithmId,
         key: SlotId,
         decipher: bool,
-    ) -> Result<Buffer, Error> {
+    ) -> Result<Buffer> {
         let in_len = sign_in.len();
         let mut indata = [0u8; 1024];
         let templ = [0, Ins::Authenticate.code(), algorithm.into(), key.into()];
@@ -364,12 +364,7 @@ impl<'tx> Transaction<'tx> {
     /// messages into smaller APDU-sized messages (using the provided APDU
     /// template to construct them), and then sending those via
     /// [`Transaction::transmit`].
-    pub fn transfer_data(
+    pub fn transfer_data(&self, templ: &[u8], in_data: &[u8], max_out: usize) -> Result<Response> {
-        &self,
-        templ: &[u8],
-        in_data: &[u8],
-        max_out: usize,
-    ) -> Result<Response, Error> {
         let mut in_offset = 0;
         let mut out_data = vec![];
         let mut sw;
@@ -386,7 +381,7 @@ impl<'tx> Transaction<'tx> {
 
             trace!("going to send {} bytes in this go", this_size);
 
-            let response = APDU::new(templ[1])
+            let response = Apdu::new(templ[1])
                 .cla(cla)
                 .params(templ[2], templ[3])
                 .data(&in_data[in_offset..(in_offset + this_size)])
@@ -423,7 +418,7 @@ impl<'tx> Transaction<'tx> {
                 sw & 0xff
             );
 
-            let response = APDU::new(Ins::GetResponseApdu).transmit(self, 261)?;
+            let response = Apdu::new(Ins::GetResponseApdu).transmit(self, 261)?;
             sw = response.status_words().code();
 
             if sw != StatusWords::Success.code() && (sw >> 8 != 0x61) {
@@ -447,7 +442,7 @@ impl<'tx> Transaction<'tx> {
     }
 
     /// Fetch an object.
-    pub fn fetch_object(&self, object_id: ObjectId) -> Result<Buffer, Error> {
+    pub fn fetch_object(&self, object_id: ObjectId) -> Result<Buffer> {
         let mut indata = [0u8; 5];
         let templ = [0, Ins::GetData.code(), 0x3f, 0xff];
 
@@ -481,7 +476,7 @@ impl<'tx> Transaction<'tx> {
     }
 
     /// Save an object.
-    pub fn save_object(&self, object_id: ObjectId, indata: &[u8]) -> Result<(), Error> {
+    pub fn save_object(&self, object_id: ObjectId, indata: &[u8]) -> Result<()> {
         let templ = [0, Ins::PutData.code(), 0x3f, 0xff];
 
         // TODO(tarcieri): replace with vector

src/yubikey.rs

@@ -31,33 +31,36 @@
 // OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
 use crate::{
-    apdu::{Ins, APDU},
+    apdu::{Apdu, Ins},
-    cccid::CCC,
+    cccid::CccId,
-    chuid::CHUID,
+    chuid::ChuId,
     config::Config,
-    error::Error,
+    error::{Error, Result},
     mgm::MgmKey,
-    readers::{Reader, Readers},
+    piv,
+    reader::{Context, Reader},
     transaction::Transaction,
 };
 use log::{error, info};
 use pcsc::Card;
+use rand_core::{OsRng, RngCore};
 use std::{
-    convert::{TryFrom, TryInto},
     fmt::{self, Display},
     str::FromStr,
 };
 
 #[cfg(feature = "untested")]
-use crate::{
+use {
-    apdu::StatusWords, metadata, transaction::ChangeRefAction, Buffer, ObjectId, CB_BUF_MAX,
+    crate::{
-    CB_OBJ_MAX, MGMT_AID, TAG_ADMIN, TAG_ADMIN_FLAGS_1, TAG_ADMIN_TIMESTAMP,
+        apdu::StatusWords,
+        consts::{TAG_ADMIN_FLAGS_1, TAG_ADMIN_TIMESTAMP},
+        metadata::AdminData,
+        transaction::ChangeRefAction,
+        Buffer, ObjectId,
+    },
+    secrecy::ExposeSecret,
+    std::time::{SystemTime, UNIX_EPOCH},
 };
-use getrandom::getrandom;
-#[cfg(feature = "untested")]
-use secrecy::ExposeSecret;
-#[cfg(feature = "untested")]
-use std::time::{SystemTime, UNIX_EPOCH};
 
 /// Flag for PUK blocked
 pub(crate) const ADMIN_FLAGS_1_PUK_BLOCKED: u8 = 0x01;
@@ -68,12 +71,18 @@ pub(crate) const ALGO_3DES: u8 = 0x03;
 /// Card management key
 pub(crate) const KEY_CARDMGM: u8 = 0x9b;
 
+/// MGMT Applet ID.
+///
+/// <https://developers.yubico.com/PIV/Introduction/Admin_access.html>
+#[cfg(feature = "untested")]
+const MGMT_AID: [u8; 8] = [0xa0, 0x00, 0x00, 0x05, 0x27, 0x47, 0x11, 0x17];
+
 const TAG_DYN_AUTH: u8 = 0x7c;
 
-/// Cached YubiKey PIN
+/// Cached YubiKey PIN.
 pub type CachedPin = secrecy::SecretVec<u8>;
 
-/// YubiKey Serial Number
+/// YubiKey serial number.
 #[derive(Copy, Clone, Debug, Eq, PartialEq, PartialOrd, Ord)]
 pub struct Serial(pub u32);
 
@@ -92,8 +101,8 @@ impl From<Serial> for u32 {
 impl FromStr for Serial {
     type Err = Error;
 
-    fn from_str(s: &str) -> Result<Self, Error> {
+    fn from_str(s: &str) -> Result<Self> {
-        u32::from_str(s).map(Serial).map_err(|_| Error::ParseError)
+        s.parse().map(Serial).map_err(|_| Error::ParseError)
     }
 }
 
@@ -103,7 +112,7 @@ impl Display for Serial {
     }
 }
 
-/// YubiKey Version
+/// YubiKey version.
 #[derive(Copy, Clone, Debug, Eq, PartialEq)]
 pub struct Version {
     /// Major version component
@@ -133,8 +142,7 @@ impl Display for Version {
     }
 }
 
-/// YubiKey Device: this is the primary API for opening a session and
+/// YubiKey device: primary API for opening a session and performing various operations.
-/// performing various operations.
 ///
 /// Almost all functionality in this library will require an open session
 /// with a YubiKey which is represented by this type.
@@ -155,9 +163,10 @@ impl YubiKey {
     ///
     /// If you need to operate in environments with more than one YubiKey
     /// attached to the same system, use [`YubiKey::open_by_serial`] or
-    ///[`yubikey_piv::Readers`] to select from the available PC/SC readers.
+    /// [`yubikey::reader::Context`][`Context`] to select from the available
-    pub fn open() -> Result<Self, Error> {
+    /// PC/SC readers.
-        let mut readers = Readers::open().map_err(|e| match e {
+    pub fn open() -> Result<Self> {
+        let mut readers = Context::open().map_err(|e| match e {
             Error::PcscError {
                 inner: Some(pcsc::Error::NoReadersAvailable),
             } => Error::NotFound,
@@ -179,8 +188,8 @@ impl YubiKey {
     }
 
     /// Open a YubiKey with a specific serial number.
-    pub fn open_by_serial(serial: Serial) -> Result<Self, Error> {
+    pub fn open_by_serial(serial: Serial) -> Result<Self> {
-        let mut readers = Readers::open().map_err(|e| match e {
+        let mut readers = Context::open().map_err(|e| match e {
             Error::PcscError {
                 inner: Some(pcsc::Error::NoReadersAvailable),
             } => Error::NotFound,
@@ -202,9 +211,10 @@ impl YubiKey {
         Err(Error::NotFound)
     }
 
-    /// Reconnect to a YubiKey
+    /// Reconnect to a YubiKey.
     #[cfg(feature = "untested")]
-    pub fn reconnect(&mut self) -> Result<(), Error> {
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
+    pub fn reconnect(&mut self) -> Result<()> {
         info!("trying to reconnect to current reader");
 
         self.card.reconnect(
@@ -229,12 +239,12 @@ impl YubiKey {
     }
 
     /// Begin a transaction.
-    pub(crate) fn begin_transaction(&mut self) -> Result<Transaction<'_>, Error> {
+    pub(crate) fn begin_transaction(&mut self) -> Result<Transaction<'_>> {
         // TODO(tarcieri): reconnect support
-        Ok(Transaction::new(&mut self.card)?)
+        Transaction::new(&mut self.card)
     }
 
-    /// Get the name of the associated PC/SC card reader
+    /// Get the name of the associated PC/SC card reader.
     pub fn name(&self) -> &str {
         &self.name
     }
@@ -254,26 +264,26 @@ impl YubiKey {
     }
 
     /// Get device configuration.
-    pub fn config(&mut self) -> Result<Config, Error> {
+    pub fn config(&mut self) -> Result<Config> {
         Config::get(self)
     }
 
-    /// Get CHUID
+    /// Get Cardholder Unique Identifier (CHUID).
-    pub fn chuid(&mut self) -> Result<CHUID, Error> {
+    pub fn chuid(&mut self) -> Result<ChuId> {
-        CHUID::get(self)
+        ChuId::get(self)
     }
 
-    /// Get CCCID
+    /// Get Cardholder Capability Container (CCC) Identifier.
-    pub fn cccid(&mut self) -> Result<CCC, Error> {
+    pub fn cccid(&mut self) -> Result<CccId> {
-        CCC::get(self)
+        CccId::get(self)
     }
 
     /// Authenticate to the card using the provided management key (MGM).
-    pub fn authenticate(&mut self, mgm_key: MgmKey) -> Result<(), Error> {
+    pub fn authenticate(&mut self, mgm_key: MgmKey) -> Result<()> {
         let txn = self.begin_transaction()?;
 
         // get a challenge from the card
-        let challenge = APDU::new(Ins::Authenticate)
+        let challenge = Apdu::new(Ins::Authenticate)
             .params(ALGO_3DES, KEY_CARDMGM)
             .data(&[TAG_DYN_AUTH, 0x02, 0x80, 0x00])
             .transmit(&txn, 261)?;
@@ -293,16 +303,12 @@ impl YubiKey {
         data[4..12].copy_from_slice(&response);
         data[12] = 0x81;
         data[13] = 8;
-
+        OsRng.fill_bytes(&mut data[14..22]);
-        if getrandom(&mut data[14..22]).is_err() {
-            error!("failed getting randomness for authentication");
-            return Err(Error::RandomnessError);
-        }
 
         let mut challenge = [0u8; 8];
         challenge.copy_from_slice(&data[14..22]);
 
-        let authentication = APDU::new(Ins::Authenticate)
+        let authentication = Apdu::new(Ins::Authenticate)
             .params(ALGO_3DES, KEY_CARDMGM)
             .data(&data)
             .transmit(&txn, 261)?;
@@ -322,12 +328,18 @@ impl YubiKey {
         Ok(())
     }
 
-    /// Deauthenticate
+    /// Get the PIV keys contained in this YubiKey.
+    pub fn piv_keys(&mut self) -> Result<Vec<piv::Key>> {
+        piv::Key::list(self)
+    }
+
+    /// Deauthenticate.
     #[cfg(feature = "untested")]
-    pub fn deauthenticate(&mut self) -> Result<(), Error> {
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
+    pub fn deauthenticate(&mut self) -> Result<()> {
         let txn = self.begin_transaction()?;
 
-        let status_words = APDU::new(Ins::SelectApplication)
+        let status_words = Apdu::new(Ins::SelectApplication)
             .p1(0x04)
             .data(MGMT_AID)
             .transmit(&txn, 255)?
@@ -345,7 +357,7 @@ impl YubiKey {
     }
 
     /// Verify device PIN.
-    pub fn verify_pin(&mut self, pin: &[u8]) -> Result<(), Error> {
+    pub fn verify_pin(&mut self, pin: &[u8]) -> Result<()> {
         {
             let txn = self.begin_transaction()?;
             txn.verify_pin(pin)?;
@@ -358,8 +370,8 @@ impl YubiKey {
         Ok(())
     }
 
-    /// Get the number of PIN retries
+    /// Get the number of PIN retries.
-    pub fn get_pin_retries(&mut self) -> Result<u8, Error> {
+    pub fn get_pin_retries(&mut self) -> Result<u8> {
         let txn = self.begin_transaction()?;
 
         // Force a re-select to unverify, because once verified the spec dictates that
@@ -375,9 +387,10 @@ impl YubiKey {
         }
     }
 
-    /// Set the number of PIN retries
+    /// Set the number of PIN retries.
     #[cfg(feature = "untested")]
-    pub fn set_pin_retries(&mut self, pin_tries: u8, puk_tries: u8) -> Result<(), Error> {
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
+    pub fn set_pin_retries(&mut self, pin_tries: u8, puk_tries: u8) -> Result<()> {
         // Special case: if either retry count is 0, it's a successful no-op
         if pin_tries == 0 || puk_tries == 0 {
             return Ok(());
@@ -399,9 +412,10 @@ impl YubiKey {
 
     /// Change the Personal Identification Number (PIN).
     ///
-    /// The default PIN code is 123456
+    /// The default PIN code is `123456`.
     #[cfg(feature = "untested")]
-    pub fn change_pin(&mut self, current_pin: &[u8], new_pin: &[u8]) -> Result<(), Error> {
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
+    pub fn change_pin(&mut self, current_pin: &[u8], new_pin: &[u8]) -> Result<()> {
         {
             let txn = self.begin_transaction()?;
             txn.change_ref(ChangeRefAction::ChangePin, current_pin, new_pin)?;
@@ -414,15 +428,13 @@ impl YubiKey {
         Ok(())
     }
 
-    /// Set PIN last changed
+    /// Set PIN last changed.
     #[cfg(feature = "untested")]
-    pub fn set_pin_last_changed(yubikey: &mut YubiKey) -> Result<(), Error> {
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
-        let mut data = [0u8; CB_BUF_MAX];
+    pub fn set_pin_last_changed(yubikey: &mut YubiKey) -> Result<()> {
         let txn = yubikey.begin_transaction()?;
 
-        let buffer = metadata::read(&txn, TAG_ADMIN)?;
+        let mut admin_data = AdminData::read(&txn)?;
-        let mut cb_data = buffer.len();
-        data[..cb_data].copy_from_slice(&buffer);
 
         // TODO(tarcieri): double check this is little endian
         let tnow = SystemTime::now()
@@ -431,19 +443,14 @@ impl YubiKey {
             .as_secs()
             .to_le_bytes();
 
-        metadata::set_item(
+        admin_data
-            &mut data,
+            .set_item(TAG_ADMIN_TIMESTAMP, &tnow)
-            &mut cb_data,
-            CB_OBJ_MAX,
-            TAG_ADMIN_TIMESTAMP,
-            &tnow,
-        )
             .map_err(|e| {
                 error!("could not set pin timestamp, err = {}", e);
                 e
             })?;
 
-        metadata::write(&txn, TAG_ADMIN, &data).map_err(|e| {
+        admin_data.write(&txn).map_err(|e| {
             error!("could not write admin data, err = {}", e);
             e
         })?;
@@ -457,21 +464,23 @@ impl YubiKey {
     ///
     /// The PUK is part of the PIV standard that the YubiKey follows.
     ///
-    /// The default PUK code is 12345678.
+    /// The default PUK code is `12345678`.
     #[cfg(feature = "untested")]
-    pub fn change_puk(&mut self, current_puk: &[u8], new_puk: &[u8]) -> Result<(), Error> {
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
+    pub fn change_puk(&mut self, current_puk: &[u8], new_puk: &[u8]) -> Result<()> {
         let txn = self.begin_transaction()?;
         txn.change_ref(ChangeRefAction::ChangePuk, current_puk, new_puk)
     }
 
-    /// Block PUK: permanently prevent the PIN from becoming unblocked
+    /// Block PUK: permanently prevent the PIN from becoming unblocked.
     #[cfg(feature = "untested")]
-    pub fn block_puk(yubikey: &mut YubiKey) -> Result<(), Error> {
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
+    pub fn block_puk(&mut self) -> Result<()> {
         let mut puk = [0x30, 0x42, 0x41, 0x44, 0x46, 0x30, 0x30, 0x44];
         let mut tries_remaining: i32 = -1;
         let mut flags = [0];
 
-        let txn = yubikey.begin_transaction()?;
+        let txn = self.begin_transaction()?;
 
         while tries_remaining != 0 {
             // 2 -> change puk
@@ -494,8 +503,10 @@ impl YubiKey {
             }
         }
 
-        if let Ok(data) = metadata::read(&txn, TAG_ADMIN) {
+        // Attempt to set the "PUK blocked" flag in admin data.
-            if let Ok(item) = metadata::get_item(&data, TAG_ADMIN_FLAGS_1) {
+        let mut admin_data = AdminData::read(&txn)
+            .map(|data| {
+                if let Ok(item) = data.get_item(TAG_ADMIN_FLAGS_1) {
                     if item.len() == flags.len() {
                         flags.copy_from_slice(item)
                     } else {
@@ -506,22 +517,15 @@ impl YubiKey {
                         );
                     }
                 }
-        }
+
+                data
+            })
+            .unwrap_or_default();
 
         flags[0] |= ADMIN_FLAGS_1_PUK_BLOCKED;
-        let mut data = [0u8; CB_BUF_MAX];
-        let mut cb_data: usize = data.len();
 
-        if metadata::set_item(
+        if admin_data.set_item(TAG_ADMIN_FLAGS_1, &flags).is_ok() {
-            &mut data,
+            if admin_data.write(&txn).is_err() {
-            &mut cb_data,
-            CB_OBJ_MAX,
-            TAG_ADMIN_FLAGS_1,
-            &flags,
-        )
-        .is_ok()
-        {
-            if metadata::write(&txn, TAG_ADMIN, &data[..cb_data]).is_err() {
                 error!("could not write admin metadata");
             }
         } else {
@@ -534,31 +538,35 @@ impl YubiKey {
     /// Unblock a Personal Identification Number (PIN) using a previously
     /// configured PIN Unblocking Key (PUK).
     #[cfg(feature = "untested")]
-    pub fn unblock_pin(&mut self, puk: &[u8], new_pin: &[u8]) -> Result<(), Error> {
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
+    pub fn unblock_pin(&mut self, puk: &[u8], new_pin: &[u8]) -> Result<()> {
         let txn = self.begin_transaction()?;
         txn.change_ref(ChangeRefAction::UnblockPin, puk, new_pin)
     }
 
-    /// Fetch an object from the YubiKey
+    /// Fetch an object from the YubiKey.
     #[cfg(feature = "untested")]
-    pub fn fetch_object(&mut self, object_id: ObjectId) -> Result<Buffer, Error> {
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
+    pub fn fetch_object(&mut self, object_id: ObjectId) -> Result<Buffer> {
         let txn = self.begin_transaction()?;
         txn.fetch_object(object_id)
     }
 
-    /// Save an object
+    /// Save an object.
     #[cfg(feature = "untested")]
-    pub fn save_object(&mut self, object_id: ObjectId, indata: &mut [u8]) -> Result<(), Error> {
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
+    pub fn save_object(&mut self, object_id: ObjectId, indata: &mut [u8]) -> Result<()> {
         let txn = self.begin_transaction()?;
         txn.save_object(object_id, indata)
     }
 
-    /// Get an auth challenge
+    /// Get an auth challenge.
     #[cfg(feature = "untested")]
-    pub fn get_auth_challenge(&mut self) -> Result<[u8; 8], Error> {
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
+    pub fn get_auth_challenge(&mut self) -> Result<[u8; 8]> {
         let txn = self.begin_transaction()?;
 
-        let response = APDU::new(Ins::Authenticate)
+        let response = Apdu::new(Ins::Authenticate)
             .params(ALGO_3DES, KEY_CARDMGM)
             .data(&[0x7c, 0x02, 0x81, 0x00])
             .transmit(&txn, 261)?;
@@ -570,9 +578,10 @@ impl YubiKey {
         Ok(response.data()[4..12].try_into().unwrap())
     }
 
-    /// Verify an auth response
+    /// Verify an auth response.
     #[cfg(feature = "untested")]
-    pub fn verify_auth_response(&mut self, response: [u8; 8]) -> Result<(), Error> {
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
+    pub fn verify_auth_response(&mut self, response: [u8; 8]) -> Result<()> {
         let mut data = [0u8; 12];
         data[0] = 0x7c;
         data[1] = 0x0a;
@@ -583,7 +592,7 @@ impl YubiKey {
         let txn = self.begin_transaction()?;
 
         // send the response to the card and a challenge of our own.
-        let status_words = APDU::new(Ins::Authenticate)
+        let status_words = Apdu::new(Ins::Authenticate)
             .params(ALGO_3DES, KEY_CARDMGM)
             .data(&data)
             .transmit(&txn, 261)?
@@ -602,7 +611,8 @@ impl YubiKey {
     ///
     /// The reset function is only available when both pins are blocked.
     #[cfg(feature = "untested")]
-    pub fn reset_device(&mut self) -> Result<(), Error> {
+    #[cfg_attr(docsrs, doc(cfg(feature = "untested")))]
+    pub fn reset_device(&mut self) -> Result<()> {
         let templ = [0, Ins::Reset.code(), 0, 0];
         let txn = self.begin_transaction()?;
         let status_words = txn.transfer_data(&templ, &[], 255)?.status_words();
@@ -618,7 +628,7 @@ impl YubiKey {
 impl<'a> TryFrom<&'a Reader<'_>> for YubiKey {
     type Error = Error;
 
-    fn try_from(reader: &'a Reader<'_>) -> Result<Self, Error> {
+    fn try_from(reader: &'a Reader<'_>) -> Result<Self> {
         let mut card = reader.connect().map_err(|e| {
             error!("error connecting to reader '{}': {}", reader.name(), e);
             e

tests/integration.rs

@@ -3,19 +3,17 @@
 #![forbid(unsafe_code)]
 #![warn(missing_docs, rust_2018_idioms, trivial_casts, unused_qualifications)]
 
-use getrandom::getrandom;
 use lazy_static::lazy_static;
 use log::trace;
+use rand_core::{OsRng, RngCore};
 use rsa::{hash::Hash::SHA2_256, PaddingScheme, PublicKey};
 use sha2::{Digest, Sha256};
-use std::convert::TryInto;
 use std::{env, sync::Mutex};
 use x509::RelativeDistinguishedName;
-use yubikey_piv::{
+use yubikey::{
     certificate::{Certificate, PublicKeyInfo},
-    key::{self, AlgorithmId, Key, RetiredSlotId, SlotId},
+    piv::{self, AlgorithmId, Key, RetiredSlotId, SlotId},
-    policy::{PinPolicy, TouchPolicy},
+    Error, MgmKey, PinPolicy, TouchPolicy, YubiKey,
-    Error, MgmKey, YubiKey,
 };
 
 lazy_static! {
@@ -107,6 +105,42 @@ fn test_verify_pin() {
     assert!(yubikey.verify_pin(b"123456").is_ok());
 }
 
+//
+// Management key support
+//
+
+#[cfg(feature = "untested")]
+#[test]
+#[ignore]
+fn test_set_mgmkey() {
+    let mut yubikey = YUBIKEY.lock().unwrap();
+
+    assert!(yubikey.verify_pin(b"123456").is_ok());
+    assert!(MgmKey::get_protected(&mut yubikey).is_err());
+    assert!(yubikey.authenticate(MgmKey::default()).is_ok());
+
+    // Set a protected management key.
+    assert!(MgmKey::generate().set_protected(&mut yubikey).is_ok());
+    let protected = MgmKey::get_protected(&mut yubikey).unwrap();
+    assert!(yubikey.authenticate(MgmKey::default()).is_err());
+    assert!(yubikey.authenticate(protected.clone()).is_ok());
+
+    // Set a manual management key.
+    let manual = MgmKey::generate();
+    assert!(manual.set_manual(&mut yubikey, false).is_ok());
+    assert!(MgmKey::get_protected(&mut yubikey).is_err());
+    assert!(yubikey.authenticate(MgmKey::default()).is_err());
+    assert!(yubikey.authenticate(protected.clone()).is_err());
+    assert!(yubikey.authenticate(manual.clone()).is_ok());
+
+    // Set back to the default management key.
+    assert!(MgmKey::set_default(&mut yubikey).is_ok());
+    assert!(MgmKey::get_protected(&mut yubikey).is_err());
+    assert!(yubikey.authenticate(protected).is_err());
+    assert!(yubikey.authenticate(manual).is_err());
+    assert!(yubikey.authenticate(MgmKey::default()).is_ok());
+}
+
 //
 // Certificate support
 //
@@ -120,7 +154,7 @@ fn generate_self_signed_cert(algorithm: AlgorithmId) -> Certificate {
     let slot = SlotId::Retired(RetiredSlotId::R1);
 
     // Generate a new key in the selected slot.
-    let generated = key::generate(
+    let generated = piv::generate(
         &mut yubikey,
         slot,
         algorithm,
@@ -130,7 +164,7 @@ fn generate_self_signed_cert(algorithm: AlgorithmId) -> Certificate {
     .unwrap();
 
     let mut serial = [0u8; 20];
-    getrandom(&mut serial).unwrap();
+    OsRng.fill_bytes(&mut serial);
 
     // Generate a self-signed certificate for the new key.
     let extensions: &[x509::Extension<'_, &[u64]>] = &[];
@@ -201,9 +235,42 @@ fn generate_self_signed_ec_cert() {
     let sig_algo_len = data[7 + tbs_cert_len + 1] as usize;
     let sig_start = 7 + tbs_cert_len + 2 + sig_algo_len + 3;
     let msg = &data[4..7 + tbs_cert_len];
-    let sig = &data[sig_start..];
+    let sig = p256::ecdsa::Signature::from_der(&data[sig_start..]).unwrap();
+    let vk = p256::ecdsa::VerifyingKey::from_sec1_bytes(pubkey.as_bytes()).unwrap();
 
-    use ring::signature::{UnparsedPublicKey, ECDSA_P256_SHA256_ASN1};
+    use p256::ecdsa::signature::Verifier;
-    let ring_pk = UnparsedPublicKey::new(&ECDSA_P256_SHA256_ASN1, pubkey.as_bytes());
+    assert!(vk.verify(msg, &sig).is_ok());
-    assert!(ring_pk.verify(msg, sig).is_ok());
+}
+
+#[test]
+#[ignore]
+fn test_slot_id_display() {
+    assert_eq!(format!("{}", SlotId::Authentication), "Authentication");
+    assert_eq!(format!("{}", SlotId::Signature), "Signature");
+    assert_eq!(format!("{}", SlotId::KeyManagement), "KeyManagement");
+    assert_eq!(
+        format!("{}", SlotId::CardAuthentication),
+        "CardAuthentication"
+    );
+    assert_eq!(format!("{}", SlotId::Attestation), "Attestation");
+    assert_eq!(format!("{}", SlotId::Retired(RetiredSlotId::R1)), "R1");
+    assert_eq!(format!("{}", SlotId::Retired(RetiredSlotId::R2)), "R2");
+    assert_eq!(format!("{}", SlotId::Retired(RetiredSlotId::R3)), "R3");
+    assert_eq!(format!("{}", SlotId::Retired(RetiredSlotId::R4)), "R4");
+    assert_eq!(format!("{}", SlotId::Retired(RetiredSlotId::R5)), "R5");
+    assert_eq!(format!("{}", SlotId::Retired(RetiredSlotId::R6)), "R6");
+    assert_eq!(format!("{}", SlotId::Retired(RetiredSlotId::R7)), "R7");
+    assert_eq!(format!("{}", SlotId::Retired(RetiredSlotId::R8)), "R8");
+    assert_eq!(format!("{}", SlotId::Retired(RetiredSlotId::R9)), "R9");
+    assert_eq!(format!("{}", SlotId::Retired(RetiredSlotId::R10)), "R10");
+    assert_eq!(format!("{}", SlotId::Retired(RetiredSlotId::R11)), "R11");
+    assert_eq!(format!("{}", SlotId::Retired(RetiredSlotId::R12)), "R12");
+    assert_eq!(format!("{}", SlotId::Retired(RetiredSlotId::R13)), "R13");
+    assert_eq!(format!("{}", SlotId::Retired(RetiredSlotId::R14)), "R14");
+    assert_eq!(format!("{}", SlotId::Retired(RetiredSlotId::R15)), "R15");
+    assert_eq!(format!("{}", SlotId::Retired(RetiredSlotId::R16)), "R16");
+    assert_eq!(format!("{}", SlotId::Retired(RetiredSlotId::R17)), "R17");
+    assert_eq!(format!("{}", SlotId::Retired(RetiredSlotId::R18)), "R18");
+    assert_eq!(format!("{}", SlotId::Retired(RetiredSlotId::R19)), "R19");
+    assert_eq!(format!("{}", SlotId::Retired(RetiredSlotId::R20)), "R20");
 }