Challenge Handling Providers

On this page we document the Provider Model and the different Providers that are currently supported.

As part of the ACME specification, a client must prove that they have ownership and control of a DNS identifier (i.e. a domain name) for which they want to issue a PKI certificate. In order to satisfy this proof, an ACME client requests to authorize an identifier, and an ACME server will respond with one or more challenges that the client must complete. The server will indicate the different challenges that it supports, as well as the combinations of those challenges that must be successfully completed to satisfy the proof.

To handle these challenges, the LE-win client implements a provider model where each provider implementation addresses a specific challenge type, and oriented toward different scenarios which the client may need to support.

For example, for each supported challenge type, a manual provider exists which offers the most basic support of generating a challenge response. However, for any generated content, manual steps must be taken by a client user to apply the generated content to fully satisfy the challenge. In the case of the manual DNS provider, the user will need to manage the DNS resource records and configure them with the generated lookup value. In the case of the manual HTTP provider, the user will need to configure a Web server with the necessary directory paths, and copy the necessary file content to that server.

DNS Providers

The DNS providers support handling of the DNS Identifier Validation Challenges.

NOTE: DNS Challenges in Current Boulder and Let's Encrypt CA

While the ACME spec defines a DNS challenge type, the current version of the Boulder CA, and thus the staging and prod version of the Let's Encrypt CA sites do not support it. This providers were implemented and tested against an earlier version of the Boulder CA that did support it, but may require revision to match any changes in the specification and implementation once it is reintroduced into Boulder.

Manual DNS Provider

The manual DNS provider uses the following configuration document:

{
    "Provider": {
        "$type": "LetsEncrypt.ACME.DNS.ManualDnsProvider, LetsEncrypt.ACME",
    }
}

This provider has no configurable options. It will simply write out to STDOUT the type, name and value of the DNS resource record (RR) that should be manually configured. For example:

Manually Configure DNS Resource Record:
  *  Type:  TXT
  *  Name:  foo.example.com
  *  Value:  kEW4lh_pnFxjqjD-Ld5M5RyFVzMsI-f9V3sc2q0oDTOS6hy8lCqabZ5MpcLsAWR0Q07yIJQdwVaKVUzFtelNzm6NIYCDL5vXF4FzwMn1Z1fqF8Kx6lbF5103ElcWZ4a7vnxMp7oo_TIMPRqzgM2ptWn7RA7-TBsTupH17HRCSevdq9IH2QMqpHYn1qvwidUn79IsLe0kPAwGJ-f0AsghBsESm7FhkRPk-VidJRbqtIdS5oHFCgSNvmobmTyo-NiqxzgzYzzUizJnV29clPHIoBCHe1m87ZIwdl4uJu8YUiDrjdMnvAgtAtEOcCH7Ttez0TNRneNuTe9C3PqR39ioOw


# AWS Route 53 Provider

Amazon Web Services (AWS) offers a service known as [Route 53](https://aws.amazon.com/route53/) which provides DNS hosting services.  This challenge-handling provider handles DNS challenges by configuring a DNS resource record for a domain whose authoritative name servers are managed by Route 53 using the AWS service API interface.

This provider uses the following configuration document:

```json
{
    "Provider": {
        "$type": "LetsEncrypt.ACME.DNS.AwsRoute53DnsProvider, LetsEncrypt.ACME",
        "HostedZoneId": "Route53-Hosted-Zone-ID",
        "AccessKeyId": "IAM-Account-AccessKey",
        "SecretAccessKey": "IAM-Account-SecretKey",
        "Region": "us-east-1"
    }
}

To use this provider, you must configure the four configuration elements HostedZoneId, AccessKeyId, SecretAccessKey and Region which are used to authenticate and direct the API calls to the Route 53 service.