Crate linux_keyutils

Rust interface to the Linux key-management facility. Provides a safe interface around the raw system calls allowing user-space programs to perform key manipulation.

Example usage:

use linux_keyutils::{Key, KeyRing, KeyError, KeyRingIdentifier};
use linux_keyutils::{KeyPermissionsBuilder, Permission};

fn main() -> Result<(), KeyError> {
    // Obtain the default session keyring for the current process
    // See [KeyRingIdentifier] and `man 2 keyctl` for more information on default
    // keyrings for processes.
    let ring = KeyRing::from_special_id(KeyRingIdentifier::Session, false)?;

    // Insert a new key
    let key = ring.add_key("my-new-key", b"secret")?;

    // Utiltiies to create proper permissions
    let perms = KeyPermissionsBuilder::builder()
        .posessor(Permission::ALL)
        .user(Permission::ALL)
        .group(Permission::VIEW | Permission::READ)
        .build();

    // Perform manipulations on the key such as setting permissions
    key.set_perms(perms)?;

    // Or setting a timeout for how long the key should exist
    key.set_timeout(300)?;

    // Or invalidating (removing) the key
    key.invalidate()?;
    Ok(())
}

To look for an existing key you can use the KeyRing::search method. Usage:

use linux_keyutils::{Key, KeyRing, KeyError, KeyRingIdentifier};
use linux_keyutils::{KeyPermissionsBuilder, Permission};

fn get_key(description: &str) -> Result<Key, KeyError> {
    // Obtain the default session keyring for the current process
    // See `KeyRingIdentifier` and `man 7 keyrings` for more information on default
    // keyrings for processes and users.
    let ring = KeyRing::from_special_id(KeyRingIdentifier::Session, false)?;

    // Lookup an existing key
    let key = ring.search(description)?;
    Ok(key)
}

Structs

Key

A key corresponding to a specific real ID.

KeyPermissions

Construct key permissions for use with Key::set_perms or returned by Metadata::get_perms.

KeyPermissionsBuilder

Construct key permissions with the builder pattern.

KeyRing

Interface to perform keyring operations. Used to locate, create, search, add, and link/unlink keys to & from keyrings.

KeySerialId

Primary kernel identifier for a key or keyring.

Links

A collection of LinkNodes, returned from KeyRing::get_links

Metadata

Information about the given node/entry. Returned by Key::metadata or KeyRing::metadata

Permission

Pre-defined bit-flags to construct permissions easily.

Enums

KeyError

Error type for this library, optionally implements std::error::Error.

KeyRingIdentifier

Special identifiers for default keyrings. See man 7 keyrings.

KeyType

Pre-defined key types the kernel understands. See man 7 keyrings.

LinkNode

An item/node linked to a ring. Both keys and other keyrings can be linked to a particular keyring.