Add KeyRing::get_persistent (#3)

* Add KeyRing::get_persistent
* Update example to use search API
* Improve doc commments and deny warnings
* Ensure persistent User ring is different than the user ring
* Update readme, bump version, add comments to example.

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

Author: landhb

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "linux-keyutils"
-version = "0.1.0"
+version = "0.1.1"
 edition = "2021"
 authors = ["landhb <[email protected]>"]
 description = """

README.md

@@ -12,7 +12,7 @@ To use `linux-keyutils`, first add this to your `Cargo.toml`:
 linux_keyutils = "0.1"
 ```
 
-For more information please view the full [documentation](https://docs.rs/linux-keyutils).
+For more information please view the full [documentation](https://docs.rs/linux-keyutils). There is also a small example program in the [examples directory](examples/keyctl.rs).
 
 ## Features
 

examples/keyctl.rs

@@ -3,8 +3,8 @@
 //!
 //! Demo code for the linux_keyutils crate.
 use clap::Parser;
-use linux_keyutils::{Key, KeyRing, KeyRingIdentifier, KeySerialId};
 use linux_keyutils::{KeyPermissionsBuilder, Permission};
+use linux_keyutils::{KeyRing, KeyRingIdentifier};
 use std::error::Error;
 use zeroize::Zeroizing;
 
@@ -28,12 +28,12 @@ enum Command {
     /// Read the secret from a key
     Read {
         #[clap(short, long)]
-        id: i32,
+        description: String,
     },
     /// Change ownership of a key
     Chown {
         #[clap(short, long)]
-        id: i32,
+        description: String,
 
         #[clap(short, long)]
         uid: Option<u32>,
@@ -44,12 +44,12 @@ enum Command {
     /// Change permissions of a key
     Chmod {
         #[clap(short, long)]
-        id: i32,
+        description: String,
     },
     /// Invalidate a key
     Invalidate {
         #[clap(short, long)]
-        id: i32,
+        description: String,
     },
 }
 
@@ -59,35 +59,48 @@ fn main() -> Result<(), Box<dyn Error>> {
     // Obtain the default User keyring for the current UID/user
     // See [KeyRingIdentifier] and `man 2 keyctl` for more information on default
     // keyrings for processes.
-    let ring = KeyRing::from_special_id(KeyRingIdentifier::User, false)?;
+    let ring = KeyRing::get_persistent(KeyRingIdentifier::User)?;
 
     _ = match args.subcommand {
+        // Add a new key to the keyring
         Command::Create {
             description,
             secret,
         } => {
             let key = ring.add_key(&description, &secret)?;
             println!("Created key with ID {:?}", key.get_id());
         }
-        Command::Read { id } => {
-            let key = Key::from_id(KeySerialId(id));
+        // Search for an existing key by description and read the secret
+        // data from the keyring
+        Command::Read { description } => {
+            let key = ring.search(&description)?;
             let mut buf = Zeroizing::new([0u8; 2048]);
             let len = key.read(&mut buf)?;
             println!("Secret {:?}", std::str::from_utf8(&buf[..len])?);
         }
-        Command::Chown { id, uid, gid } => {
-            let key = Key::from_id(KeySerialId(id));
+        // Search for an existing key by description and attempt to
+        // change ownership of the key
+        Command::Chown {
+            description,
+            uid,
+            gid,
+        } => {
+            let key = ring.search(&description)?;
             key.chown(uid, gid)?;
         }
-        Command::Chmod { id } => {
-            let key = Key::from_id(KeySerialId(id));
+        // Search for an existing key by description and attempt to
+        // change permissions of the key
+        Command::Chmod { description } => {
+            let key = ring.search(&description)?;
             let perms = KeyPermissionsBuilder::builder()
                 .user(Permission::ALL)
                 .build();
             key.set_perm(perms)?;
         }
-        Command::Invalidate { id } => {
-            let key = Key::from_id(KeySerialId(id));
+        // Search for an existing key by description and attempt to
+        // invalidate they key
+        Command::Invalidate { description } => {
+            let key = ring.search(&description)?;
             key.invalidate()?;
         }
     };

src/ffi/functions.rs

@@ -22,19 +22,25 @@ pub(crate) fn add_key(
     ktype: KeyType,
     keyring: libc::c_ulong,
     description: &str,
-    payload: &[u8],
+    payload: Option<&[u8]>,
 ) -> Result<KeySerialId, KeyError> {
     // Perform conversion into a c string
     let description = CString::new(description).or(Err(KeyError::InvalidDescription))?;
 
+    // When creating keyrings the payload will be NULL
+    let (payload, plen) = match payload {
+        Some(p) => (p.as_ptr(), p.len()),
+        None => (core::ptr::null(), 0),
+    };
+
     // Perform the actual system call
     let res = unsafe {
         libc::syscall(
             libc::SYS_add_key,
             Into::<&'static CStr>::into(ktype).as_ptr(),
             description.as_ptr(),
-            payload.as_ptr(),
-            payload.len() as libc::size_t,
+            payload,
+            plen as libc::size_t,
             keyring as u32,
         )
     };

src/key.rs

@@ -155,7 +155,7 @@ impl Key {
     ///
     /// 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.
+    /// key will fail with the error `EKEYREVOKED`.
     ///
     /// The caller must have write or setattr permission on the key.
     pub fn revoke(&self) -> Result<(), KeyError> {

src/keyring.rs

@@ -12,11 +12,6 @@ pub struct KeyRing {
 }
 
 impl KeyRing {
-    /// 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
@@ -36,6 +31,36 @@ impl KeyRing {
         Ok(Self { id })
     }
 
+    /// Get the persistent keyring  (persistent-keyring(7)) of the current user
+    /// and link it to a specified keyring.
+    ///
+    /// If the call is successful, a link to the persistent keyring is added to the
+    /// keyring specified in the `link_with` argument.
+    ///
+    /// The caller must have write permission on the keyring.
+    ///
+    /// The persistent keyring will be created by the kernel if it does not yet exist.
+    ///
+    /// Each time the [KeyRing::get_persistent] operation is performed, the persistent
+    /// keyring will have its expiration timeout reset to the value in:
+    ///
+    ///    `/proc/sys/kernel/keys/persistent_keyring_expiry`
+    ///
+    /// Should the timeout be reached, the persistent keyring will be removed and
+    /// everything it pins can then be garbage collected.
+    ///
+    /// Persistent keyrings were added to Linux in kernel version 3.13.
+    pub fn get_persistent(link_with: KeyRingIdentifier) -> Result<Self, KeyError> {
+        let id: KeySerialId = ffi::keyctl!(
+            KeyCtlOperation::GetPersistent,
+            u32::MAX as _,
+            link_with as libc::c_ulong
+        )?
+        .try_into()
+        .or(Err(KeyError::InvalidIdentifier))?;
+        Ok(Self { id })
+    }
+
     /// Creates or updates a key of the given type and description, instantiates
     /// it with the payload of length plen, attaches it to the User keyring.
     ///
@@ -53,7 +78,7 @@ impl KeyRing {
             KeyType::User,
             self.id.as_raw_id() as libc::c_ulong,
             description.as_ref(),
-            secret.as_ref(),
+            Some(secret.as_ref()),
         )?;
         Ok(Key::from_id(id))
     }
@@ -154,6 +179,16 @@ mod test {
         assert!(ring.id.as_raw_id() > 0);
     }
 
+    #[test]
+    fn tet_get_persistent() {
+        // Test that a keyring that should already exist is returned
+        let user_ring = KeyRing::from_special_id(KeyRingIdentifier::User, false).unwrap();
+        assert!(user_ring.id.as_raw_id() > 0);
+
+        let user_perm_ring = KeyRing::get_persistent(KeyRingIdentifier::User).unwrap();
+        assert_ne!(user_ring.id.as_raw_id(), user_perm_ring.id.as_raw_id());
+    }
+
     #[test]
     fn test_search_existing_key() {
         // Test that a keyring that normally doesn't exist by default is

src/lib.rs

@@ -54,7 +54,7 @@
 //! }
 //! ```
 #![cfg_attr(not(feature = "std"), no_std)]
-//#![deny(warnings)]
+#![deny(warnings)]
 
 // no_std CStr/CString support stabilized in Rust 1.64.0
 // CString requires alloc however