pub struct Keyring { /* private fields */ }
Expand description
Representation of a kernel keyring.
Implementations§
source§impl Keyring
impl Keyring
sourcepub unsafe fn new(id: KeyringSerial) -> Self
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.
sourcepub fn set_default(keyring: DefaultKeyring) -> Result<DefaultKeyring>
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.
sourcepub 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>>>,
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
).
sourcepub fn attach(id: SpecialKeyring) -> Result<Self>
pub fn attach(id: SpecialKeyring) -> Result<Self>
Attach to a special keyring. Fails if the keyring does not already exist.
sourcepub fn attach_or_create(id: SpecialKeyring) -> Result<Self>
pub fn attach_or_create(id: SpecialKeyring) -> Result<Self>
Attach to a special keyring or create it if it does not exist.
sourcepub fn join_anonymous_session() -> Result<Self>
pub fn join_anonymous_session() -> Result<Self>
Create a new anonymous keyring and set it as the session keyring.
sourcepub fn join_session<N>(name: N) -> Result<Self>where
N: AsRef<str>,
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.
sourcepub fn clear(&mut self) -> Result<()>
pub fn clear(&mut self) -> Result<()>
Clears the contents of the keyring.
Requires write
permission on the keyring.
sourcepub fn link_key(&mut self, key: &Key) -> Result<()>
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.
sourcepub fn unlink_key(&mut self, key: &Key) -> Result<()>
pub fn unlink_key(&mut self, key: &Key) -> Result<()>
Removes the link to key
from the keyring.
Requires write
permission on the keyring.
sourcepub fn link_keyring(&mut self, keyring: &Keyring) -> Result<()>
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.
sourcepub fn unlink_keyring(&mut self, keyring: &Keyring) -> Result<()>
pub fn unlink_keyring(&mut self, keyring: &Keyring) -> Result<()>
Removes the link to keyring
from the keyring.
Requires write
permission on the keyring.
sourcepub 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>>,
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.
sourcepub 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>>,
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.
sourcepub fn read(&self) -> Result<(Vec<Key>, Vec<Keyring>)>
pub fn read(&self) -> Result<(Vec<Key>, Vec<Keyring>)>
Return all immediate children of the keyring.
Requires read
permission on the keyring.
sourcepub fn attach_persistent(&mut self) -> Result<Self>
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.
sourcepub 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>,
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.
sourcepub fn add_keyring<D>(&mut self, description: D) -> Result<Self>where
D: Borrow<<Keyring as KeyType>::Description>,
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.
sourcepub fn revoke(self) -> Result<()>
pub fn revoke(self) -> Result<()>
Revokes the keyring.
Requires write
permission on the keyring.
sourcepub fn chown(&mut self, uid: uid_t) -> Result<()>
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.
sourcepub fn chgrp(&mut self, gid: gid_t) -> Result<()>
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.
sourcepub fn set_permissions(&mut self, perms: Permission) -> Result<()>
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.
sourcepub fn restrict_all(&mut self) -> Result<()>
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.
sourcepub fn restrict_by_type<K, R>(&mut self, restriction: R) -> Result<()>where
K: RestrictableKeyType,
R: Borrow<K::Restriction>,
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.
sourcepub fn description(&self) -> Result<Description>
pub fn description(&self) -> Result<Description>
Retrieve metadata about the keyring.
Panics
If the kernel returns malformed data, the the parser will panic.
sourcepub fn set_timeout(&mut self, timeout: Duration) -> Result<()>
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.
sourcepub fn security(&self) -> Result<String>
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).
sourcepub fn invalidate(self) -> Result<()>
pub fn invalidate(self) -> Result<()>
Invalidates the keyring and schedules it for removal. Requires the search
permission on
the keyring.