Difference between revisions of "ACME API"

From Dogtag
Jump to: navigation, search
m (Overview)
m (Preauthentication)
 
(One intermediate revision by the same user not shown)
Line 23: Line 23:
 
| POST /acme/new-order
 
| POST /acme/new-order
 
| 201 -> order
 
| 201 -> order
|-
 
| Create authorization
 
| POST /acme/new-authz
 
| 201 -> authz
 
 
|-
 
|-
 
| Check authorization
 
| Check authorization
Line 51: Line 47:
 
| POST-as-GET /acme/cert/{certID}
 
| POST-as-GET /acme/cert/{certID}
 
| 200
 
| 200
 +
|}
 +
 +
== Pre-authorization ==
 +
 +
{| class="wikitable" width="800"
 +
! width="200" | Action
 +
! width="500" | Request
 +
! width="100" | Response
 +
|-
 +
| Create authorization
 +
| POST /acme/new-authz
 +
| 201 -> authz
 
|}
 
|}
  

Latest revision as of 01:07, 7 November 2019

Overview

Issuing a Certificate

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
Check authorization POST-as-GET /acme/authz/{authzID} 200
Respond to challenges POST /acme/chall/{challengeID} 200
Poll authorization for status POST-as-GET /acme/authz/{authzID} 200
Finalize order POST /acme/order/{orderID}/finalize 200
Poll order for status POST-as-GET /acme/order/{orderID} 200
Download certificate POST-as-GET /acme/cert/{certID} 200

Pre-authorization

Action Request Response
Create authorization POST /acme/new-authz 201 -> authz

Revoking a Certificate

Action Request Response
Get directory GET /acme/directory 200
Generate nonce HEAD /acme/new-nonce 200
Revoke certificate POST /acme/revoke-cert 200

Registering an Account

Action Request Response
Get directory GET /acme/directory 200
Generate nonce HEAD /acme/new-nonce 200
Creating account POST /acme/new-acct 200

Updating an Account

Action Request Response
Get directory GET /acme/directory 200
Generate nonce HEAD /acme/new-nonce 200
Verifying existing account POST /acme/new-acct 200
Updating account POST /acme/acct/{accountID} 200

Unregistering an Account

Action Request Response
Get directory GET /acme/directory 200
Generate nonce HEAD /acme/new-nonce 200
Verifying existing account POST /acme/new-acct 200
Deactivating account POST /acme/acct/{accountID} 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