Account creation & Authorization

ACME account

Account on the ACME server is represented by an ACME Account URL, which must be included in every JWS header ("kid" parameter). To acquire the ACME Account URL, ACME client must go through the authorization process.

ACME Account creation and authorization

To perform the authorization, ACME client must send a EC P-256 public key, associated with the ACME account. If account with such key does not exist on the server, it will be created.

Public keys must be sent to the ACME server in JWK format (RFC 7517):

{
  "kty" : "EC",
  "crv" : "P-256",
  "x" : "<EC pubkey X point>",
  "y" : "<EC pubkey Y point>",
  "kid" : "<Human-readable Key Identifier string>"
}

To authorize on the ACME server, send a POST request to the newAccount URL with JWK in protected header (instead of "kid"), and an empty payload:

POST https://stica.peeringhub.io/acme/new-account
Content-Type: application/jose+json
Content-Length: 512
{
  "protected" : BASE64URL(
    {
      "alg" : "ES256",
      "nonce" : "ABECF2EDB773493ABC9C6E000420DBEC",
      "url" : "https://stica.peeringhub.io/acme/new-account",
      "jwk": {
        "kty" : "EC",
        "crv" : "P-256",
        "x" : "4nHODmypbnfKdJd-IxbMsLwOtJqC0fPysqKFu8cssEY",
        "y" : "u5McBHfPXkFvlHtFM38GEmMiv2owHxPawpWfH17Y0MY",
        "kid" : "My key"
      }
    }
  ),
  "payload" : "",
  "signature" : "<base64url-encoded signature>"
}

If account with such key already exists, ACME server shall return an empty 200 OK reply with the ACME Account URL in the Location header:

HTTP/1.1 200 OK
Replay-Nonce: 86CB00B0430D4C71B2D156B2AE785353
Location: https://stica.peeringhub.io/acme/acct/6A1AD155B73D45448E7B832888C3EF54
Content-Length: 0

Otherwise, a new account should be created, and ACME server shall send back a 201 Created reply with the ACME Account object.

HTTP/1.1 201 Created
Replay-Nonce: 7BDB37ADEB3C41E8A95BADEB1A3CE38C
Location: https://stica.peeringhub.io/acme/acct/6A1AD155B73D45448E7B832888C3EF54
Content-Type: application/json; charset=utf-8
Content-Length: 106
{
  "status" : "valid",
  "orders" : "https://stica.peeringhub.io/acme/orders/6A1AD155B73D45448E7B832888C3EF54"
}

It's also possible to check, whether the ACME Account with such key exists on the server, without creating one. For this, ACME client must put a "onlyReturnExisting" boolean parameter into the JWS payload:

POST https://stica.peeringhub.io/acme/new-account
Content-Type: application/jose+json
Content-Length: 512
{
  "protected" : BASE64URL(
    {
      "alg" : "ES256",
      "nonce" : "ABECF2EDB773493ABC9C6E000420DBEC",
      "url" : "https://stica.peeringhub.io/acme/new-account",
      "jwk": {
        "kty" : "EC",
        "crv" : "P-256",
        "x" : "4nHODmypbnfKdJd-IxbMsLwOtJqC0fPysqKFu8cssEY",
        "y" : "u5McBHfPXkFvlHtFM38GEmMiv2owHxPawpWfH17Y0MY",
        "kid" : "My key"
      }
    }
  ),
  "payload" : BASE64URL(
    {
      "onlyReturnExisting" : true
    }
  ),
  "signature" : "<base64url-encoded signature>"
}

If ACME Account with such key cannot be found, ACME server should reply with a 400 Bad Request and "accountDoesNotExist" error:

HTTP/1.1 400 Bad Request
Replay-Nonce: 29FC5BFA9F1748FEBC77D8CA7F3DE1FF
Content-Type: application/json; charset=utf-8
Content-Length: 57
{
  "type" : "urn:ietf:params:acme:error:accountDoesNotExist"
}