Struct linux_keyutils::Key

source ·
pub struct Key(_);
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§

Initialize a new Key object from the provided ID

Obtain a copy of the ID of this key

Obtain information describing the attributes of this key.

The key must grant the caller view permission.

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

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

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.

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

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.

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.

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.

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.

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.

Trait Implementations§

Returns a copy of the value. Read more
Performs copy-assignment from source. Read more
Formats the value using the given formatter. Read more
Formats the value using the given formatter. Read more
This method tests for self and other values to be equal, and is used by ==.
This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
This method tests for self and other values to be equal, and is used by ==.
This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
This method tests for self and other values to be equal, and is used by ==.
This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

Auto Trait Implementations§

Blanket Implementations§

Gets the TypeId of self. Read more
Immutably borrows from an owned value. Read more
Mutably borrows from an owned value. Read more

Returns the argument unchanged.

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

The resulting type after obtaining ownership.
Creates owned data from borrowed data, usually by cloning. Read more
Uses borrowed data to replace owned data, usually by cloning. Read more
Converts the given value to a String. Read more
The type returned in the event of a conversion error.
Performs the conversion.
The type returned in the event of a conversion error.
Performs the conversion.