Skip to main content
Skip table of contents

ACME device-attest-01 challenge PoC

The ACME (Automatic Certificate Management Environment) protocol is mainly used the enroll Transport Layer Security (TLS) server certificates and offers a built-in proof-of-possession for the identifiers such as host names or IP.

With the ACME device-attest-01 challenge properties of a device requesting a certificate, such as the identity of the device or whether the certificate key is protected by a secure cryptoprocessor can be validated.

With this new ACME challenge, the device sends it's attestation certificate signed by the manufacturer to the CA server. EJBCA than validates the proof-of-possession of the permanent identifier (OID 1.3.6.1.5.5.7.8.3) or hardware module name (OID 1.3.6.1.5.5.7.8.4) or other attributes included in this attestation certificate.

Several attestation types (also called attestation statement types) are available. Two of those are partially implemented with the ACME device-attest-01 challenge PoC.

Open todo

  • ECA-12520 'Add a validator for REST requests.'. The ACME device-attest-01 challenge is supposed to enroll certificates for pre-registered devices only. The RFC draft recommends ACME EAB (External Account Binding) using a pre-shared key as pre-registration mechanism. To overcome the pre-shared secret, a REST API Validator based on the EJBCA validator framework requests the device status at the MDM (Mobile device Managmenet) server manageing the device.

  • Detail specification of data received and sent. This essentially concerns the definition of properties and data in the CSR (Certificate Signing Request) and in the enrolled certificate.

  • Code re-factoring, unit, system tests and a code cleanup.

  • The current main branch including the Jakarta EE 10 upgrade needs to merged into the feature branch.

Test Certificate Enrollment for Apple Anonymous Attestation Statement Type.

Configure EJBCA

Configure EJBCA for ACME as described in TODO.

Shortly summarized here:

  • Ensure the ACME protocol is enabled in the protocol configuration.

  • Create an X.509 root-CA and sub-CA to issue device certificates.

  • Create a certificate profile.

  • Create a end entity profile.

  • Create your ACME configuration alias.

The device-attest-01 challenge is enabled by default. To enroll a device certificate we need to import the root-CA certificate of the device's attestation certificate as an external CA into EJBCA.

The issuer DN of the manufacturer's attestation root-CA needs to be copied into the field 'Device attestation ACA root' of the ACME alias.

The certificate profile's KU (Key Usage) should be changed from 'Key Enciphernment' to 'Key Agreement'.

The certificate profile's EKU (Extended Key Usage) needs to be set to 'Client Authentication'.

Test with mimecast and Jamf Cloud as MDM solution

TODO

The configuration of the Jamf Cloud MDM solution is out of scope of Keyfactor.

Below we show some configuration properties for the PoC of important objects in the Jamf web GUI. For further information, please refer to the Jamf Cloud documentation.

Configure Jamf MDM ACME profile

TODO

Configure Jamf MDM API role and user

The API role and user can be created or updated in the Jamf Web GUI - Settings - API roles and client.

jamf-api-roles-and-clients.png

The API role needs the permission ‘Read computer’ to request data about registered computer devices (Apple Mac Book Pro)

jamf-api-role.png

The role is assigned, the ‘Access token lifetime’ is entered and a client secret is generated in the configuration for the API client.

jamf-api-client.png

Configure Device

See Mimecast.

Get API access token

With our API client the access token can be requested at the Jamf MDM API.

CODE
curl \
--location \
--request POST 'https://mimecastkeywanjaffxy.jamfcloud.com/api/oauth/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=1cbda354-3a75-4bb2-9d9e-7243d53c9c0b' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_secret=0eQsfffzlIxISZcWtbKZueJYEt0Jf1-XAgmkSQ69vn0Bm8aevcCLMfleW5P06Ed3'

Your access token is included in the response.

CODE
{
"access_token":"eyJhbGciOiJIUzI1 ... ojNjjcPw7EjQ7K0",
"scope":"api-role:1",
"token_type":"Bearer",
"expires_in":94607999
}

Verify the UDID is pre-registered

Send an HTTP GET request to verify that the device had been pre-registered.

CODE
curl \
--request GET \
--url https://mimecastkeywanjaffxy.jamfcloud.com/JSSResource/computers/udid/FA8BD57C-432D-5D5C-8A64-ECAAEB119CA5 \
--header "accept: application/json" \
--header "Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiIxY2JkYTM1NC0zYTc1LTRiYjItOWQ5ZS03MjQzZDUzYzljMGIiLCJhdWQiOiIxY2JkYTM1NC0zYTc1LTRiYjItOWQ5ZS03MjQzZDUzYzljMGIiLCJuYmYiOjE3Mjc4NjE3OTMsInRva2VuLXV1aWQiOiIzMzc5YzYzYS03OTNmLTRjZjAtODYxMy03NDM2OTRmMTdhM2QiLCJzdWJqZWN0LXR5cGUiOiJSRUdJU1RFUkVEX0NMSUVOVF9JRCIsImF1dGhlbnRpY2F0aW9uLXR5cGUiOiJDTElFTlRfQ1JFREVOVElBTFMiLCJzY29wZSI6WyJhcGktcm9sZToxIl0sImlzcyI6Imh0dHBzOi8vbWltZWNhc3RrZXl3YW5qYWZmeHkuamFtZmNsb3VkLmNvbSIsImV4cCI6MTgyMjQ2OTc5MywiaWF0IjoxNzI3ODYxNzkzLCJqdGkiOiI1YjY5Nzk0OC04NjhiLTRiNjItYWQ2MS05YWRkZmY0YjdjNDcifQ.VxLl-PqoIF4KbUVmlPXauBXrH0O1ojNjjcPw7EjQ7K0"

Test with Primekey acme-test-client

The certificate enrollment with the ACME device-attest-01 challenge can be tested with the acme-test-client (see ).

To display the help the acme-test-client can be run without parameters.

java -jar acme-test-client-0.4.0-jar-with-dependencies.jar

It can be helpful to store the base command with an alias. Please replace the parameters with your values.

CODE
alias acme-test-client='sudo java \
-Dorg.slf4j.simpleLogger.defaultLogLevel=debug \
-Dorg.slf4j.simpleLogger.log.org=debug \
-Dorg.slf4j.simpleLogger.log.com=debug \
-jar acme-test-client-0.4.0-jar-with-dependencies.jar \
--challenge-type device-attest-01 \
--aik-certificate ../test/device-attest-01/mac-book-pro-attestation.pem \
--aca-chain ../test/device-attest-01/Apple_Enterprise_Attestation_Sub_CA.pem \
-a https://localhost:8442/ejbca/acme/directory \
--truststore $JBOSS_HOME/standalone/configuration/keystore/truststore.p12 \
--truststore-pass changeit '

With the alias we can enroll a certificate using the device-attest-01 challenge.

CODE
acme-test-client \
-r ../test/device-attest-01/mimecast-csr-1-empty.pem \
-i permanentIdentifier:FA8BD57C-432D-5D5C-8A64-ECAAEB119CA5

Specification

ACME newOrder resource

A the payload of a valid newOrder request must include orders for one or two identifier(s). Allowed are one identifier of type 'permanent-identifier', one identifier of type 'hardware-module', or both. The 'hardware-module' identifier is not considered when using the Apple Anonymous Attestation Statement format (fmt=apple).

Other identifiers like DNS or IP identifiers must not be included in the newOrder request.

Sample payload of a newOrder request for the Apple Anonymous Attestation Statement format with Jamf Cloud. The value is the UDID by Jamf Cloud, which is used to validate the pre-registration of the device with the Jamf Cloud API. It is not the UDID by the device manufacturer in the attestation certificate received with the challenge resource request, which is supposed to be issued with the certificate later.

CODE
{
    "identifiers":[
        { "type":"permanent-identifier", "value":"FA8BD57C-432D-5D5C-8A64-ECAAEB119CA5" }
    ]
}

ACME challenge resource

With the request to the challenge resource, the client signals the CA server, that it has prepared the key authorization for challenge response. For http-01 or tls-alpn-01 challenges the key authorization is made available on a web server or for the dns-01 challenge on a DNS server. The request payload is empty.

For the device-attest-01 challenge, the request payload contains the base64 URL encoded attestation object as described in draft-acme-device-attest-01 ch. 5.

CODE
"payload": base64url({
    "attObj": base64url(/* WebAuthn attestation object */),
})

PoC with Mimecast

Attestation object and attestation statement format

TODO

Attestation certificate and CA chain

X.509 Device attestion certificate

  • The certificate contains the X.509 extension with OID 1.2.840.113635.100.8.9.1 holding the device serial number. This is the serial number by the manufacturer written into the certificate's CN later.

  • The certificate contains the X.509 extension with OID 1.2.840.113635.100.8.9.2 holding the device UDID (Unique Device ID) by the manufacturer

  • TODO CN

Logged during the PoC with Mimecast:

CODE
-----BEGIN CERTIFICATE-----
MIIDAzCCAomgAwIBAgIGAZIFLBJXMAoGCCqGSM49BAMDMFIxLjAsBgNVBAMMJUFw
cGxlIEVudGVycHJpc2UgQXR0ZXN0YXRpb24gU3ViIENBIDExEzARBgNVBAoMCkFw
cGxlIEluYy4xCzAJBgNVBAYTAlVTMB4XDTI0MDkxNzEyNDcwN1oXDTI1MDkxODEy
NDcwN1owgZExSTBHBgNVBAMMQDgyYWUzZWE3MzNhNjEyZTlhOWUzOGFmNTU3MWVj
Mjg5ZTA0YTYyMGVlZGQyMDIyOWVhOTk5ZmE3ZGZlZTdmOWMxGjAYBgNVBAsMEUFB
QSBDZXJ0aWZpY2F0aW9uMRMwEQYDVQQKDApBcHBsZSBJbmMuMRMwEQYDVQQIDApD
YWxpZm9ybmlhMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEG71xQ9QQyvo3V0yzMdKo
KQUFMT7KRJdS+eoKHgICTyj5CvtoLRNoSPnb5iiMkUE6dO3nUphy4SNU0m6U4P8o
r4WMjrpwUOrG3j8mm2FSjzLuTz+X4/MuaCI85fdq5OwCo4HtMIHqMAwGA1UdEwEB
/wQCMAAwDgYDVR0PAQH/BAQDAgTwMBQGCiqGSIb3Y2QICgIEBjE0LjYuMTARBgoq
hkiG92NkCA0BBAMCAQAwGwYKKoZIhvdjZAgNAgQNRnVsbCBTZWN1cml0eTARBgoq
hkiG92NkCA0DBAMCAQEwGAYKKoZIhvdjZAgJAQQKSExRUVkxMkc1VjAnBgoqhkiG
92NkCAkCBBkwMDAwNjAzMC0wMDBBNzEzODExMjgwMDFDMC4GCiqGSIb3Y2QICwEE
IA9YPVl9PC9AY5O9bYhF4FTcYfNTg1vEl3ci+45tkJ3vMAoGCCqGSM49BAMDA2gA
MGUCMAs3sdEqdNlyftdQa2MGwjCkSQzdaqiphY8Qz6mJR0UXFb+sTDiD23QnfpHC
VEXfygIxAMOUi7q4HtMoDYTpDSMXwxHig5ZO4rssH+CJzmB+HzHIGchULtxwPirt
/JYFcB24Gg==
-----END CERTIFICATE-----

X.509 root CA certificate

Downloaded from Apple https://www.apple.com/certificateauthority/private/

CODE
CN=Apple Enterprise Attestation Root CA,O=Apple Inc.,C=US

-----BEGIN CERTIFICATE REQUEST-----
MIIBXTCB5QIBADAwMRIwEAYDVQQKEwlrZXlmYWN0b3IxDTALBgNVBAsTBHRlc3Qx
CzAJBgNVBAYTAlNFMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEJJcOhMjXvkvsP27y
itnjoKxo1l0iW6s3cMxL0xYHbR0BHt+OPBrWsPLnYTJfquFMoH2LJgbF6MnNvCmS
n+U/4ao62s/T0e+OPpZ44q5XaB4z64kSVp2jydafBvpFwFzpoDYwNAYJKoZIhvcN
AQkOMScwJTATBgNVHSUEDDAKBggrBgEFBQcDAjAOBgNVHQ8BAf8EBAMCB4AwCgYI
KoZIzj0EAwIDZwAwZAIwFdU3CbQgtZuVtuPMgV4wwue+ha40nfQ9gCU7df7R4flR
Hwdjc3A1kg5ZVSNRCXTLAjBrvRFLLrqQA3Jg3rIqGr+/PWNnWO0rZzYJ5OC7KEhz
mhFDeIVUdUtg9jJmZxrOSDw=
-----END CERTIFICATE REQUEST-----

CSR

  • The CSR must not contain a CN (Common Name) in the SDN (Subject Distinguish Name), but it is allowed to have attributes specified in the entity profile.

  • The CSR contains the uncritical EKU extension with TLS Web Client Authentication (Client Authentication)

  • The CSR contains the uncritical KU with 'Digital Signature'

  • The CSR does not contain any other X.509 extension.

  • TODO keys

Logged during the PoC with Mimecast:

CODE
-----BEGIN CERTIFICATE REQUEST-----
MIIBXzCB5QIBADAwMRIwEAYDVQQKEwlrZXlmYWN0b3IxDTALBgNVBAsTBHRlc3Qx
CzAJBgNVBAYTAlNFMHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEjSqEmkh5ABKBqliN
10jyjQLwWJu4p5cXh9gWZa8F1jOuP1oMJ+fHggkzRTybsKGA/3S9p6dCmq6M6lAR
EvqR6CiGcsO8jRbIjQALrYM9Q0BU9L+98zUwc+m4wCvUkxi7oDYwNAYJKoZIhvcN
AQkOMScwJTATBgNVHSUEDDAKBggrBgEFBQcDAjAOBgNVHQ8BAf8EBAMCB4AwCgYI
KoZIzj0EAwIDaQAwZgIxAM5OubmekTEL5xyEramqbFAvbfpTsIPWs/JQJITuCFDF
y0mpwjMeK9DXQxwYQjgVugIxAPt66W9y7c+STXTdpGUuj3T3faMuYcAO7oynD/2H
nPXvrZxIF8XA7ICacPXI0+sxLQ==
-----END CERTIFICATE REQUEST-----

REST API interface to verify pre-registered UDID

The API supports an HTTP GET request with TLS with the following URL.

CODE
https://mimecastkeywanjaffxy.jamfcloud.com/JSSResource/computers/udid/{UDID}

Two request headers ‘accept: application/json' and 'Authorization: Bearer {access-token}’ are required.

The response is either HTTP status code 200 (Ok) or 404 (Not found). In case of a pre-registered UDID and HTTP status code 200, the object returned in the response payload is not processed by EJBCA.

ACME certificate issued by EJBCA

The X.509 certificate enrolled by EJBCA.

  • The certificate contains the serial number by the device attestation certificate in the SDN CN attribute.

  • The certificate contains the non CN attributes given with the CSR but only the ones specified in the end entity profile.

  • The certificate contains no SAN extension.

  • The certificate contains the critical KU extension with Digital Signature, Non Repudiation, Key Encipherment, Key Agreement (TODO).

  • The certificate contains the non critical EKU extension with TLS Web Client Authentication

  • The certificate may contain other X.509 certificate extensions specified in the end entity or certificate profile.

References

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.