This is an automated email from the ASF dual-hosted git repository.
mssun pushed a commit to branch develop
in repository https://gitbox.apache.org/repos/asf/incubator-teaclave.git
The following commit(s) were added to refs/heads/develop by this push:
new 8578322 [attestation] Add documentation for remote attestation (#246)
8578322 is described below
commit 8578322d6a898f97b3cefb171b52debaa22a836f
Author: Devashish Dixit <[email protected]>
AuthorDate: Wed Mar 25 01:41:24 2020 +0800
[attestation] Add documentation for remote attestation (#246)
---
attestation/src/lib.rs | 26 ++++++++++++++++++++------
attestation/src/report.rs | 40 ++++++++++++++++++++++++++++++++++------
attestation/src/verifier.rs | 7 +++++++
3 files changed, 61 insertions(+), 12 deletions(-)
diff --git a/attestation/src/lib.rs b/attestation/src/lib.rs
index 26f234a..6477d39 100644
--- a/attestation/src/lib.rs
+++ b/attestation/src/lib.rs
@@ -24,6 +24,7 @@ use serde::{Deserialize, Serialize};
use std::prelude::v1::*;
use std::sync::Arc;
+/// Errors that can happen during attestation and verification process
#[derive(thiserror::Error, Debug)]
pub enum AttestationError {
#[error("OCall error")]
@@ -38,15 +39,21 @@ pub enum AttestationError {
ConnectionError,
}
+/// Remote attestation configuration
#[derive(Clone)]
pub enum AttestationConfig {
+ /// Trust enclave without attestation
NoAttestation,
+ /// Perform attestation before trusting enclave
WithAttestation(AttestationServiceConfig),
}
+/// Remote attestation algorithm
#[derive(Clone)]
pub(crate) enum AttestationAlgorithm {
+ /// Use Intel EPID
SgxEpid,
+ /// Use ECDSA
SgxEcdsa,
}
@@ -60,21 +67,28 @@ impl AttestationAlgorithm {
}
}
+/// Attestation Service Configuration
#[derive(Clone)]
pub struct AttestationServiceConfig {
+ /// Algorithm to use
algo: AttestationAlgorithm,
+ /// URL of attestation service
as_url: url::Url,
+ /// IAS API Key
api_key: String,
+ /// SPID
spid: sgx_types::sgx_spid_t,
}
pub struct DcapConfig {}
impl AttestationConfig {
+ /// Creates `AttestationConfig` for no attestation
pub fn no_attestation() -> Arc<Self> {
Arc::new(Self::NoAttestation)
}
+ /// Creates `AttestationConfig` for attestation using given values
pub fn new(algorithm: &str, url: &str, api_key: &str, spid_str: &str) ->
Arc<Self> {
if cfg!(sgx_sim) {
return Self::no_attestation();
@@ -100,19 +114,19 @@ impl AttestationConfig {
}
}
-// AttestationReport can be endorsed by either the Intel Attestation Service
-// using EPID or Data Center Attestation Service (platform dependent) using
-// ECDSA.
+/// AttestationReport can be endorsed by either the Intel Attestation Service
using EPID or Data Center Attestation
+/// Service (platform dependent) using ECDSA.
#[derive(Default, Serialize, Deserialize)]
pub(crate) struct EndorsedAttestationReport {
- // Attestation report generated by the hardware
+ /// Attestation report generated by the hardware
pub report: Vec<u8>,
- // Singature of the report
+ /// Singature of the report
pub signature: Vec<u8>,
- // Certificate matching the signing key of the signature
+ /// Certificate matching the signing key of the signature
pub signing_cert: Vec<u8>,
}
+/// Configuration for TLS communication in Remote Attestation
#[derive(Debug)]
pub struct AttestedTlsConfig {
pub cert: Vec<u8>,
diff --git a/attestation/src/report.rs b/attestation/src/report.rs
index d13fbcb..c0fbbe9 100644
--- a/attestation/src/report.rs
+++ b/attestation/src/report.rs
@@ -1,3 +1,5 @@
+//! Types that contain information about report generated by enclave
+
// 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
@@ -50,20 +52,30 @@ static SUPPORTED_SIG_ALGS: SignatureAlgorithms = &[
&webpki::RSA_PKCS1_3072_8192_SHA384,
];
-// Do not confuse SgxEnclaveReport with AttestationReport.
-// SgxReport is generated by SGX hardware and endorsed by Quoting Enclave
through
-// local attestation. The endorsed SgxReport is an SGX quote. The quote is then
-// sent to some attestation service (IAS or DCAP-based AS). The endorsed SGX
quote
-// is an attestation report signed by attestation service private key, aka
-// EndorsedAttestationReport
+/// A report generated by an enclave that contains measurement, identity and
other data related to enclave.
+///
+/// # Note
+///
+/// Do not confuse `SgxEnclaveReport` with `AttestationReport`.
`SgxEnclaveReport` is generated by SGX hardware and
+/// endorsed by Quoting Enclave through local attestation. The endorsed
`SgxEnclaveReport` is an `SgxQuote`. The quote
+/// is then sent to some attestation service (IAS or DCAP-based AS). The
endorsed `SgxQuote` is an attestation report
+/// signed by attestation service's private key, a.k.a.,
`EndorsedAttestationReport`.
pub struct SgxEnclaveReport {
+ /// Security version number of host system's CPU
pub cpu_svn: [u8; 16],
+ /// Misc select bits for the target enclave. Reserved for future function
extension.
pub misc_select: u32,
+ /// Attributes of the enclave, for example, whether the enclave is running
in debug mode.
pub attributes: [u8; 16],
+ /// Measurement value of the enclave. See
[`EnclaveMeasurement`](../types/struct.EnclaveMeasurement.html)
pub mr_enclave: [u8; 32],
+ /// Measurement value of the public key that verified the enclave. See
[`EnclaveMeasurement`](../types/struct.EnclaveMeasurement.html)
pub mr_signer: [u8; 32],
+ /// Product ID of the enclave
pub isv_prod_id: u16,
+ /// Security version number of the enclave
pub isv_svn: u16,
+ /// Set of data used for communication between enclave and target enclave
pub report_data: [u8; 64],
}
@@ -149,6 +161,7 @@ impl SgxEnclaveReport {
}
}
+/// SGX Quote structure version
#[derive(Debug, PartialEq)]
pub enum SgxQuoteVersion {
V1(SgxEpidQuoteSigType),
@@ -156,6 +169,7 @@ pub enum SgxQuoteVersion {
V3(SgxEcdsaQuoteAkType),
}
+/// Intel EPID signature type
#[derive(Debug, PartialEq)]
pub enum SgxEpidQuoteSigType {
Unlinkable,
@@ -168,6 +182,7 @@ pub enum SgxEcdsaQuoteAkType {
P384_384,
}
+/// SGX Quote status
#[derive(PartialEq, Debug)]
pub enum SgxQuoteStatus {
OK,
@@ -197,13 +212,24 @@ impl From<&str> for SgxQuoteStatus {
}
}
+/// An application that hosts an enclave can ask the enclave to produce a
report (`SgxEnclaveReport`) and then pass this
+/// report to a platform service (Quoting Enclave) to produce a type of
credential that reflects the enclave and
+/// platform state. The quote can be passed to entities off the platform, and
verified using Intel EPID signature
+/// verification techniques.
pub struct SgxQuote {
+ /// Version of the quote structure
pub version: SgxQuoteVersion,
+ // ID of the Intel EPID group of the platform belongs to
pub gid: u32,
+ /// Security version number of Quoting Enclave
pub isv_svn_qe: u16,
+ /// Security version number of PCE
pub isv_svn_pce: u16,
+ /// Vendor ID of Quoting Enclave
pub qe_vendor_id: Uuid,
+ /// User data
pub user_data: [u8; 20],
+ /// Report generated by the enclave
pub isv_enclave_report: SgxEnclaveReport,
}
@@ -295,6 +321,8 @@ impl SgxQuote {
}
}
+/// A report that can be signed by Intel EPID (which generates
`EndorsedAttestationReport`) and then sent off of the
+/// platform to be verified by remote client.
#[derive(Debug)]
pub struct AttestationReport {
pub freshness: Duration,
diff --git a/attestation/src/verifier.rs b/attestation/src/verifier.rs
index dd2aa12..d688f18 100644
--- a/attestation/src/verifier.rs
+++ b/attestation/src/verifier.rs
@@ -1,3 +1,5 @@
+//! 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
@@ -22,13 +24,18 @@ use teaclave_types::EnclaveAttr;
pub type AttestationReportVerificationFn = fn(&AttestationReport) -> bool;
+/// 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)
pub accepted_enclave_attrs: Vec<EnclaveAttr>,
+ /// Root certificate
pub root_ca: Vec<u8>,
+ /// Attestation report verifier function
pub verifier: AttestationReportVerificationFn,
}
+/// Checks if he quote's status is not `UnknownBadStatus`
pub fn universal_quote_verifier(report: &AttestationReport) -> bool {
debug!("report.sgx_quote_status: {:?}", report.sgx_quote_status);
report.sgx_quote_status != crate::report::SgxQuoteStatus::UnknownBadStatus
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
