Enum Fingerprint

#[non_exhaustive]pub enum Fingerprint {
    V6([u8; 32]),
    V4([u8; 20]),
    Unknown {
        version: Option<u8>,
        bytes: Box<[u8]>,
    },
}

Expand description

A key’s fingerprint, as the crates that do not use Sequoia themselves name it. A long identifier for certificates and keys.

A Fingerprint uniquely identifies a public key.

Currently, Sequoia supports version 6 fingerprints and Key IDs, and version 4 fingerprints and Key IDs. Version 3 fingerprints and Key IDs were deprecated by RFC 4880 in 2007.

Essentially, a fingerprint is a hash over the key’s public key packet. For details, see Section 5.5.4 of RFC 9580.

Fingerprints are used, for example, to reference the issuing key of a signature in its IssuerFingerprint subpacket. As a general rule of thumb, you should prefer using fingerprints over KeyIDs because the latter are vulnerable to birthday attacks.

§Examples

use openpgp::Fingerprint;

let fp: Fingerprint =
    "0123 4567 89AB CDEF 0123 4567 89AB CDEF 0123 4567".parse()?;

assert_eq!("0123456789ABCDEF0123456789ABCDEF01234567", fp.to_hex());

Variants (Non-exhaustive)§

This enum is marked as non-exhaustive

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

§

V6([u8; 32])

Fingerprint of v6 certificates and keys.

§

V4([u8; 20])

Fingerprint of v4 certificates and keys.

§

Unknown

Fingerprint of unknown version or shape.

Fields

§version: Option<u8>

Version of the fingerprint, if known.

§bytes: Box<[u8]>

Raw bytes of the fingerprint.

Implementations§

§

impl Fingerprint

pub fn from_bytes(version: u8, raw: &[u8]) -> Result<Fingerprint, Error>

Creates a Fingerprint from a byte slice in big endian representation.

§Examples

use openpgp::Fingerprint;

let fp: Fingerprint =
    "0123 4567 89AB CDEF 0123 4567 89AB CDEF 0123 4567".parse()?;
let bytes =
    [0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF, 0x01, 0x23,
     0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF, 0x01, 0x23, 0x45, 0x67];

assert_eq!(Fingerprint::from_bytes(4, &bytes)?, fp);

pub fn as_bytes(&self) -> &[u8] ⓘ

Returns the raw fingerprint as a byte slice in big endian representation.

§Examples

use openpgp::Fingerprint;

let fp: Fingerprint =
    "0123 4567 89AB CDEF 0123 4567 89AB CDEF 0123 4567".parse()?;

assert_eq!(fp.as_bytes(),
           [0x01, 0x23, 0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF, 0x01, 0x23,
            0x45, 0x67, 0x89, 0xAB, 0xCD, 0xEF, 0x01, 0x23, 0x45, 0x67]);

pub fn to_hex(&self) -> String

Converts this fingerprint to its canonical hexadecimal representation.

This representation is always uppercase and without spaces and is suitable for stable key identifiers.

The output of this function is exactly the same as formatting this object with the :X format specifier.

use openpgp::Fingerprint;

let fp: Fingerprint =
    "0123 4567 89AB CDEF 0123 4567 89AB CDEF 0123 4567".parse()?;

assert_eq!("0123456789ABCDEF0123456789ABCDEF01234567", fp.to_hex());
assert_eq!(format!("{:X}", fp), fp.to_hex());

pub fn to_spaced_hex(&self) -> String

Converts this fingerprint to its hexadecimal representation with spaces.

This representation is always uppercase and with spaces grouping the hexadecimal digits into groups of four with a double space in the middle. It is only suitable for manual comparison of fingerprints.

Note: The spaces will hinder other kind of use cases. For example, it is harder to select the whole fingerprint for copying, and it has to be quoted when used as a command line argument. Only use this form for displaying a fingerprint with the intent of manual comparisons.

pub fn from_hex(s: &str) -> Result<Fingerprint, Error>

Parses the hexadecimal representation of an OpenPGP fingerprint.

This function is the reverse of to_hex. It also accepts other variants of the fingerprint notation including lower-case letters, spaces and optional leading 0x.

use openpgp::Fingerprint;

let fp =
    Fingerprint::from_hex("0123456789ABCDEF0123456789ABCDEF01234567")?;

assert_eq!("0123456789ABCDEF0123456789ABCDEF01234567", fp.to_hex());

let fp =
    Fingerprint::from_hex("0123 4567 89ab cdef 0123 4567 89ab cdef 0123 4567")?;

assert_eq!("0123456789ABCDEF0123456789ABCDEF01234567", fp.to_hex());

pub fn to_icao(&self) -> String

Converts the hex representation of the Fingerprint to a phrase in the ICAO spelling alphabet.

§Examples

use openpgp::Fingerprint;

let fp: Fingerprint =
    "01AB 4567 89AB CDEF 0123 4567 89AB CDEF 0123 4567".parse()?;

assert!(fp.to_icao().starts_with("Zero One Alfa Bravo"));

pub fn aliases<H>(&self, other: H) -> bool
where H: Borrow<KeyHandle>,

Returns whether self and other could be aliases of each other.

KeyHandle’s PartialEq implementation cannot assert that a Fingerprint and a KeyID are equal, because distinct fingerprints may have the same KeyID, and PartialEq must be transitive, i.e.,

a == b and b == c implies a == c.

That is, if fpr1 and fpr2 are distinct fingerprints with the same key ID then:

fpr1 == keyid and fpr2 == keyid, but fpr1 != fpr2.

This definition of equality makes searching for a given KeyHandle using PartialEq awkward. This function fills that gap. It answers the question: given a KeyHandle and a Fingerprint, could they be aliases? That is, it implements the desired, non-transitive equality relation:

// fpr1 and fpr2 are different fingerprints with the same KeyID.
assert_ne!(fpr1, fpr2);
assert!(fpr1.aliases(KeyHandle::from(&keyid)));
assert!(fpr2.aliases(KeyHandle::from(&keyid)));
assert!(! fpr1.aliases(KeyHandle::from(&fpr2)));