From fe2946f76c50bee4e62ca3df429c206e8bb8aa68 Mon Sep 17 00:00:00 2001 From: Marc Hartmayer Date: Tue, 15 Oct 2024 16:55:34 +0000 Subject: [PATCH] rust/pv: Fix some comments The library is used by multiple PV related tools, not only for managing the guest secret store. Reviewed-by: Steffen Eiden Signed-off-by: Marc Hartmayer Signed-off-by: Steffen Eiden --- rust/pv/src/lib.rs | 2 +- rust/pv/src/uvsecret/user_data.rs | 2 +- rust/pv/src/verify.rs | 4 ++-- rust/pv/src/verify/helper.rs | 2 +- rust/pv_core/README.md | 2 +- rust/pv_core/src/confidential.rs | 2 +- rust/pv_core/src/utils.rs | 4 ++-- rust/pv_core/src/uvdevice.rs | 4 ++-- rust/pv_core/src/uvdevice/attest.rs | 8 ++++---- rust/pv_core/src/uvdevice/ffi.rs | 6 +++--- rust/pv_core/src/uvdevice/secret.rs | 2 +- rust/pv_core/src/uvdevice/secret_list.rs | 2 +- rust/pv_core/src/uvsecret.rs | 2 +- 13 files changed, 21 insertions(+), 21 deletions(-) diff --git a/rust/pv/src/lib.rs b/rust/pv/src/lib.rs index 8e0e877d..021a6306 100644 --- a/rust/pv/src/lib.rs +++ b/rust/pv/src/lib.rs @@ -11,7 +11,7 @@ unused_qualifications )] #![doc = include_str!("../README.md")] -//! # Manage guest secret store +//! # Library for Protected Virtualization (PV) related tools //! //! 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. diff --git a/rust/pv/src/uvsecret/user_data.rs b/rust/pv/src/uvsecret/user_data.rs index fd38c811..ec0b537d 100644 --- a/rust/pv/src/uvsecret/user_data.rs +++ b/rust/pv/src/uvsecret/user_data.rs @@ -141,7 +141,7 @@ impl UserData { Ok(Self::Signed(SignedUserData { sign_key, data })) } - /// Signs data in buf, writes signature to buf+user_data_offset+sign_offset if applicable. + /// Signs data in buf, writes signature to `buf+user_data_offset+sign_offset` if applicable. /// /// Uses [`MessageDigest::sha512`] as digest. Does not modify the abritary user data buffer. /// diff --git a/rust/pv/src/verify.rs b/rust/pv/src/verify.rs index 553eb7ac..161c2e67 100644 --- a/rust/pv/src/verify.rs +++ b/rust/pv/src/verify.rs @@ -23,7 +23,7 @@ use crate::Result; mod helper; mod test; -/// A HkdVerifier verifies that a host-key document(HKD) can be trusted. +/// A `HkdVerifier` verifies that a host-key document(HKD) can be trusted. /// /// If the verification fails the HKD should not be used to create requests. pub trait HkdVerifier { @@ -62,7 +62,7 @@ impl HkdVerifier for CertVerifier { /// This function verifies a host-key /// document. To do so multiple steps are required: /// - /// 1. issuer(host_key) == subject(ibm_z_sign_key) + /// 1. `issuer(host_key`) == `subject(ibm_z_sign_key`) /// 2. Signature verification /// 3. @hkd must not be expired /// 4. @hkd must not be revoked diff --git a/rust/pv/src/verify/helper.rs b/rust/pv/src/verify/helper.rs index 8c28b16d..f7d009c5 100644 --- a/rust/pv/src/verify/helper.rs +++ b/rust/pv/src/verify/helper.rs @@ -119,7 +119,7 @@ pub fn store_setup, Q: AsRef, R: AsRef>( } /// Verify that the given IBM signing keys can be trusted -/// -> check the chain: IBMsignKey<-InterCA(s)<-RootCA +/// -> check the chain: `IBMsignKey`<-InterCA(s)<-`RootCA` pub fn verify_chain( store: &X509StoreRef, untrusted_certs: &Stack, diff --git a/rust/pv_core/README.md b/rust/pv_core/README.md index 0068adf7..1c42d463 100644 --- a/rust/pv_core/README.md +++ b/rust/pv_core/README.md @@ -3,7 +3,7 @@ SPDX-License-Identifier: MIT Copyright 2024 IBM Corp. --> -# s390_pv_core - basic library for pv-tools +# `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. diff --git a/rust/pv_core/src/confidential.rs b/rust/pv_core/src/confidential.rs index ce74adc4..61d7a067 100644 --- a/rust/pv_core/src/confidential.rs +++ b/rust/pv_core/src/confidential.rs @@ -90,7 +90,7 @@ impl Confidential { &self.0 } - /// Get an immutable reference to the contained value + /// Get a mutable reference to the contained value /// /// NOTE that modifications to a mutable reference can trigger reallocation. /// e.g. a [`Vec`] might expand if more space needed. -> preallocate enough space diff --git a/rust/pv_core/src/utils.rs b/rust/pv_core/src/utils.rs index a193fdc2..515f7270 100644 --- a/rust/pv_core/src/utils.rs +++ b/rust/pv_core/src/utils.rs @@ -214,8 +214,8 @@ pub fn create_file>(path: P) -> Result { /// If this function encounters an "end of file" before completely filling /// the buffer, it returns an error. The contents of `buf` are unspecified in this case. /// -/// If aber so hast du mmmeny other read error is encountered then this function immediately -/// returns. The contents of `buf` are unspecified in this case. +/// If any other read error occurs, this function returns immediately. The +/// contents of `buf` are unspecified in this case. /// /// If this function returns an error, it is unspecified how many bytes it /// has read, but it will never read more than would be necessary to diff --git a/rust/pv_core/src/uvdevice.rs b/rust/pv_core/src/uvdevice.rs index 3778b69f..d4176815 100644 --- a/rust/pv_core/src/uvdevice.rs +++ b/rust/pv_core/src/uvdevice.rs @@ -95,7 +95,7 @@ pub trait UvCmd { /// /// # Returns /// - /// The IOCTL cmd for this UvCmd usually something like `uv_ioctl!(CMD_NR)` + /// The IOCTL cmd for this `UvCmd` usually something like `uv_ioctl!(CMD_NR)` fn cmd(&self) -> u64 { uv_ioctl(Self::UV_IOCTL_NR) } @@ -162,7 +162,7 @@ pub enum UvcSuccess { RC_MORE_DATA = UvDevice::RC_MORE_DATA, } -/// The UvDevice is a (virtual) device on s390 machines to send Ultravisor commands(UVCs) from +/// 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 diff --git a/rust/pv_core/src/uvdevice/attest.rs b/rust/pv_core/src/uvdevice/attest.rs index eb5f1c7f..66be3966 100644 --- a/rust/pv_core/src/uvdevice/attest.rs +++ b/rust/pv_core/src/uvdevice/attest.rs @@ -242,10 +242,10 @@ impl ffi::uvio_attest { /// /// # SAFETY /// It is safe to call this function iff: - /// - arcb.len() < u32::MAX - /// - additional.len() < u32::MAX - /// - user_len() <= 256 - /// - pointyer fit into an u64 + /// - `arcb.len() < u32::MAX` + /// - `additional.len() < u32::MAX` + /// - `user_len() <= 256` + /// - pointer fits into an u64 unsafe fn new( arcb: &[u8], measurement: &mut [u8], diff --git a/rust/pv_core/src/uvdevice/ffi.rs b/rust/pv_core/src/uvdevice/ffi.rs index d061860a..bbcc5867 100644 --- a/rust/pv_core/src/uvdevice/ffi.rs +++ b/rust/pv_core/src/uvdevice/ffi.rs @@ -28,7 +28,7 @@ pub const UVIO_IOCTL_LOCK_SECRETS_NR: u8 = 4; /// Programs can use this struct to communicate with the uvdevice via IOCTLs /// `argument_{addr,len}` specifies in/out data depending on the request /// -/// 'uv_rc' and `uv_rrc` are the response and reason response codes from the +/// `uv_rc` and `uv_rrc` are the response and reason response codes from the /// Ultravisor. /// /// `flags` is currently unused and to be set zero @@ -55,7 +55,7 @@ assert_size!(uvio_ioctl_cb, 0x40); /// If the bit is set in both, `supp_uvio_cmds` and `supp_uv_cmds`, /// the uvdevice and the Ultravisor support that call. /// -/// Note that bit 0 (UVIO_IOCTL_UVDEV_INFO_NR) is always zero for `supp_uv_cmds` +/// Note that bit 0 (`UVIO_IOCTL_UVDEV_INFO_NR`) is always zero for `supp_uv_cmds` /// as there is no corresponding UV-call. #[repr(C)] #[derive(Debug, Copy, Clone, AsBytes, FromZeroes, FromBytes)] @@ -103,7 +103,7 @@ pub struct uvio_attest { } assert_size!(uvio_attest, 0x138); -/// corresponds to the UV_IOCTL macro +/// corresponds to the `UV_IOCTL` macro pub(crate) const fn uv_ioctl(nr: u8) -> u64 { iowr(UVIO_TYPE_UVC, nr, size_of::()) } diff --git a/rust/pv_core/src/uvdevice/secret.rs b/rust/pv_core/src/uvdevice/secret.rs index b31b0bf5..277fe691 100644 --- a/rust/pv_core/src/uvdevice/secret.rs +++ b/rust/pv_core/src/uvdevice/secret.rs @@ -54,7 +54,7 @@ impl AddCmd { /// # Errors /// /// This function will return an error if the provided data does not start with the - /// ['crate::AddSecretRequest'] magic Value. + /// [`crate::AddSecretRequest`] magic Value. pub fn new(bin_add_secret_req: &mut R) -> Result { let mut data = Vec::with_capacity(PAGESIZE); bin_add_secret_req.read_to_end(&mut data)?; diff --git a/rust/pv_core/src/uvdevice/secret_list.rs b/rust/pv_core/src/uvdevice/secret_list.rs index 8bfcefff..8aab4359 100644 --- a/rust/pv_core/src/uvdevice/secret_list.rs +++ b/rust/pv_core/src/uvdevice/secret_list.rs @@ -177,7 +177,7 @@ impl FromIterator for SecretList { } impl SecretList { - /// Creates a new SecretList. + /// Creates a new `SecretList`. /// /// The content of this list will very likely not represent the status of the guest in the /// Ultravisor. Use of [`SecretList::decode`] in any non-test environments is encuraged. diff --git a/rust/pv_core/src/uvsecret.rs b/rust/pv_core/src/uvsecret.rs index 472c8957..c0765e8f 100644 --- a/rust/pv_core/src/uvsecret.rs +++ b/rust/pv_core/src/uvsecret.rs @@ -11,7 +11,7 @@ use byteorder::{BigEndian, ByteOrder}; use std::{fmt::Display, mem::size_of}; use zerocopy::{AsBytes, U16}; -/// The magic value used to identify an ['crate:AddSecretRequest'] +/// The magic value used to identify an [`crate:AddSecretRequest`] /// /// The magic value is ASCII: /// ```rust