Skip to main content

Keyring

Struct Keyring 

Source
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

Source

pub fn new() -> Self

Creates a new Keyring using the default pacman keyring path.

Source

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.

Source

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?;
Source

pub fn get_homedir(&self) -> &str

Source

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);
}
Source

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.

Source

pub async fn check_signatures( &self, keyid: Option<&str>, ) -> Result<Vec<Signature>>

Lists and verifies signatures on keys (--check-sigs).

See ReadOnlyKeyring::check_signatures.

Source

pub async fn export_keys(&self, keyids: &[&str]) -> Result<String>

Exports the given keys (or all keys) as an ASCII-armored block.

See ReadOnlyKeyring::export_keys.

Source

pub async fn fingerprints(&self, keyids: &[&str]) -> Result<Vec<String>>

Returns the fingerprints of the given keys (or all keys).

See ReadOnlyKeyring::fingerprints.

Source

pub async fn verify_signature( &self, sig: &Path, file: Option<&Path>, ) -> Result<VerifyResult>

Verifies a signature against the keyring.

See ReadOnlyKeyring::verify_signature.

Source

pub async fn get_ownertrust(&self) -> Result<Vec<(String, OwnerTrust)>>

Reads owner-trust assignments.

See ReadOnlyKeyring::get_ownertrust.

Source

pub fn is_initialized(&self) -> Result<InitializationStatus>

Checks whether the keyring is initialized without spawning GPG.

See ReadOnlyKeyring::is_initialized for details.

Source

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.

Source

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.

Source

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.

Source

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.

Source

pub async fn receive_keys(&self, keyids: &[&str]) -> Result<()>

Receives keys from a keyserver.

Source

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.

Source

pub async fn locally_sign_key(&self, keyid: &str) -> Result<()>

Locally signs a key to mark it as trusted.

Source

pub async fn delete_key(&self, keyid: &str) -> Result<()>

Deletes a key from the keyring.

Source

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.

Source

pub async fn add_keys_with_options( &self, files: &[&Path], options: OperationOptions, ) -> Result<()>

Imports keys from file(s) with timeout and cancellation support.

Source

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.

Source

pub async fn update_trustdb_with_options( &self, options: OperationOptions, ) -> Result<()>

Rebuilds the trust database with timeout and cancellation support.

Source

pub async fn import_keyrings(&self, dirs: &[&Path]) -> Result<()>

Imports pubring.gpg from one or more keyring directories (pacman-key --import).

Source

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).

Source

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.

Source

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?;

Trait Implementations§

Source§

impl Default for Keyring

Source§

fn default() -> Self

Returns the “default value” for a type. Read more

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.