Module destructured

Source

Expand description

Import of destructured OpenPGP certificates as VOA verifiers.

Destructured OpenPGP certificates are represented by (binary or ASCII-armored) OpenPGP packet data in separate files.

§Note

Destructured OpenPGP certificates are a non-standardized format.

§Formats

This module allows reading OpenPGP certificates from the following set of directory structures.

§Flat structure

A flat structure can be created by splitting an OpenPGP certificate using specialised tooling such as rpacket:

rpacket split < cert.pgp

This may create output similar to the following:

.
├── 000000-PublicKey
├── 000001-UserId
├── 000002-Signature
├── 000003-Signature
├── 000004-Signature
├── 000005-Signature
├── 000006-Signature
├── 000007-Signature
├── 000008-Signature
├── 000009-Signature
├── 000010-PublicSubkey
├── 000011-Signature
├── 000012-PublicSubkey
├── 000013-Signature
├── 000014-PublicSubkey
└── 000015-Signature

Here, each file contains raw OpenPGP packet data. The concatenation of all files in sequence represents a valid OpenPGP certificate, e.g.

cat 0000* > cert-concant.pgp

§Arch Linux keyring structure

The archlinux-keyring project chose a more fine grained approach, that is based on a custom directory structure. Here, files containing raw ASCII-armored OpenPGP packet data are grouped by their specific use in an OpenPGP certificate.

A single top-level file contains the primary component key, named after its OpenPGP fingerprint (e.g. F1D2D2F924E986AC86FDF7B36C94BCDF32BEEC15.asc).

The following directories are used to group specific OpenPGP packet data:

revocation: If it exists, contains a file containing Key Revocation Signature data, named after the OpenPGP fingerprint of the primary component key (e.g. revocation/F1D2D2F924E986AC86FDF7B36C94BCDF32BEEC15.asc).
directkey: If it exists, contains a directory structure in which files containing Direct Key Signature data reside. Individual files are located in a directory that reflects the OpenPGP fingerprint of the targeted component key and are named after their specific creation time (e.g. directkey/certification/F1D2D2F924E986AC86FDF7B36C94BCDF32BEEC15/2024-06-23_12-55-20.asc)
uid: If it exists, contains a directory structure for each User ID or User Attribute packet of the certificate. Here, User IDs are represented by directories named after their string representation, with unusable characters replaced and an additional unique identifier appended to prevent collision (e.g. John Doe <jdoe@example.org> -> uid/John_Doe__jdoe@example.org_d2ad250f). Each User ID directory contains a top-level file, which represents the User ID packet (e.g. uid/John_Doe__jdoe@example.org_d2ad250f/John_Doe__jdoe@example.org_d2ad250f.asc). Further, each such directory contains a certification and may contain a revocation directory. The certification directory may contain User ID binding signatures and third-party certifications (e.g. uid/John_Doe__jdoe@example.org_d2ad250f/certification/ F1D2D2F924E986AC86FDF7B36C94BCDF32BEEC15.asc). The revocation directory may contain User ID revocation signatures or third-party certification revocation signatures (e.g. uid/John_Doe__jdoe@example.org_d2ad250f/revocation/ F1D2D2F924E986AC86FDF7B36C94BCDF32BEEC15.asc).
subkey: If it exists, contains a directory structure for each subkey component key bound to the primary component key of the certificate. A top-level directory is named after the OpenPGP fingerprint of the component key (e.g. subkey/E242ED3BFFCCDF271B7FBAF34ED72D089537B42F/). Each top-level directory contains a file containing Public Subkey data (e.g. subkey/E242ED3BFFCCDF271B7FBAF34ED72D089537B42F/E242ED3BFFCCDF271B7FBAF34ED72D089537B42F. asc). Further, each such directory contains a certification and may contain a revocation directory. The certification directory contains files containing Subkey Binding Signature data, named after the OpenPGP fingerprint of the issuing key (e.g. subkey/E242ED3BFFCCDF271B7FBAF34ED72D089537B42F/certification/ F1D2D2F924E986AC86FDF7B36C94BCDF32BEEC15.asc). The revocation directory may contain files containing Subkey Revocation Signature data, named after the OpenPGP fingerprint of the issuing key (e.g. subkey/E242ED3BFFCCDF271B7FBAF34ED72D089537B42F/revocation/ F1D2D2F924E986AC86FDF7B36C94BCDF32BEEC15.asc).

The following example illustrates a destructured OpenPGP certificate using the archlinux-keyring specific directory format:

.
├── F1D2D2F924E986AC86FDF7B36C94BCDF32BEEC15.asc
├── subkey
│   ├── E242ED3BFFCCDF271B7FBAF34ED72D089537B42F
│   │   ├── E242ED3BFFCCDF271B7FBAF34ED72D089537B42F.asc
│   │   └── certification
│   │       └── F1D2D2F924E986AC86FDF7B36C94BCDF32BEEC15.asc
│   ├── D3B0F7C0B825ECBB0F0D7398072947E7B1537B6F
│   │   ├── D3B0F7C0B825ECBB0F0D7398072947E7B1537B6F.asc
│   │   └── certification
│   │       └── F1D2D2F924E986AC86FDF7B36C94BCDF32BEEC15.asc
│   └── 6EADEAC2DADE6347E87C0D24FD455FEFFA7069F0
│       ├── 6EADEAC2DADE6347E87C0D24FD455FEFFA7069F0.asc
│       └── certification
│           └── F1D2D2F924E986AC86FDF7B36C94BCDF32BEEC15.asc
└── uid
    └── John_Doe__jdoe@example.org_d2ad250f
        ├── John_Doe__jdoe@example.org_d2ad250f.asc
        └── certification
            ├── B787A81C32997FD39A5F4C0188363902D3586E7B.asc
            ├── 2072A695613E5103D9AC03C2885C5E2656CB5FF0.asc
            ├── 68D61AF364B99AD0226A9C8859F18BF95A99BCE9.asc
            ├── 033DB9A2637803F63BDA651106B2C4BEF184C21D.asc
            ├── 868672B9CDB0BF449BF3782CFDA1DBE372838AA3.asc
            ├── F1D2D2F924E986AC86FDF7B36C94BCDF32BEEC15.asc
            ├── 98EECC29ABC53C31B0DA5C85CB26CE720C7FF763.asc
            └── 52428846EFFD79371A81D6C82D00FBFED9C654F3.asc

Modules§

error: Error handling for importing destructured OpenPGP certificates as VOA verifiers.

Structs§

ComponentDir 🔒: The representation of a component directory.
DirectKeyCertificationDir 🔒: The representation of a direct key certification directory.

Constants§

CERTIFICATION_DIR 🔒: The name of a directory used for OpenPGP packets that serve as certification.
DIRECTKEY_DIR 🔒: The name of a directory used for OpenPGP packets that serve as direct key signatures.
REVOCATION_DIR 🔒: The name of a directory used for OpenPGP packets that serve as revocation.
SUBKEY_DIR 🔒: The name of a directory containing directory structures with OpenPGP packet files for subkeys.
UID_DIR 🔒: The name of a directory containing directory structures with OpenPGP packet files for User IDs.

Functions§

collect_files_in_dir 🔒: Collects all regular files in a directory in the order of an OpenPGP Transferable Public Key.
component_dirs_from_dir 🔒: Creates a list of component directories from a directory.
dir_entry 🔒: Maps a std::io::Error for a DirEntry to a crate::Error.
direct_key_certification_dirs_from_dir 🔒: Creates a list of direct key certification directories from a directory.
files_in_dir 🔒: Collects all regular files in a directory path.
load_from_dir: Creates an OpenPgpImport from a directory containing OpenPGP packet files.
parse_packet_from_reader 🔒: Recognizes a single OpenPGP packet in a reader.
path_metadata 🔒: Retrieves Metadata for a path and maps std::io::Error to crate::Error.
read_dir 🔒: Reads a directory path.
read_packet_from_file 🔒: Reads a single OpenPGP packet from a file.
signed_public_key_from_dir 🔒: Creates a single [SignedPublicKey] from regular files in a directory.