feat(protocol): relying party attestation policy (#741)

Introduces AttestationPolicy to carry the attestation verification decisions §8 delegates to the Relying Party, configured on webauthn.Config and threaded through to the format handlers. Its first member selects the Android Key authorization lists the origin and purpose requirements are evaluated against, defaulting to teeEnforced alone so an unset policy accepts only keys generated within a trusted execution environment.

BREAKING CHANGE: AttestationObject.Verify and AttestationObject.VerifyAttestation take an AttestationPolicy, and ConfigProvider requires GetAttestationPolicy.

Author: james-d-elliott

protocol/attestation.go

@@ -99,7 +99,7 @@ type NonCompoundAttestationObject struct {
 	AttStatement map[string]any `json:"attStmt,omitempty"`
 }
 
-type attestationFormatValidationHandler func(att AttestationObject, clientDataHash []byte, mds metadata.Provider) (attestationType string, x5cs []any, err error)
+type attestationFormatValidationHandler func(att AttestationObject, clientDataHash []byte, mds metadata.Provider, policy AttestationPolicy) (attestationType string, x5cs []any, err error)
 
 var attestationRegistry = make(map[AttestationFormat]attestationFormatValidationHandler)
 
@@ -149,7 +149,7 @@ func (ccr *AuthenticatorAttestationResponse) Parse() (p *ParsedAttestationRespon
 //
 // Steps 13 through 15 are verified against the auth data. These steps are identical to 15 through 18 for assertion so we
 // handle them with AuthData.
-func (a *AttestationObject) Verify(relyingPartyID string, clientDataHash []byte, userVerificationRequired bool, userPresenceRequired bool, mds metadata.Provider, credParams []CredentialParameter) (err error) {
+func (a *AttestationObject) Verify(relyingPartyID string, clientDataHash []byte, userVerificationRequired bool, userPresenceRequired bool, mds metadata.Provider, credParams []CredentialParameter, policy AttestationPolicy) (err error) {
 	rpIDHash := sha256.Sum256([]byte(relyingPartyID))
 
 	// Begin Step 13 through 15. Verify that the rpIdHash in authData is the SHA-256 hash of the RP ID expected by the RP.
@@ -177,12 +177,15 @@ func (a *AttestationObject) Verify(relyingPartyID string, clientDataHash []byte,
 		return ErrAttestationFormat.WithInfo("Credential public key algorithm not supported")
 	}
 
-	return a.VerifyAttestation(clientDataHash, mds)
+	return a.VerifyAttestation(clientDataHash, mds, policy)
 }
 
 // VerifyAttestation only verifies the attestation object excluding the AuthData values. If you wish to also verify the
 // AuthData values you should use [Verify].
-func (a *AttestationObject) VerifyAttestation(clientDataHash []byte, mds metadata.Provider) (err error) {
+//
+// The policy carries the Relying Party decisions which §8 leaves to the Relying Party. Its zero value selects the
+// most restrictive behavior available. See [AttestationPolicy].
+func (a *AttestationObject) VerifyAttestation(clientDataHash []byte, mds metadata.Provider, policy AttestationPolicy) (err error) {
 	// Step 18. Determine the attestation statement format by performing a
 	// USASCII case-sensitive match on fmt against the set of supported
 	// WebAuthn Attestation Statement Format Identifier values. The up-to-date
@@ -223,7 +226,7 @@ func (a *AttestationObject) VerifyAttestation(clientDataHash []byte, mds metadat
 	// Step 19. Verify that attStmt is a correct attestation statement, conveying a valid attestation signature, by using
 	// the attestation statement format fmt’s verification procedure given attStmt, authData and the hash of the serialized
 	// client data computed in step 7.
-	if attestationType, x5cs, err = handler(*a, clientDataHash, mds); err != nil {
+	if attestationType, x5cs, err = handler(*a, clientDataHash, mds, policy); err != nil {
 		var e *Error
 
 		if errors.As(err, &e) {

protocol/attestation_androidkey.go

@@ -37,7 +37,7 @@ import (
 // See: https://www.w3.org/TR/webauthn/#sctn-android-key-attestation
 //
 //nolint:gocyclo
-func attestationFormatValidationHandlerAndroidKey(att AttestationObject, clientDataHash []byte, _ metadata.Provider) (attestationType string, x5cs []any, err error) {
+func attestationFormatValidationHandlerAndroidKey(att AttestationObject, clientDataHash []byte, _ metadata.Provider, policy AttestationPolicy) (attestationType string, x5cs []any, err error) {
 	var (
 		alg int64
 		sig []byte
@@ -145,22 +145,30 @@ func attestationFormatValidationHandlerAndroidKey(att AttestationObject, clientD
 		return "", nil, ErrAttestationFormat.WithDetails("Attestation challenge not equal to clientDataHash")
 	}
 
-	if protoErr := androidKeyValidateAuthorizationLists(&decoded); protoErr != nil {
+	if protoErr := androidKeyValidateAuthorizationLists(&decoded, policy.AndroidKey.AuthorizationScope); protoErr != nil {
 		return "", nil, protoErr
 	}
 
 	return string(metadata.BasicFull), x5c, err
 }
 
-// androidKeyValidateAuthorizationLists performs the §8.4 verification steps which apply to the authorization lists of
-// the Android key attestation certificate extension.
-func androidKeyValidateAuthorizationLists(decoded *androidkeyDescription) *Error {
+// androidKeyValidateAuthorizationLists performs the §8.4 verification steps which apply to the authorization lists
+// of the Android key attestation certificate extension.
+//
+// The scope selects the lists the origin and purpose requirements are evaluated against, which §8.4 leaves to the
+// Relying Party. See [AndroidKeyAuthorizationScope].
+func androidKeyValidateAuthorizationLists(decoded *androidkeyDescription, scope AndroidKeyAuthorizationScope) *Error {
 	// The AuthorizationList.allApplications field is not present on either authorization list (softwareEnforced nor teeEnforced), since PublicKeyCredential MUST be scoped to the RP ID.
+	//
+	// This requirement precedes the sentence which introduces the Relying Party's choice of scope, so it applies to
+	// both lists regardless of the scope in effect.
 	if len(decoded.SoftwareEnforced.AllApplications.FullBytes) != 0 || len(decoded.TeeEnforced.AllApplications.FullBytes) != 0 {
 		return ErrAttestationFormat.WithDetails("Attestation certificate extensions contains all applications field")
 	}
 
 	// For the following, use only the teeEnforced authorization list if the RP wants to accept only keys from a trusted execution environment, otherwise use the union of teeEnforced and softwareEnforced.
+	union := scope.union()
+
 	// The value in the AuthorizationList.origin field is equal to KM_ORIGIN_GENERATED (which == 0).
 	var (
 		originTee, originSoftware   int
@@ -172,26 +180,51 @@ func androidKeyValidateAuthorizationLists(decoded *androidkeyDescription) *Error
 		return ErrAttestationFormat.WithDetails("Unable to parse the origin of the teeEnforced authorization list").WithError(err)
 	}
 
-	if originSoftware, presentSoftware, err = authorizationListOrigin(&decoded.SoftwareEnforced); err != nil {
-		return ErrAttestationFormat.WithDetails("Unable to parse the origin of the softwareEnforced authorization list").WithError(err)
+	// The softwareEnforced list is only parsed when the scope consults it, so a malformed origin there cannot fail
+	// an attestation the teeEnforced scope would otherwise accept on the teeEnforced list alone.
+	if union {
+		if originSoftware, presentSoftware, err = authorizationListOrigin(&decoded.SoftwareEnforced); err != nil {
+			return ErrAttestationFormat.WithDetails("Unable to parse the origin of the softwareEnforced authorization list").WithError(err)
+		}
 	}
 
-	// The union is satisfied when either list carries an origin equal to KM_ORIGIN_GENERATED. An absent origin
-	// satisfies nothing as there is no value to compare against, which mirrors the purpose check below.
-	generated := (presentTee && originTee == KM_ORIGIN_GENERATED) || (presentSoftware && originSoftware == KM_ORIGIN_GENERATED)
+	// An absent origin satisfies nothing as there is no value to compare against, which mirrors the purpose check
+	// below.
+	generated := presentTee && originTee == KM_ORIGIN_GENERATED
+
+	if union && !generated {
+		generated = presentSoftware && originSoftware == KM_ORIGIN_GENERATED
+	}
 
 	if !generated {
-		return ErrAttestationFormat.WithDetails("Attestation certificate extensions contains authorization list with origin not equal KM_ORIGIN_GENERATED")
+		return ErrAttestationFormat.WithDetails(fmt.Sprintf("Attestation certificate extensions contains %s with origin not equal KM_ORIGIN_GENERATED", androidKeyScopeDescription(union)))
 	}
 
 	// The value in the AuthorizationList.purpose field is equal to KM_PURPOSE_SIGN (which == 2).
-	if !contains(decoded.SoftwareEnforced.Purpose, KM_PURPOSE_SIGN) && !contains(decoded.TeeEnforced.Purpose, KM_PURPOSE_SIGN) {
-		return ErrAttestationFormat.WithDetails("Attestation certificate extensions contains authorization list with purpose not equal KM_PURPOSE_SIGN")
+	sign := contains(decoded.TeeEnforced.Purpose, KM_PURPOSE_SIGN)
+
+	if union && !sign {
+		sign = contains(decoded.SoftwareEnforced.Purpose, KM_PURPOSE_SIGN)
+	}
+
+	if !sign {
+		return ErrAttestationFormat.WithDetails(fmt.Sprintf("Attestation certificate extensions contains %s with purpose not equal KM_PURPOSE_SIGN", androidKeyScopeDescription(union)))
 	}
 
 	return nil
 }
 
+// androidKeyScopeDescription names the authorization lists the §8.4 origin and purpose requirements were evaluated
+// against so that a failure identifies the scope in effect. The union wording is unqualified as it matches the
+// specification's own phrasing and preserves the error text of the union scope.
+func androidKeyScopeDescription(union bool) string {
+	if union {
+		return "authorization list"
+	}
+
+	return "teeEnforced authorization list"
+}
+
 // authorizationListOrigin returns the origin of an authorization list and reports whether the field was present. The
 // value is decoded from the raw element because encoding/asn1 leaves an absent optional integer at its zero value,
 // which is indistinguishable from a present origin of KM_ORIGIN_GENERATED.
@@ -264,8 +297,10 @@ var authorizationListValidatedTags = []int{
 // [authorizationList] can't model and which precedes a field the verification procedure depends on.
 //
 // An unmodelled tag otherwise defeats the §8.4 requirement that allApplications is absent, as the element is dropped
-// along with every field declared after it while the union permits the other list to supply the origin and purpose. A
-// list which can't be modelled in full is rejected explicitly rather than silently truncated.
+// along with every field declared after it. That requirement is checked against both lists in every scope, not only
+// when the union scope draws on softwareEnforced for the origin and purpose checks, so an unmodelled tag in either
+// list needs the same protection regardless of which scope the Relying Party has selected. A list which can't be
+// modelled in full is rejected explicitly rather than silently truncated.
 func androidKeyVerifyAuthorizationListTags(raw *androidkeyDescriptionRaw) *Error {
 	for _, list := range []struct {
 		name string

protocol/attestation_androidkey_scope_wiring_test.go

@@ -0,0 +1,131 @@
+package protocol_test
+
+import (
+	"encoding/base64"
+	"encoding/hex"
+	"encoding/json"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/go-webauthn/webauthn/protocol"
+	"github.com/go-webauthn/webauthn/protocol/webauthncose"
+	"github.com/go-webauthn/webauthn/webauthn"
+)
+
+func TestCreateCredential_AndroidKeyAuthorizationScope(t *testing.T) {
+	const (
+		errTEEEnforced = "Attestation certificate extensions contains teeEnforced authorization list with origin not equal KM_ORIGIN_GENERATED"
+		errUnion       = "Attestation certificate extensions contains authorization list with origin not equal KM_ORIGIN_GENERATED"
+	)
+
+	testCases := []struct {
+		name        string
+		attestation protocol.AttestationPolicy
+		err         string
+	}{
+		{
+			name:        "ShouldRejectSoftwareBackedKeyUnderDefaultScope",
+			attestation: protocol.AttestationPolicy{},
+			err:         errTEEEnforced,
+		},
+		{
+			name: "ShouldRejectSoftwareBackedKeyUnderTEEEnforcedScope",
+			attestation: protocol.AttestationPolicy{
+				AndroidKey: protocol.AndroidKeyPolicy{AuthorizationScope: protocol.AndroidKeyAuthorizationScopeTEEEnforced},
+			},
+			err: errTEEEnforced,
+		},
+		{
+			name: "ShouldRejectSoftwareBackedKeyUnderUnionScopeWithUnionWording",
+			attestation: protocol.AttestationPolicy{
+				AndroidKey: protocol.AndroidKeyPolicy{AuthorizationScope: protocol.AndroidKeyAuthorizationScopeUnion},
+			},
+			err: errUnion,
+		},
+	}
+
+	for _, tc := range testCases {
+		t.Run(tc.name, func(t *testing.T) {
+			body, challenge := androidKeyScopeWiringSpecVector(t)
+
+			parsedResponse, err := protocol.ParseCredentialCreationResponseBytes(body)
+			require.NoError(t, err)
+
+			userID := []byte("test-user-id")
+
+			w := &webauthn.WebAuthn{
+				Config: &webauthn.Config{
+					RPID:        "example.org",
+					RPOrigins:   []string{"https://example.org"},
+					Attestation: tc.attestation,
+				},
+			}
+
+			session := webauthn.SessionData{
+				Challenge:  challenge,
+				UserID:     userID,
+				CredParams: []protocol.CredentialParameter{{Type: protocol.PublicKeyCredentialType, Algorithm: webauthncose.AlgES256}},
+			}
+
+			credential, err := w.CreateCredential(androidKeyScopeWiringTestUser{id: userID}, session, parsedResponse)
+
+			assert.Nil(t, credential)
+			assert.EqualError(t, err, tc.err)
+		})
+	}
+}
+
+type androidKeyScopeWiringTestUser struct {
+	id []byte
+}
+
+func (u androidKeyScopeWiringTestUser) WebAuthnID() []byte                         { return u.id }
+func (u androidKeyScopeWiringTestUser) WebAuthnName() string                       { return "test-user" }
+func (u androidKeyScopeWiringTestUser) WebAuthnDisplayName() string                { return "Test User" }
+func (u androidKeyScopeWiringTestUser) WebAuthnCredentials() []webauthn.Credential { return nil }
+
+func androidKeyScopeWiringSpecVector(t *testing.T) (body []byte, challenge string) {
+	t.Helper()
+
+	const (
+		attestationObjectHex = "a363666d746b616e64726f69642d6b65796761747453746d74a363616c67266373696758483046022100e95512982aa3f216cff2e87c8ec57057b8529f674eaabeccaa27fd03d8779f19022100afb6bf459da4a826f00d01fc6b60712ff31dc4eb331619c8f874bb17e4314e94637835638159026e3082026a30820210a00302010202101ff91f76b63f44812f998b250b0286bf300a06082a8648ce3d0403023062311e301c06035504030c15576562417574686e207465737420766563746f7273310c300a060355040a0c0357334331253023060355040b0c1c41757468656e74696361746f72204174746573746174696f6e204341310b30090603550406130241413020170d3234303130313030303030305a180f33303234303130313030303030305a305f311e301c06035504030c15576562417574686e207465737420766563746f7273310c300a060355040a0c0357334331223020060355040b0c1941757468656e74696361746f72204174746573746174696f6e310b30090603550406130241413059301306072a8648ce3d020106082a8648ce3d0301070342000499169657036d089a2a9821a7d0063d341f1a4613389359636efab5f3cbf1accfdd91c55543176ea99b644406dd1dd63774b6af65ac759e06ff40b1c8ab02df6ba381a83081a5300c0603551d130101ff04023000300e0603551d0f0101ff040403020780301d0603551d0e041604141ac81e50641e8d1339ab9f7eb25f0cd5aac054b0301f0603551d2304183016801445aff715b0dd786741fee996ebc16547a3931b1e3045060a2b06010401d679020111043730350202012c0a01000201000a01000420b435028d7b6a8f83bb461d41c19b053a9d3cdb30351a4f374cd4cde8dbefb606040030003000300a06082a8648ce3d040302034800304502202d27f0ca39d2f519fc8f49c6d96dfc793059e211ff80516a50398cf1eac2a322022100d482a88c740f64cf6a98ccc6c8b9f5e1e533fa5e509f0a7b4c3a02f964a8eba768617574684461746158a4bfabc37432958b063360d3ad6461c9c4735ae7f8edd46592a5e0f01452b2e4b55d00000000ade9705e1ce7085b899a540d02199bf800200a4729519788b6ed8a2d772b494e186244d8c798c052960dbc8c10c915176795a501020326200121582099169657036d089a2a9821a7d0063d341f1a4613389359636efab5f3cbf1accf225820dd91c55543176ea99b644406dd1dd63774b6af65ac759e06ff40b1c8ab02df6b"
+		clientDataJSONHex    = "7b2274797065223a22776562617574686e2e637265617465222c226368616c6c656e6765223a2250654877747a5a647a4e345f384d76795869625f7037725f682d385162494438686c334541746d57414641222c226f726967696e223a2268747470733a2f2f6578616d706c652e6f7267222c2263726f73734f726967696e223a66616c73652c22657874726144617461223a22636c69656e74446174614a534f4e206d617920626520657874656e6465642077697468206164646974696f6e616c206669656c647320696e20746865206675747572652c207375636820617320746869733a205656316351755232714c4d5f616d50666f487a4c3067227d"
+		credentialIDHex      = "0a4729519788b6ed8a2d772b494e186244d8c798c052960dbc8c10c915176795" //nolint:gosec
+		challengeHex         = "3de1f0b7365dccde3ff0cbf25e26ffa7baff87ef106c80fc865dc402d9960050"
+	)
+
+	credentialID, err := hex.DecodeString(credentialIDHex)
+	require.NoError(t, err)
+
+	challengeBytes, err := hex.DecodeString(challengeHex)
+	require.NoError(t, err)
+
+	challenge = base64.RawURLEncoding.EncodeToString(challengeBytes)
+
+	attestationObjectBytes, err := hex.DecodeString(attestationObjectHex)
+	require.NoError(t, err)
+
+	clientDataJSONBytes, err := hex.DecodeString(clientDataJSONHex)
+	require.NoError(t, err)
+
+	id := base64.RawURLEncoding.EncodeToString(credentialID)
+	attObj := base64.RawURLEncoding.EncodeToString(attestationObjectBytes)
+	cdj := base64.RawURLEncoding.EncodeToString(clientDataJSONBytes)
+
+	response := map[string]any{
+		"id":    id,
+		"rawId": id,
+		"type":  "public-key",
+		"response": map[string]any{
+			"attestationObject": attObj,
+			"clientDataJSON":    cdj,
+		},
+	}
+
+	body, err = json.Marshal(response)
+	require.NoError(t, err)
+
+	return body, challenge
+}