LetsEncrypt with ACME on OpenWRT

Wiki.TerraBase.info
Revision as of 11:01, 4 November 2021 by Root (talk | contribs)
Jump to navigation Jump to search

ACME

ACME is a Let'sEncrypt Client implementation for OpenWRT. It will request and store SSL / HTTPS Certificates for various purposes. It can be utilized by Apache, NGinx, UHTTPD, etc. on OpenWRT.

Installation

opkg update

opkg install acme acme-dnsapi luci-app-acme

Functionality

Based on the script files, it appears the "ACME Service" can be triggered by CRON or a Start or Restart of the service.

Usage Via Command Line

Quick Notes

--cert-file: Path and File Name where certificate will be copied to (IE, the 'originals' are stored elsewhere)

--key-file: Path and File Name where key will be copied to (IE, the 'originals' are stored elsewhere)

--fullchain-file: Path and File Name where full-chain will be copied to (IE, the 'originals' are stored elsewhere)

--ca-file: Path and File Name where ca will be copied to (IE, the 'originals' are stored elsewhere)

--home

--cert-home

--config-home

Source: https://github.com/acmesh-official/acme.sh

Also see contents of acme.sh --help below.

Examples

  • /usr/lib/acme/acme.sh --revoke --domain WhatEverDomainName.xyz
  • /usr/lib/acme/acme.sh --list
  • /usr/lib/acme/acme.sh --issue --webroot /usr/share/apache2/htdocs --domain WhatEverDomainName.xyz --home /etc/acme --cert-home /etc/acme/certs --config-home /etc/acme/config

Certbot Comparisons

  • Webroot Method
    • Acme.sh: --webroot WhatEverPath
    • Certbot: --webroot --webroot-path WhatEverPath (there are no parameters after --webroot, so it seems Acme.sh just combined the two commands since --webroot for Certbot implies --webroot-path would be needed, if there's no default)
  • Get a Certificate
    • Acme.sh --issue
    • Certbot: certonly (no double dashes)
  • Obtaining a Certificate via DNS
    • Acme.sh --issue --dns dns_nsupdate --domain WhatEverDomain
    • Certbot: certonly --dns-rfc2136 --dns-rfc2136-credentials WhatEverCredentialFile -d WhatEverDomain

Using DNS (BIND / Named) to Obtain a Certificate (with a Certbot comparison thrown in)

BIND / Named Stuff to do

First generate a "user name / password" (AKA nametypeand key)

  • Acme.sh: dnssec-keygen -a hmac-sha512 -b 512 -n USER
  • Certbot:

Acme.sh Stuff to do

This needs a dedicated article...

Files

/etc/config/acme: OpenWRT configuration file that receives / sends information from LuCI GUI

config acme
       option state_dir '/etc/acme'
       option account_email 'email@example.org'
       option debug 0

config cert 'example'
       option enabled 0
       option use_staging 1
       option keylength 2048
       option update_uhttpd 1
       option update_nginx 1
       option webroot ""
       option dns ""
       list domains example.org

/etc/acme: Storage location for certificates, referenced by /etc/config/acme /etc/init.d/acme: Service stop / start file

#!/bin/sh /etc/rc.common

USE_PROCD=1

START=50
SCRIPT=/usr/lib/acme/run-acme

start_service()
{
    procd_open_instance
    procd_set_param command $SCRIPT
    procd_set_param file /etc/config/acme
    procd_set_param stdout 1
    procd_set_param stderr 1
    procd_close_instance
}

reload_service() {
    rc_procd start_service "$@"
    return 0
}

stop_service() {
    return 0
}

boot() {
    touch "/var/run/acme_boot"
    start
}

service_triggers()
{
    procd_add_reload_trigger acme
}

/usr/lib/acme/acme.sh: Appears to be a generic shell script. It can be used via the command line and is also used by the below /usr/lib/acme/run-acme "wrapper". Below is the help file;

https://github.com/Neilpang/acme.sh
v2.8.5
Usage: acme.sh  command ...[parameters]....
Commands:
  --help, -h               Show this help message.
  --version, -v            Show version info.
  --install                Install acme.sh to your system.
  --uninstall              Uninstall acme.sh, and uninstall the cron job.
  --upgrade                Upgrade acme.sh to the latest code from https://github.com/Neilpang/acme.sh.
  --issue                  Issue a cert.
  --signcsr                Issue a cert from an existing csr.
  --deploy                 Deploy the cert to your server.
  --install-cert           Install the issued cert to apache/nginx or any other server.
  --renew, -r              Renew a cert.
  --renew-all              Renew all the certs.
  --revoke                 Revoke a cert.
  --remove                 Remove the cert from list of certs known to acme.sh.
  --list                   List all the certs.
  --showcsr                Show the content of a csr.
  --install-cronjob        Install the cron job to renew certs, you don't need to call this. The 'install' command can automatically install the cron job.
  --uninstall-cronjob      Uninstall the cron job. The 'uninstall' command can do this automatically.
  --cron                   Run cron job to renew all the certs.
  --toPkcs                 Export the certificate and key to a pfx file.
  --toPkcs8                Convert to pkcs8 format.
  --update-account         Update account info.
  --register-account       Register account key.
  --deactivate-account     Deactivate the account.
  --create-account-key     Create an account private key, professional use.
  --create-domain-key      Create an domain private key, professional use.
  --createCSR, -ccsr       Create CSR , professional use.
  --deactivate             Deactivate the domain authz, professional use.
  --set-notify             Set the cron notification hook, level or mode.


Parameters:
  --domain, -d   domain.tld         Specifies a domain, used to issue, renew or revoke etc.
  --challenge-alias domain.tld      The challenge domain alias for DNS alias mode: https://github.com/Neilpang/acme.sh/wiki/DNS-alias-mode
  --domain-alias domain.tld         The domain alias for DNS alias mode: https://github.com/Neilpang/acme.sh/wiki/DNS-alias-mode
  --force, -f                       Used to force to install or force to renew a cert immediately.
  --staging, --test                 Use staging server, just for test.
  --debug                           Output debug info.
  --output-insecure                 Output all the sensitive messages. By default all the credentials/sensitive messages are hidden from the output/debug/log for secure.
  --webroot, -w  /path/to/webroot   Specifies the web root folder for web root mode.
  --standalone                      Use standalone mode.
  --alpn                            Use standalone alpn mode.
  --stateless                       Use stateless mode, see: https://github.com/Neilpang/acme.sh/wiki/Stateless-Mode
  --apache                          Use apache mode.
  --dns [dns_cf|dns_dp|dns_cx|/path/to/api/file]   Use dns mode or dns api.
  --dnssleep  [120]                  The time in seconds to wait for all the txt records to take effect in dns api mode. Default 120 seconds.

  --keylength, -k [2048]            Specifies the domain key length: 2048, 3072, 4096, 8192 or ec-256, ec-384.
  --accountkeylength, -ak [2048]    Specifies the account key length.
  --log    [/path/to/logfile]       Specifies the log file. The default is: "/root/.acme.sh/acme.sh.log" if you don't give a file path here.
  --log-level 1|2                   Specifies the log level, default is 1.
  --syslog [0|3|6|7]                Syslog level, 0: disable syslog, 3: error, 6: info, 7: debug.

  These parameters are to install the cert to nginx/apache or any other server after issue/renew a cert:

  --cert-file                       After issue/renew, the cert will be copied to this path.
  --key-file                        After issue/renew, the key will be copied to this path.
  --ca-file                         After issue/renew, the intermediate cert will be copied to this path.
  --fullchain-file                  After issue/renew, the fullchain cert will be copied to this path.

  --reloadcmd "service nginx reload" After issue/renew, it's used to reload the server.

  --server SERVER                   ACME Directory Resource URI. (default: https://acme-v01.api.letsencrypt.org/directory)
  --accountconf                     Specifies a customized account config file.
  --home                            Specifies the home dir for acme.sh.
  --cert-home                       Specifies the home dir to save all the certs, only valid for '--install' command.
  --config-home                     Specifies the home dir to save all the configurations.
  --useragent                       Specifies the user agent string. it will be saved for future use too.
  --accountemail                    Specifies the account email, only valid for the '--install' and '--update-account' command.
  --accountkey                      Specifies the account key path, only valid for the '--install' command.
  --days                            Specifies the days to renew the cert when using '--issue' command. The default value is 60 days.
  --httpport                        Specifies the standalone listening port. Only valid if the server is behind a reverse proxy or load balancer.
  --tlsport                         Specifies the standalone tls listening port. Only valid if the server is behind a reverse proxy or load balancer.
  --local-address                   Specifies the standalone/tls server listening address, in case you have multiple ip addresses.
  --listraw                         Only used for '--list' command, list the certs in raw format.
  --stopRenewOnError, -se           Only valid for '--renew-all' command. Stop if one cert has error in renewal.
  --insecure                        Do not check the server certificate, in some devices, the api server's certificate may not be trusted.
  --ca-bundle                       Specifies the path to the CA certificate bundle to verify api server's certificate.
  --ca-path                         Specifies directory containing CA certificates in PEM format, used by wget or curl.
  --nocron                          Only valid for '--install' command, which means: do not install the default cron job. In this case, the certs will not be renewed automatically.
  --noprofile                       Only valid for '--install' command, which means: do not install aliases to user profile.
  --no-color                        Do not output color text.
  --force-color                     Force output of color text. Useful for non-interactive use with the aha tool for HTML E-Mails.
  --ecc                             Specifies to use the ECC cert. Valid for '--install-cert', '--renew', '--revoke', '--toPkcs' and '--createCSR'
  --csr                             Specifies the input csr.
  --pre-hook                        Command to be run before obtaining any certificates.
  --post-hook                       Command to be run after attempting to obtain/renew certificates. No matter the obtain/renew is success or failed.
  --renew-hook                      Command to be run once for each successfully renewed certificate.
  --deploy-hook                     The hook file to deploy cert
  --ocsp-must-staple, --ocsp        Generate ocsp must Staple extension.
  --always-force-new-domain-key     Generate new domain key when renewal. Otherwise, the domain key is not changed by default.
  --auto-upgrade   [0|1]            Valid for '--upgrade' command, indicating whether to upgrade automatically in future.
  --listen-v4                       Force standalone/tls server to listen at ipv4.
  --listen-v6                       Force standalone/tls server to listen at ipv6.
  --openssl-bin                     Specifies a custom openssl bin location.
  --use-wget                        Force to use wget, if you have both curl and wget installed.
  --yes-I-know-dns-manual-mode-enough-go-ahead-please  Force to use dns manual mode: https://github.com/Neilpang/acme.sh/wiki/dns-manual-mode
  --branch, -b                      Only valid for '--upgrade' command, specifies the branch name to upgrade to.

  --notify-level  0|1|2|3           Set the notification level:  Default value is 2.
                                     0: disabled, no notification will be sent.
                                     1: send notifications only when there is an error.
                                     2: send notifications when a cert is successfully renewed, or there is an error.
                                     3: send notifications when a cert is skipped, renewed, or error.
  --notify-mode   0|1               Set notification mode. Default value is 0.
                                     0: Bulk mode. Send all the domain's notifications in one message(mail).
                                     1: Cert mode. Send a message for every single cert.
  --notify-hook   [hookname]        Set the notify hook

/usr/lib/acme/run-acme: According to the notes in the file, it's a "wrapper" for the acme.sh script.


Retrieved from "https://wiki.terrabase.info/index.php?title=LetsEncrypt_with_ACME_on_OpenWRT&oldid=1530"