This crate transforms sets of OpenPGP certificates into https://codeberg.org/heiko/wot-network/ representation, for use in Web of Trust calculations.

Status

⚠️ This crate is in an early development stage! Use with caution.

NOTE: Third-party direct key signatures are not yet supported (no delegation edges are produced for them)!

Forming an OpenPGP WoT network

A WoT network graph is formed from a set of OpenPGP certificates. WoT network formation is a particular kind of normalization of OpenPGP certificate data, geared towards efficient WoT path searches.

To form a WoT network, validity of all relevant elements (certificates, identities, certifications and delegations) is determined at a given reference time. A WoT network graph represents a snapshot of the OpenPGP artifacts at that point in time.

Specifically, the output of network formation in this crate is a wot-network::Network data structure.

After network formation, a separate subsystem can perform lookups on the abstract Network representation. Such a path search subsystem does not need to be aware of any OpenPGP specifics.

For more context, see https://codeberg.org/openpgp/wot/.

WoT network formation in this crate

This crate forms a WoT network graph from a set of OpenPGP certificates as follows:

• Parse OpenPGP certificate data. Note that certificate data includes certificates and identities, as well as certifying signatures (including both self-signatures and third party signatures)
• Evaluate validity of relevant components (that is: certificates as a whole, and individual User IDs) at the reference time, and drop all invalid components from consideration
• Consider the most recent valid certifying self signature for each User ID that is in effect at the reference time
  • Generate a certification edge for any valid certifying self-signature
• Consider the most recent valid third party certification by each issuer and for each target (including both certifications on User IDs and direct key signatures)
  • For each valid third-party certification over a User ID, produce a certification edge
  • For each valid third-party certification over a User ID, or certifying direct key signature, that has a "trust signature" subpacket with depth > 0, generate a delegation edge. (Delegation edges include the "trust amount" and "trust depth" value from the trust signature. They also include "regex" subpacket settings, if those are encoded in the third-party signature.)

The notion of "validity" here encompasses:

• OpenPGP semantics, such as revocation and expiration (of both certificates as a whole, and User IDs specifically)
• A policy (which may cause an implementation to reject signatures or keys, e.g. because of weak algorithms)
• For all relevant signatures: Cryptographic validity of the signature

This crate relies on the rpgpie crate for OpenPGP semantics and policy.

Use as library

This crate is mainly intended for use as a library.

The most convenient entrypoint is wot_network_rpgpie::from_file(path: &Path, reference_time: DateTime<Utc>) -> Network, which loads a certificate ring from a file and produces a Network at the reference time.

CLI tool

Alternatively, for easy exploratory use of the library, the CLI tool (wnr) is provided. Note, however that this CLI tool uses simple output formats, which are a helpful for inspecting simple test networks, but not appropriate for representing complex, general OpenPGP data!

A certificate file can be exported in the "simple text" WoT network format (also see wot_network::util::simple_text):

$ wnr export <certs>

Additionally, a certificate name mapping can be applied via

$ wnr export <certs> --map <mapping>

Mermaid WoT network graphs can be generated analogously, with the graph command:

$ wnr graph <certs>

Producing certificate sets for testing

See wot-observatory for a tool that generates certificate sets based on a configuration file that describes a set of OpenPGP certificates and certifying signatures.