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/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