rust/pv: More documentation

Improve the API documentation of the pv crate.

Acked-by: Marc Hartmayer <mhartmay@linux.ibm.com>
Signed-off-by: Steffen Eiden <seiden@linux.ibm.com>

rust/pv/README.md

@@ -0,0 +1,25 @@
+<!--
+SPDX-License-Identifier: MIT
+
+Copyright 2024 IBM Corp.
+-->
+# 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
+```

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;

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<Private>, PKey<Public>) {
     let pub_key = get_test_asset!("keys/public_cust.bin");

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<Vec<u8>> {
         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<Vec<u8>> {
         //encrypt data w/o aead

rust/pv_core/README.md

@@ -0,0 +1,24 @@
+<!--
+SPDX-License-Identifier: MIT
+
+Copyright 2024 IBM Corp.
+-->
+# 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
+```

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};

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 {

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"])),