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
impl KeyRing
Sourcepub fn from_special_id(
id: KeyRingIdentifier,
create: bool,
) -> Result<Self, KeyError>
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.
Sourcepub fn get_persistent(link_with: KeyRingIdentifier) -> Result<Self, KeyError>
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.
Sourcepub fn metadata(&self) -> Result<Metadata, KeyError>
pub fn metadata(&self) -> Result<Metadata, KeyError>
Obtain information describing the attributes of this keyring.
The keyring must grant the caller view permission.
Sourcepub fn add_key<D: AsRef<str> + ?Sized, S: AsRef<[u8]> + ?Sized>(
&self,
description: &D,
secret: &S,
) -> Result<Key, KeyError>
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.
Sourcepub fn search<D: AsRef<str> + ?Sized>(
&self,
description: &D,
) -> Result<Key, KeyError>
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.
Sourcepub fn get_links(&self, max: usize) -> Result<Links, KeyError>
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.
Sourcepub fn link_key(&self, key: Key) -> Result<(), KeyError>
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.
Sourcepub fn unlink_key(&self, key: Key) -> Result<(), KeyError>
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.