teaclave-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From ms...@apache.org
Subject [incubator-teaclave] branch master updated: [attestation] Improve doumentation and API polishing (#270)
Date Wed, 22 Apr 2020 03:26:14 GMT
This is an automated email from the ASF dual-hosted git repository.

mssun pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/incubator-teaclave.git


The following commit(s) were added to refs/heads/master by this push:
     new 159fd7d  [attestation] Improve doumentation and API polishing (#270)
159fd7d is described below

commit 159fd7d9c4eea2f72f4fd55ca66cc73321b627ed
Author: Mingshen Sun <bob@mssun.me>
AuthorDate: Tue Apr 21 20:26:06 2020 -0700

    [attestation] Improve doumentation and API polishing (#270)
---
 attestation/Cargo.toml                     |  4 +-
 attestation/src/attestation.rs             | 54 +++++++++---------
 attestation/src/cert.rs                    |  5 +-
 attestation/src/key.rs                     | 25 +++++++--
 attestation/src/lib.rs                     |  9 ++-
 attestation/src/platform.rs                | 89 ++++++++++++++++++++++++------
 attestation/src/report.rs                  | 11 ++--
 attestation/src/service.rs                 | 43 ++++++++++-----
 attestation/src/verifier.rs                | 22 +++++---
 services/access_control/enclave/src/lib.rs |  3 +-
 services/authentication/enclave/src/lib.rs |  3 +-
 services/frontend/enclave/src/lib.rs       |  3 +-
 services/management/enclave/src/lib.rs     |  3 +-
 services/scheduler/enclave/src/lib.rs      |  3 +-
 services/storage/enclave/src/lib.rs        |  3 +-
 15 files changed, 186 insertions(+), 94 deletions(-)

diff --git a/attestation/Cargo.toml b/attestation/Cargo.toml
index ef5578d..d0ade53 100644
--- a/attestation/Cargo.toml
+++ b/attestation/Cargo.toml
@@ -2,7 +2,7 @@
 name = "teaclave_attestation"
 version = "0.1.0"
 authors = ["Teaclave Contributors <dev@teaclave.apache.org>"]
-description = "Teaclave Attestation"
+description = "Provides TLS-based remote attestation mechanism in Teaclave."
 license = "Apache-2.0"
 edition = "2018"
 
@@ -31,10 +31,10 @@ rustls           = { version = "0.16.0", features = ["dangerous_configuration"]
 serde            = { version = "1.0.92", features = ["derive"] }
 serde_json       = { version = "1.0.39" }
 thiserror        = { version = "1.0.9" }
+url              = { version = "2.1.1" }
 uuid             = { version = "0.8.1", features = ["v4"] }
 webpki           = { version = "0.21.0" }
 webpki-roots     = { version = "0.19.0" }
-url              = { version = "2.1.1" }
 yasna            = { version = "0.3.0", features = ["bit-vec", "num-bigint", "chrono"] }
 
 teaclave_types  = { path = "../types" }
diff --git a/attestation/src/attestation.rs b/attestation/src/attestation.rs
index ee176c5..3f5391a 100644
--- a/attestation/src/attestation.rs
+++ b/attestation/src/attestation.rs
@@ -15,18 +15,22 @@
 // specific language governing permissions and limitations
 // under the License.
 
+//! This module provide attestation public APIs in server side.
+
+use std::prelude::v1::*;
+
 use crate::key;
 use crate::AttestationConfig;
 use crate::AttestedTlsConfig;
 use crate::EndorsedAttestationReport;
-use anyhow::{anyhow, Result};
-use log::debug;
-use std::prelude::v1::*;
+
 use std::sync::{Arc, SgxRwLock as RwLock};
 use std::thread;
-use std::time::Duration;
-use std::time::{self, SystemTime};
+use std::time::{Duration, SystemTime};
 use std::untrusted::time::SystemTimeEx;
+
+use anyhow::{anyhow, Result};
+use log::debug;
 use teaclave_config::build::ATTESTATION_VALIDITY_SECS;
 
 const CERT_ISSUER: &str = "Teaclave";
@@ -37,26 +41,16 @@ pub struct RemoteAttestation {
     attested_tls_config: Option<Arc<RwLock<AttestedTlsConfig>>>,
 }
 
-impl Default for RemoteAttestation {
-    fn default() -> Self {
-        let attestation_config = AttestationConfig::no_attestation();
+impl RemoteAttestation {
+    /// Construct a `RemoteAttestation` with attestation configuration.
+    pub fn new(attestation_config: Arc<AttestationConfig>) -> Self {
         Self {
             attestation_config,
             attested_tls_config: None,
         }
     }
-}
-
-impl RemoteAttestation {
-    pub fn new() -> Self {
-        Self::default()
-    }
-
-    pub fn config(mut self, attestation_config: Arc<AttestationConfig>) -> Self
{
-        self.attestation_config = attestation_config;
-        Self { ..self }
-    }
 
+    /// Generate a endorsed attestation report.
     pub fn generate_and_endorse(self) -> Result<Self> {
         let attested_tls_config = Arc::new(RwLock::new(AttestedTlsConfig::new(
             &self.attestation_config,
@@ -72,6 +66,7 @@ impl RemoteAttestation {
         })
     }
 
+    /// Construct a attested TLS config for TLS connection (RPC in Teaclave).
     pub fn attested_tls_config(&self) -> Option<Arc<RwLock<AttestedTlsConfig>>>
{
         self.attested_tls_config.clone()
     }
@@ -83,21 +78,19 @@ impl AttestedTlsConfig {
         let report = match attestation_config {
             AttestationConfig::NoAttestation => EndorsedAttestationReport::default(),
             AttestationConfig::WithAttestation(config) => {
-                EndorsedAttestationReport::new(&config, key_pair.pub_k)?
+                EndorsedAttestationReport::new(&config, key_pair.pub_k())?
             }
         };
 
-        let cert_extension = serde_json::to_vec(&report)?;
-        let cert_der =
-            key_pair.create_cert_with_extension(CERT_ISSUER, CERT_SUBJECT, &cert_extension);
-        let prv_key_der = key_pair.private_key_into_der();
-
+        let extension = serde_json::to_vec(&report)?;
+        let cert = key_pair.create_cert_with_extension(CERT_ISSUER, CERT_SUBJECT, &extension);
+        let private_key = key_pair.private_key_into_der();
         let time = SystemTime::now();
-        let validity = time::Duration::from_secs(ATTESTATION_VALIDITY_SECS);
+        let validity = Duration::from_secs(ATTESTATION_VALIDITY_SECS);
 
         let attested_tls_config = AttestedTlsConfig {
-            cert: cert_der,
-            private_key: prv_key_der,
+            cert,
+            private_key,
             time,
             validity,
         };
@@ -108,6 +101,7 @@ impl AttestedTlsConfig {
     }
 }
 
+/// To keep attestation report fresh. Refresh current valid report periodically.
 struct AttestationFreshnessKeeper {
     attestation_config: Arc<AttestationConfig>,
     attested_tls_config: Arc<RwLock<AttestedTlsConfig>>,
@@ -124,6 +118,8 @@ impl AttestationFreshnessKeeper {
         }
     }
 
+    /// Start the fresshness keeper which will periodically refresh it's
+    /// `attested_tls_config`.
     pub(crate) fn start(&self) {
         debug!("AttestationFreshnessKeeper started");
         loop {
@@ -135,6 +131,8 @@ impl AttestationFreshnessKeeper {
         }
     }
 
+    /// Get updated report form attestation service and create an updated
+    /// attested TLS config.
     fn refresh(&self) -> Result<()> {
         debug!("begin refresh");
         let updated_attested_tls_config = AttestedTlsConfig::new(&self.attestation_config)?;
diff --git a/attestation/src/cert.rs b/attestation/src/cert.rs
index 20ef234..bbc8fc9 100644
--- a/attestation/src/cert.rs
+++ b/attestation/src/cert.rs
@@ -15,9 +15,10 @@
 // specific language governing permissions and limitations
 // under the License.
 
+//! This module provides a X.509 certificate parser.
+
 #![allow(clippy::unused_unit)]
-// Insert std prelude in the top for the sgx feature
-#[cfg(feature = "mesalock_sgx")]
+
 use std::prelude::v1::*;
 
 use yasna::ASN1Result;
diff --git a/attestation/src/key.rs b/attestation/src/key.rs
index e061b91..87acf3f 100644
--- a/attestation/src/key.rs
+++ b/attestation/src/key.rs
@@ -15,22 +15,29 @@
 // specific language governing permissions and limitations
 // under the License.
 
+//! This module implements ECDSA (NIST P-256 curve) keys related functions. You
+//! can export private key to a DER format or create a certificate with
+//! extension for TLS-based remote attestation.
+
+use std::prelude::v1::*;
+
 use anyhow::Result;
 use sgx_tcrypto::SgxEccHandle;
 use sgx_types::{sgx_ec256_private_t, sgx_ec256_public_t};
-use std::prelude::v1::*;
 
+/// Validation days of cert for TLS connection.
 const CERT_VALID_DAYS: i64 = 90i64;
 
 /// NistP256KeyPair stores a pair of ECDSA (private, public) key based on the
 /// NIST P-256 curve (a.k.a secp256r1).
-pub struct NistP256KeyPair {
+pub(crate) struct NistP256KeyPair {
     prv_k: sgx_ec256_private_t,
-    pub pub_k: sgx_ec256_public_t,
+    pub_k: sgx_ec256_public_t,
 }
 
 impl NistP256KeyPair {
-    pub fn new() -> Result<Self> {
+    /// Generate a ECDSA key pair.
+    pub(crate) fn new() -> Result<Self> {
         let ecc_handle = SgxEccHandle::new();
         ecc_handle.open()?;
         let (prv_k, pub_k) = ecc_handle.create_key_pair()?;
@@ -38,12 +45,17 @@ impl NistP256KeyPair {
         Ok(Self { prv_k, pub_k })
     }
 
-    pub fn private_key_into_der(&self) -> Vec<u8> {
+    pub(crate) fn pub_k(&self) -> sgx_ec256_public_t {
+        self.pub_k
+    }
+
+    pub(crate) fn private_key_into_der(&self) -> Vec<u8> {
         use bit_vec::BitVec;
         use yasna::construct_der;
         use yasna::models::ObjectIdentifier;
         use yasna::Tag;
 
+        // Construct useful OIDs.
         let ec_public_key_oid = ObjectIdentifier::from_slice(&[1, 2, 840, 10045, 2, 1]);
         let prime256v1_oid = ObjectIdentifier::from_slice(&[1, 2, 840, 10045, 3, 1, 7]);
 
@@ -78,7 +90,7 @@ impl NistP256KeyPair {
     /// Certificate Revocation List (CRL) Profile][1]
     ///
     /// [1]: https://tools.ietf.org/pdf/rfc5280.pdf
-    pub fn create_cert_with_extension(
+    pub(crate) fn create_cert_with_extension(
         &self,
         issuer: &str,
         subject: &str,
@@ -94,6 +106,7 @@ impl NistP256KeyPair {
         use yasna::construct_der;
         use yasna::models::{ObjectIdentifier, UTCTime};
 
+        // Construct useful OIDs.
         let ecdsa_with_sha256_oid = ObjectIdentifier::from_slice(&[1, 2, 840, 10045,
4, 3, 2]);
         let common_name_oid = ObjectIdentifier::from_slice(&[2, 5, 4, 3]);
         let ec_public_key_oid = ObjectIdentifier::from_slice(&[1, 2, 840, 10045, 2, 1]);
diff --git a/attestation/src/lib.rs b/attestation/src/lib.rs
index 9409632..5fc7685 100644
--- a/attestation/src/lib.rs
+++ b/attestation/src/lib.rs
@@ -15,16 +15,21 @@
 // specific language governing permissions and limitations
 // under the License.
 
+//! This crate provides TLS-based remote attestation mechanism for Teaclave,
+//! supporting both EPID and ECDSA attestation. By default, Intel Attestation
+//! Service is used for RA.
+
 #![cfg_attr(feature = "mesalock_sgx", no_std)]
 #[cfg(feature = "mesalock_sgx")]
 #[macro_use]
 extern crate sgx_tstd as std;
 
-use anyhow::{Context, Result};
-use serde::{Deserialize, Serialize};
 use std::prelude::v1::*;
 use std::sync::Arc;
 
+use anyhow::{Context, Result};
+use serde::{Deserialize, Serialize};
+
 /// Errors that can happen during attestation and verification process
 #[derive(thiserror::Error, Debug)]
 pub enum AttestationError {
diff --git a/attestation/src/platform.rs b/attestation/src/platform.rs
index 5357916..0ada0d9 100644
--- a/attestation/src/platform.rs
+++ b/attestation/src/platform.rs
@@ -15,30 +15,62 @@
 // specific language governing permissions and limitations
 // under the License.
 
-use crate::AttestationError;
+//! This module provides SGX platform related functions like getting local
+//! report and transform into a remotely verifiable quote.
+
+use std::prelude::v1::*;
+
 use anyhow::{ensure, Result};
 use log::debug;
-use sgx_rand::os::SgxRng;
-use sgx_rand::Rng;
+use sgx_rand::{os::SgxRng, Rng};
 use sgx_tcrypto::rsgx_sha256_slice;
 use sgx_tse::{rsgx_create_report, rsgx_verify_report};
 use sgx_types::sgx_status_t::SGX_SUCCESS;
 use sgx_types::*;
-use std::prelude::v1::*;
+
+type SgxStatus = sgx_types::sgx_status_t;
+
+#[derive(thiserror::Error, Debug)]
+pub enum PlatformError {
+    #[error("Failed to call {0}: {1}")]
+    OCallError(String, SgxStatus),
+    #[error("Failed to initialize quote : {0}")]
+    InitQuoteError(SgxStatus),
+    #[error("Failed to create the report of the enclave: {0}")]
+    CreateReportError(SgxStatus),
+    #[error("Failed to get target info of this enclave: {0}")]
+    GetSelfTargetInfoError(SgxStatus),
+    #[error("Failed to get quote: {0}")]
+    GetQuoteError(SgxStatus),
+    #[error("Failed to verify quote: {0}")]
+    VerifyReportError(SgxStatus),
+    #[error(
+        "Replay attack on report: quote_nonce.rand {0:?},
+        qe_report.body.report_data.d[..32] {1:?}"
+    )]
+    ReportReplay(Vec<u8>, Vec<u8>),
+    #[error("Failed to use SGX rng to generate random number: {0}")]
+    SgxRngError(std::io::Error),
+    #[error("Other SGX platform error: {0}")]
+    Others(SgxStatus),
+}
 
 extern "C" {
+    /// Ocall to use sgx_init_quote_ex to init the quote and key_id.
     fn ocall_sgx_init_quote(
         p_retval: *mut sgx_status_t,
         p_sgx_att_key_id: *mut sgx_att_key_id_t,
         p_target_info: *mut sgx_target_info_t,
     ) -> sgx_status_t;
 
+    /// Ocall to get the required buffer size for the quote.
     fn ocall_sgx_get_quote_size(
         p_retval: *mut sgx_status_t,
         p_sgx_att_key_id: *const sgx_att_key_id_t,
         p_quote_size: *mut u32,
     ) -> sgx_status_t;
 
+    /// Ocall to use sgx_get_quote_ex to generate a quote with enclave's report.
     fn ocall_sgx_get_quote(
         p_retval: *mut sgx_status_t,
         p_report: *const sgx_report_t,
@@ -48,9 +80,12 @@ extern "C" {
         quote_size: u32,
     ) -> sgx_status_t;
 
+    /// OCall to get target information of myself.
     fn sgx_self_target(p_target_info: *mut sgx_target_info_t) -> sgx_status_t;
 }
 
+/// Initialize SGX quote, return attestation key ID selected by the platform and
+/// target information for creating report that only QE can verify.
 pub(crate) fn init_sgx_quote() -> Result<(sgx_att_key_id_t, sgx_target_info_t)>
{
     debug!("init_quote");
     let mut ti = sgx_target_info_t::default();
@@ -59,12 +94,16 @@ pub(crate) fn init_sgx_quote() -> Result<(sgx_att_key_id_t, sgx_target_info_t)>
 
     let res = unsafe { ocall_sgx_init_quote(&mut rt as _, &mut ak_id as _, &mut
ti as _) };
 
-    ensure!(res == SGX_SUCCESS, AttestationError::OCallError(res));
-    ensure!(rt == SGX_SUCCESS, AttestationError::PlatformError(rt));
+    ensure!(
+        res == SGX_SUCCESS,
+        PlatformError::OCallError("ocall_sgx_init_quote".to_string(), res)
+    );
+    ensure!(rt == SGX_SUCCESS, PlatformError::InitQuoteError(rt));
 
     Ok((ak_id, ti))
 }
 
+/// Create report of the enclave with target_info.
 pub(crate) fn create_sgx_isv_enclave_report(
     pub_k: sgx_ec256_public_t,
     target_info: sgx_target_info_t,
@@ -79,23 +118,28 @@ pub(crate) fn create_sgx_isv_enclave_report(
     report_data.d[32..].clone_from_slice(&pub_k_gy);
 
     let report =
-        rsgx_create_report(&target_info, &report_data).map_err(AttestationError::PlatformError)?;
+        rsgx_create_report(&target_info, &report_data).map_err(PlatformError::CreateReportError)?;
+
     Ok(report)
 }
 
+/// Get quote with attestation key ID and enclave's local report.
 pub(crate) fn get_sgx_quote(ak_id: &sgx_att_key_id_t, report: sgx_report_t) -> Result<Vec<u8>>
{
     let mut rt = sgx_status_t::SGX_ERROR_UNEXPECTED;
     let mut quote_len: u32 = 0;
 
     let res = unsafe { ocall_sgx_get_quote_size(&mut rt as _, ak_id as _, &mut quote_len
as _) };
 
-    ensure!(res == SGX_SUCCESS, AttestationError::OCallError(res));
-    ensure!(rt == SGX_SUCCESS, AttestationError::PlatformError(rt));
+    ensure!(
+        res == SGX_SUCCESS,
+        PlatformError::OCallError("ocall_sgx_get_quote_size".to_string(), res)
+    );
+    ensure!(rt == SGX_SUCCESS, PlatformError::GetQuoteError(rt));
 
     let mut qe_report_info = sgx_qe_report_info_t::default();
     let mut quote_nonce = sgx_quote_nonce_t::default();
 
-    let mut rng = SgxRng::new()?;
+    let mut rng = SgxRng::new().map_err(PlatformError::SgxRngError)?;
     rng.fill_bytes(&mut quote_nonce.rand);
     qe_report_info.nonce = quote_nonce;
 
@@ -104,7 +148,10 @@ pub(crate) fn get_sgx_quote(ak_id: &sgx_att_key_id_t, report: sgx_report_t)
-> R
     // returned with the quote
     let res = unsafe { sgx_self_target(&mut qe_report_info.app_enclave_target_info as
_) };
 
-    ensure!(res == SGX_SUCCESS, AttestationError::PlatformError(res));
+    ensure!(
+        res == SGX_SUCCESS,
+        PlatformError::GetSelfTargetInfoError(res)
+    );
 
     let mut quote = vec![0; quote_len as usize];
 
@@ -120,13 +167,16 @@ pub(crate) fn get_sgx_quote(ak_id: &sgx_att_key_id_t, report: sgx_report_t)
-> R
         )
     };
 
-    ensure!(res == SGX_SUCCESS, AttestationError::OCallError(res));
-    ensure!(rt == SGX_SUCCESS, AttestationError::PlatformError(rt));
+    ensure!(
+        res == SGX_SUCCESS,
+        PlatformError::OCallError("ocall_sgx_get_quote".to_string(), res)
+    );
+    ensure!(rt == SGX_SUCCESS, PlatformError::GetQuoteError(rt));
 
     debug!("rsgx_verify_report");
     let qe_report = qe_report_info.qe_report;
     // Perform a check on qe_report to verify if the qe_report is valid.
-    rsgx_verify_report(&qe_report).map_err(AttestationError::PlatformError)?;
+    rsgx_verify_report(&qe_report).map_err(PlatformError::VerifyReportError)?;
 
     // Check qe_report to defend against replay attack. The purpose of
     // p_qe_report is for the ISV enclave to confirm the QUOTE it received
@@ -139,9 +189,12 @@ pub(crate) fn get_sgx_quote(ak_id: &sgx_att_key_id_t, report: sgx_report_t)
-> R
     let mut rhs_vec: Vec<u8> = quote_nonce.rand.to_vec();
     rhs_vec.extend(&quote);
     debug!("rsgx_sha256_slice");
-    let rhs_hash = rsgx_sha256_slice(&rhs_vec).map_err(AttestationError::PlatformError)?;
+    let rhs_hash = rsgx_sha256_slice(&rhs_vec).map_err(PlatformError::Others)?;
     let lhs_hash = &qe_report.body.report_data.d[..32];
-    ensure!(rhs_hash == lhs_hash, AttestationError::ReportError);
+    ensure!(
+        rhs_hash == lhs_hash,
+        PlatformError::ReportReplay(rhs_hash.to_vec(), lhs_hash.to_vec())
+    );
 
     Ok(quote)
 }
@@ -167,14 +220,14 @@ pub mod tests {
     fn test_create_sgx_isv_enclave_report() {
         let (_ak_id, qe_target_info) = init_sgx_quote().unwrap();
         let key_pair = key::NistP256KeyPair::new().unwrap();
-        let sgx_report_result = create_sgx_isv_enclave_report(key_pair.pub_k, qe_target_info);
+        let sgx_report_result = create_sgx_isv_enclave_report(key_pair.pub_k(), qe_target_info);
         assert!(sgx_report_result.is_ok());
     }
 
     fn test_get_sgx_quote() {
         let (ak_id, qe_target_info) = init_sgx_quote().unwrap();
         let key_pair = key::NistP256KeyPair::new().unwrap();
-        let sgx_report = create_sgx_isv_enclave_report(key_pair.pub_k, qe_target_info).unwrap();
+        let sgx_report = create_sgx_isv_enclave_report(key_pair.pub_k(), qe_target_info).unwrap();
         let quote_result = get_sgx_quote(&ak_id, sgx_report);
         assert!(quote_result.is_ok());
     }
diff --git a/attestation/src/report.rs b/attestation/src/report.rs
index c734a0b..7d334e7 100644
--- a/attestation/src/report.rs
+++ b/attestation/src/report.rs
@@ -1,7 +1,3 @@
-//! Types that contain information about attestation report.
-//! The implementation is based on Attestation Service API version 4.
-//! https://api.trustedservices.intel.com/documents/sgx-attestation-api-spec.pdf
-
 // Licensed to the Apache Software Foundation (ASF) under one
 // or more contributor license agreements.  See the NOTICE file
 // distributed with this work for additional information
@@ -19,6 +15,10 @@
 // specific language governing permissions and limitations
 // under the License.
 
+//! Types that contain information about attestation report.
+//! The implementation is based on Attestation Service API version 4.
+//! https://api.trustedservices.intel.com/documents/sgx-attestation-api-spec.pdf
+
 #[cfg(feature = "mesalock_sgx")]
 use std::prelude::v1::*;
 
@@ -433,6 +433,9 @@ pub struct AttestationReport {
 }
 
 impl AttestationReport {
+    /// Construct a AttestationReport from a X509 certificate and verify
+    /// attestation report with the report_ca_cert which is from the attestation
+    /// service provider.
     pub fn from_cert(cert: &[u8], report_ca_cert: &[u8]) -> Result<Self>
{
         // Before we reach here, Webpki already verifed the cert is properly signed.
         use crate::cert::*;
diff --git a/attestation/src/service.rs b/attestation/src/service.rs
index 105ed00..3117c03 100644
--- a/attestation/src/service.rs
+++ b/attestation/src/service.rs
@@ -15,42 +15,54 @@
 // specific language governing permissions and limitations
 // under the License.
 
+//! This module provide API to communicate with attestation service (AS) to get
+//! attestation report endorsed by AS.
+
 use crate::platform;
 use crate::AttestationAlgorithm;
 use crate::AttestationServiceConfig;
 use crate::EndorsedAttestationReport;
-use anyhow::Result;
-use anyhow::{anyhow, bail};
-use log::{debug, trace};
-use serde_json::json;
-use sgx_types::*;
+
 use std::collections::HashMap;
 use std::io::{Read, Write};
 use std::net::TcpStream;
 use std::prelude::v1::*;
 use std::sync::Arc;
 
+use anyhow::{anyhow, bail, Result};
+use log::{debug, trace};
+use serde_json::json;
+use sgx_types::*;
+
+/// Root certification of the DCAP attestation service provider.
 #[cfg(dcap)]
 const DCAP_ROOT_CA_CERT: &str = include_str!("../../keys/dcap_root_ca_cert.pem");
 
-/// URL path to get the report
+/// URL path to get the report from the attestation service.
 const AS_REPORT_URL: &str = "/sgx/dev/attestation/v4/report";
 
 #[derive(thiserror::Error, Debug)]
-pub enum AttestationServiceError {
+pub(crate) enum AttestationServiceError {
     #[error("Invalid attestation service address.")]
     InvalidAddress,
     #[error("Attestation service responds an malformed response.")]
     InvalidResponse,
     #[error("{0} is missing in HTTP header.")]
     MissingHeader(String),
-    #[error("Invalid Attestation Evidence Payload. The client should not repeat the request
without modifications.")]
+    #[error(
+        "Invalid Attestation Evidence Payload. The client should not repeat the
+        request without modifications."
+    )]
     BadRequest,
     #[error("Failed to authenticate or authorize request.")]
     Unauthorized,
     #[error("Internal error occurred.")]
     InternalServerError,
-    #[error("Service is currently not able to process the request (due to a temporary overloading
or maintenance). This is a temporary state –the same request can be repeated after some
time.")]
+    #[error(
+        "Service is currently not able to process the request (due to a
+        temporary overloading or maintenance). This is a temporary state –the
+        same request can be repeated after some time."
+    )]
     ServiceUnavailable,
     #[error("TLS connection error.")]
     TlsError,
@@ -109,6 +121,8 @@ fn new_tls_stream(url: &url::Url) -> Result<rustls::StreamOwned<rustls::ClientSe
     Ok(stream)
 }
 
+/// Get attestation report form the attestation service (e.g., Intel Attestation
+/// Service and customized DCAP attestation service).
 fn get_report(
     algo: &AttestationAlgorithm,
     url: &url::Url,
@@ -163,8 +177,8 @@ fn get_report(
         }
         Some(400) => {
             debug!(
-                "Invalid Attestation Evidence Payload. \
-                 The client should not repeat the request without modifications."
+                "Invalid Attestation Evidence Payload. The client should not
+                 repeat the request without modifications."
             );
             bail!(AttestationServiceError::BadRequest);
         }
@@ -177,8 +191,11 @@ fn get_report(
             bail!(AttestationServiceError::InternalServerError);
         }
         Some(503) => {
-            debug!("Service is currently not able to process the request (due to a temporary
overloading or maintenance). \
-             This is a temporary state –the same request can be repeated after some time.");
+            debug!(
+                "Service is currently not able to process the request (due to a
+                 temporary overloading or maintenance). This is a temporary
+                 state, the same request can be repeated after some time."
+            );
             bail!(AttestationServiceError::ServiceUnavailable);
         }
         _ => {
diff --git a/attestation/src/verifier.rs b/attestation/src/verifier.rs
index c710669..494d6f6 100644
--- a/attestation/src/verifier.rs
+++ b/attestation/src/verifier.rs
@@ -1,5 +1,3 @@
-//! Types used to verify attestation reports
-
 // Licensed to the Apache Software Foundation (ASF) under one
 // or more contributor license agreements.  See the NOTICE file
 // distributed with this work for additional information
@@ -17,21 +15,28 @@
 // specific language governing permissions and limitations
 // under the License.
 
+//! This module provides types used to verify attestation reports.
+
 use crate::report::AttestationReport;
-use log::{debug, error};
+
 use std::vec::Vec;
+
+use log::{debug, error};
 use teaclave_types::EnclaveAttr;
 
+/// User defined verification function to further verify the attestation report.
 pub type AttestationReportVerificationFn = fn(&AttestationReport) -> bool;
 
-/// Type used to verify attestation reports (this can be set as a certificate verifier in
`rustls::ClientConfig`)
+/// Type used to verify attestation reports (this can be set as a certificate
+/// verifier in `rustls::ClientConfig`).
 #[derive(Clone)]
 pub struct AttestationReportVerifier {
-    /// Valid enclave attributes (only enclaves with attributes in this vector will be accepted)
+    /// Valid enclave attributes (only enclaves with attributes in this vector
+    /// will be accepted).
     pub accepted_enclave_attrs: Vec<EnclaveAttr>,
-    /// Root certificate
+    /// Root certificate of the attestation service provider (e.g., IAS).
     pub root_ca: Vec<u8>,
-    /// Attestation report verifier function
+    /// User defined function to verify the attestation report.
     pub verifier: AttestationReportVerificationFn,
 }
 
@@ -54,6 +59,8 @@ impl AttestationReportVerifier {
         }
     }
 
+    /// Verify whether the `MR_SIGNER` and `MR_ENCLAVE` in the attestation report is
+    /// accepted by us, which are defined in `accepted_enclave_attrs`.
     fn verify_measures(&self, attestation_report: &AttestationReport) -> bool
{
         debug!("verify measures");
         let this_mr_signer = attestation_report
@@ -70,6 +77,7 @@ impl AttestationReportVerifier {
         })
     }
 
+    /// Verify TLS certificate.
     fn verify_cert(&self, cert_der: &[u8]) -> bool {
         debug!("verify cert");
         if cfg!(sgx_sim) {
diff --git a/services/access_control/enclave/src/lib.rs b/services/access_control/enclave/src/lib.rs
index 36a1a28..a45cdcf 100644
--- a/services/access_control/enclave/src/lib.rs
+++ b/services/access_control/enclave/src/lib.rs
@@ -48,8 +48,7 @@ mod service;
 fn start_service(config: &RuntimeConfig) -> anyhow::Result<()> {
     let listen_address = config.internal_endpoints.access_control.listen_address;
     let attestation_config = AttestationConfig::from_teaclave_config(&config)?;
-    let attested_tls_config = RemoteAttestation::new()
-        .config(attestation_config)
+    let attested_tls_config = RemoteAttestation::new(attestation_config)
         .generate_and_endorse()
         .unwrap()
         .attested_tls_config()
diff --git a/services/authentication/enclave/src/lib.rs b/services/authentication/enclave/src/lib.rs
index f082ff8..18d3775 100644
--- a/services/authentication/enclave/src/lib.rs
+++ b/services/authentication/enclave/src/lib.rs
@@ -133,8 +133,7 @@ fn start_service(config: &RuntimeConfig) -> anyhow::Result<()>
{
     let api_listen_address = config.api_endpoints.authentication.listen_address;
     let internal_listen_address = config.internal_endpoints.authentication.listen_address;
     let attestation_config = AttestationConfig::from_teaclave_config(&config)?;
-    let attested_tls_config = RemoteAttestation::new()
-        .config(attestation_config)
+    let attested_tls_config = RemoteAttestation::new(attestation_config)
         .generate_and_endorse()
         .unwrap()
         .attested_tls_config()
diff --git a/services/frontend/enclave/src/lib.rs b/services/frontend/enclave/src/lib.rs
index 0ca62f2..bf0cf20 100644
--- a/services/frontend/enclave/src/lib.rs
+++ b/services/frontend/enclave/src/lib.rs
@@ -48,8 +48,7 @@ mod service;
 fn start_service(config: &RuntimeConfig) -> anyhow::Result<()> {
     let listen_address = config.api_endpoints.frontend.listen_address;
     let attestation_config = AttestationConfig::from_teaclave_config(&config)?;
-    let attested_tls_config = RemoteAttestation::new()
-        .config(attestation_config)
+    let attested_tls_config = RemoteAttestation::new(attestation_config)
         .generate_and_endorse()
         .unwrap()
         .attested_tls_config()
diff --git a/services/management/enclave/src/lib.rs b/services/management/enclave/src/lib.rs
index 05007cc..ba29069 100644
--- a/services/management/enclave/src/lib.rs
+++ b/services/management/enclave/src/lib.rs
@@ -46,8 +46,7 @@ mod service;
 fn start_service(config: &RuntimeConfig) -> anyhow::Result<()> {
     let listen_address = config.internal_endpoints.management.listen_address;
     let attestation_config = AttestationConfig::from_teaclave_config(&config)?;
-    let attested_tls_config = RemoteAttestation::new()
-        .config(attestation_config)
+    let attested_tls_config = RemoteAttestation::new(attestation_config)
         .generate_and_endorse()
         .unwrap()
         .attested_tls_config()
diff --git a/services/scheduler/enclave/src/lib.rs b/services/scheduler/enclave/src/lib.rs
index d3de3fa..90d85d4 100644
--- a/services/scheduler/enclave/src/lib.rs
+++ b/services/scheduler/enclave/src/lib.rs
@@ -49,8 +49,7 @@ use teaclave_types::{EnclaveInfo, TeeServiceError, TeeServiceResult};
 fn start_service(config: &RuntimeConfig) -> anyhow::Result<()> {
     let listen_address = config.internal_endpoints.scheduler.listen_address;
     let attestation_config = AttestationConfig::from_teaclave_config(&config)?;
-    let attested_tls_config = RemoteAttestation::new()
-        .config(attestation_config)
+    let attested_tls_config = RemoteAttestation::new(attestation_config)
         .generate_and_endorse()
         .unwrap()
         .attested_tls_config()
diff --git a/services/storage/enclave/src/lib.rs b/services/storage/enclave/src/lib.rs
index f7fa91f..46c3958 100644
--- a/services/storage/enclave/src/lib.rs
+++ b/services/storage/enclave/src/lib.rs
@@ -49,8 +49,7 @@ mod service;
 fn start_service(config: &RuntimeConfig) -> anyhow::Result<()> {
     let listen_address = config.internal_endpoints.storage.listen_address;
     let attestation_config = AttestationConfig::from_teaclave_config(&config)?;
-    let attested_tls_config = RemoteAttestation::new()
-        .config(attestation_config)
+    let attested_tls_config = RemoteAttestation::new(attestation_config)
         .generate_and_endorse()
         .unwrap()
         .attested_tls_config()


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@teaclave.apache.org
For additional commands, e-mail: commits-help@teaclave.apache.org


Mime
View raw message