Struct CertD

Source

pub struct CertD { /* private fields */ }

Expand description

A certificate store.

This is a handle to an on-disk certificate store that can be used to lookup and insert certificates.

A certificate store contains certificates. Its main role is to hold certificates indexed by their fingerprint. (Note: certificates are not indexed by their subkey fingerprints.) But, it can also store certificates under special names. Currently, the specification defines one special name, trust-root, which holds the user’s local trust root. Non-standard special names are possible. These MUST start with an underscore, which SHOULD be immediately followed by the vendor’s name, e.g., _sequoia_some_special.pgp.

Implementations§

Source §

impl CertD

Source

pub fn new() -> Result<CertD>

Opens the default certificate store.

If not explicitly requested otherwise, an application SHOULD use the default store. To use a store with a different location, use CertD::with_base_dir.

Source

pub fn user_configured_store_path() -> Result<PathBuf>

Returns the location of the user-configured store.

If set, this is the value of the environment variable PGP_CERT_D. Otherwise, it is the default store’s path as returned by CertD::default_store_path.

Source

pub fn default_store_path() -> Result<PathBuf>

Returns the location of the default store.

The location of the default store is platform specific. This returns an error on unsupported platforms.

Source

pub fn with_base_dir<P: AsRef<Path>>(base: P) -> Result<CertD>

Opens a store with an explicit location.

Note: Most applications should use the default store, which is shared. The default store can be opened using CertD::new.

Source

pub fn base_dir(&self) -> &Path

Get the this Certd’s base path.

Source

pub fn tag(&self) -> Tag

Computes the certificate directory’s tag.

Modulo collisions in the hashing algorithm, this tag will change whenever a certificate indexed by its fingerprint is added, updated, or removed. The tag is designed to not change when a certificate indexed by a special name, or some other unrelated data in the certd directory is added, updated, or removed.

The tag should be stable in the sense that you can serialize it to disk, read it in again later, and compare it to the current value. However, how the tag is computed may change. In this case, you may observe a spurious update.

Source

pub fn get_path_by_fingerprint(&self, fingerprint: &str) -> Result<PathBuf>

Turns a fingerprint into a path in the store.

The transformation from a fingerprint to a path is defined by the standard.

Source

pub fn get_path_by_special(&self, special: &str) -> Result<PathBuf>

Turns a special name into a path in the store.

The specification currently defines one special name. Non-standard special names are allowed, but they must MUST start with an underscore, which SHOULD be immediately followed by the vendor’s name, e.g., _sequoia_some_special.pgp. Other names cause this function to return Error::BadName.

Source

pub fn is_special(special: &str) -> Result<()>

Returns whether the special name is valid.

The specification currently defines one special name. Non-standard special names are allowed, but they must MUST start with an underscore, which SHOULD be immediately followed by the vendor’s name, e.g., _sequoia_some_special.pgp. Other names cause this function to return Error::BadName.

Source

pub fn get(&self, name: &str) -> Result<Option<(Tag, Vec<u8>)>>

Looks up a certificate in the store by name, i.e., by fingerprint or by special name.

The specification currently defines one special name. Non-standard special names are allowed, but they must MUST start with an underscore, which SHOULD be immediately followed by the vendor’s name, e.g., _sequoia_some_special.pgp. Other names cause this function to return Error::BadName.

If the certificate exists, this function computes the tag, reads in the certificate data, and returns Ok(Some((tag, cert_data))). See Tag for how the tag can be used to cache lookups.

If the certificate does not exist, this function returns Ok(None).

If an I/O error occurs, or the name was invalid, this function returns an Error.

CertD::get_file is often more efficient if you don’t necessarily need the tag or the file’s contents.

Source

pub fn get_file(&self, name: &str) -> Result<Option<File>>

Looks up a certificate in the store by name, i.e., by fingerprint or by special name.

The specification currently defines one special name. Non-standard special names are allowed, but they must MUST start with an underscore, which SHOULD be immediately followed by the vendor’s name, e.g., _sequoia_some_special.pgp. Other names cause this function to return Error::BadName.

If the certificate exists, this function returns Ok(Some([std::fs::File])). If the certificate does not exist, it returns Ok(None). If an I/O error occurs, or the name was invalid, this function returns an Error.

You can get the file’s Tag by doing: Tag::try_from(&file). See Tag for how the tag can be used to cache lookups.

Source

pub fn get_if_changed( &self, since: Tag, name: &str, ) -> Result<Option<(Tag, Vec<u8>)>>

Conditionally looks up a certificate in the store by an name, i.e. a fingerprint or a special name.

The specification currently defines one special name. Non-standard special names are allowed, but they must MUST start with an underscore, which SHOULD be immediately followed by the vendor’s name, e.g., _sequoia_some_special.pgp. Other names cause this function to return Error::BadName.

If the certificate has changed, i.e., the provided tag does not match the current tag, this function returns Ok(Some((cert, tag))). The tag can be used in subsequent calls to this function.

If the certificate has not changed, i.e., the provided tag matches the current tag, or the certificate does not exist, this function returns Ok(None).

If an I/O error occurs, or the name was invalid, this function returns an Error.

Source

pub fn get_path(&self, name: &str) -> Result<PathBuf>

Get the path to a certificate by fingerprint or special name.

The specification currently defines one special name. Non-standard special names are allowed, but they must MUST start with an underscore, which SHOULD be immediately followed by the vendor’s name, e.g., _sequoia_some_special.pgp. Other names cause this function to return Error::BadName.

Source

pub fn insert<'a, D, M>( &self, fingerprint: &str, data: D, return_inserted: bool, merge: M, ) -> Result<(Tag, Option<Vec<u8>>)>
where M: FnOnce(D, Option<&[u8]>) -> Result<MergeResult<'a>>,

Inserts or updates a cert.

Requires the fingerprint and a callback function. The callback is passed data, and an Option<Vec<u8>>, which contains the existing cert data, if any. The callback is expected to merge the two copies of the certificate together. The returned data is written to the store. Note: The callback may decide to omit (parts of) the existing data, but this should be done with great care as not to lose any vital information.

The new Tag is returned, and if return_inserted is true, the data written to the store is also returned.

This function locks store, which may block the current thread. Use CertD::try_insert to avoid blocking.

Source

pub fn insert_extended<'a, D, PRE, M, POST>( &self, fingerprint: &str, data: D, return_inserted: bool, pre: PRE, merge: M, post: POST, ) -> Result<(Tag, Option<Vec<u8>>)>
where PRE: FnOnce(D) -> Result<D>, M: FnOnce(D, Option<&[u8]>) -> Result<MergeResult<'a>>, POST: FnOnce((Tag, Option<Vec<u8>>)) -> Result<(Tag, Option<Vec<u8>>)>,

Inserts or updates a cert, extended version.

This function is like CertD::insert, but after obtaining the lock on the cert-d, and before doing anything else, it calls pre. Similarly, just before dropping the lock, it calls post.

If the pre callback returns an error, the operation is aborted, and the error is propagated to the caller. The post callback can also transform the result.

The caller can use this functionality to get the cert-d’s tag prior to and after an insert operation, for instance.

Source

pub fn try_insert<'a, D, M>( &self, fingerprint: &str, data: D, return_inserted: bool, merge: M, ) -> Result<(Tag, Option<Vec<u8>>)>
where M: FnOnce(D, Option<&[u8]>) -> Result<MergeResult<'a>>,

Inserts or updates a cert, non-blocking variant.

Requires the fingerprint and a callback function. The callback is passed data, and an Option<Vec<u8>>, which contains the existing cert data, if any. The callback is expected to merge the two copies of the certificate together. The returned data is written to the store. Note: The callback may decide to omit (parts of) the existing data, but this should be done with great care as not to lose any vital information.

The new Tag is returned, and if return_inserted is true, the data written to the store is also returned.

This function attempts to lock the store. If the store is already locked, then it instead returns Error::IoError with an std::io::ErrorKind::WouldBlock.

Source

pub fn try_insert_extended<'a, D, PRE, M, POST>( &self, fingerprint: &str, data: D, return_inserted: bool, pre: PRE, merge: M, post: POST, ) -> Result<(Tag, Option<Vec<u8>>)>
where PRE: FnOnce(D) -> Result<D>, M: FnOnce(D, Option<&[u8]>) -> Result<MergeResult<'a>>, POST: FnOnce((Tag, Option<Vec<u8>>)) -> Result<(Tag, Option<Vec<u8>>)>,

Inserts or updates a cert, extended version.

This function is like CertD::try_insert, but after obtaining the lock on the cert-d, and before doing anything else, it calls pre. Similarly, just before dropping the lock, it calls post.

If the pre callback returns an error, the operation is aborted, and the error is propagated to the caller. The post callback can also transform the result.

The caller can use this functionality to get the cert-d’s tag prior to and after an insert operation, for instance.

Source

pub fn insert_data<'a, M>( &self, data: &'a [u8], return_inserted: bool, merge: M, ) -> Result<(Tag, Option<Vec<u8>>)>
where M: FnOnce(&'a [u8], Option<&[u8]>) -> Result<MergeResult<'a>>,

Inserts or updates a cert.

Requires the new certificate data, and a callback function. The fingerprint is extracted from data. The callback is passed data, and an Option<Vec<u8>>, which contains the existing cert data, if any. The callback is expected to merge the two copies of the certificate together. The returned data is written to the store. Note: The callback may decide to omit (parts of) the existing data, but this should be done with great care as not to lose any vital information.

The new Tag is returned, and if return_inserted is true, the data written to the store is also returned.

This function locks store, which may block the current thread. Use CertD::try_insert_data to avoid blocking.

Source

pub fn insert_data_extended<'a, PRE, M, POST>( &self, data: &'a [u8], return_inserted: bool, pre: PRE, merge: M, post: POST, ) -> Result<(Tag, Option<Vec<u8>>)>
where PRE: FnOnce(&'a [u8]) -> Result<&'a [u8]>, M: FnOnce(&'a [u8], Option<&[u8]>) -> Result<MergeResult<'a>>, POST: FnOnce((Tag, Option<Vec<u8>>)) -> Result<(Tag, Option<Vec<u8>>)>,

Inserts or updates a cert, extended version.

This function is like CertD::insert_data, but after obtaining the lock on the cert-d, and before doing anything else, it calls pre. Similarly, just before dropping the lock, it calls post.

If the pre callback returns an error, the operation is aborted, and the error is propagated to the caller. The post callback can also transform the result.

Source

pub fn try_insert_data<'a, M>( &self, data: &'a [u8], return_inserted: bool, merge: M, ) -> Result<(Tag, Option<Vec<u8>>)>
where M: FnOnce(&'a [u8], Option<&[u8]>) -> Result<MergeResult<'a>>,

Inserts or updates a cert, non-blocking variant.

Requires the new certificate data, and a callback function. The fingerprint is extracted from data. The callback is passed data, and an Option<Vec<u8>>, which contains the existing cert data, if any. The callback is expected to merge the two copies of the certificate together. The returned data is written to the store. Note: The callback may decide to omit (parts of) the existing data, but this should be done with great care as not to lose any vital information.

The new Tag is returned, and if return_inserted is true, the data written to the store is also returned.

This function attempts to lock the store. If the store is already locked, then it instead returns Error::IoError with an std::io::ErrorKind::WouldBlock.

Source

pub fn try_insert_data_extended<'a, PRE, M, POST>( &self, data: &'a [u8], return_inserted: bool, pre: PRE, merge: M, post: POST, ) -> Result<(Tag, Option<Vec<u8>>)>
where PRE: FnOnce(&'a [u8]) -> Result<&'a [u8]>, M: FnOnce(&'a [u8], Option<&[u8]>) -> Result<MergeResult<'a>>, POST: FnOnce((Tag, Option<Vec<u8>>)) -> Result<(Tag, Option<Vec<u8>>)>,

Inserts or updates a cert, non-blocking variant, extended version.

This function is like CertD::try_insert_data, but after obtaining the lock on the cert-d, and before doing anything else, it calls pre. Similarly, just before dropping the lock, it calls post.

If the pre callback returns an error, the operation is aborted, and the error is propagated to the caller. The post callback can also transform the result.

Source

pub fn insert_special<'a, D, M>( &self, special_name: &str, data: D, return_inserted: bool, merge: M, ) -> Result<(Tag, Option<Vec<u8>>)>
where M: FnOnce(D, Option<&[u8]>) -> Result<MergeResult<'a>>,

Inserts or updates the cert or key stored under a special name.

Requires the special name, the cert or key in binary format and a callback function. The callback is invoked with an Option<Vec<u8>> of the existing data (if any), and is expected to merge the two copies together. The returned Vec<u8> is written to the store under the special name. (Note: The function may decide to omit (parts of) the existing data, but this should be done with great care as not to lose any vital information.) The new Tag is returned, and if return_inserted is true, the data written to the store is also returned. Otherwise, None is returned.

This function locks store, which may block the current thread. Use CertD::try_insert_special to avoid blocking.

The specification currently defines one special name. Non-standard special names are allowed, but they must MUST start with an underscore, which SHOULD be immediately followed by the vendor’s name, e.g., _sequoia_some_special.pgp. Other names cause this function to return Error::BadName.

Source

pub fn insert_special_extended<'a, D, PRE, M, POST>( &self, special_name: &str, data: D, return_inserted: bool, pre: PRE, merge: M, post: POST, ) -> Result<(Tag, Option<Vec<u8>>)>
where PRE: FnOnce(D) -> Result<D>, M: FnOnce(D, Option<&[u8]>) -> Result<MergeResult<'a>>, POST: FnOnce((Tag, Option<Vec<u8>>)) -> Result<(Tag, Option<Vec<u8>>)>,

Inserts or updates the cert or key stored under a special name, extended version.

This function is like CertD::insert_special, but after obtaining the lock on the cert-d, and before doing anything else, it calls pre. Similarly, just before dropping the lock, it calls post.

If the pre callback returns an error, the operation is aborted, and the error is propagated to the caller. The post callback can also transform the result.

The caller can use this functionality to get the cert-d’s tag prior to and after an insert operation, for instance.

Source

pub fn try_insert_special<'a, D, M>( &self, special_name: &str, data: D, return_inserted: bool, merge: M, ) -> Result<(Tag, Option<Vec<u8>>)>
where M: FnOnce(D, Option<&[u8]>) -> Result<MergeResult<'a>>,

Inserts or updates the cert or key stored under a special name, non-blocking variant.

Requires the special name, the cert or key in binary format and a callback function. The callback is invoked with an Option<Vec<u8>> of the existing data (if any), and is expected to merge the two copies together. The returned Vec<u8> is written to the store under the special name. (Note: The function may decide to omit (parts of) the existing data, but this should be done with great care as not to lose any vital information.) The new Tag is returned, and if return_inserted is true, the data written to the store is also returned. Otherwise, None is returned.

This function attempts to lock the store. If the store is already locked, then it instead returns Error::IoError with an std::io::ErrorKind::WouldBlock.

The specification currently defines one special name. Non-standard special names are allowed, but they must MUST start with an underscore, which SHOULD be immediately followed by the vendor’s name, e.g., _sequoia_some_special.pgp. Other names cause this function to return Error::BadName.

Source

pub fn try_insert_special_extended<'a, D, PRE, M, POST>( &self, special_name: &str, data: D, return_inserted: bool, pre: PRE, merge: M, post: POST, ) -> Result<(Tag, Option<Vec<u8>>)>
where PRE: FnOnce(D) -> Result<D>, M: FnOnce(D, Option<&[u8]>) -> Result<MergeResult<'a>>, POST: FnOnce((Tag, Option<Vec<u8>>)) -> Result<(Tag, Option<Vec<u8>>)>,

Inserts or updates the cert or key stored under a special name, non-blocking variant, extended version.

This function is like CertD::try_insert_special, but after obtaining the lock on the cert-d, and before doing anything else, it calls pre. Similarly, just before dropping the lock, it calls post.

If the pre callback returns an error, the operation is aborted, and the error is propagated to the caller. The post callback can also transform the result.

The caller can use this functionality to get the cert-d’s tag prior to and after an insert operation, for instance.

Source