Skip to content

A
acme-dns-tiny
Commit 3d7ea3eb authored by Adrien Dorsaz's avatar Adrien Dorsaz
Browse files
Options

Readme: move how to use informations on wiki

parent 1356b245
Pipeline #43 passed with stage
    in 3 minutes and 16 seconds
    Hide whitespace changes
    Inline Side-by-side
    Showing with 25 additions and 151 deletions
    README.md
    View file @ 3d7ea3eb
    ......@@ -3,17 +3,19 @@
    [![build status](https://projects.adorsaz.ch/adrien/acme-dns-tiny/badges/master/build.svg)](https://projects.adorsaz.ch/adrien/acme-dns-tiny/commits/master)
    [![coverage status](https://projects.adorsaz.ch/adrien/acme-dns-tiny/badges/master/coverage.svg)](https://projects.adorsaz.ch/adrien/acme-dns-tiny/commits/master)
    This is a tiny, auditable script that you can throw on your server to issue
    and renew [Let's Encrypt](https://letsencrypt.org/) certificates with DNS
    This is a tiny, auditable script that you can throw on any secure machine to
    issue and renew [Let's Encrypt](https://letsencrypt.org/) certificates with DNS
    validation.
    Since it has to have access to your private ACME account key and the
    rights to update the DNS records of your DNS server, this code has been designed
    to be as tiny as possible (currently less than 250 lines).
    The only prerequisites are python (especially the dnspython module) and openssl.
    The only prerequisites are Python 3, OpenSSL and the dnspython module (with
    release before 1.14.0 (this release have a bug with dynamic DNS updates)).
    **PLEASE READ THE SOURCE CODE! YOU MUST TRUST IT! IT HANDLES YOUR ACCOUNT PRIVATE KEYS!**
    **PLEASE READ THE SOURCE CODE! YOU MUST TRUST IT!
    IT HANDLES YOUR ACCOUNT PRIVATE KEYS!**
    Note: this script is a fork of the [acme-tiny project](https://github.com/diafygi/acme-tiny)
    which uses ACME HTTP verification to create signed certificates.
    ......@@ -27,170 +29,42 @@ but they do fantastic work.
    ## How to use this script
    If you already have a Let's Encrypt issued certificate and just want to renew,
    you should only have to do Steps 3 and 6.
    See our the [HowTo Use](howto-use) wiki page for main informations.
    ### Step 1: Create a Let's Encrypt account private key (if you haven't already)
    You may be interested by the [HowTo Setup with BIND9](howto-setup-with-bind9)
    page too which show a step by step example to set up the script
    with a BIND9 DNS server.
    You must have a public key registered with Let's Encrypt and sign your requests
    with the corresponding private key. If you don't understand what I just said,
    this script likely isn't for you! Please use the official Let's Encrypt
    [client](https://github.com/letsencrypt/letsencrypt).
    To accomplish this you need to initially create a key, that can be used by
    acme-tiny, to register a account for you and sign all following requests.
    ```
    openssl genrsa 4096 > account.key
    ```
    #### Use existing Let's Encrypt key
    Alternatively you can convert your key, previously generated by the original
    Let's Encrypt client.
    The private account key from the Let's Encrypt client is saved in the
    [JWK](https://tools.ietf.org/html/rfc7517) format. `acme-tiny` is using the PEM
    key format. To convert the key, you can use the tool
    [conversion script](https://gist.github.com/JonLundy/f25c99ee0770e19dc595)
    by JonLundy:
    ```sh
    # Download the script
    curl "https://gist.githubusercontent.com/JonLundy/f25c99ee0770e19dc595/raw/6035c1c8938fae85810de6aad1ecf6e2db663e26/conv.py" > conv.py
    # Copy your private key to your working directory
    cp /etc/letsencrypt/accounts/acme-v01.api.letsencrypt.org/directory/<id>/private_key.json private_key.json
    # Create a DER encoded private key
    openssl asn1parse -noout -out private_key.der -genconf <(python conv.py private_key.json)
    # Convert to PEM
    openssl rsa -in private_key.der -inform der > account.key
    ```
    ### Step 2: Create a certificate signing request (CSR) for your domains.
    The ACME protocol (what Let's Encrypt uses) requires a CSR file to be submitted
    to it, even for renewals. You can use the same CSR for multiple renewals.
    NOTE: you can't use your account private key as your domain private key!
    ```
    #generate a domain private key (if you haven't already)
    openssl genrsa 4096 > domain.key
    ```
    ```
    #for a single domain
    openssl req -new -sha256 -key domain.key -subj "/CN=example.org" > domain.csr
    #for multiple domains (use this one if you want both www.example.org and example.org)
    openssl req -new -sha256 -key domain.key -subj "/" -reqexts SAN -config <(cat /etc/ssl/openssl.cnf <(printf "[SAN]\nsubjectAltName=DNS:example.org,DNS:www.example.org")) > domain.csr
    ```
    ### Step 3: Make your DNS server allows dynamic updates
    You must prove you own the domains you want a certificate for, so Let's Encrypt
    requires you host some DNS resource records.
    This script will generate and write those DNS records to your DNS server by
    use of DNS dynamic message updates.
    So you have to configure your DNS server to allow dynamic DNS
    updates and create a TSIG key which will give rights to perform updates.
    The configuration of the script will need:
    * the TSIG key name and value
    * the algorithm used for TSIG key (hmac-md5, hmac-sha1, hmac-sha224, hmac-sha256, hmac-sha384 or hmac-512; list of algoithm depends on knowe ones by dnspython module)
    * the DNS zone to update
    * the address and the port of the DNS server
    The simplest way to configure the script is to copy the `example.ini` file
    from this repository and update values as needed.
    **Be careful! Set read permissions correctly on the configuration file, because
    it will contain the key authorized to modify your DNS configuration !**
    ### Step 4: Get a signed certificate!
    Now that you have setup your server and generated all the needed files, run this
    script on a computer containing your private account key, the CSR and the configuration.
    ```
    python acme_dns_tiny.py example.ini > ./chain.pem
    ```
    If every thing was ok, chain.crt contains your signed certificate followed by the
    CA's certificate which signed yours.
    ### Step 5: Install the certificate
    The certificate chain that is output by this script can be used along
    with your private key to run any service on your server which need TSL encryption.
    You need to include both in the TLS settings of your services.
    ### Step 6: Setup an auto-renew cronjob
    Congrats! Your server is now using TLS! Unfortunately, Let's Encrypt
    certificates only last for 90 days, so you need to renew them often. No worries!
    It's automated! Just make a bash script and add it to your crontab (see below
    for example script).
    Example of a skeleton for `renew_cert.sh` script:
    ```sh
    #!/bin/bash
    # Configuration
    # You should use another directory as /tmp could be destroyed regularly
    WORKINGDIR="/tmp/acme-dns-tiny"
    # Pre run script: configure a secure workspace using ACL POSIX
    mkdir -p ${WORKINGDIR}
    setfacl -m "default:other:--- , other:---" ${WORKINGDIR}
    # You should also add code to create backup of older certificates
    # You may need code to handle HPKP (key pining in HTTP) updates
    # You may need to update DANE (key pining in DNS) too
    # With HPKP and DANE, you should also consider your automatic key rollover
    # which will need to update the CSR file and/or your DNS DANE records.
    # Run the script
    python /path/to/acme_dns_tiny.py example.ini > ${WORKINGDIR}/chain.pem || exit
    # Post run script
    # You should reload each service using TLS
    ```
    Then you'll need to configure a cron job to execute this script regularly (think
    to set random minutes to avoid to DDOS the CA servers).
    Note that, this script can be run on any secure machine which have access to
    Internet and your public DNS server.
    ## Permissions
    The biggest problem you'll likely come across while setting up and running this
    script is permissions. You want to limit access to your account private key, your
    CSR and your configuration file. I'd recommend creating a user
    specifically for handling this script, the account private key, the CSR and
    the DNS key. Then add the ability for that user to write to your installed
    certificate file (e.g. `/path/to/chain.pem`) and reload your services. That
    way, the cron job will do its thing, overwrite your old certificate, and
    reload your webserver without having permission to do anything else.
    script is permissions.
    You want to limit access for this script to:
    * Your account private key
    * Your Certificate Signing Request (CSR) file (without your domain key)
    * Your configuration file (which contain DNS update secret)
    I'd recommend to create a user specifically to run this script and the
    above files. This user should *NOT* have access to your domain key!
    **BE SURE TO:**
    * Backup your account private key (e.g. `account.key`)
    * Don't allow this script to be able to read your *domain* private key!
    * Don't allow this script to be run as *root*!
    * Understand and configure correctly your cron job to do all your needs !
    (if you don't know bash, write it in your preferred language to manage your
    server)
    (write it with your preferred language to manage your server)
    ## Feedback/Contributing
    This project has a very, very limited scope and codebase. The project is happy
    to receive bug reports and pull requests, but please don't add any new features.
    This script must stay under 250 lines of code to ensure it can be easily audited
    by anyone who wants to run it.
    This script must stay under ~250 lines of code to ensure it can be easily
    audited by anyone who wants to run it.
    If you want to add features for your own setup to make things easier for you,
    please do! It's open source, so feel free to fork it and modify as necessary.
    Markdown is supported
    0% or
    You are about to add 0 people to the discussion. Proceed with caution.
    Finish editing this message first!
    Please register or to comment