Awesome

ACME cookbook

Automatically get/renew free and trusted certificates from Let's Encrypt (letsencrypt.org). ACME is the Automated Certificate Management Environment protocol used by Let's Encrypt.

Starting with v4.0.0 of the acme cookbook the acme_ssl_certificate provider has been removed! The TLS-SNI-01 validation method used by this provider been disabled by Let's Encrypt due to security concerns. Please switch to the acme_certificate provider in this cookbook to request and renew your certificate using the supported HTTP-01 validation method.

Attributes

Recipes

default

Installs the required acme-client rubygem.

Usage

Use the acme_certificate resource to request a certificate with the http-01 challenge. The webserver for the domain for which you are requesting a certificate must be running on the local server. This resource only supports the http validation method. To use the tls-sni-01 challenge, please see the resource below. Provide the path to your wwwroot for the specified domain.

acme_certificate 'test.example.com' do
  crt               '/etc/ssl/test.example.com.crt'
  key               '/etc/ssl/test.example.com.key'
  wwwroot           '/var/www'
end

If your webserver needs an existing certificate already when installing a new server, you will have a bootstrap problem: The web server cannot start without a certificate, but the certificate cannot be requested without the running web server. To overcome this, a temporary self-signed certificate can be generated with the acme_selfsigned resource, allowing the web server to start.

acme_selfsigned 'test.example.com' do
  crt     '/etc/ssl/test.example.com.crt'
  chain   '/etc/ssl/test.example.com-chain.crt'
  key     '/etc/ssl/test.example.com.key'
end

A working example can be found in the included acme_client test cookbook.

Providers

certificate

selfsigned

Example

To generate a certificate for an apache2 website you can use code like this:

# Include the recipe to install the gems
include_recipe 'acme'

# Set up contact information. Note the mailto: notation
node.override['acme']['contact'] = ['mailto:me@example.com']
# Real certificates please...
node.override['acme']['endpoint'] = 'https://acme-v01.api.letsencrypt.org'

site = "example.com"
sans = ["www.#{site}"]

# Generate a self-signed if we don't have a cert to prevent bootstrap problems
acme_selfsigned "#{site}" do
  crt     "/etc/httpd/ssl/#{site}.crt"
  key     "/etc/httpd/ssl/#{site}.key"
  chain    "/etc/httpd/ssl/#{site}.pem"
  owner   "apache"
  group   "apache"
  notifies :restart, "service[apache2]", :immediate
end

# Set up your web server here...

# Get and auto-renew the certificate from Let's Encrypt
acme_certificate "#{site}" do
  crt               "/etc/httpd/ssl/#{site}.crt"
  key               "/etc/httpd/ssl/#{site}.key"
  wwwroot           "/var/www/#{site}/htdocs/"
  notifies :restart, "service[apache2]"
  alt_names sans
end

DNS verification

Letsencrypt supports DNS validation. Depending on the setup there may be different ways to deploy an acme challenge to your infrastructure. If you want to use DSN validation, you have to provide two block arguments to the acme_certificate resource.

Implement 2 methods in a library in your cookbook, each returning a Proc object. The following example uses a HTTP API to provide challenges to the DNS infrastructure.

# my_cookbook/libraries/acme_dns.rb

class Chef
  class Recipe
    def install_dns_challenge(apitoken)
      Proc.new do |authorization, new_resource|
        # use DNS authorization
        authz = authorization.dns
        fqdn = authorization.identifier['value']
        r = Net::HTTP.post(URI("https://my_awesome_dns_api/#{fqdn}"), authz.record_content, {'Authorization' => "Token #{apitoken}"})
        if r.code != '200'
          fail "DNS API does not want to install Challenge for #{fqdn}"
        else
          # do some validation that the challenge has propagated to the infrastructure
        end
        # it is important that the authz and fqdn is passed back, so it can be passed to the remove_dns_challenge method
        [authz, fqdn]
      end
    end
    def remove_dns_challenge(apitoken)
      Proc.new do |authz, fqdn|
        uri = URI("https://my_awesome_dns_api/#{fqdn}")
        Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme=='https') do |http|
          http.delete(uri, {'Authorization' => "Token #{apitoken}"})
        end
      end
    end
  end
end

Use it in your recipe the following way:

apitoken = chef_vault_item(vault, item)['dns_api_token']
acme_certificate node['fqdn'] do
  key '/path/to/key'
  crt '/path/to/crt'
  install_authz_block install_dns_challenge(apitoken)
  remove_authz_block remove_dns_challenge(apitoken)
end

Testing

The kitchen includes a pebble server to run the integration tests with, so testing can run locally without interaction with the online APIs.

Contributing

1. Fork the repository on Github
2. Create a named feature branch (like add_component_x)
3. Write your change
4. Write tests for your change (if applicable)
5. Run the tests, ensuring they all pass
6. Submit a Pull Request using Github

License and Authors

Authors: Thijs Houtenbos thoutenbos@schubergphilis.com

Credits

Let’s Encrypt is a trademark of the Internet Security Research Group. All rights reserved.