Struct openpgp_card_sequoia::Card

pub struct Card<S>
where
    S: State,
{ /* private fields */ }

Representation of an OpenPGP card.

A card transitions between States by starting a transaction (that groups together a number of operations into an atomic sequence) and via PIN presentation.

Depending on the State of the card, and the access privileges that are associated with that state, different operations can be performed. In many cases, client software will want to transition between states while performing one workflow for the user.

Implementations

impl Card<Open>

pub fn open_by_ident( cards: impl Iterator<Item = Result<Box<dyn CardBackend + Send + Sync>, SmartcardError>>, ident: &str ) -> Result<Self, Error>

Takes an iterator over CardBackends, tries to SELECT the OpenPGP card application on each of them, and checks if its application id matches ident. Returns a Card<Open> for the first match, if any.

pub fn new<B>(backend: B) -> Result<Self, Error>

where B: Into<Box<dyn CardBackend + Send + Sync>>,

Returns a Card<Open> based on backend (after SELECTing the OpenPGP card application).

pub fn transaction(&mut self) -> Result<Card<Transaction<'_>>, Error>

Starts a transaction on the underlying backend (if the backend implementation supports transactions, otherwise the backend will operate without transaction guarantees).

The resulting Card<Transaction> object allows performing operations on the card.

pub fn into_backend(self) -> Box<dyn CardBackend + Send + Sync>

Retrieve the underlying CardBackend.

This is useful to take the card object into a different context (e.g. to perform operations on the card with the yubikey-management crate, without closing the connection to the card).

impl<'a> Card<Transaction<'a>>

pub fn reload_ard(&mut self) -> Result<(), Error>

Replace cached “application related data” in this instance of Open with the current data on the card.

This is needed e.g. after importing or generating keys on a card, to see these changes reflected in the internal cached openpgp_card::card_do::ApplicationRelatedData.

pub fn feature_pinpad_verify(&mut self) -> bool

True if the reader for this card supports PIN verification with a pin pad.

pub fn feature_pinpad_modify(&mut self) -> bool

True if the reader for this card supports PIN modification with a pin pad.

pub fn verify_user_pin(&mut self, pin: &str) -> Result<(), Error>

Verify the User PIN (for operations such as decryption)

pub fn verify_user_pinpad( &mut self, pinpad_prompt: &dyn Fn() ) -> Result<(), Error>

Verify the User PIN with a physical PIN pad (if available, see Self::feature_pinpad_verify).

pub fn verify_user_signing_pin(&mut self, pin: &str) -> Result<(), Error>

Verify the User PIN for signing operations.

(Note that depending on the configuration of the card, this may enable performing just one signing operation, or an unlimited amount of signing operations).

pub fn verify_user_signing_pinpad( &mut self, pinpad_prompt: &dyn Fn() ) -> Result<(), Error>

Verify the User PIN for signing operations with a physical PIN pad (if available, see Self::feature_pinpad_verify).

pub fn verify_admin_pin(&mut self, pin: &str) -> Result<(), Error>

Verify the Admin PIN.

pub fn verify_admin_pinpad( &mut self, pinpad_prompt: &dyn Fn() ) -> Result<(), Error>

Verify the Admin PIN with a physical PIN pad (if available, see Self::feature_pinpad_verify).

pub fn check_user_verified(&mut self) -> Result<(), Error>

Ask the card if the user password has been successfully verified.

NOTE: on some cards this functionality seems broken and may decrease the pin’s error count!

pub fn check_admin_verified(&mut self) -> Result<(), Error>

Ask the card if the admin password has been successfully verified.

NOTE: on some cards this functionality seems broken and may decrease the pin’s error count!

pub fn change_user_pin(&mut self, old: &str, new: &str) -> Result<(), Error>

Change the User PIN, based on the old User PIN.

pub fn change_user_pin_pinpad( &mut self, pinpad_prompt: &dyn Fn() ) -> Result<(), Error>

Change the User PIN, based on the old User PIN, with a physical PIN pad (if available, see Self::feature_pinpad_modify).

pub fn reset_user_pin(&mut self, rst: &str, new: &str) -> Result<(), Error>

Change the User PIN, based on the resetting code rst.

pub fn change_admin_pin(&mut self, old: &str, new: &str) -> Result<(), Error>

Change the Admin PIN, based on the old Admin PIN.

pub fn change_admin_pin_pinpad( &mut self, pinpad_prompt: &dyn Fn() ) -> Result<(), Error>

Change the Admin PIN, based on the old Admin PIN, with a physical PIN pad (if available, see Self::feature_pinpad_modify).

pub fn to_user_card<'b, 'p, P>( &'b mut self, pin: P ) -> Result<Card<User<'a, 'b>>, Error>

where P: Into<OptionalPin<'p>>,

Get a view of the card in the Card<User> state, and authenticate for that state with pin, if available.

If pin is not None, verify_user is called with that pin.

pub fn to_signing_card<'b, 'p, P>( &'b mut self, pin: P ) -> Result<Card<Sign<'a, 'b>>, Error>

where P: Into<OptionalPin<'p>>,

Get a view of the card in the Card<Sign> state, and authenticate for that state with pin, if available.

If pin is not None, verify_user_for_signing is called with that pin.

pub fn to_admin_card<'b, 'p, P>( &'b mut self, pin: P ) -> Result<Card<Admin<'a, 'b>>, Error>

where P: Into<OptionalPin<'p>>,

Get a view of the card in the Card<Admin> state, and authenticate for that state with pin, if available.

If pin is not None, verify_admin is called with that pin.

pub fn application_identifier(&self) -> Result<ApplicationIdentifier, Error>

The Application Identifier is unique for each card. It includes a manufacturer code and serial number.

(This is an immutable field on the card. The value is cached in the underlying Card object. It can be retrieved without incurring a call to the card)

pub fn extended_capabilities(&self) -> Result<ExtendedCapabilities, Error>

The “Extended Capabilities” data object describes features of a card to the caller. This includes the availability and length of various data fields.

(This is an immutable field on the card. The value is cached in the underlying Card object. It can be retrieved without incurring a call to the card)

pub fn historical_bytes(&self) -> Result<HistoricalBytes, Error>

The “Historical Bytes” data object describes features of a card to the caller. The information in this field is probably not relevant for most users of this library, however, some of it is used for the internal operation of the openpgp-card library.

(This is an immutable field on the card. The value is cached in the underlying Card object. It can be retrieved without incurring a call to the card)

pub fn extended_length_information( &self ) -> Result<Option<ExtendedLengthInfo>, Error>

The “Extended Length Information” data object was introduced in version 3.0 of the OpenPGP card standard.

The information in this field should not be relevant for users of this library. However, it is used for the internal operation of the openpgp-card library.

(This is an immutable field on the card. The value is cached in the underlying Card object. It can be retrieved without incurring a call to the card)

pub fn pw_status_bytes(&self) -> Result<PWStatusBytes, Error>

PW Status Bytes

pub fn algorithm_attributes( &self, key_type: KeyType ) -> Result<AlgorithmAttributes, Error>

Get algorithm attributes for a key slot.

pub fn fingerprints(&self) -> Result<KeySet<Fingerprint>, Error>

Get the Fingerprints for the three basic KeyTypes.

(The fingerprints for the three basic key slots are stored in a shared field on the card, thus they can be retrieved in one go)

pub fn fingerprint( &mut self, key_type: KeyType ) -> Result<Option<Fingerprint>, Error>

Get the Fingerprint for one KeyType.

This function allows retrieval for all slots, including KeyType::Attestation, if available.

pub fn key_generation_times(&self) -> Result<KeySet<KeyGenerationTime>, Error>

Get the Key Creation Times for the three basic KeyTypes.

(The creation time for the three basic key slots are stored in a shared field on the card, thus they can be retrieved in one go)

pub fn key_generation_time( &mut self, key_type: KeyType ) -> Result<Option<KeyGenerationTime>, Error>

Get the Key Creation Time for one KeyType.

This function allows retrieval for all slots, including KeyType::Attestation, if available.

pub fn key_information(&self) -> Result<Option<KeyInformation>, Error>

pub fn user_interaction_flag( &self, key_type: KeyType ) -> Result<Option<UserInteractionFlag>, Error>

Get the UserInteractionFlag for a key slot. This includes the TouchPolicy, if the card supports touch confirmation.

pub fn ca_fingerprints(&self) -> Result<[Option<Fingerprint>; 3], Error>

List of CA-Fingerprints of “Ultimately Trusted Keys”. May be used to verify Public Keys from servers.

pub fn private_use_do(&mut self, num: u8) -> Result<Vec<u8>, Error>

Get optional “Private use” data from the card.

The presence and maximum length of these DOs is announced in ExtendedCapabilities.

If available, there are 4 data fields for private use:

• 1: read accessible without PIN verification
• 2: read accessible without PIN verification
• 3: read accessible with User PIN verification
• 4: read accessible with Admin PIN verification

pub fn login_data(&mut self) -> Result<Vec<u8>, Error>

Login Data

This DO can be used to store any information used for the Log-In process in a client/server authentication (e.g. user name of a network). The maximum length of this DO is announced in Extended Capabilities.

pub fn url(&mut self) -> Result<String, Error>

Get “cardholder” URL from the card.

“The URL should contain a link to a set of public keys in OpenPGP format, related to the card.”

pub fn cardholder_related_data( &mut self ) -> Result<CardholderRelatedData, Error>

Cardholder related data (contains the fields: Name, Language preferences and Sex)

pub fn cardholder_name(&mut self) -> Result<String, Error>

Get cardholder name.

This is an ISO 8859-1 (Latin 1) String of up to 39 characters.

Note that the standard specifies that this field should be encoded according to ISO/IEC 7501-1:

“The data element consists of surname (e. g. family name and given name(s)) and forename(s) (including name suffix, e. g., Jr. and number). Each item is separated by a ´<´ filler character (3C), the family- and fore-name(s) are separated by two ´<<´ filler characters.”

This library doesn’t perform this encoding.

pub fn digital_signature_count(&mut self) -> Result<u32, Error>

Get the current digital signature count (how many signatures have been issued by the card)

pub fn select_data(&mut self, num: u8, tag: &[u8]) -> Result<(), Error>

SELECT DATA (“select a DO in the current template”).

pub fn cardholder_certificate(&mut self) -> Result<Vec<u8>, Error>

Get cardholder certificate.

Call select_data() before calling this fn to select a particular certificate (if the card supports multiple certificates).

pub fn next_cardholder_certificate(&mut self) -> Result<Vec<u8>, Error>

“GET NEXT DATA” for the DO cardholder certificate.

Cardholder certificate data for multiple slots can be read from the card by first calling cardholder_certificate(), followed by up to two calls to next_cardholder_certificate().

pub fn kdf_do(&mut self) -> Result<KdfDo, Error>

Get KDF DO configuration (from cache).

pub fn algorithm_information( &mut self ) -> Result<Option<AlgorithmInformation>, Error>

Algorithm Information (list of supported Algorithm attributes).

pub fn manage_security_environment( &mut self, for_operation: KeyType, key_ref: KeyType ) -> Result<(), Error>

“MANAGE SECURITY ENVIRONMENT”. Make key_ref usable for the operation normally done by the key designated by for_operation

pub fn attestation_certificate(&mut self) -> Result<Vec<u8>, Error>

Get “Attestation Certificate (Yubico)”

pub fn firmware_version(&mut self) -> Result<Vec<u8>, Error>

Firmware Version, YubiKey specific (?)

pub fn set_identity(&mut self, id: u8) -> Result<(), Error>

Set “identity”, Nitrokey Start specific (possible values: 0, 1, 2). https://docs.nitrokey.com/start/windows/multiple-identities.html

A Nitrokey Start can present as 3 different virtual OpenPGP cards. This command enables one of those virtual cards.

Each virtual card identity behaves like a separate, independent OpenPGP card.

pub fn public_key_material( &mut self, key_type: KeyType ) -> Result<PublicKeyMaterial, Error>

Get the raw public key material for a key slot on the card (also see Self::public_key for getting a Sequoia PGP key object)

pub fn public_key(&mut self, kt: KeyType) -> Result<Option<PublicKey>, Error>

Get a sequoia public key representation (Key<key::PublicParts, key::UnspecifiedRole>) for a key slot on the card

pub fn factory_reset(&mut self) -> Result<(), Error>

Reset all state on this OpenPGP card

impl<'app, 'open> Card<User<'app, 'open>>

pub fn decryptor( &mut self, touch_prompt: &'open (dyn Fn() + Send + Sync) ) -> Result<CardDecryptor<'_, 'app>, Error>

pub fn decryptor_from_public( &mut self, pubkey: PublicKey, touch_prompt: &'open (dyn Fn() + Send + Sync) ) -> CardDecryptor<'_, 'app>

pub fn authenticator( &mut self, touch_prompt: &'open (dyn Fn() + Send + Sync) ) -> Result<CardSigner<'_, 'app>, Error>

pub fn authenticator_from_public( &mut self, pubkey: PublicKey, touch_prompt: &'open (dyn Fn() + Send + Sync) ) -> CardSigner<'_, 'app>

pub fn set_private_use_do( &mut self, num: u8, data: Vec<u8> ) -> Result<(), Error>

Set optional “Private use” data on the card.

The presence and maximum length of these DOs is announced in ExtendedCapabilities.

If available, there are 4 data fields for private use:

• 1: write accessible with User PIN verification
• 2: write accessible with Admin PIN verification
• 3: write accessible with User PIN verification
• 4: write accessible with Admin PIN verification

impl<'app, 'open> Card<Sign<'app, 'open>>

pub fn signer( &mut self, touch_prompt: &'open (dyn Fn() + Send + Sync) ) -> Result<CardSigner<'_, 'app>, Error>

pub fn signer_from_public( &mut self, pubkey: PublicKey, touch_prompt: &'open (dyn Fn() + Send + Sync) ) -> CardSigner<'_, 'app>

pub fn generate_attestation( &mut self, key_type: KeyType, touch_prompt: &'open (dyn Fn() + Send + Sync) ) -> Result<(), Error>

Generate Attestation (Yubico)

impl<'app, 'open> Card<Admin<'app, 'open>>

pub fn as_transaction(&mut self) -> &mut Card<Transaction<'app>>

impl Card<Admin<'_, '_>>

pub fn set_cardholder_name(&mut self, name: &str) -> Result<(), Error>

Set cardholder name.

This is an ISO 8859-1 (Latin 1) String of max. 39 characters.

Note that the standard specifies that this field should be encoded according to ISO/IEC 7501-1:

“The data element consists of surname (e. g. family name and given name(s)) and forename(s) (including name suffix, e. g., Jr. and number). Each item is separated by a ´<´ filler character (3C), the family- and fore-name(s) are separated by two ´<<´ filler characters.”

This library doesn’t perform this encoding.

pub fn set_lang(&mut self, lang: &[Lang]) -> Result<(), Error>

pub fn set_sex(&mut self, sex: Sex) -> Result<(), Error>

pub fn set_private_use_do( &mut self, num: u8, data: Vec<u8> ) -> Result<(), Error>

Set optional “Private use” data on the card.

The presence and maximum length of these DOs is announced in ExtendedCapabilities.

If available, there are 4 data fields for private use:

• 1: write accessible with User PIN verification
• 2: write accessible with Admin PIN verification
• 3: write accessible with User PIN verification
• 4: write accessible with Admin PIN verification

pub fn set_login_data(&mut self, login_data: &[u8]) -> Result<(), Error>

pub fn set_url(&mut self, url: &str) -> Result<(), Error>

Set “cardholder” URL on the card.

“The URL should contain a link to a set of public keys in OpenPGP format, related to the card.”

pub fn set_pw_status_bytes( &mut self, pw_status: &PWStatusBytes, long: bool ) -> Result<(), Error>

Set PW Status Bytes.

According to the spec, length information should not be changed.

If long is false, sends 1 byte to the card, otherwise 4.

So, effectively, with long == false the setting pw1_cds_multi can be changed. With long == true, the settings pw1_pin_block and pw3_pin_block can also be changed.

pub fn set_user_pin_signing_validity(&mut self, once: bool) -> Result<(), Error>

Configure the “only valid for one PSO:CDS” setting in PW Status Bytes.

If once is true, the User PIN must be verified before each signing operation on the card. If once is false, one User PIN verification is good for an unlimited number of signing operations.

pub fn set_touch_policy( &mut self, key: KeyType, policy: TouchPolicy ) -> Result<(), Error>

Set the touch policy for a key slot (if the card supports this feature).

Note that the current touch policy setting (if available) can be read via Card<Transaction>::user_interaction_flag.

pub fn reset_user_pin(&mut self, new: &str) -> Result<(), Error>

Set the User PIN on the card (also resets the User PIN error count)

pub fn set_resetting_code(&mut self, pin: &str) -> Result<(), Error>

Define the “resetting code” on the card

pub fn set_pso_enc_dec_key(&mut self, key: &[u8]) -> Result<(), Error>

Set optional AES encryption/decryption key (32 bytes for AES256, or 16 bytes for AES128), if the card supports this feature.

The availability of this feature is announced in Card<Transaction>::extended_capabilities.

pub fn upload_key( &mut self, vka: ValidErasedKeyAmalgamation<'_, SecretParts>, key_type: KeyType, password: Option<String> ) -> Result<(), Error>

Upload a Sequoia PGP ValidErasedKeyAmalgamation to the card into a specific key slot.

(The caller needs to make sure that vka is suitable as key_type)

pub fn set_algorithm( &mut self, key_type: KeyType, algo: AlgoSimple ) -> Result<(), Error>

Configure the algorithm_attributes for key slot key_type based on the algorithm algo. This can be useful in preparation for Self::generate_key.

This is a convenience wrapper for Self::set_algorithm_attributes that determines the exact appropriate AlgorithmAttributes by reading information from the card.

pub fn set_algorithm_attributes( &mut self, key_type: KeyType, algorithm_attributes: &AlgorithmAttributes ) -> Result<(), Error>

Configure the key slot key_type to algorithm_attributes. This can be useful in preparation for Self::generate_key.

Note that legal values for AlgorithmAttributes are card-specific. Different OpenPGP card implementations may support different algorithms, sometimes with differing requirements for the encoding (e.g. field sizes)

See Self::set_algorithm for a convenience function that sets the algorithm attributes based on an AlgoSimple.

pub fn generate_key( &mut self, key_type: KeyType ) -> Result<(PublicKeyMaterial, KeyGenerationTime), Error>

Generate a new cryptographic key in slot key_type, with the currently configured cryptographic algorithm (see Self::set_algorithm for changing the algorithm setting).