Struct openpgp_card::Transaction

pub struct Transaction<'a> { /* private fields */ }

To perform commands on a Card, a Transaction must be started. This struct offers low-level access to OpenPGP card functionality.

On backends that support transactions, operations are grouped together in transaction, while an object of this type lives.

A Transaction on typical underlying card subsystems must be short lived. (Typically, smart cards can’t be kept open for longer than a few seconds, before they are automatically closed.)

Implementations

impl<'a> Transaction<'a>

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

Select the OpenPGP card application

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

7.2.16 TERMINATE DF

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

7.2.17 ACTIVATE FILE

pub fn feature_pinpad_verify(&self) -> bool

Does the reader support FEATURE_VERIFY_PIN_DIRECT?

pub fn feature_pinpad_modify(&self) -> bool

Does the reader support FEATURE_MODIFY_PIN_DIRECT?

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

Get the “application related data” from the card.

(This data should probably be cached in a higher layer. Some parts of it are needed regularly, and it does not usually change during normal use of a card.)

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

Application Identifier.

This function returns data that is cached during initialization. Calling it doesn’t require sending a command to the card.

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

Extended capabilities.

This function returns data that is cached during initialization. Calling it doesn’t require sending a command to the card.

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

Historical Bytes (if available).

This function returns data that is cached during initialization. Calling it doesn’t require sending a command to the card.

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

Extended length info (if available).

This function returns data that is cached during initialization. Calling it doesn’t require sending a command to the card.

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

Get URL (5f50)

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

Get Login Data (5e)

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

Get cardholder related data (65)

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

Get security support template (7a)

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

Get cardholder certificate (each for AUT, DEC and SIG).

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

According to the OpenPGP card specification:

The cardholder certificate DOs are designed to store a certificate (e. g. X.509) for the keys in the card. They can be used to identify the card in a client-server authentication, where specific non-OpenPGP-certificates are needed, for S-MIME and other x.509 related functions.

(See https://support.nitrokey.com/t/nitrokey-pro-and-pkcs-11-support-on-linux/160/4 for some discussion of the cardholder certificate OpenPGP card feature)

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

Call “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” (announced in Extended Capabilities)

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

Get “Algorithm Information”

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<Vec<u8>, Error>

Set identity (Nitrokey Start specific (?)). [see: https://docs.nitrokey.com/start/linux/multiple-identities.html https://github.com/Nitrokey/nitrokey-start-firmware/pull/33/]

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

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

This command currently only applies to cardholder_certificate and set_cardholder_certificate in OpenPGP card. (This library leaves it up to consumers to decide on a strategy for dealing with this issue. Possible strategies include:

• asking the card for its Transaction::firmware_version and using the workaround if version <=5.4.3
• trying this command first without the workaround, then with workaround if the card returns StatusBytes::IncorrectParametersCommandDataField
• for read operations: using Transaction::next_cardholder_certificate instead of SELECT DATA)

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

Get data from “private use” DO.

num must be between 1 and 4.

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

Reset all state on this OpenPGP card.

Note: the “factory reset” operation is not directly offered by the card spec. It is implemented as a series of OpenPGP card commands:

• send 4 bad requests to verify pw1,
• send 4 bad requests to verify pw3,
• terminate_df,
• activate_file.

With most cards, this sequence of operations causes the card to revert to a “blank” state.

(However, e.g. vanilla Gnuk doesn’t support this functionality. Gnuk needs to be built with the --enable-factory-reset option to the configure script to enable this functionality).

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

Verify pw1 (user) for signing operation (mode 81).

Depending on the PW1 status byte (see Extended Capabilities) this access condition is only valid for one PSO:CDS command or remains valid for several attempts.

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

Verify pw1 (user) for signing operation (mode 81) using a pinpad on the card reader. If no usable pinpad is found, an error is returned.

Depending on the PW1 status byte (see Extended Capabilities) this access condition is only valid for one PSO:CDS command or remains valid for several attempts.

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

Check the current access of PW1 for signing (mode 81).

If verification is not required, an empty Ok Response is returned.

(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)

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

Verify PW1 (user). (For operations except signing, mode 82).

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

Verify PW1 (user) for operations except signing (mode 82), using a pinpad on the card reader. If no usable pinpad is found, an error is returned.

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

Check the current access of PW1. (For operations except signing, mode 82).

If verification is not required, an empty Ok Response is returned.

(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)

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

Verify PW3 (admin).

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

Verify PW3 (admin) using a pinpad on the card reader. If no usable pinpad is found, an error is returned.

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

Check the current access of PW3 (admin).

If verification is not required, an empty Ok Response is returned.

(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 factory reset the card)

pub fn change_pw1(&mut self, old: &[u8], new: &[u8]) -> Result<(), Error>

Change the value of PW1 (user password).

The current value of PW1 must be presented in old for authorization.

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

Change the value of PW1 (0x81) using a pinpad on the card reader. If no usable pinpad is found, an error is returned.

pub fn change_pw3(&mut self, old: &[u8], new: &[u8]) -> Result<(), Error>

Change the value of PW3 (admin password).

The current value of PW3 must be presented in old for authorization.

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

Change the value of PW3 (admin password) using a pinpad on the card reader. If no usable pinpad is found, an error is returned.

pub fn reset_retry_counter_pw1( &mut self, new_pw1: &[u8], resetting_code: Option<&[u8]> ) -> Result<(), Error>

Reset the error counter for PW1 (user password) and set a new value for PW1.

For authorization, either:

• PW3 must have been verified previously,
• secure messaging must be currently used,
• the resetting_code must be presented.

pub fn decipher(&mut self, dm: Cryptogram<'_>) -> Result<Vec<u8>, Error>

Decrypt the ciphertext in dm, on the card.

(This is a wrapper around the low-level pso_decipher operation, it builds the required data field from dm)

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

Run decryption operation on the smartcard (low level operation) (7.2.11 PSO: DECIPHER)

(consider using the Self::decipher method if you don’t want to create the data field manually)

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

Set the key to be used for the pso_decipher and the internal_authenticate commands.

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 Self::pso_decipher and then sets the Decryption key to be used for Self::internal_authenticate.

tx.manage_security_environment(KeyType::Decryption, KeyType::Authentication)?;
tx.manage_security_environment(KeyType::Authentication, KeyType::Decryption)?;

pub fn signature_for_hash(&mut self, hash: Hash<'_>) -> Result<Vec<u8>, Error>

Sign hash, on the card.

This is a wrapper around the low-level pso_compute_digital_signature operation. It builds the required data field from hash.

For RSA, this means a “DigestInfo” data structure is generated. (see 7.2.10.2 DigestInfo for RSA).

With ECC the hash data is processed as is, using Self::pso_compute_digital_signature.

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

Run signing operation on the smartcard (low level operation) (7.2.10 PSO: COMPUTE DIGITAL SIGNATURE)

(consider using the Self::signature_for_hash method if you don’t want to create the data field manually)

pub fn authenticate_for_hash( &mut self, hash: Hash<'_> ) -> Result<Vec<u8>, Error>

Auth-sign hash, on the card.

This is a wrapper around the low-level internal_authenticate operation. It builds the required data field from hash.

For RSA, this means a “DigestInfo” data structure is generated. (see 7.2.10.2 DigestInfo for RSA).

With ECC the hash data is processed as is.

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

Run signing operation on the smartcard (low level operation) (7.2.13 INTERNAL AUTHENTICATE)

(consider using the authenticate_for_hash() method if you don’t want to create the data field manually)

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

Set data of “private use” DO.

num must be between 1 and 4.

Access condition:

• 1/3 need PW1 (82)
• 2/4 need PW3

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

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

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

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

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

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

Set cardholder certificate (for AUT, DEC or SIG).

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

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

Set algorithm attributes for a key slot (4.4.3.9 Algorithm Attributes)

Note: algorithm_attributes needs to precisely specify the RSA bit-size of e (if applicable), and import format, with values that the current card supports.

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

Set PW Status Bytes.

If long is false, send 1 byte to the card, otherwise 4. According to the spec, length information should not be changed.

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.

(See OpenPGP card spec, pg. 28)

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

pub fn set_ca_fingerprint_1(&mut self, fp: Fingerprint) -> Result<(), Error>

pub fn set_ca_fingerprint_2(&mut self, fp: Fingerprint) -> Result<(), Error>

pub fn set_ca_fingerprint_3(&mut self, fp: Fingerprint) -> Result<(), Error>

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

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

Set resetting code (4.3.4 Resetting Code)

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

Set AES key for symmetric decryption/encryption operations.

Optional DO (announced in Extended Capabilities) for PSO:ENC/DEC with AES (32 bytes dec. in case of AES256, 16 bytes dec. in case of AES128).

pub fn set_uif_pso_cds( &mut self, uif: &UserInteractionFlag ) -> Result<(), Error>

Set UIF for PSO:CDS

pub fn set_uif_pso_dec( &mut self, uif: &UserInteractionFlag ) -> Result<(), Error>

Set UIF for PSO:DEC

pub fn set_uif_pso_aut( &mut self, uif: &UserInteractionFlag ) -> Result<(), Error>

Set UIF for PSO:AUT

pub fn set_uif_attestation( &mut self, uif: &UserInteractionFlag ) -> Result<(), Error>

Set UIF for Attestation key

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

Generate Attestation (Yubico)

pub fn key_import( &mut self, key: Box<dyn CardUploadableKey>, key_type: KeyType ) -> Result<(), Error>

Import an existing private key to the card. (This implicitly sets the algorithm attributes, fingerprint and timestamp)

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

Generate a key on the card. (7.2.14 GENERATE ASYMMETRIC KEY PAIR)

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

Get public key material from the card.

Note: this fn returns a set of raw public key data (not an OpenPGP data structure).

Note also that the information from the card is insufficient to reconstruct a pre-existing OpenPGP public key that corresponds to the private key on the card.