feat: ml-dsa preference list and gated availability (#768)

This adds webauthn.CredentialParametersPQCRecommendedL3 which includes the recommended order of algorithms for RP's that support ML-DSA. In addition it gates all ML-DSA availability on go 1.27 so that the API is clearer.

Author: james-d-elliott

protocol/attestation_mldsa_test.go

@@ -60,6 +60,50 @@ func TestVerifyAttestationPublicKeyMatchMLDSA(t *testing.T) {
 	})
 }
 
+// TestAKPHelpersRejectOtherKeyTypes asserts that neither helper claims a key which is not of the AKP key type. Each
+// is reached only from the default arm of a switch which has already handled every other key type, so a helper
+// which claimed one of them would divert a key away from the branch that knows how to handle it.
+func TestAKPHelpersRejectOtherKeyTypes(t *testing.T) {
+	keys := []any{
+		struct{}{},
+		webauthncose.EC2PublicKeyData{},
+		webauthncose.RSAPublicKeyData{},
+		webauthncose.OKPPublicKeyData{},
+	}
+
+	for _, key := range keys {
+		algorithm, ok := akpKeyAlgorithm(key)
+
+		assert.False(t, ok)
+		assert.Zero(t, algorithm)
+
+		public, ok, err := akpPublicKey(key)
+
+		assert.False(t, ok)
+		assert.Nil(t, public)
+		require.NoError(t, err)
+	}
+
+	t.Run("ShouldClaimAKPKey", func(t *testing.T) {
+		_, pub := mldsaTestCredentialPublicKey(t, webauthncose.AlgMLDSA44, mldsa.MLDSA44())
+
+		parsed, err := webauthncose.ParsePublicKey(pub)
+
+		require.NoError(t, err)
+
+		algorithm, ok := akpKeyAlgorithm(parsed)
+
+		assert.True(t, ok)
+		assert.Equal(t, int64(webauthncose.AlgMLDSA44), algorithm)
+
+		public, ok, err := akpPublicKey(parsed)
+
+		assert.True(t, ok)
+		require.NoError(t, err)
+		assert.NotNil(t, public)
+	})
+}
+
 // TestPackedFormat_SelfAttestationMLDSA asserts that a packed self attestation made with an ML-DSA credential key
 // verifies, and that a statement whose alg contradicts the credential public key does not.
 //

protocol/attestation_packed.go

@@ -214,10 +214,13 @@ func handleSelfAttestation(alg int64, pubKey, authData, clientDataHash, sig []by
 		err = verifyKeyAlgorithm(k.Algorithm, alg)
 	case webauthncose.RSAPublicKeyData:
 		err = verifyKeyAlgorithm(k.Algorithm, alg)
-	case webauthncose.AKPPublicKeyData:
-		err = verifyKeyAlgorithm(k.Algorithm, alg)
 	default:
-		return "", nil, ErrInvalidAttestation.WithDetails("Error verifying the public key data")
+		keyAlgorithm, ok := akpKeyAlgorithm(key)
+		if !ok {
+			return "", nil, ErrInvalidAttestation.WithDetails("Error verifying the public key data")
+		}
+
+		err = verifyKeyAlgorithm(keyAlgorithm, alg)
 	}
 
 	if err != nil {

protocol/mldsa.go

@@ -0,0 +1,35 @@
+//go:build go1.27
+
+package protocol
+
+import (
+	"crypto"
+
+	"github.com/go-webauthn/webauthn/protocol/webauthncose"
+)
+
+// akpKeyAlgorithm returns the COSE algorithm a credential public key of the AKP key type names, and whether the key
+// is one at all. It exists so that the attestation formats can hold such a key to the algorithm an attestation
+// statement declares without naming a type which only exists on a build that can verify with it.
+func akpKeyAlgorithm(key any) (algorithm int64, ok bool) {
+	k, is := key.(webauthncose.AKPPublicKeyData)
+	if !is {
+		return 0, false
+	}
+
+	return k.Algorithm, true
+}
+
+// akpPublicKey converts a credential public key of the AKP key type into the equivalent standard library key. The
+// second value reports whether the key was one at all, which distinguishes a key this does not handle from an AKP
+// key which could not be converted.
+func akpPublicKey(key any) (public crypto.PublicKey, ok bool, err error) {
+	k, is := key.(webauthncose.AKPPublicKeyData)
+	if !is {
+		return nil, false, nil
+	}
+
+	public, err = k.ToPublicKey()
+
+	return public, true, err
+}

protocol/mldsa_unsupported.go

@@ -0,0 +1,18 @@
+//go:build !go1.27
+
+package protocol
+
+import (
+	"crypto"
+)
+
+// akpKeyAlgorithm reports that the key is not one of the AKP key type. No parser on a build which cannot verify an
+// ML-DSA signature produces such a key, so nothing carrying one reaches the attestation formats.
+func akpKeyAlgorithm(_ any) (algorithm int64, ok bool) {
+	return 0, false
+}
+
+// akpPublicKey reports that the key is not one of the AKP key type, for the same reason as [akpKeyAlgorithm].
+func akpPublicKey(_ any) (public crypto.PublicKey, ok bool, err error) {
+	return nil, false, nil
+}

protocol/mldsa_unsupported_test.go

@@ -0,0 +1,38 @@
+//go:build !go1.27
+
+package protocol
+
+import (
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+
+	"github.com/go-webauthn/webauthn/protocol/webauthncose"
+)
+
+// TestAKPHelpersUnsupported asserts that neither helper claims a key on a build which cannot verify an ML-DSA
+// signature. Neither is reached today, as no parser on such a build produces a key of the AKP key type, so they are
+// asserted directly: they are what keeps the attestation formats from treating an unverifiable key as one they
+// handle if that ever changes.
+func TestAKPHelpersUnsupported(t *testing.T) {
+	keys := []any{
+		struct{}{},
+		webauthncose.EC2PublicKeyData{},
+		webauthncose.RSAPublicKeyData{},
+		webauthncose.OKPPublicKeyData{},
+	}
+
+	for _, key := range keys {
+		algorithm, ok := akpKeyAlgorithm(key)
+
+		assert.False(t, ok)
+		assert.Zero(t, algorithm)
+
+		public, ok, err := akpPublicKey(key)
+
+		assert.False(t, ok)
+		assert.Nil(t, public)
+		require.NoError(t, err)
+	}
+}

protocol/utils.go

@@ -246,9 +246,11 @@ func attestationCredentialPublicKey(credentialPublicKey any) (public crypto.Publ
 		// The coordinate is of the length ed25519 requires as webauthncose.ParsePublicKey rejects any other, so no
 		// length is asserted here.
 		return ed25519.PublicKey(k.XCoord), nil
-	case webauthncose.AKPPublicKeyData:
-		return k.ToPublicKey()
 	default:
+		if public, ok, err := akpPublicKey(credentialPublicKey); ok {
+			return public, err
+		}
+
 		return nil, fmt.Errorf("unsupported public key type %T", credentialPublicKey)
 	}
 }

protocol/webauthncose/akp.go

@@ -1,8 +1,12 @@
+//go:build go1.27
+
 package webauthncose
 
 import (
 	"crypto"
 	"fmt"
+
+	"github.com/go-webauthn/webauthn/protocol/webauthncbor"
 )
 
 // AKPPublicKeyData is a credential public key of the AKP (Algorithm Key Pair) key type, which carries its key
@@ -29,9 +33,6 @@ func (k *AKPPublicKeyData) Verify(data []byte, sig []byte) (bool, error) {
 
 // ToPublicKey converts the AKPPublicKeyData to the standard library key of the algorithm it names, which for the
 // ML-DSA parameter sets is a *[crypto/mldsa.PublicKey].
-//
-// The concrete type is not named in the signature because the package which declares it is only present from Go
-// 1.27, which is also the point from which this returns a key at all.
 func (k *AKPPublicKeyData) ToPublicKey() (key crypto.PublicKey, err error) {
 	if err = validateAKPPublicKey(k); err != nil {
 		return nil, err
@@ -40,6 +41,48 @@ func (k *AKPPublicKeyData) ToPublicKey() (key crypto.PublicKey, err error) {
 	return mldsaPublicKey(COSEAlgorithmIdentifier(k.Algorithm), k.PublicKey)
 }
 
+// parseAKPPublicKey decodes a credential public key of the AKP key type. It is the arm [ParsePublicKey] delegates
+// that key type to, so that the parser itself does not name a type which only exists on a build that can verify
+// with it.
+func parseAKPPublicKey(pk PublicKeyData, keyBytes []byte) (key any, err error) {
+	var a AKPPublicKeyData
+
+	if err = webauthncbor.Unmarshal(keyBytes, &a); err != nil {
+		return nil, err
+	}
+
+	a.PublicKeyData = pk
+
+	if err = validateAKPPublicKey(&a); err != nil {
+		return nil, err
+	}
+
+	return a, nil
+}
+
+// verifyAKPSignature is the arm [VerifySignature] delegates a key of the AKP key type to. A key of any other type
+// has already been handled by its caller, so anything reaching here that is not one is a key this library does not
+// verify with.
+func verifyAKPSignature(key any, data []byte, sig []byte) (bool, error) {
+	k, ok := key.(AKPPublicKeyData)
+	if !ok {
+		return false, ErrUnsupportedKey
+	}
+
+	return k.Verify(data, sig)
+}
+
+// displayAKPPublicKey is the arm [DisplayPublicKey] delegates a key of the AKP key type to. A nil encoding and a
+// nil error report that the key is not an AKP key at all, which the caller renders as a key type it cannot display.
+func displayAKPPublicKey(key any) (der []byte, err error) {
+	k, ok := key.(AKPPublicKeyData)
+	if !ok {
+		return nil, nil
+	}
+
+	return mldsaMarshalPublicKey(COSEAlgorithmIdentifier(k.Algorithm), k.PublicKey)
+}
+
 // validateAKPPublicKey checks that a credential public key of type AKP names an algorithm this library verifies
 // with, and carries key material that algorithm accepts.
 //

protocol/webauthncose/akp_test.go

@@ -447,6 +447,22 @@ func TestMLDSAFailsClosed(t *testing.T) {
 		require.EqualError(t, err, "AKP key is not a valid ML-DSA public key")
 	})
 
+	t.Run("DispatchOfOtherKeyTypes", func(t *testing.T) {
+		// Each dispatch arm is reached only from the default of a switch which has handled every other key
+		// type, so claiming one would divert it from the branch which knows how to handle it.
+		for _, other := range []any{struct{}{}, EC2PublicKeyData{}, RSAPublicKeyData{}, OKPPublicKeyData{}} {
+			der, err := displayAKPPublicKey(other)
+
+			assert.Nil(t, der)
+			require.NoError(t, err)
+
+			valid, err := verifyAKPSignature(other, data, sig)
+
+			assert.False(t, valid)
+			require.EqualError(t, err, "Unsupported Public Key Type")
+		}
+	})
+
 	t.Run("MarshalPublicKey", func(t *testing.T) {
 		der, err := mldsaMarshalPublicKey(AlgES256, key.PublicKey)
 

protocol/webauthncose/akp_unsupported.go

@@ -0,0 +1,26 @@
+//go:build !go1.27
+
+package webauthncose
+
+// This file supplies the arms which [ParsePublicKey], [VerifySignature] and [DisplayPublicKey] delegate the AKP key
+// type to on a build which cannot verify a signature made with one.
+//
+// The only algorithms registered for that key type are the ML-DSA parameter sets, which this library verifies with
+// through crypto/mldsa, and the standard library did not have that package before Go 1.27. The credential is
+// refused when it is parsed rather than when it is verified, so a Relying Party never registers a credential it
+// would be unable to authenticate with.
+
+// parseAKPPublicKey refuses a credential public key of the AKP key type.
+func parseAKPPublicKey(_ PublicKeyData, _ []byte) (key any, err error) {
+	return nil, ErrUnsupportedKey.WithDetails("AKP key type requires this library to be built with Go 1.27 or newer")
+}
+
+// verifyAKPSignature refuses a key of the AKP key type, which no parser on this build produces.
+func verifyAKPSignature(_ any, _ []byte, _ []byte) (bool, error) {
+	return false, ErrUnsupportedKey
+}
+
+// displayAKPPublicKey reports that the key is not one it renders, as no key of the AKP key type reaches it.
+func displayAKPPublicKey(_ any) (der []byte, err error) {
+	return nil, nil
+}