From b159b9e6aef79138161b73d96692573f65395617 Mon Sep 17 00:00:00 2001 From: Priyanshu Thapliyal Date: Sat, 4 Jan 2025 00:33:50 +0530 Subject: [PATCH] Update doc.go to align with the current implementation of AttestationResult --- doc.go | 106 +++++++++++++++++++++++++++++++-------------------------- 1 file changed, 57 insertions(+), 49 deletions(-) diff --git a/doc.go b/doc.go index ced67d9..bcb92d1 100644 --- a/doc.go +++ b/doc.go @@ -9,56 +9,64 @@ https://datatracker.ietf.org/doc/draft-ietf-rats-ar4si/ # Construction An AttestationResult object is constructed by populating the relevant fields. -The mandatory attributes are: status, timestamp and profile. +The mandatory attributes are: status, issued_at, profile, submods, and verifier_id. For example, a simple AttestationResult payload with only the bare minimum claims could be created as follows: - myStatus := TrustTierAffirming - myTimestamp := time.Now().Format(time.RFC3339) - myPolicyID := `https://veraison.example/policy/1A4DF345-B512-4F3B-8461-967DE7F60ECA` - myProfile := EatProfile - - ar := AttestationResult{ - Status: &myStatus, - Timestamp: &testTimestamp, - AppraisalPolicyID: &testPolicyID, - Profile: &testProfile, - } + myStatus := TrustTierAffirming + myTimestamp := time.Now().Unix() + myPolicyID := `https://veraison.example/policy/1A4DF345-B512-4F3B-8461-967DE7F60ECA` + myProfile := EatProfile + + ar := AttestationResult{ + Profile: &myProfile, + IssuedAt: &myTimestamp, + Submods: map[string]*Appraisal{ + "submodName": { + TrustVector: &TrustVector{}, + Status: &myStatus, + }, + }, + VerifierID: &VerifierIdentity{ + Build: &verifierBuild, + Developer: &verifierDeveloper, + }, + } A richer one would normally include the Trustworthiness Vector, which provides -details about the appraised attester components. In the example below, the +details about the appraised attester components. In the example below, the attester has been assessed as genuine, i.e., all claims are in the "affirming" -range. (See §2.3 of draft-ietf-rats-ar4si-03 for details about the allowed values +range. (See §2.3 of draft-ietf-rats-ar4si-03 for details about the allowed values and their meaning.) - tv := TrustVector{ - InstanceIdentity: 2, - Configuration: 2, - Executables: 2, - Hardware: 2, - } + tv := TrustVector{ + InstanceIdentity: 2, + Configuration: 2, + Executables: 2, + Hardware: 2, + } - ar.TrustVector := &tv + ar.Submods["submodName"].TrustVector = &tv # Signing and Serializing Once the AttestationResult is populated, it can be signed (i.e., wrapped in a JWT) by invoking the Sign method: - myECDSAPrivateKey = `{ - "kty": "EC", - "crv": "P-256", - "x": "usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8", - "y": "IBOL-C3BttVivg-lSreASjpkttcsz-1rb7btKLv8EX4", - "d": "V8kgd2ZBRuh2dgyVINBUqpPDr7BOMGcF22CQMIUHtNM" - }` + myECDSAPrivateKey := `{ + "kty": "EC", + "crv": "P-256", + "x": "usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8", + "y": "IBOL-C3BttVivg-lSreASjpkttcsz-1rb7btKLv8EX4", + "d": "V8kgd2ZBRuh2dgyVINBUqpPDr7BOMGcF22CQMIUHtNM" + }` - sigK, _ := jwk.ParseKey([]byte(myECDSAPrivateKey)) + sigK, _ := jwk.ParseKey([]byte(myECDSAPrivateKey)) - buf, _ = ar.Sign(jwa.ES256, sigK) + buf, _ := ar.Sign(jwa.ES256, sigK) In this case, the returned buf contains a signed ES256 JWT with the JSON -serialization of the AttestationResult object as its payload. This is the usual +serialization of the AttestationResult object as its payload. This is the usual JWT format that can be used as-is for interchange with other applications. # Parsing and Verifying @@ -67,38 +75,38 @@ On the consumer end of the protocol, when the EAT containing the attestation result is received from a veraison verifier, the relying party needs to first parse it and verify the signature using the Verify method: - myECDSAPublicKey = `{ - "kty": "EC", - "crv": "P-256", - "x": "usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8", - "y": "IBOL-C3BttVivg-lSreASjpkttcsz-1rb7btKLv8EX4" - }` + myECDSAPublicKey := `{ + "kty": "EC", + "crv": "P-256", + "x": "usWxHK2PmfnHKwXPS54m0kTcGJ90UiglWiGahtagnv8", + "y": "IBOL-C3BttVivg-lSreASjpkttcsz-1rb7btKLv8EX4" + }` - vfyK, _ := jwk.ParseKey([]byte(myECDSAPublicKey)) + vfyK, _ := jwk.ParseKey([]byte(myECDSAPublicKey)) - var ar AttestationResult + var ar AttestationResult - err := ar.Verify(token, jwa.ES256, vfyK) - if err != nil { - // handle verification error - } + err := ar.Verify(token, jwa.ES256, vfyK) + if err != nil { + // handle verification error + } If there are no errors, the relying party can trust the attestation result and inspect the relevant fields to decide about the trustworthiness of the attested entity. - if *ar.Status != TrustTierAffirming { - // handle troubles with appraisal - } + if *ar.Submods["submodName"].Status != TrustTierAffirming { + // handle troubles with appraisal + } # Pretty printing The package provides a Report method that allows pretty printing of the -Trustworthiness Vector. The caller can request a short summary or a detailed +Trustworthiness Vector. The caller can request a short summary or a detailed printout, as well as using colors when displaying the claims' values. - short, color := true, true + short, color := true, true - fmt.Print(ar.TrustVector.Report(short, color)) + fmt.Print(ar.Submods["submodName"].TrustVector.Report(short, color)) */ package ear