Struct Oca

pub struct Oca { /* private fields */ }

An initialized OpenPGP CA instance, with a configured backend. Oca exposes the main functionality of OpenPGP CA.

Implementations

impl Oca

pub fn open(db_url: Option<&str>) -> Result<Self>

Open an initialized Oca instance.

The SQLite backend filename can be configured:

• explicitly via the db_url parameter, or
• the environment variable OPENPGP_CA_DB.

pub fn domainname(&self) -> &str

pub fn set_card_backend(self, card_ident: &str, user_pin: &str) -> Result<()>

Change which card backs an OpenPGP CA instance (e.g. to switch to a replacement for a broken card).

pub fn ca_generate_revocations(&self, output: PathBuf) -> Result<()>

Generate revocations for the CA key, write to output file.

pub fn ca_import_tsig(&self, cert: &[u8]) -> Result<()>

Ingest/merge in any new tsigs for our CA certificate from ‘cert’

pub fn ca_get_cert_pub(&self) -> Result<Cert>

Get current CA certificate from storage. This representation of the CA cert includes user certifications.

Get from database storage, if possible - the cert will then contain all certifications we know of. However, on split-mode backends, we don’t rely on storage, unless we get a readonly copy of the online CA. In this case, the CA certificate may lack some or all certifications.

pub fn ca_get_pubkey_armored(&self) -> Result<String>

Returns the public key of the CA as an armored String (see Self::ca_get_cert_pub).

pub fn get_ca_email(&self) -> Result<String>

Get the email of this CA

pub fn ca_show(&self) -> Result<()>

Print information about the Ca to stdout.

This shows the domainname, fingerprint and creation time of this OpenPGP CA instance.

pub fn ca_print_private(&self) -> Result<()>

Print private key of the Ca to stdout.

This operation is only supported for Softkey and SplitBack+Softkey instances.

pub fn ca_re_certify( &self, ca_cert_old: &[u8], validity_days: u64, ) -> Result<()>

Find all User IDs that have been certified by ca_cert_old and re-certify them with the current CA key.

This can be useful after CA key rotation: when the CA has a new key, ca_re_certify issues fresh certifications for all previously CA-certified user certs.

pub fn ca_split_into(self, front: &Path, back: &Path) -> Result<()>

Split a CA instance into a pair of “front” and “back” CA instances.

This operation is currently supported for softkey or card-backed CAs.

pub fn ca_merge_split(self, back: &Path) -> Result<()>

Merge a back CA into a front CA instance, resulting in a regular (“non-split”) CA.

pub fn ca_split_export(&self, file: PathBuf) -> Result<()>

Export certification requests for the backing CA in a simple human-readable output format (inspired by https://github.com/wiktor-k/airsigner/, but with some adjustments!).

The output file is a tar-archive:

• The archive contains a top-level file “csr.txt”, which lists User IDs that should be certified.
• Current versions of all certs are provided in the tar in armored format, as individual files “certs/”.

One design goal of this format is to make it easy to implement small (and thus more easily auditable) certification services, which may use arbitrary underlying mechanisms (and/or PGP implementations) for signing.

pub fn ca_split_certify( &self, import: PathBuf, export: PathBuf, batch: bool, ) -> Result<()>

Process certification requests in a SplitBack instance

When “batch” is false, this fn is interactive.

In interactive mode, it reads KeyEvents for user feedback about certification operations.

pub fn ca_split_import(&self, file: PathBuf) -> Result<()>

Ingest the certifications that were generated by the split backend

pub fn ca_split_show_queue(&self) -> Result<()>

Show the currently not done entries in the queue of a split mode front instance

pub fn user_certs_get_all(&self) -> Result<Vec<Cert>>

Get a list of all User Certs

pub fn certs_expired( &self, days: u64, ) -> Result<HashMap<Cert, Option<SystemTime>>>

Which certs will be expired in ‘days’ days?

If a cert is not “alive” now, it will not get returned as expiring (otherwise old/abandoned certs would clutter the results)

pub fn cert_check_ca_sig(&self, cert: &Cert) -> Result<CertificationStatus>

Check if this Cert has been certified by the CA Key, returns all certified User IDs

pub fn cert_check_tsig_on_ca(&self, cert: &Cert) -> Result<bool>

Check if this Cert has tsigned the CA Key

pub fn check_tsig_on_bridge(&self, bridge: &Bridge) -> Result<bool>

Check if this CA has tsigned the bridge cert

pub fn certs_refresh_ca_certifications( &self, threshold_days: u64, validity_days: u64, ) -> Result<()>

Check all Certs for certifications from the CA. If a certification expires in less than threshold_days and it is not marked as ‘inactive’, make a new certification that is good for validity_days and update the Cert.

pub fn user_new( &self, name: Option<&str>, emails: &[&str], duration_days: Option<u64>, password: bool, password_file: Option<String>, output_format_minimal: bool, cipher_suite: Option<CipherSuite>, enable_encryption_subkey: bool, enable_signing_subkey: bool, enable_authentication_subkey: bool, ) -> Result<()>

Create a new OpenPGP CA User. (“Centralized key creation workflow”)

This generates a fresh OpenPGP key for the new User. The private key is printed to stdout and NOT stored in OpenPGP CA. The public key material (Cert) is stored in the OpenPGP CA database.

The CA Cert is trust-signed by this new user key and the user Cert is certified by the CA.

pub fn cert_import_new( &self, cert: &[u8], revoc_certs: &[&[u8]], name: Option<&str>, emails: &[&str], duration_days: Option<u64>, ) -> Result<()>

Import an existing OpenPGP Cert (public key) as a new OpenPGP CA user.

The cert parameter accepts the user’s armored public key.

User IDs that correspond to emails will be signed by the CA.

A symbolic name and a list of emails for this User can optionally be supplied. If those are not set, emails are taken from the list of User IDs in the public key. If the key has exactly one User ID, the symbolic name is taken from that User ID.

Optionally, revocation certificates can be supplied for storage in OpenPGP CA.

pub fn cert_import_update(&self, cert: &[u8]) -> Result<()>

Update existing Cert in database (e.g. if the user has extended the expiry date)

pub fn cert_delist(&self, fp: &str) -> Result<()>

Mark a cert as “delisted” in the OpenPGP CA database. As a result, the cert will not be exported to WKD anymore.

Note: existing CA certifications will still get renewed for delisted certs, but as the cert is not published via WKD, third parties might not learn about refreshed certifications.

CAUTION: This method is probably rarely appropriate. In most cases, it’s better to “deactivate” a cert (in almost all cases, it is best to continually serve the latest version of a cert to third parties, so they can learn about e.g. revocations on the cert)

pub fn cert_deactivate(&self, fp: &str) -> Result<()>

Mark a certificate as “deactivated”. It will continue to be listed and exported to WKD. However, the certification by our CA will expire and not get renewed.

This approach is probably appropriate in most cases to phase out a certificate.

pub fn cert_get_by_fingerprint(&self, fingerprint: &str) -> Result<Option<Cert>>

Get Cert by fingerprint.

The fingerprint parameter is normalized (e.g. if it contains spaces, they will be filtered out).

pub fn get_certs_by_user(&self, user: &User) -> Result<Vec<Cert>>

Get a list of all Certs for one User

pub fn users_get_all(&self) -> Result<Vec<User>>

Get a list of all Users, ordered by name

pub fn certs_by_email(&self, email: &str) -> Result<Vec<Cert>>

Get a list of the Certs that are associated with email

pub fn cert_get_users(&self, cert: &Cert) -> Result<Option<User>>

Get database User(s) for database Cert

pub fn cert_get_name(&self, cert: &Cert) -> Result<String>

Get the user name that is associated with this Cert.

The name is only for display purposes, it is set to “” if no name can be found, or to “” if the Cert is associated with more than one User.

pub fn print_certifications_status(&self) -> Result<()>

pub fn print_expiry_status(&self, exp_days: u64) -> Result<()>

pub fn print_users(&self) -> Result<()>

pub fn revocations_get(&self, cert: &Cert) -> Result<Vec<Revocation>>

Get a list of all Revocations for a cert

pub fn revocation_add(&self, revoc_cert: &[u8]) -> Result<()>

Add a revocation certificate to the OpenPGP CA database.

The matching cert is looked up by issuer Fingerprint, if possible - or by exhaustive search otherwise.

Verifies that applying the revocation cert can be validated by the cert. Only if this is successful is the revocation stored.

pub fn revocation_add_from_file(&self, filename: &Path) -> Result<()>

Add a revocation certificate to the OpenPGP CA database (from a file).

pub fn revocation_get_by_hash(&self, hash: &str) -> Result<Revocation>

Get a Revocation by hash

pub fn revocation_apply(&self, revoc: Revocation) -> Result<()>

Apply a revocation.

The revocation is merged into out copy of the OpenPGP Cert.

pub fn revocation_details( revocation: &Revocation, ) -> Result<(String, Option<SystemTime>)>

Get reason and creation time for a Revocation

pub fn revoc_to_armored(sig: &Signature) -> Result<String>

Get an armored representation of a revocation certificate

pub fn print_revocations(&self, email: &str) -> Result<()>

pub fn emails_get(&self, cert: &Cert) -> Result<Vec<CertEmail>>

Get all Emails for a Cert

pub fn get_emails_all(&self) -> Result<Vec<CertEmail>>

Get all Emails

pub fn bridges_get(&self) -> Result<Vec<Bridge>>

Get a list of Bridges

pub fn bridges_search(&self, email: &str) -> Result<Bridge>

Get a specific Bridge

pub fn bridge_get_cert(&self, bridge: &Bridge) -> Result<Cert>

Get the Cert row for a Bridge

pub fn add_bridge( &self, email: Option<&str>, key_file: &Path, scope: Option<&str>, unscoped: bool, ) -> Result<(String, String)>

pub fn bridge_revoke(&self, email: &str) -> Result<()>

Create a revocation Certificate for a Bridge and apply it the our copy of the remote CA’s public key.

Both the revoked remote public key and the revocation cert are printed to stdout.

pub fn print_bridges(&self, email: Option<String>) -> Result<()>

pub fn list_bridges(&self) -> Result<()>

pub fn export_wkd(&self, domain: &str, path: &Path) -> Result<()>

Export all user keys (that have a userid in domain) and the CA key into a wkd directory structure

https://tools.ietf.org/html/draft-koch-openpgp-webkey-service-08

pub fn export_keylist( &self, path: PathBuf, signature_uri: String, force: bool, ) -> Result<()>

Export the contents of a CA in Keylist format.

https://code.firstlook.media/keylist-rfc-explainer

path: filesystem path into which the exported keylist and signature files will be written.

signature_uri: the https address from which the signature file will be retrievable

force: by default, this fn fails if the files exist; when force is true, overwrite.

pub fn export_certs_as_files( &self, email_filter: Option<String>, path: &str, ) -> Result<()>

Export Certs from this CA into files, with filenames based on email addresses of user ids.

pub fn print_certring(&self, email_filter: Option<String>) -> Result<()>

pub fn update_from_wkd(&self) -> Result<()>

Pull updates for all certs from WKD and merge them into our local storage.

pub fn update_from_keyserver(&self) -> Result<()>

Update all certs from the hagrid keyserver (https://keys.openpgp.org/) and merge any updates into our local storage for this cert.