Module destructured

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.

Functions

collect_files_in_dir 🔒

Collects all regular files in a directory in the order of an OpenPGP Transferable Public Key.

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.

read_packet_from_file 🔒

Reads a single OpenPGP packet from a file.

recursively_collect_files 🔒

Recursively collects the paths to all regular files in a directory.

signed_public_key_from_dir 🔒

Creates a single [SignedPublicKey] from regular files in a directory.