improve docs

Signed-off-by: Jun Kimura <jun.kimura@datachain.jp>

Author: bluele

crates/quote-verifier/src/crypto.rs

@@ -7,8 +7,8 @@ use sha3::Keccak256;
 /// using the provided data, signature, and public key.
 /// # Arguments
 /// * `data` - The data that was signed.
-/// * `signature` - The signature is the signature (in raw form [r][s]) of the data as a byte slice. (64 bytes)
-/// * `public_key` - The public key (in uncompressed form [4][x][y]) of the entity that signed the data. (65 bytes)
+/// * `signature` - The signature is the signature (in raw form \[r\]\[s\]) of the data as a byte slice. (64 bytes)
+/// * `public_key` - The public key (in uncompressed form \[4\]\[\x\]\[y\]) of the entity that signed the data. (65 bytes)
 /// # Returns
 /// * Returns true if the signature is valid, false otherwise.
 pub fn verify_p256_signature_bytes(data: &[u8], signature: &[u8], public_key: &[u8]) -> Result<()> {
@@ -22,7 +22,7 @@ pub fn verify_p256_signature_bytes(data: &[u8], signature: &[u8], public_key: &[
 /// # Arguments
 /// * `data` - The data that was signed.
 /// * `signature_der` - The der encoded signature of the data as a byte slice.
-/// * `public_key` - The public key (in uncompressed form [4][x][y]) of the entity that signed the data. (65 bytes)
+/// * `public_key` - The public key (in uncompressed form \[4\]\[\x\]\[y\]) of the entity that signed the data. (65 bytes)
 /// # Returns
 /// * Returns true if the signature is valid, false otherwise.
 pub fn verify_p256_signature_der(

crates/quote-verifier/src/tdx_module.rs

@@ -8,7 +8,7 @@ use std::str::FromStr;
 /// ref. <https://github.com/intel/SGX-TDX-DCAP-QuoteVerificationLibrary/blob/7e5b2a13ca5472de8d97dd7d7024c2ea5af9a6ba/Src/AttestationLibrary/src/Verifiers/Checks/TdxModuleCheck.cpp#L62-L97>
 ///
 /// # Arguments
-/// - `tee_tcb_svn`: The SVN of the TEE TCB extracted from the `TD10ReportBody::tee_tcb_svn`
+/// - `tee_tcb_svn`: The SVN of the TEE TCB extracted from the `TD10ReportBody`
 /// - `tcb_info_v3`: The TDX TCB Info V3
 /// # Returns
 /// - The TCB status of the TDX module

crates/types/src/lib.rs

@@ -9,20 +9,21 @@ pub mod quotes;
 pub mod tcbinfo;
 pub mod utils;
 
+// ref. p.37 <https://download.01.org/intel-sgx/sgx-dcap/1.22/linux/docs/Intel_TDX_DCAP_Quoting_Library_API.pdf>
 pub const SGX_TEE_TYPE: u32 = 0x00000000;
+// ref. p.37 <https://download.01.org/intel-sgx/sgx-dcap/1.22/linux/docs/Intel_TDX_DCAP_Quoting_Library_API.pdf>
 pub const TDX_TEE_TYPE: u32 = 0x00000081;
 
+/// ref. p.68 <https://download.01.org/intel-sgx/sgx-dcap/1.22/linux/docs/Intel_SGX_ECDSA_QuoteLibReference_DCAP_API.pdf>
 pub const ECDSA_256_WITH_P256_CURVE: u16 = 2;
-
-pub const HEADER_LEN: usize = 48;
-
-pub const ENCLAVE_REPORT_LEN: usize = 384;
-pub const TD10_REPORT_LEN: usize = 584;
-pub const TD15_REPORT_LEN: usize = 684;
-
+/// ref. p.68 <https://download.01.org/intel-sgx/sgx-dcap/1.22/linux/docs/Intel_SGX_ECDSA_QuoteLibReference_DCAP_API.pdf>
 pub const INTEL_QE_VENDOR_ID: [u8; 16] = [
     0x93, 0x9A, 0x72, 0x33, 0xF7, 0x9C, 0x4C, 0xA9, 0x94, 0x0A, 0x0D, 0xB3, 0x95, 0x7F, 0x06, 0x07,
 ];
+/// ref. p.69 <https://download.01.org/intel-sgx/sgx-dcap/1.22/linux/docs/Intel_SGX_ECDSA_QuoteLibReference_DCAP_API.pdf>
+pub const ENCLAVE_REPORT_LEN: usize = 384;
+/// ref. p.37 <https://download.01.org/intel-sgx/sgx-dcap/1.22/linux/docs/Intel_TDX_DCAP_Quoting_Library_API.pdf>
+pub const TD10_REPORT_LEN: usize = 584;
 
 pub(crate) type Result<T> = core::result::Result<T, anyhow::Error>;
 

crates/types/src/quotes/body.rs

@@ -154,20 +154,20 @@ pub struct TD10ReportBody {
     /// Must be zero for TDX 1.0 [8 bytes]
     pub td_attributes: u64,
     /// TD Attributes [8 bytes]
-    /// [0:7]    : (TUD) TD Under Debug flags.
+    /// \[0:7\]    : (TUD) TD Under Debug flags.
     ///            If any of the bits in this group are set to 1, the TD is untrusted.
-    ///            [0]     - (DEBUG) Defines whether the TD runs in TD debug mode (set to 1) or not (set to 0).
+    ///            \[0\]     - (DEBUG) Defines whether the TD runs in TD debug mode (set to 1) or not (set to 0).
     ///                      In TD debug mode, the CPU state and private memory are accessible by the host VMM.
-    ///            [1:7]   - (RESERVED) Reserved for future TUD flags, must be 0.
-    /// [8:31]   : (SEC) Attributes that may impact the security of the TD
-    ///            [8:27]  - (RESERVED) Reserved for future SEC flags, must be 0.
-    ///            [28]    - (SEPT_VE_DISABLE) Disable EPT violation conversion to #VE on TD access of PENDING pages
-    ///            [29]    - (RESERVED) Reserved for future SEC flags, must be 0.
-    ///            [30]    - (PKS) TD is allowed to use Supervisor Protection Keys.
-    ///            [31]    - (KL) TD is allowed to use Key Locker.
-    /// [32:63]  : (OTHER) Attributes that do not impact the security of the TD
-    ///            [32:62] - (RESERVED) Reserved for future OTHER flags, must be 0.
-    ///            [63]    - (PERFMON) TD is allowed to use Perfmon and PERF_METRICS capabilities.
+    ///            \[1:7\]   - (RESERVED) Reserved for future TUD flags, must be 0.
+    /// \[8:31]   : (SEC) Attributes that may impact the security of the TD
+    ///            \[8:27\]  - (RESERVED) Reserved for future SEC flags, must be 0.
+    ///            \[28\]    - (SEPT_VE_DISABLE) Disable EPT violation conversion to #VE on TD access of PENDING pages
+    ///            \[29\]    - (RESERVED) Reserved for future SEC flags, must be 0.
+    ///            \[30\]    - (PKS) TD is allowed to use Supervisor Protection Keys.
+    ///            \[31\]    - (KL) TD is allowed to use Key Locker.
+    /// \[32:63]  : (OTHER) Attributes that do not impact the security of the TD
+    ///            \[32:62\] - (RESERVED) Reserved for future OTHER flags, must be 0.
+    ///            \[63\]    - (PERFMON) TD is allowed to use Perfmon and PERF_METRICS capabilities.
     pub xfam: u64,
     /// (SHA384) Measurement of the initial contents of the TD. [48 bytes]
     pub mrtd: [u8; 48],

crates/types/src/quotes/version_4.rs

@@ -4,17 +4,20 @@ use anyhow::bail;
 
 #[derive(Clone, Debug)]
 pub struct QuoteV4 {
-    pub header: QuoteHeader, // [48 bytes]
-    // Header of Quote data structure.
-    // This field is transparent (the user knows its internal structure).
-    // Rest of the Quote data structure can be treated as opaque (hidden from the user).
-    pub quote_body: QuoteBody, // May either contain a SGX Enclave Report (384 bytes) or TD10 Report (584 bytes)
-    pub signature_len: u32,    // [4 bytes]
-    // Size of the Quote Signature Data structure in bytes.
-    pub signature: QuoteSignatureDataV4, // [variable bytes]
+    /// Header of Quote data structure.
+    /// This field is transparent (the user knows its internal structure).
+    /// Rest of the Quote data structure can be treated as opaque (hidden from the user).
+    pub header: QuoteHeader,
+    /// May either contain a SGX Enclave Report (384 bytes) or TD10 Report (584 bytes)
+    pub quote_body: QuoteBody,
+    /// Size of the Quote Signature Data structure in bytes.
+    pub signature_len: u32,
+    /// Quote Signature Data
+    pub signature: QuoteSignatureDataV4,
 }
 
 impl QuoteV4 {
+    /// Parse a byte slice into a `QuoteV4` structure.
     pub fn from_bytes(raw_bytes: &[u8]) -> Result<Self> {
         let header = QuoteHeader::from_bytes(&raw_bytes[0..48]);
         let quote_body;
@@ -55,17 +58,17 @@ impl QuoteV4 {
 
 #[derive(Clone, Debug)]
 pub struct QuoteSignatureDataV4 {
-    pub quote_signature: [u8; 64], // [64 bytes]
-    // ECDSA signature, the r component followed by the s component, 2 x 32 bytes.
-    // Public part of the Attestation Key generated by the Quoting Enclave.
-    pub ecdsa_attestation_key: [u8; 64], // [64 bytes]
-    // EC KT-I Public Key, the x-coordinate followed by the y-coordinate (on the RFC 6090 P-256 curve), 2 x 32 bytes.
-    // Public part of the Attestation Key generated by the Quoting Enclave.
-    pub qe_cert_data: CertData, // [variable bytes]
-                                // QE Cert Data
+    /// ECDSA signature, the r component followed by the s component, 2 x 32 bytes.
+    pub quote_signature: [u8; 64],
+    /// Public part of the Attestation Key generated by the Quoting Enclave.
+    /// EC KT-I Public Key, the x-coordinate followed by the y-coordinate (on the RFC 6090 P-256 curve), 2 x 32 bytes.
+    pub ecdsa_attestation_key: [u8; 64],
+    /// QE Cert Data
+    pub qe_cert_data: CertData,
 }
 
 impl QuoteSignatureDataV4 {
+    /// Parse a byte slice into a `QuoteSignatureDataV4` structure.
     pub fn from_bytes(raw_bytes: &[u8]) -> Self {
         let mut quote_signature = [0; 64];
         quote_signature.copy_from_slice(&raw_bytes[0..64]);