Merge pull request #8 from datachainlab/improve-docs

Fix Quote v4 verifier and improve docs

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

Author: bluele

crates/quote-verifier/src/cert.rs

@@ -5,9 +5,9 @@ use dcap_types::cert::{SgxExtensionTcbLevel, SgxExtensions};
 use dcap_types::tcbinfo::{TcbComponent, TcbInfoV3};
 use dcap_types::TcbInfoV3TcbStatus;
 use dcap_types::{SGX_TEE_TYPE, TDX_TEE_TYPE};
-use x509_parser::oid_registry::OID_X509_EXT_CRL_DISTRIBUTION_POINTS;
 use x509_parser::prelude::*;
 
+/// Parse a PEM-encoded certificate chain into a vector of `X509Certificate`.
 pub fn parse_certchain(pem_certs: &[Pem]) -> crate::Result<Vec<X509Certificate>> {
     Ok(pem_certs
         .iter()
@@ -44,7 +44,7 @@ pub fn verify_crl_signature(
     verify_p256_signature_der(data, signature, public_key)
 }
 
-// verify_certchain_signature just verify that the certchain signature matches, any other checks will be done by the caller
+/// verify_certchain_signature just verify that the certchain signature matches, any other checks will be done by the caller
 pub fn verify_certchain_signature(
     certs: &[&X509Certificate],
     root_cert: &X509Certificate,
@@ -61,67 +61,52 @@ pub fn verify_certchain_signature(
     verify_certificate(prev_cert, root_cert)
 }
 
+/// Get the Subject Common Name (CN) from a certificate.
 pub fn get_x509_subject_cn(cert: &X509Certificate) -> String {
     let subject = cert.subject();
     let cn = subject.iter_common_name().next().unwrap();
     cn.as_str().unwrap().to_string()
 }
 
+/// Get the Issuer Common Name (CN) from a certificate.
 pub fn get_x509_issuer_cn(cert: &X509Certificate) -> String {
     let issuer = cert.issuer();
     let cn = issuer.iter_common_name().next().unwrap();
     cn.as_str().unwrap().to_string()
 }
 
-pub fn get_crl_uri(cert: &X509Certificate) -> Option<String> {
-    let crl_ext = cert
-        .get_extension_unique(&OID_X509_EXT_CRL_DISTRIBUTION_POINTS)
-        .unwrap()
-        .unwrap();
-    let crl_uri = match crl_ext.parsed_extension() {
-        ParsedExtension::CRLDistributionPoints(crls) => {
-            match &crls.iter().next().unwrap().distribution_point {
-                Some(DistributionPointName::FullName(uri)) => {
-                    let uri = &uri[0];
-                    match uri {
-                        GeneralName::URI(uri) => Some(uri.to_string()),
-                        _ => None,
-                    }
-                }
-                _ => None,
-            }
-        }
-        _ => {
-            unreachable!();
-        }
-    };
-    crl_uri
-}
-
-/// https://github.com/intel/SGX-TDX-DCAP-QuoteVerificationLibrary/blob/7e5b2a13ca5472de8d97dd7d7024c2ea5af9a6ba/Src/AttestationLibrary/src/Verifiers/Checks/TcbLevelCheck.cpp#L129-L181
-pub fn get_sgx_tdx_fmspc_tcbstatus_v3(
+/// Get the TCB status of the SGX and TDX corresponding to the given SVN from the TCB Info V3.
+/// This function returns the TCB status of the SGX and TDX, and the advisory IDs.
+/// ref. <https://github.com/intel/SGX-TDX-DCAP-QuoteVerificationLibrary/blob/7e5b2a13ca5472de8d97dd7d7024c2ea5af9a6ba/Src/AttestationLibrary/src/Verifiers/Checks/TcbLevelCheck.cpp#L129-L181>
+///
+/// # Arguments
+/// * `tee_type` - The type of TEE (SGX or TDX)
+/// * `tee_tcb_svn` - The TCB SVN of the TEE (only for TDX)
+/// * `sgx_extensions` - The SGX Extensions from the PCK Certificate
+/// * `tcbinfov3` - The TCB Info V3
+/// # Returns
+/// * `(sgx_tcb_status, tdx_tcb_status, advisory_ids)` - The TCB status of the SGX and TDX, and the advisory IDs
+pub fn get_sgx_tdx_tcb_status_v3(
     tee_type: u32,
     tee_tcb_svn: Option<[u8; 16]>,
-    // SGX Extensions from the PCK Certificate
     sgx_extensions: &SgxExtensions,
     tcbinfov3: &TcbInfoV3,
 ) -> crate::Result<(TcbInfoV3TcbStatus, Option<TcbInfoV3TcbStatus>, Vec<String>)> {
-    let is_tdx = tee_type == TDX_TEE_TYPE && tcbinfov3.tcb_info.id == "TDX";
-    if !is_tdx {
-        // check if tee_type and tcb_info.id are consistent
-        assert!(tee_type == SGX_TEE_TYPE && tcbinfov3.tcb_info.id == "SGX");
-    }
-
-    let is_tdx = if tee_type == SGX_TEE_TYPE {
-        false
+    if tee_type == SGX_TEE_TYPE {
+        if tcbinfov3.tcb_info.id != "SGX" {
+            bail!("Invalid TCB Info ID for SGX TEE Type");
+        } else if tee_tcb_svn.is_some() {
+            bail!("SGX TCB SVN is not needed");
+        }
     } else if tee_type == TDX_TEE_TYPE {
-        if tee_tcb_svn.is_none() {
+        if tcbinfov3.tcb_info.id != "TDX" {
+            bail!("Invalid TCB Info ID for TDX TEE Type");
+        } else if tee_tcb_svn.is_none() {
             bail!("TDX TCB SVN is missing");
         }
-        true
     } else {
         bail!("Unsupported TEE type: {}", tee_type);
-    };
+    }
 
     // ref. https://github.com/intel/SGX-TDX-DCAP-QuoteVerificationLibrary/blob/7e5b2a13ca5472de8d97dd7d7024c2ea5af9a6ba/Src/AttestationLibrary/src/Verifiers/QuoteVerifier.cpp#L117
     if sgx_extensions.fmspc != tcbinfov3.tcb_info.fmspc()? {
@@ -148,15 +133,16 @@ pub fn get_sgx_tdx_fmspc_tcbstatus_v3(
             && extension_pcesvn >= tcb_level.tcb.pcesvn
         {
             sgx_tcb_status = Some(TcbInfoV3TcbStatus::from_str(tcb_level.tcb_status.as_str())?);
-            if !is_tdx {
+            if tee_type == SGX_TEE_TYPE {
                 return Ok((
                     sgx_tcb_status.unwrap(),
                     None,
                     tcb_level.advisory_ids.clone().unwrap_or_default(),
                 ));
             }
         }
-        if is_tdx && sgx_tcb_status.is_some() {
+
+        if tee_type == TDX_TEE_TYPE && sgx_tcb_status.is_some() {
             let tdxtcbcomponents = match &tcb_level.tcb.tdxtcbcomponents {
                 Some(cmps) => cmps,
                 None => bail!("TDX TCB Components are missing"),
@@ -178,6 +164,18 @@ pub fn get_sgx_tdx_fmspc_tcbstatus_v3(
     }
 }
 
+/// Merge two vectors of advisory ids into one vector
+/// This function will remove any duplicates
+pub fn merge_advisory_ids(advisory_ids: Vec<String>, advisory_ids2: Vec<String>) -> Vec<String> {
+    let mut ids = advisory_ids
+        .into_iter()
+        .chain(advisory_ids2)
+        .collect::<Vec<_>>();
+    ids.sort();
+    ids.dedup();
+    ids
+}
+
 fn match_sgxtcbcomp(tcb: &SgxExtensionTcbLevel, sgxtcbcomponents: &[TcbComponent; 16]) -> bool {
     // Compare all of the SGX TCB Comp SVNs retrieved from the SGX PCK Certificate (from 01 to 16) with the corresponding values of SVNs in sgxtcbcomponents array of TCB Level.
     // If all SGX TCB Comp SVNs in the certificate are greater or equal to the corresponding values in TCB Level, then return true.
@@ -197,15 +195,3 @@ fn match_tdxtcbcomp(tee_tcb_svn: &[u8; 16], tdxtcbcomponents: &[TcbComponent; 16
         .zip(tdxtcbcomponents.iter())
         .all(|(tee, tcb)| *tee >= tcb.svn)
 }
-
-/// Merge two vectors of advisory ids into one vector
-/// This function will remove any duplicates
-pub fn merge_advisory_ids(advisory_ids: Vec<String>, advisory_ids2: Vec<String>) -> Vec<String> {
-    let mut ids = advisory_ids
-        .into_iter()
-        .chain(advisory_ids2)
-        .collect::<Vec<_>>();
-    ids.sort();
-    ids.dedup();
-    ids
-}

crates/quote-verifier/src/collaterals.rs

@@ -6,36 +6,34 @@ use x509_parser::{certificate::X509Certificate, revocation_list::CertificateRevo
 
 use crate::Result;
 
-/**
- * IntelCollateral is a struct that holds the collateral data that is required to verify the
- * authenticity of the quote. This includes the TCBInfo, QEIdentity, certificates and CRLs.
- */
+/// IntelCollateral is a struct that holds the collateral data that is required to verify the
+/// authenticity of the quote. This includes the TCBInfo, QEIdentity, certificates and CRLs.
 #[derive(Clone, Debug, Default)]
 pub struct IntelCollateral {
     /// TCBInfo in JSON format
-    /// ref. https://api.portal.trustedservices.intel.com/content/documentation.html#pcs-tcb-info-model-v3
+    /// ref. <https://api.portal.trustedservices.intel.com/content/documentation.html#pcs-tcb-info-model-v3>
     pub tcbinfo_bytes: Vec<u8>,
     /// QEIdentity in JSON format
-    /// ref. https://api.portal.trustedservices.intel.com/content/documentation.html#pcs-enclave-identity-model-v2
+    /// ref. <https://api.portal.trustedservices.intel.com/content/documentation.html#pcs-enclave-identity-model-v2>
     pub qeidentity_bytes: Vec<u8>,
     /// SGX Intel Root CA certificate in DER format
-    /// ref. https://certificates.trustedservices.intel.com/Intel_SGX_Provisioning_Certification_RootCA.pem
+    /// ref. <https://certificates.trustedservices.intel.com/Intel_SGX_Provisioning_Certification_RootCA.pem>
     pub sgx_intel_root_ca_der: Vec<u8>,
     /// SGX TCB Signing certificate in DER format
     /// You can get this from the response header of the TCBInfo API
-    /// ref. https://api.portal.trustedservices.intel.com/content/documentation.html#pcs-tcb-info-v4
+    /// ref. <https://api.portal.trustedservices.intel.com/content/documentation.html#pcs-tcb-info-v4>
     pub sgx_tcb_signing_der: Vec<u8>,
     /// SGX Intel Root CA CRL in DER format
-    /// ref. https://certificates.trustedservices.intel.com/IntelSGXRootCA.der
+    /// ref. <https://certificates.trustedservices.intel.com/IntelSGXRootCA.der>
     pub sgx_intel_root_ca_crl_der: Vec<u8>,
     /// SGX PCK Platform/Processor CA CRL in DER format
     /// NOTE: This CRL issuer must be matched with the quote's PCK cert issuer
-    /// ref. https://api.portal.trustedservices.intel.com/content/documentation.html#pcs-revocation-v4
+    /// ref. <https://api.portal.trustedservices.intel.com/content/documentation.html#pcs-revocation-v4>
     pub sgx_pck_crl_der: Vec<u8>,
 }
 
 impl IntelCollateral {
-    /// Serializes the IntelCollateral struct into a Vec<u8>
+    /// Serializes the IntelCollateral struct into a `Vec<u8>`
     pub fn to_bytes(&self) -> Vec<u8> {
         // serialization scheme is simple: the bytestream is made of 2 parts
         // the first contains a u32 length for each of the members

crates/quote-verifier/src/crl.rs

@@ -142,7 +142,7 @@ impl<'a> IntelSgxCrls<'a> {
 
 /// Get the CRL type of the certificate
 /// We assume that the issuer of the certificate issues the only one type of CRL
-/// ref. p.5 https://download.01.org/intel-sgx/sgx-dcap/1.22/linux/docs/SGX_PCK_Certificate_CRL_Spec-1.4.pdf
+/// ref. p.5 <https://download.01.org/intel-sgx/sgx-dcap/1.22/linux/docs/SGX_PCK_Certificate_CRL_Spec-1.4.pdf>
 fn get_crl_type_from_cert(cert: &X509Certificate) -> Result<CrlType> {
     let issuer_cn = cert
         .issuer()
@@ -155,7 +155,7 @@ fn get_crl_type_from_cert(cert: &X509Certificate) -> Result<CrlType> {
 
 /// Get the type of the CRL from the issuer common name of the CRL
 /// We assume that the issuer of the crl issues the only one type of CRL
-/// ref. p.5 https://download.01.org/intel-sgx/sgx-dcap/1.22/linux/docs/SGX_PCK_Certificate_CRL_Spec-1.4.pdf
+/// ref. p.5 <https://download.01.org/intel-sgx/sgx-dcap/1.22/linux/docs/SGX_PCK_Certificate_CRL_Spec-1.4.pdf>
 fn get_crl_type_from_crl(crl: &CertificateRevocationList) -> Result<CrlType> {
     get_crl_type_from_issuer_cn(
         crl.issuer()

crates/quote-verifier/src/crypto.rs

@@ -3,18 +3,28 @@ use p256::ecdsa::{signature::Verifier, Signature, VerifyingKey};
 use sha2::{Digest, Sha256};
 use sha3::Keccak256;
 
-// verify_p256_signature_bytes verifies a P256 ECDSA signature
-// using the provided data, signature, and public key.
-// The data is the message that was signed as a byte slice.
-// The signature is the signature (in raw form [r][s]) of the data as a byte slice. (64 bytes)
-// The public_key is the public key (in uncompressed form [4][x][y]) of the entity that signed the data. (65 bytes)
-// Returns true if the signature is valid, false otherwise.
+/// verify_p256_signature_bytes verifies a P256 ECDSA signature
+/// 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)
+/// # Returns
+/// * Returns true if the signature is valid, false otherwise.
 pub fn verify_p256_signature_bytes(data: &[u8], signature: &[u8], public_key: &[u8]) -> Result<()> {
     let signature = Signature::from_bytes(signature.into())?;
     let verifying_key = VerifyingKey::from_sec1_bytes(public_key)?;
     Ok(verifying_key.verify(data, &signature)?)
 }
 
+/// verify_p256_signature_der verifies a P256 ECDSA signature
+/// using the provided data, signature, and 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)
+/// # Returns
+/// * Returns true if the signature is valid, false otherwise.
 pub fn verify_p256_signature_der(
     data: &[u8],
     signature_der: &[u8],
@@ -25,6 +35,7 @@ pub fn verify_p256_signature_der(
     Ok(verifying_key.verify(data, &signature)?)
 }
 
+/// sha256sum returns the SHA-256 hash of the input data.
 pub fn sha256sum(data: &[u8]) -> [u8; 32] {
     let mut hasher = Sha256::new();
     hasher.update(data);
@@ -34,6 +45,7 @@ pub fn sha256sum(data: &[u8]) -> [u8; 32] {
     output
 }
 
+/// keccak256sum returns the Keccak-256 hash of the input data.
 pub fn keccak256sum(data: &[u8]) -> [u8; 32] {
     let mut hasher = Keccak256::new();
     hasher.update(data);

crates/quote-verifier/src/enclave_identity.rs

@@ -59,7 +59,10 @@ pub fn validate_qe_identityv2(
     })
 }
 
-pub fn get_qe_tcbstatus(
+/// Get the TCB status for matching the ISV SVN of the QE report
+///
+/// ref. <https://github.com/intel/SGX-TDX-DCAP-QuoteVerificationLibrary/blob/stable/Src/AttestationLibrary/src/Verifiers/EnclaveIdentityV2.cpp#L326>
+pub fn get_qe_tcb_status(
     qe_report_isv_svn: u16,
     qeidentityv2_tcb_levels: &[EnclaveIdentityV2TcbLevelItem],
 ) -> Result<(EnclaveIdentityV2TcbStatus, Vec<String>)> {
@@ -154,23 +157,23 @@ mod tests {
         ]))
         .unwrap();
 
-        let (status, advisory_ids) = get_qe_tcbstatus(9, &tcb_levels).unwrap();
+        let (status, advisory_ids) = get_qe_tcb_status(9, &tcb_levels).unwrap();
         assert_eq!(status, EnclaveIdentityV2TcbStatus::UpToDate);
         assert!(advisory_ids.is_empty());
 
-        let (status, advisory_ids) = get_qe_tcbstatus(8, &tcb_levels).unwrap();
+        let (status, advisory_ids) = get_qe_tcb_status(8, &tcb_levels).unwrap();
         assert_eq!(status, EnclaveIdentityV2TcbStatus::UpToDate);
         assert!(advisory_ids.is_empty());
 
-        let (status, advisory_ids) = get_qe_tcbstatus(7, &tcb_levels).unwrap();
+        let (status, advisory_ids) = get_qe_tcb_status(7, &tcb_levels).unwrap();
         assert_eq!(status, EnclaveIdentityV2TcbStatus::OutOfDate);
         assert!(advisory_ids.is_empty());
 
-        let (status, advisory_ids) = get_qe_tcbstatus(5, &tcb_levels).unwrap();
+        let (status, advisory_ids) = get_qe_tcb_status(5, &tcb_levels).unwrap();
         assert_eq!(status, EnclaveIdentityV2TcbStatus::Revoked);
         assert_eq!(advisory_ids, vec!["INTEL-SA-00615"]);
 
-        let res = get_qe_tcbstatus(4, &tcb_levels);
+        let res = get_qe_tcb_status(4, &tcb_levels);
         assert!(res.is_err(), "{:?}", res);
     }
 }

crates/quote-verifier/src/quotes/mod.rs

@@ -6,7 +6,7 @@ use crate::collaterals::IntelCollateral;
 use crate::crl::IntelSgxCrls;
 use crate::crypto::sha256sum;
 use crate::crypto::verify_p256_signature_bytes;
-use crate::enclave_identity::get_qe_tcbstatus;
+use crate::enclave_identity::get_qe_tcb_status;
 use crate::enclave_identity::validate_qe_identityv2;
 use crate::pck::validate_pck_cert;
 use crate::sgx_extensions::extract_sgx_extensions;
@@ -187,7 +187,7 @@ fn check_quote_header(quote_header: &QuoteHeader, expected_quote_version: u16) -
 }
 /// Verify the QE Report and return the TCB Status and Advisory IDs
 ///
-/// ref. https://github.com/intel/SGX-TDX-DCAP-QuoteVerificationLibrary/blob/29bd3b0a3b46c1159907d656b45f378f97e7e686/Src/AttestationLibrary/src/Verifiers/EnclaveReportVerifier.cpp#L47
+/// ref. <https://github.com/intel/SGX-TDX-DCAP-QuoteVerificationLibrary/blob/29bd3b0a3b46c1159907d656b45f378f97e7e686/Src/AttestationLibrary/src/Verifiers/EnclaveReportVerifier.cpp#L47>
 /// do the following checks:
 /// - ensure that `ecdsa_attestation_key` and `qe_auth_data` are valid against the `qe_report.report_data`
 /// - validate the `qe_report` against the `qeidentityv2`
@@ -223,7 +223,7 @@ fn verify_qe_report(
     // https://github.com/intel/SGX-TDX-DCAP-QuoteVerificationLibrary/blob/29bd3b0a3b46c1159907d656b45f378f97e7e686/Src/AttestationLibrary/src/Verifiers/EnclaveReportVerifier.cpp#L92
     // https://github.com/intel/SGX-TDX-DCAP-QuoteVerificationLibrary/blob/7e5b2a13ca5472de8d97dd7d7024c2ea5af9a6ba/Src/AttestationLibrary/src/Verifiers/QuoteVerifier.cpp#L286
     let (tcb_status, advisory_ids) =
-        get_qe_tcbstatus(qe_report.isv_svn, &qeidentityv2.enclave_identity.tcb_levels)?;
+        get_qe_tcb_status(qe_report.isv_svn, &qeidentityv2.enclave_identity.tcb_levels)?;
 
     Ok(QeTcb {
         tcb_evaluation_data_number: qeidentityv2.enclave_identity.tcb_evaluation_data_number,

crates/quote-verifier/src/quotes/version_3.rs

@@ -1,6 +1,6 @@
 use super::{check_quote_header, converge_tcb_status_with_qe_tcb, verify_quote_common, Result};
 use crate::{
-    cert::{get_sgx_tdx_fmspc_tcbstatus_v3, merge_advisory_ids},
+    cert::{get_sgx_tdx_tcb_status_v3, merge_advisory_ids},
     collaterals::IntelCollateral,
     crypto::keccak256sum,
     verifier::QuoteVerificationOutput,
@@ -41,7 +41,7 @@ pub fn verify_quote_v3(
     )?;
     let TcbInfo::V3(tcb_info_v3) = tcb_info;
     let (tcb_status, _, tcb_advisory_ids) =
-        get_sgx_tdx_fmspc_tcbstatus_v3(quote.header.tee_type, None, &sgx_extensions, &tcb_info_v3)?;
+        get_sgx_tdx_tcb_status_v3(quote.header.tee_type, None, &sgx_extensions, &tcb_info_v3)?;
 
     Ok(QuoteVerificationOutput {
         version: VERIFIER_VERSION,