From 7b94783cb79dcb8ccffaf6fa8ef2968b3f4aad47 Mon Sep 17 00:00:00 2001 From: Steffen Eiden Date: Thu, 7 Mar 2024 16:27:29 +0100 Subject: [PATCH] rust/pv: More documentation Improve the API documentation of the pv crate. Acked-by: Marc Hartmayer Signed-off-by: Steffen Eiden --- rust/pv/README.md | 25 +++++++++++++++++++++++++ rust/pv/src/lib.rs | 22 +++++++++++++++------- rust/pv/src/test_utils.rs | 4 ++-- rust/pv/src/uvsecret/asrcb.rs | 4 ++-- rust/pv_core/README.md | 24 ++++++++++++++++++++++++ rust/pv_core/src/lib.rs | 15 +++++---------- rust/pv_core/src/uvdevice.rs | 29 +++++++++++++++++++++++++++-- rust/utils/src/cli.rs | 2 +- 8 files changed, 101 insertions(+), 24 deletions(-) create mode 100644 rust/pv/README.md create mode 100644 rust/pv_core/README.md diff --git a/rust/pv/README.md b/rust/pv/README.md new file mode 100644 index 00000000..fc5aa9cc --- /dev/null +++ b/rust/pv/README.md @@ -0,0 +1,25 @@ + +# s390_pv - library for pv-tools + +This library is intended to be used by tools and libraries that +are used for creating and managing [IBM Secure Execution](https://www.ibm.com/docs/en/linux-on-systems?topic=virtualization-secure-execution) guests. +`pv` provides abstraction layers for encryption, secure memory management, +and accessing the uvdevice. + +If your project is not targeted to provide tooling for and/or managing of IBM Secure execution +guests, do **not** use this crate. + +## OpenSSL 1.1.0+ is required + +If you do not need any OpenSSL features use [s390_pv_core](https://crates.io/crates/s390_pv_core). +This crate reexports all symbols from `s390_pv_core`. If your project uses this crate do **not** include `s390_pv_core` as well. + +## Import crate +The recommended way of importing this crate is: +```bash +cargo add s390_pv --rename pv +``` diff --git a/rust/pv/src/lib.rs b/rust/pv/src/lib.rs index 4ad408e7..35677c97 100644 --- a/rust/pv/src/lib.rs +++ b/rust/pv/src/lib.rs @@ -3,15 +3,23 @@ // Copyright IBM Corp. 2023, 2024 #![deny(missing_docs)] -//! pv - library for pv-tools +#![doc = include_str!("../README.md")] +//! # Manage guest secret store //! -//! This library is intened to be used by tools and libraries that -//! are used for creating and managing IBM Secure Execution guests. -//! `pv` provides abstraction layers for encryption, secure memory management, -//! and accessing the uvdevice. +//! This crate provides functionalities for creating add-secret requests. Also provides support for +//! sending those requests, list all stored secrets, and lock the secret store. //! -//! If you do not need any OpenSSL features use `pv_core`. -//! This crate reexports all symbols from `pv_core` +//! ## Create +//! [`secret::AddSecretRequest`] +//! +//! ## Add +//! [`uv::UvDevice`] and [`uv::AddCmd`] +//! +//! ## List +//! [`uv::UvDevice`] and [`uv::ListCmd`] +//! +//! ## Lock +//! [`uv::UvDevice`] and [`uv::LockCmd`] mod brcb; mod confidential; mod crypto; diff --git a/rust/pv/src/test_utils.rs b/rust/pv/src/test_utils.rs index 2db26659..141afdca 100644 --- a/rust/pv/src/test_utils.rs +++ b/rust/pv/src/test_utils.rs @@ -60,7 +60,7 @@ pub fn load_gen_cert(asset_path: &'static str) -> X509 { cert.pop().unwrap() } -/// TEST ONLY! Load the crl found in the asset path +/// TEST ONLY! Load the CRL found in the asset path /// /// panic on errors pub fn load_gen_crl(asset_path: &'static str) -> X509Crl { @@ -73,7 +73,7 @@ pub fn load_gen_crl(asset_path: &'static str) -> X509Crl { /// TEST ONLY! Get a fixed private/public pair and a fixed public key /// -/// Intened for TESTING only. All parts of the key including the private key are checked in git and +/// Intended for TESTING only. All parts of the key including the private key are checked in git and /// visible for the public pub fn get_test_keys() -> (PKey, PKey) { let pub_key = get_test_asset!("keys/public_cust.bin"); diff --git a/rust/pv/src/uvsecret/asrcb.rs b/rust/pv/src/uvsecret/asrcb.rs index 1df2fabc..4076f06e 100644 --- a/rust/pv/src/uvsecret/asrcb.rs +++ b/rust/pv/src/uvsecret/asrcb.rs @@ -217,7 +217,7 @@ impl AddSecretRequest { Ok(()) } - /// compiles the authenticated area of this request + /// Compiles the authenticated area of this request fn aad(&self, ctx: &ReqEncrCtx, conf_len: usize) -> Result> { let cust_pub_key = ctx.key_coords()?; let secr_auth = self.conf.secret.auth(); @@ -255,7 +255,7 @@ impl AddSecretRequest { Ok(res) } - /// encrypt data, sign request with user-provided signing key, insert signature into aad, + /// Encrypts data, sign request with user-provided signing key, insert signature into aad, /// calculate request tag fn encrypt_with_signed_user_data(&self, ctx: &ReqEncrCtx) -> Result> { //encrypt data w/o aead diff --git a/rust/pv_core/README.md b/rust/pv_core/README.md new file mode 100644 index 00000000..0068adf7 --- /dev/null +++ b/rust/pv_core/README.md @@ -0,0 +1,24 @@ + +# s390_pv_core - basic library for pv-tools + +This library is intended to be used by tools and libraries that +are used for creating and managing [IBM Secure Execution](https://www.ibm.com/docs/en/linux-on-systems?topic=virtualization-secure-execution) guests. +`s390_pv_core` provides abstraction layers for secure memory management, +logging, and accessing the uvdevice. + +If your project is not targeted to provide tooling for and/or managing of IBM Secure execution +guests, do **not** use this crate. + +It does not provide any cryptographic operations through OpenSSL. +For this use [s390_pv](https://crates.io/crates/s390_pv_core) which reexports all symbols from this crate. +If your project uses `s390_pv` crate do **not** include `s390_pv_core` as well. + +## Import crate +The recommended way of importing this crate is: +```bash +cargo add s390_pv_core --rename pv_core +``` diff --git a/rust/pv_core/src/lib.rs b/rust/pv_core/src/lib.rs index cb69cda8..0088af41 100644 --- a/rust/pv_core/src/lib.rs +++ b/rust/pv_core/src/lib.rs @@ -1,17 +1,9 @@ // SPDX-License-Identifier: MIT // -// Copyright IBM Corp. 2023 +// Copyright IBM Corp. 2023, 2024 #![deny(missing_docs)] #![allow(unused)] -//! pv_core - basic library for pv-tools -//! -//! This library is intened to be used by tools and libraries that -//! are used for creating and managing IBM Secure Execution guests. -//! `pv_core` provides abstraction layers for secure memory management, -//! and accessing the uvdevice. -//! -//! It does not provide any cryptographic operations through OpenSSL. -//! For this use `pv` which reexports all symbos from this crate. +#![doc = include_str!("../README.md")] mod error; mod macros; mod utils; @@ -30,6 +22,9 @@ pub mod misc { } /// Definitions and functions for interacting with the Ultravisor +/// +/// For detailed Information on how to send Ultravisor Commands see [`crate::uv::UvDevice`] and +/// [`crate::uv::UvCmd`] pub mod uv { pub use crate::uvdevice::secret::{AddCmd, ListCmd, LockCmd}; pub use crate::uvdevice::secret_list::{ListableSecretType, SecretEntry, SecretId, SecretList}; diff --git a/rust/pv_core/src/uvdevice.rs b/rust/pv_core/src/uvdevice.rs index 0f6baf79..783872ad 100644 --- a/rust/pv_core/src/uvdevice.rs +++ b/rust/pv_core/src/uvdevice.rs @@ -99,7 +99,8 @@ pub trait UvCmd { } /// Converts UV return codes into human readable error messages /// - /// no need to handle `0x0000, 0x0001, 0x0002, 0x0005, 0x0030, 0x0031, 0x0032, 0x0100` + /// # Note for implementations + /// No need to handle `0x0000, 0x0001, 0x0002, 0x0005, 0x0030, 0x0031, 0x0032, 0x0100` fn rc_fmt(&self, rc: u16, rrc: u16) -> Option<&'static str>; /// Returns data used by this command if available. @@ -158,7 +159,31 @@ pub enum UvcSuccess { RC_MORE_DATA = UvDevice::RC_MORE_DATA, } -/// The UvDevice is a (virtual) device on s390 machines to send Ultravisor commands from userspace. +/// The UvDevice is a (virtual) device on s390 machines to send Ultravisor commands(UVCs) from userspace. +/// +/// On s390 machines with Ultravisor enabled (Secure Execution guest & hosts) the device at +/// `/dev/uv` will accept ioctls. +/// +/// # Example +/// +/// Use a implementation of [`UvCmd`] to send a specific Ultravisor cammand to the uvevice to +/// forward to Firmware. +/// +/// ```rust,no_run +/// # use pv_core::uv::UvDevice; +/// # use pv_core::uv::AddCmd; +/// # use std::fs::File; +/// # fn main() -> pv_core::Result<()> { +/// let mut file = File::open("request")?; +/// let uv = UvDevice::open()?; +/// let mut cmd = AddCmd::new(&mut file)?; +/// uv.send_cmd(&mut cmd)?; +/// # Ok(()) +/// # } +/// // do something with the result +/// +/// +/// ``` pub struct UvDevice(File); impl UvDevice { diff --git a/rust/utils/src/cli.rs b/rust/utils/src/cli.rs index e2dba376..6d149eea 100644 --- a/rust/utils/src/cli.rs +++ b/rust/utils/src/cli.rs @@ -17,7 +17,7 @@ use std::io::{Read, Write}; use std::path::Path; use std::process::ExitCode; -/// CLI Argument collection for handling certificates. +/// CLI Argument collection for handling host-keys, IBM signing keys, and certificates. #[derive(Args, Debug, PartialEq, Eq, Default)] #[command( group(ArgGroup::new("pv_verify").required(true).args(["no_verify", "certs"])),