Add android-key attestation format support #2322

jbpin · 2025-06-30T09:22:24Z

Add a new attestationFormat for ACME device-attest-01 challenge to support Android attestation (android-key) as defined by WebAuthn and modify by RFC (sig use key authorization).

The implementation involve adding a CRL. ACME provider support a new configuration key called RootCRLs (rootCRLs in json). When 'android-key' is specified in attestationFormat and the list is not provided by the configuration, the list will be populated and updated
automatically based on the validation implementation procedure. Other ACME challenge could use IsRootRevoked and RootCRLs in the future independantly to android-key or device-attest-01 challenge.

Name of feature:

android-key attestation support for device-attest-01 challenge

Pain or issue this feature alleviates:

All to use device identifier certificate issuing on Android devices

Why is this important to the project (if not answered above):

The project already support Apple, so supporting Android is a plus.

Is there documentation on how to use this feature? If so, where?

This PR only provide a new attestationFormat called android-key

In what environments or workflows is this feature supported?

ACME provisionner with device_attest_01 and attestationFormat android-key. The device need to be managed by a MDM and an ACME client for android should be deployed

In what environments or workflows is this feature explicitly NOT supported (if any)?

Supporting links/other PRs/issues:

💔Thank you!

Add a new attestationFormat for ACME device-attest-01 challenge to support Android attestation (android-key) as defined by WebAuthn and modify by RFC (sig use key authorization). The implementation involve adding a CRL. ACME provider support a new configuration key called RootCRLs (rootCRLs in json). When 'android-key' is specified in attestationFormat and the list is not provided by the configuration, the list will be populated and updated automatically based on the validation implementation procedure. Other ACME challenge could use IsRootRevoked and RootCRLs in the future independantly to android-key or device-attest-01 challenge.

jbpin · 2025-06-30T09:32:51Z

Hi,
This PR can be test with a provisioner config like this :

{
            "attestationFormats": [
              "android-key"
            ],
            "challenges": [
              "device-attest-01"
            ],
            "claims": {
              "defaultTLSCertDuration": "2h",
              "maxTLSCertDuration": "8h"
            },
            "name": "android-acme",
            "type": "ACME"
          },

However, this PR will require an update to linkedca for two reason:

android-key is not supported on attestionFormat [in the proto].(https://github.com/smallstep/linkedca/blob/339b487a925e0cf176a55133a755a1a40e602c35/spec/linkedca/provisioners.proto#L149).
the new RootCRLs can't be included in ether ca.json nor step cli, so we can't override the default behavior that consist of loading the Android CRL Json

The CRL List is cached for 24h and refreshed when android-key attestation validation occurred passed this delay.

I will be happy to reply to any comments or suggestions.

hslatman

Hey @jbpin,

Looking quite good overall. Many suggestions are stylistic; feel free to combine them into your own commit(s).

I'd like to test this myself with a device too to inspect the full X5C that's provided. Or, alternatively, it would be nice to get a chain from your testing. There's some surprising thing in the code and the Google docs, so I just want to make sure things are correct.

Functionally, and kind of expected, the biggest thing that needs some attention/changes is fetching and refreshing the revoked attestation certificate serials. Eventually that logic needs to become "more pluggable" because of the way we integrate changes into our hosted version. Concretely, it would not be necessary to refetch the revocation list for each hosted authority, as it would simply be retrieving the same list for each. I think it'll come down to going with a basic version for now, and then we may do some changes to make it compatible with our platform ourselves, but we'll have to see how things roll.

hslatman · 2025-07-31T14:47:16Z

acme/challenge.go

 	"go.step.sm/crypto/x509util"
 	"golang.org/x/exp/slices"

+	"github.com/mbreban/attestation"


Given that this is a new package, and not used in other projects (yet), it might be better to copy/fork its code over, and maintain it internally. Are you familiar with the author?

No I'm not familiar with the author. We can manage to rewrite this lib. The lib support version 1 to 300. I saw there is version 400 now.

acme/challenge_test.go

hslatman · 2025-07-31T14:52:29Z

authority/provisioner/acme.go

+	// APPLE is the format used to enable device-attest-01 on Apple devices.
+	ANDROID ACMEAttestationFormat = "android-key"
+


Suggested change

// APPLE is the format used to enable device-attest-01 on Apple devices.

ANDROID ACMEAttestationFormat = "android-key"

// ANDROIDKEY is the format used to enable device-attest-01 for Android

// devices using Android Key Attestation.

ANDROIDKEY ACMEAttestationFormat = "android-key"

hslatman · 2025-07-31T14:52:46Z

authority/provisioner/acme.go

 func (f ACMEAttestationFormat) Validate() error {
 	switch ACMEAttestationFormat(f.String()) {
-	case APPLE, STEP, TPM:
+	case APPLE, STEP, TPM, ANDROID:


Suggested change

case APPLE, STEP, TPM, ANDROID:

case APPLE, STEP, TPM, ANDROIDKEY:

hslatman · 2025-07-31T14:53:13Z

authority/provisioner/acme.go

 		return fmt.Errorf("failed initializing Wire options: %w", err)
 	}

+	if slices.Contains(p.AttestationFormats, "android-key") && len(p.RootCRLs) == 0 {


Suggested change

if slices.Contains(p.AttestationFormats, "android-key") && len(p.RootCRLs) == 0 {

if slices.Contains(p.AttestationFormats, ANDROIDKEY) && len(p.RootCRLs) == 0 {

hslatman · 2025-07-31T21:26:49Z

authority/provisioner/acme.go

+	if slices.Contains(p.AttestationFormats, "android-key") && !p.androidCRLTimeout.IsZero() && time.Now().After(p.androidCRLTimeout) {
+		p.initializeAndroidCRL()
+	}
+	return len(p.RootCRLs) > 0 && slices.Contains(p.RootCRLs, serialNumber)


It's sufficient to just check using Contains, as it's backed by range:

Suggested change

return len(p.RootCRLs) > 0 && slices.Contains(p.RootCRLs, serialNumber)

return slices.Contains(p.RootCRLs, serialNumber)

authority/provisioner/acme.go

hslatman · 2025-07-31T21:36:06Z

authority/provisioner/acme.go

+	res, err := http.Get(ANDROID_ATTESTATION_STATUS_URL)
+	if err != nil {
+		return fmt.Errorf("client: error making Android CRL request: %s\n", err)
+	}


Can you change this into using the http.Client that's available on the Controller?

I've try but got an invalid dereference p.ctl.GetHttpClient().Get

hslatman · 2025-07-31T21:36:27Z

authority/provisioner/acme.go

+			Reason string `json:"reason"`
+		} `json:"entries"`
+	}
+	res, err := http.Get(ANDROID_ATTESTATION_STATUS_URL)


Suggested change

res, err := http.Get(ANDROID_ATTESTATION_STATUS_URL)

res, err := http.Get(androidAttestationStatusURL)

hslatman · 2025-07-31T21:36:41Z

authority/provisioner/acme.go

 	}

+	if slices.Contains(p.AttestationFormats, "android-key") && len(p.RootCRLs) == 0 {
+		p.initializeAndroidCRL()


Suggested change

p.initializeAndroidCRL()

p.fetchAndroidCRL()

hslatman · 2025-08-01T12:10:44Z

acme/challenge.go

+			return nil, NewDetailedError(ErrorBadAttestationStatementType, "Root certificate not signed by Android")
+		}
+	default:
+		return nil, NewDetailedError(ErrorBadAttestationStatementType, "Invalid root certificate signature algorithm")


We could also opt to allow other public key types. This would make testing with a different signing chain more flexible. It would now require someone to always use an RSA root. Assuming a change is made that allowed the attestation root(s) to be overridden, the assumption that it always is an RSA key can be limiting. Your logic already verifies that the root certificate is part of the chain that the device sends, and that key can thus be compared against the one configured as the attestation root.

Co-authored-by: Herman Slatman <hslatman@users.noreply.github.com>

jbpin · 2025-08-26T14:52:09Z

Hi @hslatman,
I'm back from vacation, I will implement the suggestion and change a bit the code. It looks like there are some changes since this implementation on Google side : https://developer.android.com/privacy-and-security/security-key-attestation

We will be able to implement the attestationRoots instead of key and support ECDSA as well.

Co-authored-by: Herman Slatman <hslatman@users.noreply.github.com>

attestation

jbpin · 2025-08-27T13:35:27Z

authority/provisioner/acme.go

+	for k := range CRLResponse.Entries {
+		keys = append(keys, k)
+	}
+	p.RootCRLs = keys


As for now is on Provisioner and is configurable, I proposed RevokedCertificateSerials

jbpin · 2025-08-27T14:33:22Z

acme/challenge.go

+		// 2. hardwareEnforced
+		if ch.Value != string(data.Attestation.TeeEnforced.AttestationIdSerial) {


This line ensure that the hardware identifier match the permanent-identifier. I've updated the comment.
There are actually severals others checks that can be done, like verified boot, but seems interested to leave that to a webhook validation. What do you think ?

jbpin · 2025-08-27T14:35:12Z

acme/challenge.go

+// Android Root CA
+// https://developer.android.com/privacy-and-security/security-key-attestation#root_certificate
+const AndroidRootCAPubKey = `-----BEGIN PUBLIC KEY-----
+MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAr7bHgiuxpwHsK7Qui8xU


That's correct. I've update this part. Also note that Google issue new certificate. So now, there are 2 RSA and 1 ECDSA on the code. If customer want to validate older devices they can rely on attestationRoots field and provide them all.

jbpin · 2025-08-27T14:51:25Z

authority/provisioner/acme.go

+	res, err := http.Get(ANDROID_ATTESTATION_STATUS_URL)
+	if err != nil {
+		return fmt.Errorf("client: error making Android CRL request: %s\n", err)
+	}


I've try but got an invalid dereference p.ctl.GetHttpClient().Get

jbpin · 2025-09-11T11:53:47Z

acme/challenge.go

+	// if err != nil {
+	// 	return nil, WrapDetailedError(ErrorBadAttestationStatementType, err, "")
+	// }
+	attCert := leaf


actually this is not safe. Documentation alert say:
Caution: Don't assume that the key attestation certificate extension is in the leaf certificate of the chain. Only the first occurrence of the extension in the chain can be trusted. Any further instances of the extension have not been issued by the secure hardware and might have been issued by an attacker extending the chain while attempting to create fake attestations for untrusted keys.

github-actions bot added the needs triage Waiting for discussion / prioritization by team label Jun 30, 2025

hslatman self-assigned this Jul 1, 2025

hslatman added this to the v0.28.5 milestone Jul 28, 2025

hslatman reviewed Jul 31, 2025

View reviewed changes

hslatman reviewed Aug 1, 2025

View reviewed changes

Jean-Baptiste Pin and others added 3 commits August 26, 2025 16:07

merge master

a3452b7

Apply suggestions from code review

801e176

Co-authored-by: Herman Slatman <hslatman@users.noreply.github.com>

apply suggestion from merge request

6489983

jbpin and others added 6 commits August 26, 2025 17:02

Update authority/provisioner/acme.go

d45eb9d

Co-authored-by: Herman Slatman <hslatman@users.noreply.github.com>

apply suggestion to MR

035c62e

impl. suggestin from MR

f3f0916

switch compare to subtle

fa2ed56

implement certificat based validation for root certificate in android

e892f4f

attestation

apply suggestion and refactor from MR

04bbf23

jbpin commented Sep 11, 2025

View reviewed changes

Jean-Baptiste Pin added 2 commits September 11, 2025 15:40

revert findAndroidAttestationCert to follow guideline

8548092

Merge branch 'master' into android

6a766f4

		// APPLE is the format used to enable device-attest-01 on Apple devices.
		ANDROID ACMEAttestationFormat = "android-key"

-	// APPLE is the format used to enable device-attest-01 on Apple devices.
-	ANDROID ACMEAttestationFormat = "android-key"
+	// ANDROIDKEY is the format used to enable device-attest-01 for Android
+	// devices using Android Key Attestation.
+	ANDROIDKEY ACMEAttestationFormat = "android-key"

	case APPLE, STEP, TPM, ANDROID:
	case APPLE, STEP, TPM, ANDROIDKEY:

	if slices.Contains(p.AttestationFormats, "android-key") && len(p.RootCRLs) == 0 {
	if slices.Contains(p.AttestationFormats, ANDROIDKEY) && len(p.RootCRLs) == 0 {

	return len(p.RootCRLs) > 0 && slices.Contains(p.RootCRLs, serialNumber)
	return slices.Contains(p.RootCRLs, serialNumber)

	res, err := http.Get(ANDROID_ATTESTATION_STATUS_URL)
	res, err := http.Get(androidAttestationStatusURL)

		// 2. hardwareEnforced
		if ch.Value != string(data.Attestation.TeeEnforced.AttestationIdSerial) {

Add android-key attestation format support #2322

Are you sure you want to change the base?

Add android-key attestation format support #2322

Uh oh!

Conversation

jbpin commented Jun 30, 2025

Name of feature:

Pain or issue this feature alleviates:

Why is this important to the project (if not answered above):

Is there documentation on how to use this feature? If so, where?

In what environments or workflows is this feature supported?

In what environments or workflows is this feature explicitly NOT supported (if any)?

Supporting links/other PRs/issues:

Uh oh!

jbpin commented Jun 30, 2025

Uh oh!

hslatman left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hslatman Aug 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jbpin commented Aug 26, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

hslatman Aug 1, 2025 •

edited

Loading