pub struct Key(/* private fields */);
Expand description
A key corresponding to a specific real ID.
Generally you will either create or obtain a Key via the KeyRing interface. Since keys must be linked with a keyring to be valid.
For example:
use linux_keyutils::{Key, KeyRing, KeyRingIdentifier, KeyError};
use zeroize::Zeroize;
// Name of my program's key
const KEYNAME: &'static str = "my-process-key";
// Locate the key in the process keyring and update the secret
fn update_secret<T: AsRef<[u8]> + Zeroize>(data: &T) -> Result<(), KeyError> {
// Get the current process keyring
let ring = KeyRing::from_special_id(KeyRingIdentifier::Process, false)?;
// Locate the key we previously created
let key = ring.search(KEYNAME)?;
// Change the data it contains
key.update(data)?;
Ok(())
}
Implementations§
Source§impl Key
impl Key
Sourcepub fn from_id(id: KeySerialId) -> Self
pub fn from_id(id: KeySerialId) -> Self
Initialize a new Key object from the provided ID
Sourcepub fn get_id(&self) -> KeySerialId
pub fn get_id(&self) -> KeySerialId
Obtain a copy of the ID of this key
Sourcepub fn metadata(&self) -> Result<Metadata, KeyError>
pub fn metadata(&self) -> Result<Metadata, KeyError>
Obtain information describing the attributes of this key.
The key must grant the caller view permission.
Sourcepub fn read<T: AsMut<[u8]>>(&self, buffer: &mut T) -> Result<usize, KeyError>
pub fn read<T: AsMut<[u8]>>(&self, buffer: &mut T) -> Result<usize, KeyError>
Read the payload data of a key into a provided mutable slice.
The returned usize is the number of bytes read into the slice.
The key must either grant the caller read permission, or grant the caller search permission when searched for from the process keyrings (i.e., the key is possessed).
Sourcepub fn read_to_vec(&self) -> Result<Vec<u8>, KeyError>
pub fn read_to_vec(&self) -> Result<Vec<u8>, KeyError>
Read the payload data of a key, returning a newly allocated vector.
The key must either grant the caller read permission, or grant the caller search permission when searched for from the process keyrings (i.e., the key is possessed).
Sourcepub fn update<T: AsRef<[u8]>>(&self, update: &T) -> Result<(), KeyError>
pub fn update<T: AsRef<[u8]>>(&self, update: &T) -> Result<(), KeyError>
Update a key’s data payload.
The caller must have write permission on the key specified and the key type must support updating.
A negatively instantiated key (see the description of Key::reject) can be positively instantiated with this operation.
Sourcepub fn set_perms(&self, perm: KeyPermissions) -> Result<(), KeyError>
pub fn set_perms(&self, perm: KeyPermissions) -> Result<(), KeyError>
Change the permissions of the key with the ID provided
If the caller doesn’t have the CAP_SYS_ADMIN capability, it can change permissions only only for the keys it owns. (More precisely: the caller’s filesystem UID must match the UID of the key.)
Sourcepub fn chown(&self, uid: Option<u32>, gid: Option<u32>) -> Result<(), KeyError>
pub fn chown(&self, uid: Option<u32>, gid: Option<u32>) -> Result<(), KeyError>
Change the ownership (user and group ID) of a key.
For the UID to be changed, or for the GID to be changed to a group the caller is not a member of, the caller must have the CAP_SYS_ADMIN capability (see capabilities(7)).
If the UID is to be changed, the new user must have sufficient quota to accept the key. The quota deduction will be removed from the old user to the new user should the UID be changed.
Sourcepub fn set_timeout(&self, seconds: usize) -> Result<(), KeyError>
pub fn set_timeout(&self, seconds: usize) -> Result<(), KeyError>
Set a timeout on a key.
Specifying the timeout value as 0 clears any existing timeout on the key.
The /proc/keys
file displays the remaining time until each key will expire.
(This is the only method of discovering the timeout on a key.)
The caller must either have the setattr permission on the key or hold an instantiation authorization token for the key.
The key and any links to the key will be automatically garbage collected after the timeout expires. Subsequent attempts to access the key will then fail with the error EKEYEXPIRED.
This operation cannot be used to set timeouts on revoked, expired, or negatively instantiated keys.
Sourcepub fn revoke(&self) -> Result<(), KeyError>
pub fn revoke(&self) -> Result<(), KeyError>
Revoke this key. Similar to Key::reject just without the timeout.
The key is scheduled for garbage collection; it will no longer be findable,
and will be unavailable for further operations. Further attempts to use the
key will fail with the error EKEYREVOKED
.
The caller must have write or setattr permission on the key.
Sourcepub fn reject(&self, seconds: usize) -> Result<(), KeyError>
pub fn reject(&self, seconds: usize) -> Result<(), KeyError>
Mark a key as negatively instantiated and set an expiration timer on the key.
This will prevent others from retrieving the key in further searches. And they
will receive a EKEYREJECTED
error when performing the search.
Similar to Key::revoke but with a timeout.
Sourcepub fn invalidate(&self) -> Result<(), KeyError>
pub fn invalidate(&self) -> Result<(), KeyError>
Mark a key as invalid.
To invalidate a key, the caller must have search permission on the key.
This operation marks the key as invalid and schedules immediate garbage collection. The garbage collector removes the invali‐ dated key from all keyrings and deletes the key when its refer‐ ence count reaches zero. After this operation, the key will be ignored by all searches, even if it is not yet deleted.
Keys that are marked invalid become invisible to normal key oper‐
ations immediately, though they are still visible in /proc/keys
(marked with an ‘i’ flag) until they are actually removed.