linux_keyutils/
lib.rs

1//! Rust interface to the Linux key-management facility.
2//! Provides a safe interface around the raw system calls allowing
3//! user-space programs to perform key manipulation.
4//!
5//! Example usage:
6//!
7//! ```
8//! use linux_keyutils::{Key, KeyRing, KeyError, KeyRingIdentifier};
9//! use linux_keyutils::{KeyPermissionsBuilder, Permission};
10//!
11//! fn main() -> Result<(), KeyError> {
12//!     // Obtain the default session keyring for the current process
13//!     // See [KeyRingIdentifier] and `man 2 keyctl` for more information on default
14//!     // keyrings for processes.
15//!     let ring = KeyRing::from_special_id(KeyRingIdentifier::Session, false)?;
16//!
17//!     // Insert a new key
18//!     let key = ring.add_key("my-new-key", b"secret")?;
19//!
20//!     // Utiltiies to create proper permissions
21//!     let perms = KeyPermissionsBuilder::builder()
22//!         .posessor(Permission::ALL)
23//!         .user(Permission::ALL)
24//!         .group(Permission::VIEW | Permission::READ)
25//!         .build();
26//!
27//!     // Perform manipulations on the key such as setting permissions
28//!     key.set_perms(perms)?;
29//!
30//!     // Or setting a timeout for how long the key should exist
31//!     key.set_timeout(300)?;
32//!
33//!     // Or invalidating (removing) the key
34//!     key.invalidate()?;
35//!     Ok(())
36//! }
37//! ```
38//!
39//! To look for an existing key you can use the [KeyRing::search] method. Usage:
40//!
41//! ```
42//! use linux_keyutils::{Key, KeyRing, KeyError, KeyRingIdentifier};
43//! use linux_keyutils::{KeyPermissionsBuilder, Permission};
44//!
45//! fn get_key(description: &str) -> Result<Key, KeyError> {
46//!     // Obtain the default session keyring for the current process
47//!     // See `KeyRingIdentifier` and `man 7 keyrings` for more information on default
48//!     // keyrings for processes and users.
49//!     let ring = KeyRing::from_special_id(KeyRingIdentifier::Session, false)?;
50//!
51//!     // Lookup an existing key
52//!     let key = ring.search(description)?;
53//!     Ok(key)
54//! }
55//! ```
56#![cfg_attr(not(feature = "std"), no_std)]
57#![deny(warnings)]
58
59// CString requires alloc however
60extern crate alloc;
61
62// Use the std-lib when available
63#[cfg(feature = "std")]
64mod utils {
65    pub use std::ffi::{CStr, CString};
66    pub use std::string::String;
67    pub use std::vec::Vec;
68}
69
70// #![no_std] CStr/CString support stabilized in Rust 1.64.0
71#[cfg(not(feature = "std"))]
72mod utils {
73    pub use alloc::ffi::CString;
74    pub use alloc::string::String;
75    pub use alloc::vec::Vec;
76    pub use core::ffi::CStr;
77}
78
79// Internal FFI for raw syscalls
80mod ffi;
81
82// Export certain FFI types
83pub use ffi::{KeyRingIdentifier, KeySerialId, KeyType};
84
85// Expose error types
86mod errors;
87pub use errors::KeyError;
88
89// Primary keyring interface
90mod keyring;
91pub use keyring::KeyRing;
92
93// Primary key interface
94mod key;
95pub use key::Key;
96
97// Information about nodes (either keys or keyrings)
98mod metadata;
99pub use metadata::Metadata;
100
101// Nodes in a ring/tree
102mod links;
103pub use links::{LinkNode, Links};
104
105// Expose KeyPermissions API
106mod permissions;
107pub use permissions::{KeyPermissions, KeyPermissionsBuilder, Permission};
linux_keyutils/lib.rs

linux_keyutils/
lib.rs
