Struct 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 description and User type, instantiates it with the payload of length plen, attaches it to the 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 request_key<D: AsRef<str> + ?Sized, C: AsRef<str> + ?Sized>( &self, description: &D, callout: Option<&C>, ) -> Result<Key, KeyError>

Attempts to find a key of the given type with a description that matches the specified description. If such a key could not be found, then the key is optionally created.

If the key is found or created, it is attached it to the keyring and returns the key’s serial number.

If the key is not found and callout info is empty then the call fails with the error ENOKEY.

If the key is not found and callout info is not empty, then the kernel attempts to invoke a user-space program to instantiate the key.

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

pub fn link_keyring(&self, keyring: KeyRing) -> Result<(), KeyError>

Link another keyring to this keyring.

Behaves similarly to link_key, but links a KeyRing instead. The caller must have link permission on the keyring being added as a link, and write permission on this keyring.

Source

pub fn unlink_keyring(&self, keyring: KeyRing) -> Result<(), KeyError>

Unlink another keyring from this keyring.

Behaves similarly to unlink_key, but unlinks a KeyRing instead. The caller must have write permission on the keyring to remove links from it.

Source

pub fn link_keyring_id( &self, keyringid: KeyRingIdentifier, ) -> Result<(), KeyError>

Link a default keyring from this keyring.

This method does the same thing as link_keyring, but links one of the special keyrings defined by the system. This is useful when you don’t want to have to open a keyring before linking it.

The caller must have link permissions on the added keyring, and write permission on this keyring. Requesting to link to a non-existent default keyring will result in that keyring being created automatically.

Source

pub fn unlink_keyring_id( &self, keyringid: KeyRingIdentifier, ) -> Result<(), KeyError>

Unlink a default keyring from this keyring.

This method does the same thing as unlink_keyring, but unlinks one of the special keyrings defined by the system. This is useful when you don’t want to have to open a keyring before unlinking it.

The caller must have write permission on this keyring. In addition, this method will return KeyError::KeyDoesNotExist if the target keyring has not yet been created.

Source