turnkey/openpgp-card
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

openpgp-card: rustdoc

Browse source
This commit is contained in:
Heiko Schaefer 2023-08-29 16:05:08 +02:00
parent ff1afee7c5
commit 2b0111b923
No known key found for this signature in database
GPG key ID: 4A849A1904CCBD7D
4 changed files with 47 additions and 35 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
openpgp-card/src/algorithm.rs
View file

@ -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

19
openpgp-card/src/card_do.rs
View file

@ -77,11 +77,13 @@ impl ApplicationRelatedData {
#[allow(dead_code)]
fn general_feature_management() -> Option<bool> {
// FIXME
unimplemented!()
}
#[allow(dead_code)]
fn discretionary_data_objects() {
// FIXME
unimplemented!()
}
@ -423,7 +425,8 @@ impl From<u8> 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<u8> 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 <https://en.wikipedia.org/wiki/ISO/IEC_5218>
#[derive(Debug, PartialEq, Eq, Clone, Copy)]
@ -868,9 +872,8 @@ impl From<u8> 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 <https://en.wikipedia.org/wiki/ISO_639-1>
#[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]);

8
openpgp-card/src/card_do/extended_cap.rs
View file

@ -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<u16> {
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<u16> {
self.max_resp_len
}

50
openpgp-card/src/lib.rs
View file

@ -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<dyn CardBackend + Send + Sync>,
/// Capabilites of the card, determined from hints by the Backend,
/// as well as the Application Related Data
card_caps: Option<CardCaps>,
}
@ -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<Transaction, Error> {
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