Struct keyutils::Keyring

pub struct Keyring { /* private fields */ }

Representation of a kernel keyring.

Implementations

impl Keyring

pub unsafe fn new(id: KeyringSerial) -> Self

Instantiate a keyring from an ID.

This is unsafe because no keyring is known to exist with the given ID.

Safety

This method assumes that the given serial is a valid keyring ID at the kernel level.

pub 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.

pub fn request<'s, 'a, D, I, T>( description: D, info: I, target: T ) -> Result<Self>where D: AsRef<str>, I: Into<Option<&'s str>>, T: Into<Option<TargetKeyring<'a>>>,

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

If it is not found, the info string (if provided) will be handed off to /sbin/request-key to generate the key.

If target is given, the found keyring will be linked into it. If target is not given and a new key is constructed due to the request, it will be linked into the default keyring (see Keyring::set_default).

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

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

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

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

pub fn join_anonymous_session() -> Result<Self>

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

pub fn join_session<N>(name: N) -> Result<Self>where N: AsRef<str>,

Attached to a named session keyring.

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.

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

Clears the contents of the keyring.

Requires write permission on the keyring.

pub 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.

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

Removes the link to key from the keyring.

Requires write permission on the keyring.

pub 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.

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

Removes the link to keyring from the keyring.

Requires write permission on the keyring.

pub fn search_for_key<'a, K, D, DK>( &self, description: D, destination: DK ) -> Result<Key>where K: KeyType, D: Borrow<K::Description>, DK: Into<Option<&'a mut Keyring>>,

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.

pub fn search_for_keyring<'a, D, DK>( &self, description: D, destination: DK ) -> Result<Self>where D: Borrow<<Keyring as KeyType>::Description>, DK: Into<Option<&'a mut Keyring>>,

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.

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

Return all immediate children of the keyring.

Requires read permission on the keyring.

pub 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.

pub fn add_key<K, D, P>(&mut self, description: D, payload: P) -> Result<Key>where K: KeyType, D: Borrow<K::Description>, P: Borrow<K::Payload>,

Adds a key of a specific type 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.

pub fn add_keyring<D>(&mut self, description: D) -> Result<Self>where D: Borrow<<Keyring as KeyType>::Description>,

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.

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

Revokes the keyring.

Requires write permission on the keyring.

pub 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.

pub 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.

pub fn set_permissions(&mut self, perms: Permission) -> 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.

pub fn restrict_all(&mut self) -> Result<()>

Restrict all links into the keyring.

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

pub fn restrict_by_type<K, R>(&mut self, restriction: R) -> Result<()>where K: RestrictableKeyType, R: Borrow<K::Restriction>,

Restrict links into the keyring.

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

pub fn description(&self) -> Result<Description>

Retrieve metadata about the keyring.

Panics

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

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

Set an expiration timer on the keyring to timeout.

Any partial seconds are ignored. A timeout of 0 means “no expiration”. Requires the setattr permission on the keyring.

pub 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).

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

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

Trait Implementations

impl Clone for Keyring

fn clone(&self) -> Keyring

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Keyring

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<'a> From<&'a mut Keyring> for Option<TargetKeyring<'a>>

fn from(keyring: &'a mut Keyring) -> Self

Converts to this type from the input type.

impl<'a> From<&'a mut Keyring> for TargetKeyring<'a>

fn from(keyring: &'a mut Keyring) -> Self

Converts to this type from the input type.

impl PartialEq<Keyring> for Keyring

fn eq(&self, other: &Keyring) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Eq for Keyring

impl StructuralEq for Keyring

impl StructuralPartialEq for Keyring