In this multi-part article, you'll learn how to use the Let's Encrypt ACME version 2 API with ** Python ** for ** SSL certificates **.
Let's look at an example of creating a new account. This pseudo-code example shows an HTTP POST, HTTP header, and HTTP body. "based64_encode" is not really part of the HTTP body, but it does indicate that the code needs to base64 encode the data before sending it to the ACME server.
POST /acme/new-account HTTP/1.1
Host: acme-staging-v02.api.letsencrypt.org
Content-Type: application/jose+json
{
"protected": base64_encode({
"alg": "ES256",
"jwk": {...},
"nonce": "6S8IqOGY7eL2lsGoTZYifg",
"url": "https://acme-staging-v02.api.letsencrypt.org/acme/new-acct"
}),
"payload": base64_encode({
"termsOfServiceAgreed": true,
"contact": [
"mailto:[email protected]",
"mailto:[email protected]"
]
}),
"signature": "RZPOnYoPs1PhjszF...-nh6X1qtOFPB519I"
}
ACME requests are encapsulated in JSON Web Signature (JWS) objects.
The JWS object consists of three parts. JWS Protected Header, API command parameters (payload), signature. Each part is explained below. Each part is individually base64 encoded and combined into a single JSON object.
{
"protected": base64_encode(jws_protected_header),
"payload": base64_encode(payload),
"signature": based64_encode(signature)
}
Inside the JWS object is the JWS Protected Header. The JWS Protected Header contains the following fields:
| field | Description |
|---|---|
| alg | algorithm. A MAC-based algorithm used to sign requests. The supported algorithms are ES256 and RS256. Reference See RFC 7518. In these examples, RS256(SH-RSASSA with 256-PKCS1-v1_5)Use the. I will explain briefly. RS256 means signing with the RSA private key and validating with the corresponding RSA public key. |
| jwk | JSON Web Key. jwk is used for all requests that are not signed using an existing account. For example:"New account".. jwk is a JSON object described later in this article. |
| kid | Key ID. kid will be used for all requests signed using an existing account. For example, "Get account information". |
| nonce | Nonce. A unique value used to prevent replay attacks. This value is returned by the NewNonce API and the response header "Replay" after each successful ACME API call.-It will be returned with "Nonce". |
| url | URL. This header parameter encodes the URL that the client is pointing to the request for. Please refer to each ACME API for the required values. |
The "jwk" and "kid" fields are mutually exclusive. The server must reject the request containing both.
The ACME API uses one or the other and specifies it.
JWK parameters vary depending on the type of cryptographic signature. The examples in this series use RSA key pairs.
| field | Description |
|---|---|
| e | Public index. This is the public index of RSA key pairs. |
| kty | Key Type. The method used to sign the JWS. If you use an RSA key pair, it will be RSA. See RFC 7638 for details. |
| n | Modulus. Modulus from an RSA key pair. For a 2048-bit key, the value of field "n" will be 256 octets long when decoded. |
{
"e": base64_encode(public_exponent),
"kty": "RSA",
"n": base64_encode(modulus),
}
The payload contains API call parameters. These are different for each API. The contents of the payload json object are base64 encoded. The following example shows the payload of the New Account API. There are two parameters. "termsOfServiceAgreed" and "contact". The payload is part of the JSON Web Signature (JWS) contained in the HTTP body.
"payload": base64_encode({
"termsOfServiceAgreed": true,
"contact": [
"mailto:[email protected]",
"mailto:[email protected]"
]
})
The signature is a SHA-256 message digest with an RSA private key. The ACME server uses the corresponding public key to verify the signature.
def sign(data, keyfile):
""" Create the ACME API Signature """
# Load the RSA Private Key from the file (RSA PKCS #1)
pkey = load_private_key(keyfile)
# Create the signature
sig = crypto.sign(pkey, data, "sha256")
return sig
So far, we have shown how the ACME API system works.
In the final part of the next, we'll look at how to perform DNS validation and how to create and modify DNS server resource records to support ACME DNS validation.
Recommended Posts