Skip to content

Challenge Handling Providers

Jump to bottom Edit New page
Eugene Bekker edited this page Jan 12, 2016 · 11 revisions

| PLEASE NOTE - LEGACY DOCS - Prior to v0.8.0

| This documents behavior that has been augmented, deprecated or replaced.

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

Overview

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.

Web Server (HTTP) Providers

The Web server providers support handling of the HTTP Identifier Validation Challenges.

Manual Web Server Provider

The manual Web server provider uses the following configuration document:

{
    "Provider": {
        "$type": "LetsEncrypt.ACME.WebServer.ManualWebServerProvider, LetsEncrypt.ACME",
        "FilePath": ".\\path\\to\\web-content-file"
    }
}

To use this provider, you may optionally set the FilePath configuration element with the absolute or relative path of a file to which the provider will save the challenge response content. If no FilePath is configured, then the provider will save the challenge response content to a temporary file, and return the path to the generated file.

NOTE: File Path Permissions
If an output file path is specified for this provider, then the provider must have permission to write to this file under the context in which it is executed. A common source of confusion is that this provider is configured to write the content directly to an IIS root path, which requires that the process be executed with elevated (Administrator) privileges.

This provider It will simply write out to STDOUT the URL under which the challenge response should be found and the path to the local file where the response challenge content has been saved. For example:

type, name and value of the DNS resource record (RR) that should be manually configured. For example:

Manually Upload Web Server File:"
  *           URL:  http://foo.example.com/.well-known/acme-challenge/evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA
  *  File Content:  c:\temp\tmp4261.tmp

With the information that is printed out by this provider, the user is expected to complete the challenge by manually configuring the target Web server to host a file whose path resolves to the server's local path satisfying the returned URL, and whose contents are specified by the content of the returned file.

To complete the example scenario above, let's pretend that we executed this challenge handler on a host that is the resolved target of the domain foo.example.com. Let's also assume that this host has IIS installed using the default Web sites, site paths and other configuration settings. To manually complete the challenge in the example above, we would create a file path under the default site's home directory and copy the file content to a specific file within:

mkdir "c:\inetpub\wwwroot\.well-known\acme-challenge"
copy c:\temp\tmp4261.tmp "c:\inetpub\wwwroot\.well-known\acme-challenge\evaGxfADs6pSRb2LAv9IZf17Dt3juxGJ-PCt92wr-oA"

Additionally, for a default configuration of IIS, files with no extensions, such as as the one in the example above which is needed to satisfy the HTTP challenge, are not supported and IIS will respond with a 404.3 error. In order to address this conflict is necessary to take additional steps.

IIS Site Path Provider

COMING SOON

AWS S3 + CloudFront Web Server Provider

This provider is convenient to use when you have access to the Amazon Web Services (AWS) platform, but may not have a Web server readily available (or publicly-accessible) to service HTTP challenge responses. In this scenario, we make use of two AWS services, namely S3 and CloudFront to host and serve up a static file that contains the HTTP challenge response.

In order to use this provider, you must have an S3 bucket to which you can upload content, and you must have configured a CloudFront distribution that is backed by that S3 bucket. The details of this configuration are beyond the scope of this document. Please reference the related links for more details.

Additionally, you need to created a DNS resource record for the domain which is being authorized by this challenge. This resource record should be a CNAME that points the public DNS endpoint of the CloudFront distribution. You can either perform this step manually, or optionally, you can specify a DNS provider, which can be used to configure it automatically for you.

This provider uses the following configuration document:

{
    "Provider": {
        "$type": "LetsEncrypt.ACME.WebServer.AwsS3WebServerProvider, LetsEncrypt.ACME",
        "BucketName": "acmetesting.sample.com",
        "AccessKeyId": "IAM-Account-AccessKey",
        "SecretAccessKey": "IAM-Account-SecretKey",
        "Region": "us-east-1",
        "DnsProvider": null,
        "DnsCnameTarget":  "foo.cloudfront.com"
    }
}

The BucketName, AccessKeyId, SecretAccessKey and Region are all required configuration elements that specify authentication credentials for the AWS service calls, as well as where to route the calls and into what S3 storage location to place the challenge response.

The DnsProvider and DnsCnameTarget configuration elements are optional elements that you can provide if you want this provider to automatically handle mapping a DNS resource record to your CloudFront's distribution endpoint. If provided, the DnsProvider should be a provider configuration document for one of the DNS Providers and the DnsCnameTarget should be the DNS endpoint for your CloudFront distribution that is backed by the S3 storage.

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 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:

{
    "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.

Add a custom footer

Home

Docs

Legacy Docs - out of date

Reference

A bit dated

Clone this wiki locally