diff --git a/openpgp-card/src/algorithm.rs b/openpgp-card/src/algorithm.rs index 384815a..e9cb9a7 100644 --- a/openpgp-card/src/algorithm.rs +++ b/openpgp-card/src/algorithm.rs @@ -142,7 +142,8 @@ impl AlgoSimple { } } -/// Algorithm Information [Spec section 4.4.3.11] +/// "Algorithm Information" enumerates which algorithms the current card supports +/// [Spec section 4.4.3.11] /// /// Modern OpenPGP cards (starting with version v3.4) provide a list of /// algorithms they support for each key slot. @@ -153,7 +154,7 @@ pub struct AlgorithmInformation(pub(crate) Vec<(KeyType, AlgorithmAttributes)>); /// Algorithm Attributes [Spec section 4.4.3.9] /// -/// An `Algo` describes the algorithm settings for a key on the card. +/// [`AlgorithmAttributes`] describes the algorithm settings for a key on the card. /// /// This setting specifies the data format of: /// - Key import diff --git a/openpgp-card/src/card_do.rs b/openpgp-card/src/card_do.rs index 0e81c64..4aa408c 100644 --- a/openpgp-card/src/card_do.rs +++ b/openpgp-card/src/card_do.rs @@ -77,11 +77,13 @@ impl ApplicationRelatedData { #[allow(dead_code)] fn general_feature_management() -> Option { + // FIXME unimplemented!() } #[allow(dead_code)] fn discretionary_data_objects() { + // FIXME unimplemented!() } @@ -423,7 +425,8 @@ impl From for TouchPolicy { } } -/// "additional hardware for user interaction" [Spec section 4.1.3.2] +/// Features of "additional hardware for user interaction" [Spec section 4.1.3.2]. +/// (Settings for these features are contained in [`UserInteractionFlag`]) pub struct Features(u8); impl From for Features { @@ -551,8 +554,8 @@ impl Display for KeyInformation { } } -/// KeyStatus is contained in `KeyInformation`. It encodes if key material on a card was imported -/// or generated on the card. +/// KeyStatus is contained in [`KeyInformation`]. +/// It encodes if key material on a card was imported or generated on the card. #[derive(Debug, PartialEq, Eq, Clone, Copy)] #[non_exhaustive] pub enum KeyStatus { @@ -820,7 +823,8 @@ impl Display for CardholderRelatedData { } } -/// Sex [Spec section 4.4.3.5] +/// Sex [Spec section 4.4.3.5]. +/// The Sex setting is accessible via [`CardholderRelatedData`]. /// /// Encoded in accordance with #[derive(Debug, PartialEq, Eq, Clone, Copy)] @@ -868,9 +872,8 @@ impl From for Sex { } } -/// Individual language for Language Preferences [Spec section 4.4.3.4] -/// -/// This field is accessible via `CardholderRelatedData`. +/// Individual language for Language Preferences [Spec section 4.4.3.4]. +/// Language preferences are accessible via [`CardholderRelatedData`]. /// /// Encoded according to #[derive(Debug, PartialEq, Eq, Clone, Copy)] @@ -995,7 +998,7 @@ impl PWStatusBytes { } } -/// Fingerprint [Spec page 23] +/// OpenPGP Fingerprint for a key slot [Spec page 23] #[derive(Clone, Eq, PartialEq)] pub struct Fingerprint([u8; 20]); diff --git a/openpgp-card/src/card_do/extended_cap.rs b/openpgp-card/src/card_do/extended_cap.rs index 1a34853..7a1a813 100644 --- a/openpgp-card/src/card_do/extended_cap.rs +++ b/openpgp-card/src/card_do/extended_cap.rs @@ -17,10 +17,18 @@ impl ExtendedCapabilities { self.algo_attrs_changeable } + /// Only available in OpenPGP card version 2.x + /// + /// (For OpenPGP card version 3.x, see + /// [`crate::card_do::ExtendedLengthInfo`]) pub fn max_cmd_len(&self) -> Option { self.max_cmd_len } + /// Only available in OpenPGP card version 2.x + /// + /// (For OpenPGP card version 3.x, see + /// [`crate::card_do::ExtendedLengthInfo`]) pub fn max_resp_len(&self) -> Option { self.max_resp_len } diff --git a/openpgp-card/src/lib.rs b/openpgp-card/src/lib.rs index 93a7184..9d7ed7c 100644 --- a/openpgp-card/src/lib.rs +++ b/openpgp-card/src/lib.rs @@ -3,8 +3,8 @@ //! Client library for //! [OpenPGP card](https://en.wikipedia.org/wiki/OpenPGP_card) -//! devices (such as Gnuk, YubiKey, or Java smartcards running an OpenPGP -//! card application). +//! devices (such as Gnuk, Nitrokey, YubiKey, or Java smartcards running an +//! OpenPGP card application). //! //! This library aims to offer //! - access to all features in the OpenPGP @@ -12,19 +12,17 @@ //! - without relying on a particular //! [OpenPGP implementation](https://www.openpgp.org/software/developer/). //! -//! This library can't directly access cards by itself. Instead, users -//! need to supply a backend that implements the [`card_backend::CardBackend`] -//! / [`card_backend::CardTransaction`] traits. -//! -//! The companion crate -//! [card-backend-pcsc](https://crates.io/crates/card-backend-pcsc) -//! offers a backend that uses [PC/SC](https://en.wikipedia.org/wiki/PC/SC) to -//! communicate with Smart Cards. -//! //! The [openpgp-card-sequoia](https://crates.io/crates/openpgp-card-sequoia) //! crate offers a higher level wrapper based on the [Sequoia PGP](https://sequoia-pgp.org/) //! implementation. //! +//! Note that this library can't directly access cards by itself. +//! Instead, users need to supply a backend that implements the +//! [`CardBackend`] and [`CardTransaction`] traits. +//! For example [card-backend-pcsc](https://crates.io/crates/card-backend-pcsc) +//! offers a backend implementation that uses [PC/SC](https://en.wikipedia.org/wiki/PC/SC) to +//! communicate with Smart Cards. +//! //! See the [architecture diagram](https://gitlab.com/openpgp-card/openpgp-card#architecture) //! for an overview of the ecosystem around this crate. @@ -69,6 +67,7 @@ pub enum KeyType { Decryption, Authentication, + /// Attestation is a Yubico proprietary key slot Attestation, } @@ -120,7 +119,11 @@ impl KeyType { /// Users of this crate can keep a long lived [`Card`] object, including in long running programs. /// All operations must be performed on a [`Transaction`] (which must be short lived). pub struct Card { + /// A connection to the smart card card: Box, + + /// Capabilites of the card, determined from hints by the Backend, + /// as well as the Application Related Data card_caps: Option, } @@ -223,21 +226,18 @@ impl Card { self.card } - /// Get an OpenPgpTransaction object. This starts a transaction on the underlying - /// CardBackend. + /// Start a transaction on the underlying CardBackend. + /// The resulting [Transaction] object allows performing commands on the card. /// - /// Note: transactions on the Card cannot be long running, they will be reset within seconds - /// when idle. - /// - /// If the card has been reset, and `reselect_application` is set, then - /// that application will be `SELECT`ed after starting the transaction. + /// Note: Transactions on the Card cannot be long running. + /// They may be reset by the smart card subsystem within seconds, when idle. pub fn transaction(&mut self) -> Result { let card_caps = &mut self.card_caps; let tx = self.card.transaction(Some(OPENPGP_APPLICATION))?; if tx.was_reset() { - // FIXME - // Signal state invalidation? (PIN verification, ...) + // FIXME: Signal state invalidation to the library user? + // (E.g.: PIN verifications may have been lost.) } Ok(Transaction { tx, card_caps }) @@ -713,7 +713,7 @@ impl<'a> Transaction<'a> { /// (Note: /// - some cards don't correctly implement this feature, e.g. YubiKey 5 /// - some cards that don't support this instruction may decrease the pin's error count, - /// eventually requiring the user to reset the pin) + /// eventually requiring the user to factory reset the card) pub fn check_pw3(&mut self) -> Result<(), Error> { log::info!("OpenPgpTransaction: check_pw3"); @@ -849,8 +849,8 @@ impl<'a> Transaction<'a> { /// Valid until next reset of of the card or the next call to `select` /// The only keys that can be configured by this command are the `Decryption` and `Authentication` keys. /// - /// The following first sets the *Authentication* key to be used for [`Transaction::pso_decipher`] - /// and then sets the *Decryption* key to be used for [`Transaction::internal_authenticate`]. + /// The following first sets the *Authentication* key to be used for [`Self::pso_decipher`] + /// and then sets the *Decryption* key to be used for [`Self::internal_authenticate`]. /// /// ```no_run /// # use openpgp_card::{KeyType, Transaction}; @@ -1253,8 +1253,8 @@ impl<'a> Transaction<'a> { /// Generate a key on the card. /// (7.2.14 GENERATE ASYMMETRIC KEY PAIR) /// - /// This is a wrapper around generate_key() which allows - /// using the simplified `AlgoSimple` algorithm selector enum. + /// This is a wrapper around [`Self::generate_key`] which allows + /// using the simplified [`AlgoSimple`] algorithm selector enum. /// /// Note: AlgoSimple doesn't specify card specific details (such as /// bitsize of e for RSA, and import format). This function determines