## 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. 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§

Source§

### impl Keyring

Source

#### pub fn new() -> Self

Creates a new Keyring using the default pacman keyring path.

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

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

Source

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

Initializes the pacman keyring.

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

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”. Requires root privileges.

##### §Keyring Names

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

Source

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

Source

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

Source

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

Source

#### 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§

Source§

### impl Default for Keyring

Source§

#### fn default() -> Self

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

## Auto Trait Implementations§

§

### impl Freeze for Keyring

§

### impl RefUnwindSafe for Keyring

§

### impl Send for Keyring

§

### impl Sync for Keyring

§

### impl Unpin for Keyring

§

### impl UnwindSafe for Keyring

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

§

### impl<T> Instrument for T

§

#### fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [`Span`], returning an `Instrumented` wrapper. Read more
§

#### fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current `Span`, returning an `Instrumented` wrapper. Read more
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 = Infallible

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

#### fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

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

### impl<T> WithSubscriber for T

§

#### fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided `Subscriber` to this type, returning a [`WithDispatch`] wrapper. Read more
§

#### fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default `Subscriber` to this type, returning a [`WithDispatch`] wrapper. Read more