Struct Keyring 

pub struct Keyring { /* private fields */ }

Interface for managing the pacman keyring.

Provides async methods for key listing, importing, signing, and keyring management. Most write operations require root privileges.

Example

use pacman_key::Keyring;

let keyring = Keyring::new();
let keys = keyring.list_keys().await?;
println!("Found {} keys", keys.len());

Implementations

impl Keyring

pub fn new() -> Self

Creates a new Keyring using the default pacman keyring path.

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

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

Lists signatures on keys in the keyring.

If keyid is provided, lists signatures only for that key. Otherwise lists all signatures in the keyring.

pub async fn init_keyring(&self) -> Result<()>

Initializes the pacman keyring.

Creates the keyring directory and generates a local signing key. Requires root privileges.

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

Populates the keyring with keys from distribution keyrings.

If no keyrings are specified, defaults to “archlinux”. Requires root privileges.

Keyring Names

Keyring names must contain only alphanumeric characters, hyphens, or underscores. Common valid names include “archlinux”, “archlinuxarm”, and “manjaro”.

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

Receives keys from a keyserver.

Requires root privileges.

Note

This function validates key IDs before making the request. Key IDs must be 8, 16, or 40 hexadecimal characters (with optional “0x” prefix).

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

Locally signs a key to mark it as trusted.

Requires root privileges.

Note

This function validates key IDs before making the request. Key IDs must be 8, 16, or 40 hexadecimal characters (with optional “0x” prefix).

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

Deletes a key from the keyring.

Requires root privileges.

Note

This function validates key IDs before making the request. Key IDs must be 8, 16, or 40 hexadecimal characters (with optional “0x” prefix).

pub async fn refresh_keys<F>( &self, callback: F, options: RefreshOptions, ) -> 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.

Example

use pacman_key::{Keyring, RefreshOptions, RefreshProgress};

let keyring = Keyring::new();

// With timeout
let options = RefreshOptions { timeout_secs: Some(300) };

keyring.refresh_keys(|progress| {
    match progress {
        RefreshProgress::Starting { total_keys } => {
            println!("Refreshing {} keys...", total_keys);
        }
        RefreshProgress::Refreshing { current, total, keyid } => {
            println!("[{}/{}] {}", current, total, keyid);
        }
        RefreshProgress::Completed => println!("Done!"),
        RefreshProgress::Error { keyid, message } => {
            eprintln!("Error refreshing {}: {}", keyid, message);
        }
        _ => {}
    }
}, options).await?;

Trait Implementations

impl Default for Keyring

fn default() -> Self

Returns the “default value” for a type.