Struct linux_keyutils::KeyRing

source · [−]

pub struct KeyRing { /* private fields */ }

Expand description

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

Implementations

source

impl KeyRing

source

pub fn from_special_id(
id: KeyRingIdentifier,
create: bool
) -> Result<Self, KeyError>

Obtain a KeyRing from its special identifier.

If the create argument is true, then this method will attempt to create the keyring. Otherwise it will only succeed if the keyring already exists and is valid.

Internally this uses KEYCTL_GET_KEYRING_ID to resolve a keyrings real ID from the special identifier.

source

pub fn get_persistent(link_with: KeyRingIdentifier) -> Result<Self, KeyError>

Get the persistent keyring (persistent-keyring(7)) of the current user and link it to a specified keyring.

If the call is successful, a link to the persistent keyring is added to the keyring specified in the link_with argument.

The caller must have write permission on the keyring.

The persistent keyring will be created by the kernel if it does not yet exist.

Each time the KeyRing::get_persistent operation is performed, the persistent keyring will have its expiration timeout reset to the value in:

/proc/sys/kernel/keys/persistent_keyring_expiry

Should the timeout be reached, the persistent keyring will be removed and everything it pins can then be garbage collected.

Persistent keyrings were added to Linux in kernel version 3.13.

source

pub fn metadata(&self) -> Result<Metadata, KeyError>

Obtain information describing the attributes of this keyring.

The keyring must grant the caller view permission.

source

pub fn add_key<D: AsRef<str> + ?Sized, S: AsRef<[u8]> + ?Sized>(
 &self,
 description: &D,
 secret: &S
) -> Result<Key, KeyError>

Creates or updates a key of the given type and description, instantiates it with the payload of length plen, attaches it to the User keyring.

If the destination keyring already contains a key that matches the specified type and description, then, if the key type supports it, that key will be updated rather than a new key being created; if not, a new key (with a different ID) will be created and it will displace the link to the extant key from the keyring.

source

pub fn search<D: AsRef<str> + ?Sized>(
&self,
description: &D
) -> Result<Key, KeyError>

Search for a key in the keyring tree, starting with this keyring as the head, returning its ID.

The search is performed breadth-first and recursively.

The source keyring must grant search permission to the caller. When performing the recursive search, only keyrings that grant the caller search permission will be searched. Only keys with for which the caller has search permission can be found.

If the key is found, its ID is returned as the function result.

source

pub fn get_links(&self, max: usize) -> Result<Links, KeyError>

Obtain a list of the keys/keyrings linked to this keyring.

This method allocates, but you can provide a maximum number of entries to read. Each returned entry is 4 bytes.

The keyring must either grant the caller read permission, or grant the caller search permission.

source

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

Create a link from this keyring to a key.

If a key with the same type and description is already linked in the keyring, then that key is displaced from the keyring.

Before creating the link, the kernel checks the nesting of the keyrings and returns appropriate errors if the link would produce a cycle or if the nesting of keyrings would be too deep (The limit on the nesting of keyrings is determined by the kernel constant KEYRING_SEARCH_MAX_DEPTH, defined with the value 6, and is necessary to prevent overflows on the kernel stack when recursively searching keyrings).

The caller must have link permission on the key being added and write permission on the keyring.

source

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

Unlink a key from this keyring.

If the key is not currently linked into the keyring, an error results. If the last link to a key is removed, then that key will be scheduled for destruction.

The caller must have write permission on the keyring from which the key is being removed.

source