Struct keyutils::Keyring

pub struct Keyring { /* fields omitted */ }

Representation of a kernel keyring.

Methods

impl Keyring

fn set_default(keyring: DefaultKeyring) -> Result<DefaultKeyring>

Set the default keyring to use when implicit requests on the current thread. Returns the old default keyring.

Panics

If the kernel returns a keyring value which the library does not understand, the conversion from the return value into a DefaultKeyring will panic.

fn request(description: &str) -> Result<Self>

Requests a keyring with the given description by searching the thread, process, and session keyrings.

fn request_with_fallback(description: &str, info: &str) -> Result<Self>

Requests a keyring with the given description by searching the thread, process, and session keyrings. If it is not found, the info string will be handed off to /sbin/request-key to generate the key.

fn attach(id: SpecialKeyring) -> Result<Self>

Attach to a special keyring. Fails if the keyring does not already exist.

fn attach_or_create(id: SpecialKeyring) -> Result<Self>

Attach to a special keyring or create it if it does not exist.

fn join_anonymous_session() -> Result<Self>

Create a new anonymous keyring and set it as the session keyring.

fn join_session(name: &str) -> Result<Self>

If a keyring named name exists, attach it as the session keyring (requires the search permission). If a keyring does not exist, create it and attach it as the session keyring.

fn clear(&mut self) -> Result<()>

Clears the contents of the keyring. Requires write permission on the keyring.

fn link_key(&mut self, key: &Key) -> Result<()>

Adds a link to key to the keyring. Any link to an existing key with the same description is removed. Requires write permission on the keyring and link permission on the key.

fn unlink_key(&mut self, key: &Key) -> Result<()>

Removes the link to key from the keyring. Requires write permission on the keyring.

fn link_keyring(&mut self, keyring: &Keyring) -> Result<()>

Adds a link to keyring to the keyring. Any link to an existing keyring with the same description is removed. Requires write permission on the current keyring and link permission on the linked keyring.

fn unlink_keyring(&mut self, keyring: &Keyring) -> Result<()>

Removes the link to keyring from the keyring. Requires write permission on the keyring.

fn search_for_key(&self, description: &str) -> Result<Key>

Recursively search the keyring for a key with the matching description. If it is found, it is attached to the keyring (if write permission to the keyring and link permission on the key exist) and return it. Requires the search permission on the keyring. Any children keyrings without the search permission are ignored.

fn search_for_keyring(&self, description: &str) -> Result<Self>

Recursively search the keyring for a keyring with the matching description. If it is found, it is attached to the keyring (if write permission to the keyring and link permission on the found keyring exist) and return it. Requires the search permission on the keyring. Any children keyrings without the search permission are ignored.

fn read(&self) -> Result<(Vec<Key>, Vec<Keyring>)>

Return all immediate children of the keyring. Requires read permission on the keyring.

fn attach_persistent(&mut self) -> Result<Self>

Attach the persistent keyring for the current user to the current keyring. If one does not exist, it will be created. Requires write permission on the keyring.

fn add_key(&mut self, description: &str, payload: &[u8]) -> Result<Key>

Adds a key to the keyring. If a key with the same description already exists and has the update permission, it will be updated, otherwise the link to the old key will be removed. Requires write permission.

fn add_keyring(&mut self, description: &str) -> Result<Self>

Adds a keyring to the current keyring. If a keyring with the same description already, the link to the old keyring will be removed. Requires write permission on the keyring.

fn request_key(&self, description: &str) -> Result<Key>

Requests a keyring with the given description by searching the thread, process, and session keyrings. If it is found, it is attached to the keyring.

fn request_keyring(&self, description: &str) -> Result<Self>

Requests a keyring with the given description by searching the thread, process, and session keyrings. If it is found, it is attached to the keyring.

fn request_key_with_fallback(
    &self,
    description: &str,
    info: &str
) -> Result<Key>

Requests a key with the given description by searching the thread, process, and session keyrings. If it is not found, the info string will be handed off to /sbin/request-key to generate the key. If found, it will be attached to the current keyring. Requires write permission to the keyring.

fn request_keyring_with_fallback(
    &self,
    description: &str,
    info: &str
) -> Result<Self>

Requests a keyring with the given description by searching the thread, process, and session keyrings. If it is not found, the info string will be handed off to /sbin/request-key to generate the key. If found, it will be attached to the current keyring. Requires write permission to the keyring.

fn revoke(self) -> Result<()>

Revokes the keyring. Requires write permission on the keyring.

fn chown(&mut self, uid: uid_t) -> Result<()>

Change the user which owns the keyring. Requires the setattr permission on the keyring and the SysAdmin capability to change it to anything other than the current user.

fn chgrp(&mut self, gid: gid_t) -> Result<()>

Change the group which owns the keyring. Requires the setattr permission on the keyring and the SysAdmin capability to change it to anything other than a group of which the current user is a member.

fn set_permissions(&mut self, perms: KeyPermissions) -> Result<()>

Set the permissions on the keyring. Requires the setattr permission on the keyring and the SysAdmin capability if the current user does not own the keyring.

fn description(&self) -> Result<KeyDescription>

Retrieve metadata about the keyring.

Panics

If the kernel returns malformed data, the the parser will panic.

fn set_timeout(&mut self, timeout: u32) -> Result<()>

Set an expiration timer on the keyring to timeout seconds in the future. A timeout of 0 means "no expiration". Requires the setattr permission on the keyring.

fn security(&self) -> Result<String>

The security context of the keyring. Depends on the security manager loaded into the kernel (e.g., SELinux or AppArmor).

fn invalidate(self) -> Result<()>

Invalidates the keyring and schedules it for removal. Requires the search permission on the keyring.