diff --git a/crates/attestation/README.md b/crates/attestation/README.md index 05878cb..868e83d 100644 --- a/crates/attestation/README.md +++ b/crates/attestation/README.md @@ -10,6 +10,22 @@ This crate provides: - Attestation generation and verification for DCAP and (optionally) Azure - Parsing and evaluation of measurement policies +## Verification results + +`AttestationVerifier::verify_attestation` and +`AttestationVerifier::verify_attestation_sync` return the +`ExpectedMeasurements` value from the policy record that accepted the +attestation. This is the matched policy value, not the raw register values +extracted from the quote. For example, verification against a portable policy +returns `ExpectedMeasurements::Image`, while an allow-any DCAP policy returns +`ExpectedMeasurements::Dcap` with an empty register map. Successful +verification without attestation returns `ExpectedMeasurements::NoAttestation`. + +Matched expected measurements can be transported in an HTTP header using +`ExpectedMeasurements::to_header_format` and reconstructed with +`ExpectedMeasurements::from_header_format`. See +[Expected measurement header format](#expected-measurement-header-format). + ## Runtime Requirements Verification uses the [`pccs`](../pccs) crate for collateral caching and @@ -103,8 +119,7 @@ These objects have the following fields: - `attestation_type` - a string containing one of the attestation types (confidential computing platforms) described below. - `measurements` - an object with fields referring to the five measurement - registers. Field names are the same as for the measurement headers (see - below). + registers. See [Measurement field names](#measurement-field-names). - `dcap_image_hashes` - an alternative to `measurements` that pins the hashes of the boot components (UKI, kernel, initrd, cmdline, GPT disk GUID) rather than raw register values. The verifier reconstructs the expected RTMRs at @@ -248,6 +263,69 @@ Legacy numeric field names are still supported for backwards compatibility: - "3" - RTMR2 - "4" - RTMR3 +### Expected measurement header format + +`ExpectedMeasurements::to_header_format` serializes the matched policy value +as self-describing JSON suitable for an HTTP `HeaderValue`. Hashes are +lowercase hexadecimal strings. Both SHA-384 DCAP values and SHA-256 Azure +values are represented as hex. + +DCAP and Azure register values are arrays because a policy can accept more +than one value for each register. Header JSON uses numeric register keys: + +- DCAP: `"0"` is MRTD, followed by `"1"` through `"4"` for RTMR0 through + RTMR3. +- Azure: the key is the PCR index. + +DCAP example: + +```JSON +{ + "type": "dcap", + "measurements": { + "0": ["<96 hex characters>"], + "3": ["<96 hex characters>", "<96 hex characters>"] + } +} +``` + +Azure example: + +```JSON +{ + "type": "azure", + "measurements": { + "4": ["<64 hex characters>"], + "11": ["<64 hex characters>"] + } +} +``` + +Portable image-hash example: + +```JSON +{ + "type": "image", + "measurements": { + "uki_authenticode": "<96 hex characters>", + "kernel_authenticode": "<96 hex characters>", + "cmdline_hash": "<96 hex characters>", + "initrd_hash": "<96 hex characters>", + "gpt_disk_guid_hash": "<96 hex characters>" + } +} +``` + +No-attestation example: + +```JSON +{"type":"no_attestation"} +``` + +The actual header value is compact JSON on one line. The decoder preserves +partial register policies and every alternative value in a register's +`expected_any` list. + ### Portable measurement policies The `measurements` format above specifies register values, so any change diff --git a/crates/attestation/src/gcp.rs b/crates/attestation/src/gcp.rs index a8cd3f0..f5b419c 100644 --- a/crates/attestation/src/gcp.rs +++ b/crates/attestation/src/gcp.rs @@ -173,12 +173,14 @@ mod tests { }; let gcp_firmware_cache = create_cache_with_firmware(firmware); - measurement_policy + let matched_measurements = measurement_policy .check_measurement_with_gcp_cache( &measurements, Some(&gcp_portable_platform_metadata()), Some(&gcp_firmware_cache), ) .unwrap(); + + assert_eq!(matched_measurements, ExpectedMeasurements::Image(gcp_portable_image_hashes())); } } diff --git a/crates/attestation/src/lib.rs b/crates/attestation/src/lib.rs index 7ecfc34..d87fcd2 100644 --- a/crates/attestation/src/lib.rs +++ b/crates/attestation/src/lib.rs @@ -17,7 +17,7 @@ use std::{ use attest_measure::platform::PlatformError; pub use attest_types::{AttestationEvidence, PlatformMetadata}; -use measurements::MultiMeasurements; +use measurements::{ExpectedMeasurements, MultiMeasurements}; use parity_scale_codec::{Decode, Encode}; use pccs::{Pccs, PccsError}; use serde::{Deserialize, Serialize}; @@ -535,13 +535,13 @@ impl AttestationVerifier { } } - /// Verify an attestation, and ensure the measurements match one of our - /// accepted measurements + /// Verify an attestation, and return the expected measurements from the + /// matching policy record. pub async fn verify_attestation( &self, attestation_exchange_message: AttestationExchangeMessage, expected_input_data: [u8; 64], - ) -> Result, AttestationError> { + ) -> Result { let attestation_type = attestation_exchange_message.attestation_type(); tracing::debug!("Verifying {attestation_type} attestation"); @@ -555,7 +555,7 @@ impl AttestationVerifier { return Err(AttestationError::AttestationTypeNotAccepted); } if attestation_exchange_message.attestation_evidence.is_none() { - return Ok(None); + MultiMeasurements::NoAttestation } else { return Err(AttestationError::AttestationGivenWhenNoneExpected); } @@ -599,7 +599,6 @@ impl AttestationVerifier { .attestation_evidence .as_ref() .map(|evidence| evidence.platform.clone()); - let policy_state = self.measurement_policy_read().clone(); let policy_check = policy_state.policy.check_measurement_with_gcp_cache( &measurements, @@ -607,33 +606,38 @@ impl AttestationVerifier { Some(&self.known_gcp_firmware), ); - if let Err(err) = policy_check { - // If this fails, and we have dynamic measurement policy, re-retrieve our - // measurement policy, then check the policy a second time - if let Some(file_or_url) = &self.dynamic_measurement_policy { - let new_measurement_policy = - MeasurementPolicy::from_file_or_url(file_or_url.to_string()).await?; - let measurement_policy = - self.set_measurement_policy(new_measurement_policy, policy_state.generation); - measurement_policy.check_measurement_with_gcp_cache( - &measurements, - platform_metadata.as_ref(), - Some(&self.known_gcp_firmware), - )?; - } else { - return Err(err); + let matched_measurements = match policy_check { + Ok(matched_measurements) => matched_measurements, + Err(err) => { + // If this fails, and we have dynamic measurement policy, re-retrieve our + // measurement policy, then check the policy a second time + if let Some(file_or_url) = &self.dynamic_measurement_policy { + let new_measurement_policy = + MeasurementPolicy::from_file_or_url(file_or_url.to_string()).await?; + let measurement_policy = self + .set_measurement_policy(new_measurement_policy, policy_state.generation); + measurement_policy.check_measurement_with_gcp_cache( + &measurements, + platform_metadata.as_ref(), + Some(&self.known_gcp_firmware), + )? + } else { + return Err(err); + } } - } + }; tracing::debug!("Verification successful"); - Ok(Some(measurements)) + Ok(matched_measurements) } + /// Verify an attestation synchronously, and return the expected + /// measurements from the matching policy record. pub fn verify_attestation_sync( &self, attestation_exchange_message: AttestationExchangeMessage, expected_input_data: [u8; 64], - ) -> Result, AttestationError> { + ) -> Result { let attestation_type = attestation_exchange_message.attestation_type(); tracing::debug!("Verifying {attestation_type} attestation"); @@ -647,7 +651,7 @@ impl AttestationVerifier { return Err(AttestationError::AttestationTypeNotAccepted); } if attestation_exchange_message.attestation_evidence.is_none() { - return Ok(None); + MultiMeasurements::NoAttestation } else { return Err(AttestationError::AttestationGivenWhenNoneExpected); } @@ -703,24 +707,27 @@ impl AttestationVerifier { Some(&self.known_gcp_firmware), ); - if let Err(err) = policy_check { - if let Some(file_or_url) = &self.dynamic_measurement_policy { - let new_measurement_policy = - MeasurementPolicy::from_file_or_url_sync(file_or_url.to_string())?; - let measurement_policy = - self.set_measurement_policy(new_measurement_policy, policy_state.generation); - measurement_policy.check_measurement_with_gcp_cache( - &measurements, - platform_metadata.as_ref(), - Some(&self.known_gcp_firmware), - )?; - } else { - return Err(err); + let matched_measurements = match policy_check { + Ok(matched_measurements) => matched_measurements, + Err(err) => { + if let Some(file_or_url) = &self.dynamic_measurement_policy { + let new_measurement_policy = + MeasurementPolicy::from_file_or_url_sync(file_or_url.to_string())?; + let measurement_policy = self + .set_measurement_policy(new_measurement_policy, policy_state.generation); + measurement_policy.check_measurement_with_gcp_cache( + &measurements, + platform_metadata.as_ref(), + Some(&self.known_gcp_firmware), + )? + } else { + return Err(err); + } } - } + }; tracing::debug!("Verification successful"); - Ok(Some(measurements)) + Ok(matched_measurements) } /// Whether we allow no remote attestation @@ -932,6 +939,22 @@ mod tests { let _ = running_on_gcp(); } + #[tokio::test] + async fn verifier_returns_matched_no_attestation_measurements() { + let verifier = AttestationVerifier::expect_none(); + let attestation = AttestationExchangeMessage::without_attestation(); + let input_data = [0u8; 64]; + + assert_eq!( + verifier.verify_attestation(attestation.clone(), input_data).await.unwrap(), + ExpectedMeasurements::NoAttestation + ); + assert_eq!( + verifier.verify_attestation_sync(attestation, input_data).unwrap(), + ExpectedMeasurements::NoAttestation + ); + } + #[tokio::test] async fn mock_verifier_supports_sync_verification() { let input_data = [7u8; 64]; @@ -950,7 +973,10 @@ mod tests { let result = verifier.verify_attestation_sync(attestation_evidence.into(), input_data); - assert!(result.is_ok(), "expected sync mock verification to succeed: {result:?}"); + assert!( + matches!(result, Ok(ExpectedMeasurements::Dcap(_))), + "expected sync mock verification to return matched DCAP measurements: {result:?}" + ); } #[test] @@ -969,7 +995,10 @@ mod tests { let generation = verifier_clone.measurement_policy_read().generation; verifier_clone.set_measurement_policy(MeasurementPolicy::expect_none(), generation); - assert!(matches!(verifier.verify_attestation_sync(message, input_data), Ok(None))); + assert!(matches!( + verifier.verify_attestation_sync(message, input_data), + Ok(ExpectedMeasurements::NoAttestation) + )); } #[test] @@ -1009,7 +1038,10 @@ mod tests { tokio::fs::write(&policy_path, br#"[{"attestation_type":"dcap-tdx"}]"#).await.unwrap(); - verifier.verify_attestation(attestation.into(), input_data).await.unwrap(); + let matched_measurements = + verifier.verify_attestation(attestation.into(), input_data).await.unwrap(); + + assert!(matches!(matched_measurements, ExpectedMeasurements::Dcap(_))); assert!(verifier.measurement_policy().check_measurement(&measurements, None).is_ok()); } @@ -1039,6 +1071,9 @@ mod tests { std::fs::write(&policy_path, br#"[{"attestation_type":"dcap-tdx"}]"#).unwrap(); - verifier.verify_attestation_sync(attestation.into(), input_data).unwrap(); + let matched_measurements = + verifier.verify_attestation_sync(attestation.into(), input_data).unwrap(); + + assert!(matches!(matched_measurements, ExpectedMeasurements::Dcap(_))); } } diff --git a/crates/attestation/src/measurements.rs b/crates/attestation/src/measurements.rs index 0f640e2..e34affa 100644 --- a/crates/attestation/src/measurements.rs +++ b/crates/attestation/src/measurements.rs @@ -19,7 +19,7 @@ use attest_types::{ }; use dcap_qvl::quote::Report; use http::{HeaderValue, header::InvalidHeaderValue, uri::InvalidUri}; -use serde::Deserialize; +use serde::{Deserialize, Serialize}; use thiserror::Error; use tracing::warn; @@ -116,28 +116,6 @@ impl DcapMeasurements { Self { mrtd, rtmr0, rtmr1, rtmr2, rtmr3 } } - fn from_map( - mut measurements: HashMap, - ) -> Result { - Ok(Self { - mrtd: measurements - .remove(&DcapMeasurementRegister::MRTD) - .ok_or_else(|| MeasurementFormatError::MissingValue("MRTD".to_string()))?, - rtmr0: measurements - .remove(&DcapMeasurementRegister::RTMR0) - .ok_or_else(|| MeasurementFormatError::MissingValue("RTMR0".to_string()))?, - rtmr1: measurements - .remove(&DcapMeasurementRegister::RTMR1) - .ok_or_else(|| MeasurementFormatError::MissingValue("RTMR1".to_string()))?, - rtmr2: measurements - .remove(&DcapMeasurementRegister::RTMR2) - .ok_or_else(|| MeasurementFormatError::MissingValue("RTMR2".to_string()))?, - rtmr3: measurements - .remove(&DcapMeasurementRegister::RTMR3) - .ok_or_else(|| MeasurementFormatError::MissingValue("RTMR3".to_string()))?, - }) - } - fn iter(&self) -> impl Iterator { [ (DcapMeasurementRegister::MRTD, &self.mrtd), @@ -227,63 +205,80 @@ pub enum ExpectedMeasurements { NoAttestation, } -impl MultiMeasurements { +#[derive(Serialize, Deserialize)] +#[serde(tag = "type", content = "measurements", rename_all = "snake_case")] +enum ExpectedMeasurementsHeader { + Image(DcapImageHashes), + Dcap(HashMap>), + Azure(HashMap>), + NoAttestation, +} + +impl ExpectedMeasurements { /// Convert to the JSON format used in HTTP headers pub fn to_header_format(&self) -> Result { - let measurements_map = match self { - MultiMeasurements::Dcap(dcap_measurements) => dcap_measurements - .iter() - .map(|(register, value)| ((register as u8).to_string(), hex::encode(value))) - .collect(), - MultiMeasurements::Azure(azure_measurements) => azure_measurements - .iter() - .map(|(index, value)| (index.to_string(), hex::encode(value))) - .collect(), - MultiMeasurements::NoAttestation => HashMap::new(), + let header_measurements = match self { + Self::Image(image_hashes) => ExpectedMeasurementsHeader::Image(image_hashes.clone()), + Self::Dcap(dcap_measurements) => ExpectedMeasurementsHeader::Dcap( + dcap_measurements + .iter() + .map(|(register, values)| { + ( + (register.clone() as u8).to_string(), + values.iter().map(hex::encode).collect(), + ) + }) + .collect(), + ), + Self::Azure(azure_measurements) => ExpectedMeasurementsHeader::Azure( + azure_measurements + .iter() + .map(|(index, values)| { + (index.to_string(), values.iter().map(hex::encode).collect()) + }) + .collect(), + ), + Self::NoAttestation => ExpectedMeasurementsHeader::NoAttestation, }; - Ok(HeaderValue::from_str(&serde_json::to_string(&measurements_map)?)?) + Ok(HeaderValue::from_str(&serde_json::to_string(&header_measurements)?)?) } /// Parse the JSON used in HTTP headers - pub fn from_header_format( - input: &str, - attestation_type: AttestationType, - ) -> Result { - let measurements_map: HashMap = serde_json::from_str(input)?; - - Ok(match attestation_type { - AttestationType::None => Self::NoAttestation, - AttestationType::AzureTdx => Self::Azure( - measurements_map + pub fn from_header_format(input: &str) -> Result { + fn decode_values( + values: Vec, + ) -> Result, MeasurementFormatError> { + values + .into_iter() + .map(|value| { + hex::decode(value)?.try_into().map_err(|_| MeasurementFormatError::BadLength) + }) + .collect() + } + + Ok(match serde_json::from_str(input)? { + ExpectedMeasurementsHeader::Image(image_hashes) => Self::Image(image_hashes), + ExpectedMeasurementsHeader::Dcap(dcap_measurements) => Self::Dcap( + dcap_measurements .into_iter() - .map(|(k, v)| { - Ok(( - k as u32, - hex::decode(v)? - .try_into() - .map_err(|_| MeasurementFormatError::BadLength)?, - )) + .map(|(register, values)| { + Ok((register.parse::()?.try_into()?, decode_values::<48>(values)?)) }) .collect::>()?, ), - AttestationType::DcapTdx | AttestationType::GcpTdx => { - let measurements_map = measurements_map + ExpectedMeasurementsHeader::Azure(azure_measurements) => Self::Azure( + azure_measurements .into_iter() - .map(|(k, v)| { - Ok(( - k.try_into()?, - hex::decode(v)? - .try_into() - .map_err(|_| MeasurementFormatError::BadLength)?, - )) - }) - .collect::>()?; - Self::Dcap(DcapMeasurements::from_map(measurements_map)?) - } + .map(|(index, values)| Ok((index.parse()?, decode_values::<32>(values)?))) + .collect::>()?, + ), + ExpectedMeasurementsHeader::NoAttestation => Self::NoAttestation, }) } +} +impl MultiMeasurements { /// Given a quote from the dcap_qvl library, extract the measurements pub fn from_dcap_qvl_quote( quote: &dcap_qvl::quote::Quote, @@ -421,64 +416,74 @@ impl MeasurementPolicy { } /// Given an attestation type and set of measurements, check whether - /// they are acceptable + /// they are acceptable. + /// + /// On success, returns the matched measurements. pub fn check_measurement( &self, measurements: &MultiMeasurements, platform_metadata: Option<&PlatformMetadata>, - ) -> Result<(), AttestationError> { + ) -> Result { self.check_measurement_with_gcp_cache(measurements, platform_metadata, None) } /// Given an attestation type and set of measurements, check whether /// they are acceptable, passing an optional cache for known GCP - /// firmware + /// firmware. Returns the expected measurements from the matching policy + /// record. pub(crate) fn check_measurement_with_gcp_cache( &self, measurements: &MultiMeasurements, platform_metadata: Option<&PlatformMetadata>, known_gcp_firmware: Option<&GcpFirmwareCache>, - ) -> Result<(), AttestationError> { - if self.accepted_measurements.iter().any(|measurement_record| match measurements { - MultiMeasurements::Dcap(dcap_measurements) => match &measurement_record.measurements { - ExpectedMeasurements::Dcap(expected) => { - // All measurements in our policy must be given and must match - for (k, v) in expected.iter() { - let actual_value = dcap_measurements.get(k); - if !v.iter().any(|v| actual_value == v) { - return false; + ) -> Result { + self.accepted_measurements + .iter() + .find(|measurement_record| match measurements { + MultiMeasurements::Dcap(dcap_measurements) => { + match &measurement_record.measurements { + ExpectedMeasurements::Dcap(expected) => { + // All measurements in our policy must be given and must match + for (k, v) in expected.iter() { + let actual_value = dcap_measurements.get(k); + if !v.iter().any(|v| actual_value == v) { + return false; + } + } + true + } + ExpectedMeasurements::Image(image_hashes) => { + compare_portable_dcap_measurement( + image_hashes, + dcap_measurements, + platform_metadata, + known_gcp_firmware, + ) + } + ExpectedMeasurements::Azure(_) | ExpectedMeasurements::NoAttestation => { + false } } - true } - ExpectedMeasurements::Image(image_hashes) => compare_portable_dcap_measurement( - image_hashes, - dcap_measurements, - platform_metadata, - known_gcp_firmware, - ), - ExpectedMeasurements::Azure(_) | ExpectedMeasurements::NoAttestation => false, - }, - MultiMeasurements::Azure(azure_measurements) => { - if let ExpectedMeasurements::Azure(expected) = &measurement_record.measurements { - for (k, v) in expected.iter() { - match azure_measurements.get(k) { - Some(actual_value) if v.iter().any(|v| actual_value == v) => {} - _ => return false, + MultiMeasurements::Azure(azure_measurements) => { + if let ExpectedMeasurements::Azure(expected) = &measurement_record.measurements + { + for (k, v) in expected.iter() { + match azure_measurements.get(k) { + Some(actual_value) if v.iter().any(|v| actual_value == v) => {} + _ => return false, + } } + return true; } - return true; + false } - false - } - MultiMeasurements::NoAttestation => { - matches!(measurement_record.measurements, ExpectedMeasurements::NoAttestation) - } - }) { - Ok(()) - } else { - Err(AttestationError::MeasurementsNotAccepted) - } + MultiMeasurements::NoAttestation => { + matches!(measurement_record.measurements, ExpectedMeasurements::NoAttestation) + } + }) + .map(|measurement_record| measurement_record.measurements.clone()) + .ok_or(AttestationError::MeasurementsNotAccepted) } /// Whether or not we require attestation @@ -837,8 +842,6 @@ pub(crate) fn compare_portable_dcap_measurement( pub enum MeasurementFormatError { #[error("JSON: {0}")] Json(#[from] serde_json::Error), - #[error("Missing value: {0}")] - MissingValue(String), #[error("Invalid header value: {0}")] BadHeaderValue(#[from] InvalidHeaderValue), #[error("IO: {0}")] @@ -1116,14 +1119,46 @@ mod tests { } #[test] - fn test_dcap_header_format_rejects_incomplete_measurements() { - let input = serde_json::to_string(&HashMap::from([("0", hex::encode([0u8; 48]))])).unwrap(); + fn expected_measurements_header_format_round_trips_all_variants() { + let measurements = [ + ExpectedMeasurements::Image(DcapImageHashes { + uki_authenticode: [0x11; 48], + kernel_authenticode: [0x22; 48], + cmdline_hash: [0x33; 48], + initrd_hash: [0x44; 48], + gpt_disk_guid_hash: [0x55; 48], + }), + ExpectedMeasurements::Dcap(HashMap::from([ + (DcapMeasurementRegister::MRTD, vec![[0x66; 48], [0x77; 48]]), + (DcapMeasurementRegister::RTMR2, vec![[0x88; 48]]), + ])), + ExpectedMeasurements::Azure(HashMap::from([ + (4, vec![[0x99; 32], [0xaa; 32]]), + (11, vec![[0xbb; 32]]), + ])), + ExpectedMeasurements::NoAttestation, + ]; + + for expected in measurements { + let header = expected.to_header_format().unwrap(); + let decoded = + ExpectedMeasurements::from_header_format(header.to_str().unwrap()).unwrap(); + + assert_eq!(decoded, expected); + } + } - let result = MultiMeasurements::from_header_format(&input, AttestationType::DcapTdx); + #[test] + fn expected_measurements_header_format_rejects_bad_hash_length() { + let input = serde_json::json!({ + "type": "dcap", + "measurements": { "0": ["00"] }, + }) + .to_string(); assert!(matches!( - result, - Err(MeasurementFormatError::MissingValue(register)) if register == "RTMR0" + ExpectedMeasurements::from_header_format(&input), + Err(MeasurementFormatError::BadLength) )); }