Difference between revisions of "ACME API"

From Dogtag
Jump to: navigation, search
m (Identifier Authorization)
m (Overview)
(5 intermediate revisions by the same user not shown)
Line 7: Line 7:
 
|-
 
|-
 
| Get directory
 
| Get directory
| GET directory
+
| GET /acme/directory
 
| 200
 
| 200
 
|-
 
|-
| Get nonce
+
| Generate nonce
| HEAD newNonce
+
| HEAD /acme/new-nonce
 
| 200
 
| 200
 
|-
 
|-
 
| Create account
 
| Create account
| POST newAccount
+
| POST /acme/new-account
 
| 201 -> account
 
| 201 -> account
 
|-
 
|-
| Submit order
+
| Create order
| POST newOrder
+
| POST /acme/new-order
 
| 201 -> order
 
| 201 -> order
 +
|-
 +
| Create authorization
 +
| POST /acme/new-authz
 +
| 201 -> authz
 
|-
 
|-
 
| Fetch challenges
 
| Fetch challenges
Line 43: Line 47:
 
|-
 
|-
 
| Download certificate
 
| Download certificate
| POST-as-GET order's certificate url
+
| POST-as-GET /acme/cert/<certificate ID>
 
| 200
 
| 200
 
|}
 
|}

Revision as of 19:12, 15 August 2019

Overview

Action Request Response
Get directory GET /acme/directory 200
Generate nonce HEAD /acme/new-nonce 200
Create account POST /acme/new-account 201 -> account
Create order POST /acme/new-order 201 -> order
Create authorization POST /acme/new-authz 201 -> authz
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 /acme/cert/<certificate ID> 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

The identifier authorization process establishes the authorization of an account to manage certificates for a given identifier.

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