pub struct Keyring { /* private fields */ }Expand description
Interface for managing the pacman keyring.
Provides async methods for key listing, importing, signing, and keyring management.
§Root Privileges
Write operations (init_keyring, populate, receive_keys, locally_sign_key,
delete_key) require root privileges and will return Error::PermissionDenied
if called without sufficient permissions.
§Example
use pacman_key::Keyring;
let keyring = Keyring::new();
let keys = keyring.list_keys().await?;
println!("Found {} keys", keys.len());Implementations§
Source§impl Keyring
impl Keyring
Sourcepub fn with_keyserver(self, url: impl Into<String>) -> Self
pub fn with_keyserver(self, url: impl Into<String>) -> Self
Sets the keyserver used by receive_keys and refresh_keys.
Maps to pacman-key’s --keyserver. When unset, gpg’s configured
default keyserver is used.
Sourcepub fn with_homedir(path: impl Into<String>) -> ReadOnlyKeyring
pub fn with_homedir(path: impl Into<String>) -> ReadOnlyKeyring
Creates a read-only keyring interface for a custom GPG home directory.
Returns a ReadOnlyKeyring that can only perform read operations
(list_keys, list_signatures). This is useful for inspecting
alternative keyrings without risking modifications.
§Example
use pacman_key::Keyring;
let reader = Keyring::with_homedir("/custom/gnupg");
let keys = reader.list_keys().await?;pub fn get_homedir(&self) -> &str
Sourcepub async fn list_keys(&self) -> Result<Vec<Key>>
pub async fn list_keys(&self) -> Result<Vec<Key>>
Lists all keys in the keyring.
§Example
use pacman_key::Keyring;
let keyring = Keyring::new();
for key in keyring.list_keys().await? {
println!("{} - {:?}", key.uid, key.validity);
}Sourcepub async fn list_signatures(
&self,
keyid: Option<&str>,
) -> Result<Vec<Signature>>
pub async fn list_signatures( &self, keyid: Option<&str>, ) -> Result<Vec<Signature>>
Lists signatures on keys in the keyring (non-checking --list-sigs).
If keyid is provided, lists signatures only for that key.
Otherwise lists all signatures in the keyring.
Sourcepub async fn check_signatures(
&self,
keyid: Option<&str>,
) -> Result<Vec<Signature>>
pub async fn check_signatures( &self, keyid: Option<&str>, ) -> Result<Vec<Signature>>
Lists and verifies signatures on keys (--check-sigs).
Sourcepub async fn export_keys(&self, keyids: &[&str]) -> Result<String>
pub async fn export_keys(&self, keyids: &[&str]) -> Result<String>
Exports the given keys (or all keys) as an ASCII-armored block.
Sourcepub async fn fingerprints(&self, keyids: &[&str]) -> Result<Vec<String>>
pub async fn fingerprints(&self, keyids: &[&str]) -> Result<Vec<String>>
Returns the fingerprints of the given keys (or all keys).
Sourcepub async fn verify_signature(
&self,
sig: &Path,
file: Option<&Path>,
) -> Result<VerifyResult>
pub async fn verify_signature( &self, sig: &Path, file: Option<&Path>, ) -> Result<VerifyResult>
Verifies a signature against the keyring.
Sourcepub async fn get_ownertrust(&self) -> Result<Vec<(String, OwnerTrust)>>
pub async fn get_ownertrust(&self) -> Result<Vec<(String, OwnerTrust)>>
Reads owner-trust assignments.
Sourcepub fn is_initialized(&self) -> Result<InitializationStatus>
pub fn is_initialized(&self) -> Result<InitializationStatus>
Checks whether the keyring is initialized without spawning GPG.
See ReadOnlyKeyring::is_initialized for details.
Sourcepub async fn init_keyring(&self) -> Result<()>
pub async fn init_keyring(&self) -> Result<()>
Initializes the pacman keyring.
Creates the keyring directory and generates a local signing key.
For timeout/cancellation support, use init_keyring_with_options.
Sourcepub async fn init_keyring_with_options(
&self,
options: OperationOptions,
) -> Result<()>
pub async fn init_keyring_with_options( &self, options: OperationOptions, ) -> Result<()>
Initializes the pacman keyring with timeout and cancellation support.
Creates the keyring directory and generates a local signing key.
Sourcepub async fn populate(&self, keyrings: &[&str]) -> Result<()>
pub async fn populate(&self, keyrings: &[&str]) -> Result<()>
Populates the keyring with keys from distribution keyrings.
If no keyrings are specified, defaults to “archlinux”. Keyring names
must contain only alphanumeric characters, hyphens, or underscores.
For timeout/cancellation support, use populate_with_options.
Sourcepub async fn populate_with_options(
&self,
keyrings: &[&str],
options: OperationOptions,
) -> Result<()>
pub async fn populate_with_options( &self, keyrings: &[&str], options: OperationOptions, ) -> Result<()>
Populates the keyring with timeout and cancellation support.
If no keyrings are specified, defaults to “archlinux”. Keyring names must contain only alphanumeric characters, hyphens, or underscores.
Sourcepub async fn receive_keys(&self, keyids: &[&str]) -> Result<()>
pub async fn receive_keys(&self, keyids: &[&str]) -> Result<()>
Receives keys from a keyserver.
Sourcepub async fn receive_keys_with_options(
&self,
keyids: &[&str],
options: OperationOptions,
) -> Result<()>
pub async fn receive_keys_with_options( &self, keyids: &[&str], options: OperationOptions, ) -> Result<()>
Receives keys from a keyserver with timeout and cancellation support.
Uses the keyserver set via with_keyserver, if any.
Sourcepub async fn locally_sign_key(&self, keyid: &str) -> Result<()>
pub async fn locally_sign_key(&self, keyid: &str) -> Result<()>
Locally signs a key to mark it as trusted.
Sourcepub async fn delete_key(&self, keyid: &str) -> Result<()>
pub async fn delete_key(&self, keyid: &str) -> Result<()>
Deletes a key from the keyring.
Sourcepub async fn add_keys(&self, files: &[&Path]) -> Result<()>
pub async fn add_keys(&self, files: &[&Path]) -> Result<()>
Imports keys from file(s) into the keyring (pacman-key --add).
Distinct from receive_keys, which pulls from a keyserver. Each path
must exist. pacman-key updates the trust database afterward; this crate
does not, so call update_trustdb when trust state must be current.
Sourcepub async fn add_keys_with_options(
&self,
files: &[&Path],
options: OperationOptions,
) -> Result<()>
pub async fn add_keys_with_options( &self, files: &[&Path], options: OperationOptions, ) -> Result<()>
Imports keys from file(s) with timeout and cancellation support.
Sourcepub async fn update_trustdb(&self) -> Result<()>
pub async fn update_trustdb(&self) -> Result<()>
Rebuilds the trust database (pacman-key --updatedb,
i.e. gpg --check-trustdb).
pacman-key runs this automatically after every key-mutating operation;
this crate leaves it to the caller. Run it after add_keys,
delete_key, locally_sign_key, receive_keys, or set_ownertrust
to keep computed validity current.
Sourcepub async fn update_trustdb_with_options(
&self,
options: OperationOptions,
) -> Result<()>
pub async fn update_trustdb_with_options( &self, options: OperationOptions, ) -> Result<()>
Rebuilds the trust database with timeout and cancellation support.
Sourcepub async fn import_keyrings(&self, dirs: &[&Path]) -> Result<()>
pub async fn import_keyrings(&self, dirs: &[&Path]) -> Result<()>
Imports pubring.gpg from one or more keyring directories
(pacman-key --import).
Sourcepub async fn import_trustdb(&self, dirs: &[&Path]) -> Result<()>
pub async fn import_trustdb(&self, dirs: &[&Path]) -> Result<()>
Imports owner-trust values from trustdb.gpg in one or more keyring
directories (pacman-key --import-trustdb).
Sourcepub async fn set_ownertrust(&self, entries: &[(&str, OwnerTrust)]) -> Result<()>
pub async fn set_ownertrust(&self, entries: &[(&str, OwnerTrust)]) -> Result<()>
Sets owner-trust levels for keys, non-interactively.
A scriptable replacement for the trust submenu of --edit-key: feeds
<fingerprint>:<level>: lines to gpg --import-ownertrust. Each keyid
is validated. Run update_trustdb afterward to recompute validity.
Sourcepub async fn refresh_keys<F>(
&self,
callback: F,
options: OperationOptions,
) -> Result<()>where
F: Fn(RefreshProgress),
pub async fn refresh_keys<F>(
&self,
callback: F,
options: OperationOptions,
) -> Result<()>where
F: Fn(RefreshProgress),
Refreshes all keys from the keyserver.
This is a long-running operation. The callback receives progress updates as keys are refreshed. The timeout covers the initial key listing as well as the refresh.
§Example
use pacman_key::{Keyring, OperationOptions, RefreshProgress, CancellationToken};
let keyring = Keyring::new();
let token = CancellationToken::new();
let options = OperationOptions {
timeout_secs: Some(300),
cancel_token: Some(token.clone()),
};
// Cancel from another task with: token.cancel()
keyring.refresh_keys(|p| println!("{p:?}"), options).await?;