AtHeartEngineer/specs
1
0
Fork 0
mirror of https://github.com/vacp2p/specs.git synced 2026-01-06 22:13:52 -05:00
Code Issues Packages Projects Releases Wiki Activity

add sane retry intervals and timeouts

Browse Source
This commit is contained in:
Gabriel Cruz
2025-07-22 15:45:27 -03:00
parent cd9d0b677a
commit ab91b1afa7
1 changed files with 9 additions and 9 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
tls/autotls-client.md
View File

@@ -47,12 +47,12 @@ The following is the general flow of a successful certificate request and subseq
## Paramenters
| Parameter | Description | Reasonable Default |
|--------------------------|------------------------------------------------------------------|--------------|
| `max_dns_retries` | The maximum number of DNS queries that the node SHOULD make before giving up | ??? |
| `max_dns_timeout` | The maximum number of seconds a node SHOULD wait for DNS records to be set | ??? |
| `max_acme_poll_retries` | The maximum number of GET requests that the node SHOULD issue to ACME server before giving up | ??? |
| `max_acme_timeout` | The maximum number of seconds a node SHOULD wait for an ACME resource status to change | ??? |
| Parameter | Description | Reasonable Default |
|--------------------------|---------------------------------------------------------------------------|---------------------|
| `dns_poll_interval` | Time the node SHOULD wait between of DNS queries | 1 second |
| `dns_timeout` | The maximum time a node SHOULD wait for DNS records to be set | 3 minutes |
| `acme_poll_interval` | Time the node SHOULD wait between ACME GET requests | 1 second |
| `acme_timeout` | The maximum time a node SHOULD wait for an ACME resource status to change | 3 minutes |
## Requesting challenge from ACME server
1. The node starts a libp2p peer with public IPv4 and support for the [`identify`](https://github.com/libp2p/specs/blob/master/identify/README.md) protocol.
@@ -159,14 +159,14 @@ The following is the general flow of a successful certificate request and subseq
**Note:** Here, `dashed-public-ip-address` is the public IPv4 address of the node in which the node received the confirmation dial from the broker. For example, if the node has two public IPv4 addresses `1.1.1.1` and `8.8.8.8`, and the broker dialed it through `1.1.1.1`, then the node SHOULD query the `A 1-1-1-1.{b36peerid}.libp2p.direct`.
**Note:** The node SHOULD NOT send more than `max_dns_retries` DNS requests. After `max_dns_timeout`, the communication is considered failed. What to do after `max_dns_timeout` has passed is left as an implementation decision.
**Note:** The node SHOULD NOT poll DNS for longer than `dns_timeout`. After `dns_timeout`, the communication is considered failed. What to do after `dns_timeout` has passed is left as an implementation decision.
2. Node notifies the ACME server about challenge completion so that the ACME server can lookup the DNS resource records that the AutoTLS broker has set. The notification is done in the form of a POST request to `chalUrl` with an empty HTTP body (`{}`).
1. Node sends an empty signed JSON payload (`{}`) to the ACME server using the `kid` obtained from the initial ACME registration and gets the response from the server (`completedResponse`).
2. Node extracts `url` field from `completedResponse`'s JSON body. The extracted URL is named `checkUrl` in this document.
3. The node polls the ACME server by sending a GET HTTP request to `checkUrl` with an empty body, and sign using the `kid` of the registered account. The node MUST poll the ACME server until it receives a response with `status: valid` or `status: invalid` field, meaning that the challenge checking was successful or not, respectively.
**Note:** The node SHOULD NOT send more than `max_acme_poll_retries` poll requests to the ACME server. After `max_acme_timeout`, the communication has failed. What to do after `max_acme_timeout` has passed is left as an implementation decision.
**Note:** The node SHOULD NOT send more than one request every `acme_interval` to the ACME server. The node SHOULD use exponential backoff to increase time between retries. After `acme_timeout`, the communication has failed. What to do after `acme_timeout` has passed is left as an implementation decision.
@@ -177,7 +177,7 @@ The following is the general flow of a successful certificate request and subseq
3. Send a `kid` signed POST request to `finalizeUrl` with JSON HTTP body of `{"csr": b64CSR}`.
2. Node MUST poll ACME server by sending GET requests to `orderUrl` until the ACME server's response contains a `status` field with a value different than `processing`.
**Note:** The node SHOULD NOT send more than `max_acme_poll_retries` poll requests to the ACME server. After `max_acme_timeout`, the communication has failed. What to do after `max_acme_timeout` has passed is left as an implementation decision.
**Note:** The node SHOULD NOT send more than one request every `acme_interval` to the ACME server. The node SHOULD use exponential backoff to increase time between retries. After `acme_timeout`, the communication has failed. What to do after `acme_timeout` has passed is left as an implementation decision.
3. Node downloads finalized certificate by sending a GET request to `certDownloadUrl`. `certDownloadUrl` is found in the `certificate` field of the JSON HTTP body of a response to a GET request to `orderUrl`.