voa_openpgp/

lookup.rs

//! Helper functionality to find appropriate [`SignatureVerifier`]s from a set of [`OpenpgpCert`].

use std::collections::HashMap;

use log::{debug, trace, warn};
use pgp::{
    packet::Signature,
    types::{Fingerprint, KeyDetails, KeyId},
};
use rpgpie::certificate::SignatureVerifier;

use crate::{OpenpgpCert, OpenpgpSignature};

/// Helper to efficiently look up [`OpenpgpCert`]s by [`Fingerprint`] or by [`KeyId`].
///
/// This struct keeps a lookup entry by the [`Fingerprint`] and [`KeyId`] of *each* component key
/// of each indexed [`OpenpgpCert`] (including ones that don't have the data signing key flag, and
/// invalid ones).
///
/// As a consequence, the resulting lookup configuration doesn't make any semantical guarantees
/// about lookup results, beyond that one component key bears the queried [`Fingerprint`] or
/// [`KeyId`].
///
/// Downstream users must thus perform additional checks if a certificate is actually
/// appropriate to use for a particular purpose.
#[derive(Debug)]
struct CertLookup<'a> {
    by_fingerprint: HashMap<Fingerprint, Vec<&'a OpenpgpCert>>,
    by_key_id: HashMap<KeyId, Vec<&'a OpenpgpCert>>,
}

impl<'a> From<&'a [OpenpgpCert]> for CertLookup<'a> {
    fn from(certs: &'a [OpenpgpCert]) -> Self {
        let mut lookup = Self {
            by_fingerprint: HashMap::new(),
            by_key_id: HashMap::new(),
        };

        // Insert lookup entries for the Fingerprint and KeyId of each component key of each cert
        certs.iter().for_each(|cert| lookup.insert_cert(cert));

        lookup
    }
}

impl<'a> CertLookup<'a> {
    /// Inserts an entry for the [`Fingerprint`] and [`KeyId`] of _each_ component key of an
    /// [`OpenpgpCert`].
    fn insert_cert(&mut self, cert: &'a OpenpgpCert) {
        let primary = &cert.certificate.as_signed_public_key().primary_key;
        self.insert_by_fingerprint(cert, primary.fingerprint());
        self.insert_by_key_id(cert, primary.key_id());

        for subkey in &cert.certificate.as_signed_public_key().public_subkeys {
            self.insert_by_fingerprint(cert, subkey.fingerprint());
            self.insert_by_key_id(cert, subkey.key_id());
        }
    }

    /// Inserts a lookup entry for an [`OpenpgpCert`] and an accompanying [`Fingerprint`].
    fn insert_by_fingerprint(&mut self, cert: &'a OpenpgpCert, fingerprint: Fingerprint) {
        self.by_fingerprint
            .entry(fingerprint)
            .or_default()
            .push(cert);
    }

    /// Inserts a lookup entry for an [`OpenpgpCert`] and an accompanying [`KeyId`].
    fn insert_by_key_id(&mut self, cert: &'a OpenpgpCert, key_id: KeyId) {
        self.by_key_id.entry(key_id).or_default().push(cert);
    }

    /// Returns a list of [`OpenpgpCert`]s that match a provided [`Fingerprint`].
    pub(crate) fn by_fingerprint(&self, fingerprint: &Fingerprint) -> &[&'a OpenpgpCert] {
        self.by_fingerprint
            .get(fingerprint)
            .map_or(&[], |cert| cert)
    }

    /// Returns a list of [`OpenpgpCert`]s that match a provided [`KeyId`].
    pub(crate) fn by_key_id(&self, key_id: &KeyId) -> &[&'a OpenpgpCert] {
        self.by_key_id.get(key_id).map_or(&[], |cert| cert)
    }
}

/// An abstraction over a set of [`OpenpgpCert`], to facilitate signature verification.
///
/// It can efficiently look up component keys that are appropriate for attempting validation of
/// specific signatures.
#[derive(Debug)]
pub struct VerifierLookup<'a> {
    index: CertLookup<'a>,
}

impl<'a> VerifierLookup<'a> {
    /// Creates a new [`VerifierLookup`] from a list of [`OpenpgpCert`]s.
    pub fn new(certs: &'a [OpenpgpCert]) -> Self {
        Self {
            index: certs.into(),
        }
    }

    /// Returns a list of [`SignatureVerifier`] and [`OpenpgpCert`] tuples, that are reasonable
    /// candidates for attempting to verify an [`OpenpgpSignature`].
    ///
    /// Looks up all component keys that match the [IssuerFingerprint] and/or [Issuer] subpackets in
    /// `signature`, and returns them as [`SignatureVerifier`] objects.
    /// For informational purposes, each [`SignatureVerifier`] is accompanied by a reference to the
    /// [`OpenpgpCert`] that contains it.
    ///
    /// Callers of this function will usually want to validate `signature` with the returned
    /// [`SignatureVerifier`]s.
    ///
    /// [IssuerFingerprint]: https://www.rfc-editor.org/rfc/rfc9580.html#issuer-fingerprint-subpacket
    /// [Issuer]: https://www.rfc-editor.org/rfc/rfc9580.html#name-issuer-key-id
    pub(crate) fn get_matching_verifiers(
        &self,
        signature: &OpenpgpSignature,
    ) -> Vec<(SignatureVerifier, &'a OpenpgpCert)> {
        let Some(created) = signature.creation_time() else {
            warn!("Skipping signature without creation time");
            return Vec::new();
        };

        let mut verifiers = Vec::new();

        // Iterate over all candidate certificates that contain component keys that match
        // an issuer identity that `signature` lists.
        for cert in self.candidate_certs(&signature.detached.signature) {
            // OpenPGP semantics: enumerate all component keys that are valid for data signing
            // purposes at the creation time of this signature.
            for verifier in cert
                .certificate
                .valid_signing_capable_component_keys_at(&created.into())
            {
                // This set of valid component keys may contain some that do not match the issuer
                // hints in the signature.
                // Here, we filter the valid verifiers by the signature's issuer hints again.
                if Self::matches_issuer(signature, &verifier) {
                    verifiers.push((verifier, cert))
                }
            }
        }

        debug!(
            "get_matching_verifiers for {:?}: {}",
            &signature.source,
            verifiers
                .iter()
                .map(|(verifier, cert)| format!(
                    "{}/{}",
                    verifier.as_componentkey().fingerprint(),
                    cert.fingerprint()
                ))
                .collect::<Vec<_>>()
                .join(", ")
        );

        verifiers
    }

    /// Returns a list of [`OpenpgpCert`]s that match either the
    /// [IssuerFingerprint] or [Issuer] subpackets in a [`Signature`].
    ///
    /// All component keys of each [`OpenpgpCert`] are considered when matching against the
    /// [IssuerFingerprint] and [Issuer] subpackets of the `signature`. The returned
    /// [`OpenpgpCert`]s are deduplicated by their primary [`Fingerprint`].
    ///
    /// ## Note
    ///
    /// The lookup does not enforce any semantics constraints. It does not guarantee
    /// validity of certificates or component keys for any particular purpose. Semantics checks
    /// must be performed separately, after this lookup.
    ///
    /// [IssuerFingerprint]: https://www.rfc-editor.org/rfc/rfc9580.html#issuer-fingerprint-subpacket
    /// [Issuer]: https://www.rfc-editor.org/rfc/rfc9580.html#name-issuer-key-id
    fn candidate_certs(&self, signature: &Signature) -> Vec<&'a OpenpgpCert> {
        let mut candidates = HashMap::new();

        // Try to find the signer by Issuer Fingerprint subpacket
        for fp in signature.issuer_fingerprint() {
            for &cert in self.index.by_fingerprint(fp) {
                candidates.insert(cert.fingerprint(), cert);
            }
        }

        // Try to find the signer by Issuer KeyId subpacket
        for key_id in signature.issuer() {
            for &cert in self.index.by_key_id(key_id) {
                candidates.insert(cert.fingerprint(), cert);
            }
        }

        trace!(
            "candidate_certs for {signature:#?}: {:?}",
            candidates.keys().cloned().collect::<Vec<_>>().join(", ")
        );

        candidates.into_values().collect()
    }

    /// Checks if a [`SignatureVerifier`] matches any [IssuerFingerprint] or [Issuer] subpacket in
    /// an [`OpenpgpSignature`].
    ///
    /// [IssuerFingerprint]: https://www.rfc-editor.org/rfc/rfc9580.html#issuer-fingerprint-subpacket
    /// [Issuer]: https://www.rfc-editor.org/rfc/rfc9580.html#name-issuer-key-id
    fn matches_issuer(signature: &OpenpgpSignature, verifier: &SignatureVerifier) -> bool {
        let issuer_fingerprint = signature.detached.signature.issuer_fingerprint();
        let issuer_key_id = signature.detached.signature.issuer();

        issuer_fingerprint.contains(&&verifier.as_componentkey().fingerprint())
            || issuer_key_id.contains(&&verifier.as_componentkey().key_id())
    }
}