Difference between revisions of "ACME API"

From Dogtag
Jump to: navigation, search
m (Overview)
m (Responding to a Challenge)
Line 266: Line 266:
  
 
= Responding to a Challenge =
 
= Responding to a Challenge =
 +
 +
To prove control of the identifier and receive authorization, the
 +
client needs to provision the required challenge response based on
 +
the challenge type and indicate to the server that it is ready for
 +
the challenge validation to be attempted.
  
 
Request:
 
Request:

Revision as of 22:35, 13 August 2019

Overview

Action Request Response
Get directory GET directory 200
Get nonce HEAD newNonce 200
Create account POST newAccount 201 -> account
Submit order POST newOrder 201 -> order
Fetch challenges POST-as-GET order's authorization urls 200
Respond to challenges POST authorization challenge urls 200
Poll authorization for status POST-as-GET authorization 200
Finalize order POST order's finalize url 200
Poll order for status POST-as-GET order 200
Download certificate POST-as-GET order's certificate url 200

Getting the Directory

Request:

GET /acme/directory HTTP/1.1
Host: example.com

Response:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "newNonce": "https://example.com/acme/new-nonce",
    "newAccount": "https://example.com/acme/new-account",
    "newOrder": "https://example.com/acme/new-order",
    "newAuthz": "https://example.com/acme/new-authz",
    "revokeCert": "https://example.com/acme/revoke-cert",
    "keyChange": "https://example.com/acme/key-change",
    "meta": {
        "termsOfService": "https://example.com/acme/terms/2017-5-30",
        "website": "https://www.example.com/",
        "caaIdentities": ["example.com"],
        "externalAccountRequired": false
    }
}

See also RFC 8555 - Section 7.1.1.

Creating a Nonce

Request:

HEAD /acme/new-nonce HTTP/1.1
Host: example.com

Response:

HTTP/1.1 200 OK
Replay-Nonce: oFvnlFP1wIhRlYS2jTaXbA
Cache-Control: no-store
Link: <https://example.com/acme/directory>;rel="index"

See also RFC 8555 - Section 7.2.

Creating an Account

Request:

POST /acme/new-account HTTP/1.1
Host: example.com
Content-Type: application/jose+json

{
    "protected": base64url({
        "alg": "ES256",
        "jwk": {...},
        "nonce": "6S8IqOGY7eL2lsGoTZYifg",
        "url": "https://example.com/acme/new-account"
    }),
    "payload": base64url({
        "termsOfServiceAgreed": true,
        "contact": [
            "mailto:cert-admin@example.org",
            "mailto:admin@example.org"
        ]
    }),
    "signature": "RZPOnYoPs1PhjszF...-nh6X1qtOFPB519I"
}

Response:

HTTP/1.1 201 Created
Content-Type: application/json
Replay-Nonce: D8s4D2mLs8Vn-goWuPQeKA
Link: <https://example.com/acme/directory>;rel="index"
Location: https://example.com/acme/acct/evOfKhNU60wg

{
    "status": "valid",

    "contact": [
        "mailto:cert-admin@example.org",
        "mailto:admin@example.org"
    ],

    "orders": "https://example.com/acme/acct/evOfKhNU60wg/orders"
}

See also:

Creating an Order

Request:

POST /acme/new-order HTTP/1.1
Host: example.com
Content-Type: application/jose+json

{
    "protected": base64url({
        "alg": "ES256",
        "kid": "https://example.com/acme/acct/evOfKhNU60wg",
        "nonce": "5XJ1L3lEkMG7tR6pA00clA",
        "url": "https://example.com/acme/new-order"
    }),
    "payload": base64url({
        "identifiers": [
            { "type": "dns", "value": "www.example.org" },
            { "type": "dns", "value": "example.org" }
        ],
        "notBefore": "2016-01-01T00:04:00+04:00",
        "notAfter": "2016-01-08T00:04:00+04:00"
    }),
    "signature": "H6ZXtGjTZyUnPeKn...wEA4TklBdh3e454g"
}

Response:

HTTP/1.1 201 Created
Replay-Nonce: MYAuvOpaoIiywTezizk5vw
Link: <https://example.com/acme/directory>;rel="index"
Location: https://example.com/acme/order/TOlocE8rfgo

{
    "status": "pending",
    "expires": "2016-01-05T14:09:07.99Z",

    "notBefore": "2016-01-01T00:00:00Z",
    "notAfter": "2016-01-08T00:00:00Z",

    "identifiers": [
        { "type": "dns", "value": "www.example.org" },
        { "type": "dns", "value": "example.org" }
    ],

    "authorizations": [
        "https://example.com/acme/authz/PAniVnsZcis",
        "https://example.com/acme/authz/r4HqLzrSrpI"
    ],

    "finalize": "https://example.com/acme/order/TOlocE8rfgo/finalize"
}

See also RFC 8555 - Section 7.4.

Identifier Authorization

Request:

POST /acme/authz/PAniVnsZcis HTTP/1.1
Host: example.com
Content-Type: application/jose+json

{
    "protected": base64url({
        "alg": "ES256",
        "kid": "https://example.com/acme/acct/evOfKhNU60wg",
        "nonce": "uQpSjlRb4vQVCjVYAyyUWg",
        "url": "https://example.com/acme/authz/PAniVnsZcis"
    }),
    "payload": "",
    "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps"
}

Response:

HTTP/1.1 200 OK
Content-Type: application/json
Link: <https://example.com/acme/directory>;rel="index"

{
    "status": "pending",
    "expires": "2016-01-02T14:09:30Z",

    "identifier": {
        "type": "dns",
        "value": "www.example.org"
    },

    "challenges": [
        {
            "type": "http-01",
            "url": "https://example.com/acme/chall/prV_B7yEyA4",
            "token": "DGyRejmCefe7v4NfDGDKfA"
        },
        {
            "type": "dns-01",
            "url": "https://example.com/acme/chall/Rg5dV14Gh1Q",
            "token": "DGyRejmCefe7v4NfDGDKfA"
        }
    ]
}

See also RFC 8555 - Section 7.5.

Responding to a Challenge

To prove control of the identifier and receive authorization, the client needs to provision the required challenge response based on the challenge type and indicate to the server that it is ready for the challenge validation to be attempted.

Request:

POST /acme/chall/prV_B7yEyA4 HTTP/1.1
Host: example.com
Content-Type: application/jose+json

{
    "protected": base64url({
        "alg": "ES256",
        "kid": "https://example.com/acme/acct/evOfKhNU60wg",
        "nonce": "Q_s3MWoqT05TrdkM2MTDcw",
        "url": "https://example.com/acme/chall/prV_B7yEyA4"
    }),
    "payload": base64url({}),
    "signature": "9cbg5JO1Gf5YLjjz...SpkUfcdPai9uVYYQ"
}

See also RFC 8555 - Section 7.5.1.

Finalizing an Order

Request:

POST /acme/order/TOlocE8rfgo/finalize HTTP/1.1
Host: example.com
Content-Type: application/jose+json

{
    "protected": base64url({
        "alg": "ES256",
        "kid": "https://example.com/acme/acct/evOfKhNU60wg",
        "nonce": "MSF2j2nawWHPxxkE3ZJtKQ",
        "url": "https://example.com/acme/order/TOlocE8rfgo/finalize"
    }),
    "payload": base64url({
        "csr": "MIIBPTCBxAIBADBFMQ...FS6aKdZeGsysoCo4H9P",
    }),
    "signature": "uOrUfIIk5RyQ...nw62Ay1cl6AB"
}

Response:

HTTP/1.1 200 OK
Replay-Nonce: CGf81JWBsq8QyIgPCi9Q9X
Link: <https://example.com/acme/directory>;rel="index"
Location: https://example.com/acme/order/TOlocE8rfgo

{
    "status": "valid",
    "expires": "2016-01-20T14:09:07.99Z",

    "notBefore": "2016-01-01T00:00:00Z",
    "notAfter": "2016-01-08T00:00:00Z",

    "identifiers": [
        { "type": "dns", "value": "www.example.org" },
        { "type": "dns", "value": "example.org" }
    ],

    "authorizations": [
        "https://example.com/acme/authz/PAniVnsZcis",
        "https://example.com/acme/authz/r4HqLzrSrpI"
    ],

    "finalize": "https://example.com/acme/order/TOlocE8rfgo/finalize",

    "certificate": "https://example.com/acme/cert/mAt3xBGaobw"
}

See also RFC 8555 - Section 7.4.

Downloading a Certificate

Request:

POST /acme/cert/mAt3xBGaobw HTTP/1.1
Host: example.com
Content-Type: application/jose+json
Accept: application/pem-certificate-chain

{
    "protected": base64url({
        "alg": "ES256",
        "kid": "https://example.com/acme/acct/evOfKhNU60wg",
        "nonce": "uQpSjlRb4vQVCjVYAyyUWg",
        "url": "https://example.com/acme/cert/mAt3xBGaobw"
    }),
    "payload": "",
    "signature": "nuSDISbWG8mMgE7H...QyVUL68yzf3Zawps"
}

Response:

HTTP/1.1 200 OK
Content-Type: application/pem-certificate-chain
Link: <https://example.com/acme/directory>;rel="index"

-----BEGIN CERTIFICATE-----
[End-entity certificate contents]
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
[Issuer certificate contents]
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
[Other certificate contents]
-----END CERTIFICATE-----

See also RFC 8555 - Section 7.4.2.

See Also