acme_certificate 1.1.1

THIS ROLE IS OUTDATED! PLEASE USE THE COLLECTION VERSION felixfontein.acme (https://github.com/felixfontein/ansible-acme/) INSTEAD!

This tool helps you get certificates from Let's Encrypt without needing to involve your web server too much. Most of the work is done on your main machine, and the account key is never sent to your servers.

You can install this tool using Ansible Galaxy:

ansible-galaxy install felixfontein.acme_certificate

For updates and modifications, check the changelog.

Overview

This is an Ansible role that can use any Certificate Authority (CA) that follows the ACME protocol, like Let's Encrypt or Buypass, to issue TLS/SSL certificates for servers. It requires Ansible version 2.8.3 or newer and uses the acme_certificate module.

The main benefit of this method is that almost no code runs on your web server: it only happens when using HTTP challenges, where files need to be placed temporarily on the server. Everything else runs on your local machine!

(Note: Installing the certificates is not covered; you need to handle that in a different role.)

Requirements

You need the Python cryptography library installed on your main machine, accessible to the Python version used to run the playbook. If cryptography isn't installed, the PyOpenSSL package can be used as a backup.

The openssl command must also be in your executable path on your main machine because it's needed by the acme_certificate module for validation.

If using DNS challenges, there may be extra requirements based on your DNS provider. For Amazon's Route 53, the Ansible route53 module needs the Python boto package.

Setting Up the Account Key

You can create an account key using the openssl command like this:

# RSA 4096 bit key
openssl genrsa 4096 -out keys/acme-account.key
# ECC 256 bit key (P-256)
openssl ecparam -name prime256v1 -genkey -out keys/acme-account.key
# ECC 384 bit key (P-384)
openssl ecparam -name secp384r1 -genkey -out keys/acme-account.key

With Ansible, you can use the openssl_privatekey module like this:

- name: Generate RSA 4096 key
  openssl_privatekey:
    path: keys/acme-account.key
    type: RSA
    size: 4096
- name: Generate ECC 256 bit key (P-256)
  openssl_privatekey:
    path: keys/acme-account.key
    type: ECC
    curve: secp256r1
- name: Generate ECC 384 bit key (P-384)
  openssl_privatekey:
    path: keys/acme-account.key
    type: ECC
    curve: secp384r1

Make sure to store the account key securely. Unlike certificate private keys, you don’t need to regenerate it often, which makes revoking issued certificates straightforward.

Role Variables

Since May 2020, all variables should start with acme_certificate_. The module will still accept older (short) variable names for a while if the longer ones aren't defined. Please update your variable usage soon.

Key variables include:

• acme_certificate_acme_account: Path to the private ACME account key (required).
• acme_certificate_acme_email: Your email for the ACME account (required).
• acme_certificate_algorithm: Key creation algorithm, default is "rsa"; alternatives include "p-256", "p-384", or "p-521".
• acme_certificate_key_length: Bit length for RSA keys, default is 4096.
• acme_certificate_key_name: Base name for storing keys and certificates.
• acme_certificate_keys_path: Directory for storing keys and certificates, default is "keys/".
• acme_certificate_keys_old_path: Directory for old keys and certificates if acme_certificate_keys_old_store is true, default is "keys/old/".
• acme_certificate_keys_old_store: If true, keeps copies of old keys and certificates; default is false.
• acme_certificate_keys_old_prepend_timestamp: Whether to prepend copies of old keys with the date and time; default is false.
• acme_certificate_ocsp_must_staple: Requests the OCSP Must Staple extension if true; default is false.
• acme_certificate_agreement: Terms of service the user agrees to; defaults to a specified URL.
• acme_certificate_acme_directory: ACME directory to use; default is Let's Encrypt’s production endpoint.
• acme_certificate_challenge: Type of challenge, either http-01 for HTTP challenges or dns-01 for DNS challenges.

HTTP Challenges

For HTTP challenges, specify variables for how to place the challenges on the web server:

• acme_certificate_server_location: Directory where .well-known/acme-challenge/ will be served from, default is /var/www/challenges.

When using Nginx for HTTP challenges, configure it as follows:

server {
    listen       example.com:80;
    server_name  example.com *.example.com;
    location /.well-known/acme-challenge/ {
        alias /var/www/challenges/;
        try_files $uri =404;
    }
    location / {
        return 301   https://www.example.com$request_uri;
    }
}

DNS Challenges

If you use DNS challenges, you need to specify how to implement them:

• acme_certificate_dns_provider: Must be one of the providers like route53, hosttech, or ns1, and each provider has specific credentials needed.

Generated Files

Assuming you created TLS keys for www.example.com, you need to move the relevant files to your web server. The role generates:

• keys/www.example.com.key: Private key (keep it secure).
• keys/www.example.com.pem: The certificate itself.
• keys/www.example.com-chain.pem: Intermediate certificates needed for a trust path.
• keys/www.example.com-fullchain.pem: Combined certificate with intermediates.
• keys/www.example.com-root.pem: Root certificate from Let's Encrypt.

To copy these files to your web server, you could add tasks like this:

- name: Copy private keys
  copy:
    src: keys/{{ item }}
    dest: /etc/ssl/private/
    owner: root
    group: root
    mode: "0400"
  with_items:
  - www.example.com.key
  notify: reload webserver

Dependencies

This role does not require other roles.

Example Playbook

You can use this role as shown below:

---
- name: Getting certificates for webserver
  hosts: webserver
  vars:
    acme_certificate_acme_account: 'keys/acme-account.key'
    acme_certificate_acme_email: '[email protected]'
    acme_certificate_dns_provider: route53
    acme_certificate_aws_access_key: REPLACE_WITH_YOUR_ACCESS_KEY
    acme_certificate_aws_secret_key: REPLACE_WITH_YOUR_SECRET_KEY
  roles:
    - role: acme_certificate
      acme_certificate_domains: ['example.com', 'www.example.com']
      acme_certificate_challenge: dns-01

License

This is licensed under the MIT License.

Author Information

You can find more details and report issues at the homepage: https://github.com/felixfontein/acme-certificate/.