Finish implementing KeyRing interface (#2)

* Implement `KeyRing::link` and `KeyRing::unlink`
* Implement `KeyRing::clear`
* Add `Key::set_timeout` method
* Add `Key::reject` and `Key::revoke`

Co-authored-by: landhb <[email protected]>

Author: landhb

.github/workflows/checks.yml

@@ -37,7 +37,7 @@ jobs:
           override: true
           components: clippy
     - name: Run Clippy
-      run: cargo clippy --verbose
+      run: cargo clippy --verbose -- --deny "warnings"
     - name: Run RustFmt
       run: cargo fmt -- --check
 

README.md

@@ -12,7 +12,7 @@ To use `linux-keyutils`, first add this to your `Cargo.toml`:
 linux_keyutils = "0.1"
 ```
 
-For more please view the full [documentation](https://docs.rs/linux-keyutils).
+For more information please view the full [documentation](https://docs.rs/linux-keyutils).
 
 ## Features
 

src/errors.rs

@@ -6,6 +6,7 @@ use core::fmt::Result;
 #[cfg(feature = "std")]
 use std::error::Error;
 
+/// Error type for this library, optionally implements `std::error::Error`.
 #[allow(dead_code)]
 #[derive(Debug, Copy, Clone, PartialEq, Eq, PartialOrd, Ord, Hash)]
 pub enum KeyError {

src/ffi/types.rs

@@ -3,20 +3,14 @@
 use crate::KeyError;
 use core::ffi::CStr;
 
-/// Serial Number for a Key
-///
-/// Returned by the kernel.
+/// Primary kernel identifier for a key or keyring.
 #[derive(Debug, Copy, Clone, PartialEq, Eq)]
 pub struct KeySerialId(pub i32);
 
-/// The key type is a string that specifies the key's type. Internally, the kernel
-/// defines a number of key types that are available in the core key management code.
-/// The types defined for user-space use and can be specified as the type argument to
-/// add_key() are defined in this enum.
+/// Pre-defined key types the kernel understands. See `man 7 keyrings`.
 pub enum KeyType {
     /// Keyrings  are  special  key  types that may contain links to sequences of other
-    /// keys of any type.  If `add_key` is used to create a keyring, then payload
-    /// should be NULL and plen should be zero.
+    /// keys of any type.
     KeyRing,
     /// This is a general purpose key type whose payload may be read and updated by
     /// user-space  applications. The  key is kept entirely within kernel memory.
@@ -32,6 +26,7 @@ pub enum KeyType {
     BigKey,
 }
 
+/// Special identifiers for default keyrings. See `man 7 keyrings`.
 #[allow(dead_code)]
 pub enum KeyRingIdentifier {
     /// Key ID for thread-specific keyring
@@ -172,8 +167,6 @@ impl TryFrom<u64> for KeySerialId {
     type Error = KeyError;
 
     fn try_from(n: u64) -> Result<Self, Self::Error> {
-        Ok(Self {
-            0: n.try_into().or(Err(KeyError::InvalidIdentifier))?,
-        })
+        Ok(Self(n.try_into().or(Err(KeyError::InvalidIdentifier))?))
     }
 }

src/key.rs

@@ -3,9 +3,7 @@ use crate::{KeyError, KeyPermissions};
 use alloc::string::String;
 use core::fmt;
 
-/// Rust Interface for KeyCtl operations using the kernel
-/// provided keyrings. Each method is implemented to leverage
-/// Rust strict typing.
+/// A key corresponding to a specific real ID.
 #[derive(Debug, Copy, Clone)]
 pub struct Key(KeySerialId);
 
@@ -17,7 +15,7 @@ impl fmt::Display for Key {
 }
 
 impl Key {
-    /// Initialize a new `KeyCtl` object from the provided ID
+    /// Initialize a new [Key] object from the provided ID
     pub fn from_id(id: KeySerialId) -> Self {
         Self(id)
     }
@@ -31,8 +29,8 @@ impl Key {
     ///
     /// The key must grant the caller view permission.
     ///
-    /// The returned string is null-terminated and contains the following
-    /// information about the key:
+    /// The returned string contains the following information about
+    /// the key:
     ///
     /// `type;uid;gid;perm;description`
     ///
@@ -58,14 +56,15 @@ impl Key {
     /// 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).
-    ///
-    /// The returned data will be processed for presentation according to
-    /// the key type. For example, a keyring will  return  an  array  of
-    /// key_serial_t entries  representing  the IDs of all the keys that
-    /// are linked to it. The user key type will return its data as is.
-    /// If a key type does not implement this function, the operation
-    /// fails with the error EOPNOTSUPP.
     pub fn read<T: AsMut<[u8]>>(&self, buffer: &mut T) -> Result<usize, KeyError> {
+        // TODO: alternate key types? Currenlty we only support KeyType::User
+        //
+        // The returned data will be processed for presentation according to
+        // the key type. For example, a keyring will  return  an  array  of
+        // key_serial_t entries  representing  the IDs of all the keys that
+        // are linked to it. The user key type will return its data as is.
+        // If a key type does not implement this function, the operation
+        // fails with the error EOPNOTSUPP.
         let len = ffi::keyctl!(
             KeyCtlOperation::Read,
             self.0.as_raw_id() as libc::c_ulong,
@@ -80,7 +79,7 @@ impl Key {
     /// 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 `KeyCtl::reject`)
+    /// A negatively instantiated key (see the description of [Key::reject])
     /// can be positively instantiated with this operation.
     pub fn update<T: AsRef<[u8]>>(&self, update: &T) -> Result<(), KeyError> {
         _ = ffi::keyctl!(
@@ -127,23 +126,72 @@ impl Key {
         Ok(())
     }
 
-    pub fn set_timeout() {
-        todo!()
+    /// 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.
+    pub fn set_timeout(&self, seconds: usize) -> Result<(), KeyError> {
+        _ = ffi::keyctl!(
+            KeyCtlOperation::SetTimeout,
+            self.0.as_raw_id() as libc::c_ulong,
+            seconds as _
+        )?;
+        Ok(())
+    }
+
+    /// 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.
+    pub fn revoke(&self) -> Result<(), KeyError> {
+        _ = ffi::keyctl!(KeyCtlOperation::Revoke, self.0.as_raw_id() as libc::c_ulong)?;
+        Ok(())
+    }
+
+    /// 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.
+    pub fn reject(&self, seconds: usize) -> Result<(), KeyError> {
+        _ = ffi::keyctl!(
+            KeyCtlOperation::Reject,
+            self.0.as_raw_id() as libc::c_ulong,
+            seconds as _,
+            libc::EKEYREJECTED as _
+        )?;
+        Ok(())
     }
 
     /// 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‐
+    /// 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
+    /// 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
+    /// ations  immediately,  though they are still visible in `/proc/keys`
     /// (marked with an 'i' flag) until they are actually removed.
     pub fn invalidate(&self) -> Result<(), KeyError> {
         ffi::keyctl!(
@@ -195,25 +243,4 @@ mod tests {
         assert_eq!("wow".as_bytes(), &buf[..len]);
         key.invalidate().unwrap()
     }
-    /*
-    #[test]
-    fn test_user_keyring_chmod() {
-        let secret = "Test Data";
-        let id = ffi::add_key(
-            KeyType::User,
-            KeyringIdentifier::User,
-            "my-super-secret-test-key2",
-            secret.as_bytes(),
-        )
-        .unwrap();
-        let mut buf = [0u8; 4096];
-
-        let euid = unsafe { libc::geteuid() };
-
-        let keyctl = KeyCtl::from_id(id);
-        keyctl.chown(Some(euid), Some(0)).unwrap();
-        let len = keyctl.read(&mut buf).unwrap();
-        assert_eq!(secret.as_bytes(), &buf[..len]);
-        keyctl.invalidate().unwrap()
-    }*/
 }

src/keyring.rs

@@ -4,28 +4,27 @@ use alloc::ffi::CString;
 use core::convert::TryInto;
 use core::ffi::CStr;
 
-/// Rust Interface for KeyRing operations using the kernel
-/// provided keyrings. Used to locate, create, search, add,
-/// and remove keys to & from keyrings.
+/// Interface to perform keyring operations. Used to locate, create,
+/// search, add, and link/unlink keys to & from keyrings.
 #[derive(Debug, Copy, Clone)]
 pub struct KeyRing {
     id: KeySerialId,
 }
 
 impl KeyRing {
-    /// Obtain a KeyRing directly from its ID
-    pub const fn from_id(id: KeySerialId) -> Self {
-        Self { id }
+    /// Create a new keyring with the given description
+    pub fn create<D: AsRef<str> + ?Sized>(_description: &D) -> Result<Self, KeyError> {
+        todo!()
     }
 
     /// 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.
+    /// 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.
+    /// Internally this uses KEYCTL_GET_KEYRING_ID to resolve a keyrings
+    /// real ID from the special identifier.
     pub fn from_special_id(id: KeyRingIdentifier, create: bool) -> Result<Self, KeyError> {
         let id: KeySerialId = ffi::keyctl!(
             KeyCtlOperation::GetKeyRingId,
@@ -59,12 +58,10 @@ impl KeyRing {
         Ok(Key::from_id(id))
     }
 
-    /// Search for a key in a keyring tree, returning its ID and optionally linking
-    /// it to a specified keyring.
+    /// Search for a key in the keyring tree, starting with this keyring as the head,
+    /// returning its ID.
     ///
-    /// The tree to be searched is specified by passing the ID of the head keyring
-    /// in arg2 (cast to key_serial_t). The search is performed breadth-first and
-    /// recursively.
+    /// 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
@@ -92,7 +89,7 @@ impl KeyRing {
         Ok(Key::from_id(id))
     }
 
-    /// Create a link from a keyring to a key.
+    /// 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.
@@ -106,22 +103,37 @@ impl KeyRing {
     ///
     /// The caller must have link permission on the key being added and write
     /// permission on the keyring.
-    pub fn link_key() {}
+    pub fn link_key(&self, key: Key) -> Result<(), KeyError> {
+        _ = ffi::keyctl!(
+            KeyCtlOperation::Link,
+            key.get_id().as_raw_id() as _,
+            self.id.as_raw_id() as libc::c_ulong
+        )?;
+        Ok(())
+    }
 
-    /// Unlink a key from a keyring.
+    /// 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.
-    pub fn unlink_key() {}
+    pub fn unlink_key(&self, key: Key) -> Result<(), KeyError> {
+        _ = ffi::keyctl!(
+            KeyCtlOperation::Unlink,
+            key.get_id().as_raw_id() as _,
+            self.id.as_raw_id() as libc::c_ulong
+        )?;
+        Ok(())
+    }
 
     /// Clear the contents of (i.e., unlink all keys from) this keyring.
     ///
     /// The caller must have write permission on the keyring.
-    pub fn clear(&self) {
-        todo!()
+    pub fn clear(&self) -> Result<(), KeyError> {
+        _ = ffi::keyctl!(KeyCtlOperation::Clear, self.id.as_raw_id() as libc::c_ulong)?;
+        Ok(())
     }
 }
 

src/lib.rs

@@ -27,6 +27,9 @@
 //!     // Perform manipulations on the key such as setting permissions
 //!     key.set_perm(perms)?;
 //!
+//!     // Or setting a timeout for how long the key should exist
+//!     key.set_timeout(300)?;
+//!
 //!     // Or invalidating (removing) the key
 //!     key.invalidate()?;
 //!     Ok(())
@@ -41,8 +44,8 @@
 //!
 //! fn get_key(description: &str) -> Result<Key, KeyError> {
 //!     // Obtain the default session keyring for the current process
-//!     // See [KeyRingIdentifier] and `man 2 keyctl` for more information on default
-//!     // keyrings for processes.
+//!     // See `KeyRingIdentifier` and `man 7 keyrings` for more information on default
+//!     // keyrings for processes and users.
 //!     let ring = KeyRing::from_special_id(KeyRingIdentifier::Session, false)?;
 //!
 //!     // Lookup an existing key

src/permissions.rs

@@ -30,6 +30,7 @@ pub struct KeyPermissions(u32);
 pub struct KeyPermissionsBuilder(KeyPermissions);
 
 bitflags! {
+    /// Pre-defined bit-flags to construct permissions easily.
     pub struct Permission: u8 {
         /// Allows viewing a key's attributes
         const VIEW = 0x1;