ACME klient Lego

ACME klient Lego je nezávislý, bezplatný open-source projekt napísaný v jazyku Go. Je ideálny na vlastnú integráciu a skriptovanie a teší sa širokej podpore registrátorov domén a DNS poskytovateľov. Lego je flexibilný ACME klient, ktorý možno ľahko integrovať do vlastných systémov a skriptov. Okrem HTTP-01 validácie ponúka DNS validáciu cez množstvo DNS poskytovateľov (zoznam podporovaných DNS poskytovateľov) na získanie WildCard SSL certifikátov.
Návod používa syntax overenú na verzii Lego 5.*.* a je určený pre Debian/Ubuntu s Apache 2 a ACME klientom Lego.

Základné pojmy

• ACME – protokol na automatizované vydávanie a obnovu SSL/TLS certifikátov.
• HTTP-01 – ACME metóda validácie, ktorá overuje vlastníctvo domény pomocou dočasného súboru dostupného cez HTTP.
• DNS-01 – metóda validácie cez DNS TXT záznam _acme-challenge.
• EAB kid + hmac – údaje External Account Binding (EAB) od certifikačnej autority. Prepájajú ACME klienta s účtom alebo produktom.
• Systemd služba - konfiguračný súbor, ktorý hovorí systému Linux, ako spustiť aplikáciu a udržať ju v chode aj po reštarte servera.

Ak sa v príkladoch objaví doména example.com, vždy ju nahraďte svojou vlastnou doménou.

Inštalácia Lego

apt update
apt install -y curl tar

cd /tmp
LEGO_URL=$(curl -s https://api.github.com/repos/go-acme/lego/releases/latest | sed -n 's/.*"browser_download_url": "\(.*linux_amd64.tar.gz\)".*/\1/p' | head -n1)
echo "$LEGO_URL"
curl -L -o lego.tar.gz "$LEGO_URL"
tar -xzf lego.tar.gz
install -m 0755 lego /usr/local/bin/lego
lego --version

Po úspešnej inštalácii odporúčame odstrániť dočasné súbory.

rm -f /tmp/lego /tmp/lego.tar.gz /tmp/LICENSE /tmp/CHANGELOG.md

Apache, webroot

Tento postup vytvorí základnú konfiguráciu VirtualHost pre doménu na porte 80. Nastaví DocumentRoot, oprávnenia pre webový adresár, vytvorí logy Apache, povolí konfiguráciu pomocou a2ensite, overí jej správnosť (apache2ctl configtest) a znovu načíta zmeny. Nakoniec overí dostupnosť webu pomocou HTTP požiadavky curl.

cd /var/www
apt update
apt install -y apache2
systemctl enable --now apache2
a2enmod rewrite headers ssl
systemctl reload apache2

# or just updates
apt update
apt install --only-upgrade apache2
systemctl reload apache2

DOMAIN="example.com"
mkdir -p /var/www/$DOMAIN/public
chown -R www-data:www-data /var/www/$DOMAIN
chmod -R 755 /var/www/$DOMAIN
echo "OK $DOMAIN" > /var/www/$DOMAIN/public/index.html

cat > /etc/apache2/sites-available/$DOMAIN.conf <<EOF
<VirtualHost *:80>
    ServerName $DOMAIN
    ServerAlias www.$DOMAIN

    DocumentRoot /var/www/$DOMAIN/public
    <Directory /var/www/$DOMAIN/public>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog \${APACHE_LOG_DIR}/${DOMAIN}_error.log
    CustomLog \${APACHE_LOG_DIR}/${DOMAIN}_access.log combined
</VirtualHost>
EOF

a2ensite "$DOMAIN.conf"
apache2ctl configtest
systemctl reload apache2
curl -I "http://$DOMAIN"
curl -I "http://www.$DOMAIN"

Konfiguračné súbory Lego

Odporúčaný prístup pre Lego v5 je uložiť nastavenia do konfiguračného súboru. Systemd služba tak nemusí obsahovať dlhý príkaz s doménami a hookmi.

Konfiguračný súbor lego.yml

Súbor .yml je textový konfiguračný súbor vo formáte YAML, ktorý sa používa na prehľadný zápis nastavení, parametrov a štruktúrovaných dát. Pred uložením YAML konfigurácie nahraďte example.com svojou vlastnou doménou, vas@email.cz svojím kontaktným e-mailom a hodnoty KID / HMAC údajmi z vašej objednávky ACME certifikátu.

mkdir /etc/lego/$DOMAIN
nano /etc/lego/$DOMAIN/lego.yml

storage: /etc/lego/example.com

accounts:
  certum-account:
    server: certum
    email: your@email.com   # your email address for CA Certum
    acceptsTermsOfService: true
    eab:
      kid: KID
      hmacKey: HMAC

servers:
  certum:
    url: https://acme.certum.pl/directory

challenges:
  http-chal:
    http:
      # Path to your website's document root.
      # Lego will temporarily write a file to this directory .well-known/acme-challenge/
      webroot: /var/www/example.com/public

certificates:
  example-com:
    account: certum-account
    challenge: http-chal
    domains:
      - example.com
      - www.example.com
    renew:
      days: 30

hooks:
  deploy:
    command: systemctl reload apache2

Tip! Takmer kompletný obsah YML si môžete vygenerovať priamo na serveri a potom už len doplniť správny e-mail, kid a hmacKey. Stačí spustiť príkaz nižšie a skopírovať obsah zo stránky index.html do súboru lego.yml.
›› Zobraziť/Skryť pripravené YML.

cat > "/var/www/$DOMAIN/public/index.html" <<EOF
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>${DOMAIN}</title>
<style>
body { font-family: sans-serif; max-width: 900px; margin: 40px auto; }
pre { background:#f4f4f4; padding:1em; overflow:auto; }
</style>
</head>
<body>

<h1>OK – ${DOMAIN}</h1>
<p>Apache is working correctly.</p>
<h2>lego.yml</h2>
<pre><code>storage: /etc/lego/${DOMAIN}

accounts:
  certum-account:
    server: certum
    email: YOUR_EMAIL
    acceptsTermsOfService: true
    eab:
      kid: YOUR_KID
      hmacKey: YOUR_HMAC_KEY

servers:
  certum:
    url: https://acme.certum.pl/directory

challenges:
  http-chal:
    http:
      webroot: /var/www/${DOMAIN}/public

certificates:
  ${DOMAIN//./-}:
    account: certum-account
    challenge: http-chal
    domains:
      - ${DOMAIN}
      - www.${DOMAIN}
    renew:
      days: 30

hooks:
  deploy:
    command: systemctl reload apache2
</code></pre>

</body>
</html>
EOF

Kontrola oprávnení a vlastníka súboru:

stat -c "%a %U:%G %n" /etc/lego/$DOMAIN/lego.yml

Vydanie SSL/TLS certifikátu

Pred spustením skontrolujte echo ${DOMAIN} alebo nastavte premennú DOMAIN na názov vašej domény DOMAIN="example.com". Nástroj Lego vykoná HTTP-01 validáciu pomocou súboru dočasne uloženého vo webroot, overí vlastníctvo domény a potom vytvorí SSL/TLS certifikát. Certifikát, súkromný kľúč a certifikát vydavateľa (intermediate) sa uložia do adresára /etc/lego/${DOMAIN}/certificates/.

Počas generovania ACME klient Lego vypíše informácie o požiadavke:

root@vmiXXXXXXXX:~# echo ${DOMAIN}
example.com

root@:~# lego --config /etc/lego/$DOMAIN/lego.yml

INFO  Archive account scope=accountID filepath=/etc/lego/example.com/accounts/acme.certum.pl/certum-acme/
      archives=/etc/lego/example.com/archives/accounts/acme.certum.pl_certum-acme_1785270773.zip
INFO  Private key saved. filepath=/etc/lego/example.com/accounts/acme.certum.pl/certum-account/certum-account.key
INFO  Registering the account (EAB). email=your@email.com
WARN  !!!! HEADS UP !!!!

Your account credentials have been saved in your
configuration directory at "/etc/lego/example.com/accounts".

You should make a secure backup of this folder now. This
configuration directory will also contain private keys
generated by lego and certificates obtained from the ACME
server. Making regular backups of this folder is ideal.

INFO  Obtaining bundled SAN certificate. domains="example.com, www.example.com"
INFO  Use solver. domain=www.example.com type=http-01
INFO  Use solver. domain=example.com type=http-01
INFO  http01: Trying to solve HTTP-01. domain=www.example.com
INFO  The server validated our request. domain=www.example.com
INFO  http01: Trying to solve HTTP-01. domain=example.com
INFO  The server validated our request. domain=example.com
INFO  Validations succeeded; requesting certificates. domains="example.com, www.example.com"
INFO  Waiting for certificates. timeout=30s interval=500ms domains="example.com, www.example.com"
INFO  Server responded with a certificate. domains="example.com, www.example.com"
INFO  Writing file. filepath=/etc/lego/example.com/certificates/acmeapi-online.crt
INFO  Writing file. filepath=/etc/lego/example.com/certificates/acmeapi-online.issuer.crt
INFO  Writing file. filepath=/etc/lego/example.com/certificates/acmeapi-online.key
INFO  Writing file. filepath=/etc/lego/example.com/certificates/acmeapi-online.pem
INFO  Writing file. filepath=/etc/lego/example.com/certificates/acmeapi-online.json

Overte vygenerované súbory SSL certifikátu

Zobrazí obsah adresára certificates vytvoreného službou Lego vrátane certifikátu, súkromného kľúča a certifikátu vydavateľa pre zvolenú doménu.

Adresár certificates/ obsahuje vydaný .crt, .key, intermediate certifikáty certifikačnej autority a metadáta.

Nasadenie certifikátu do Apache

Tento príklad používa premennú ${DOMAIN}, ktorú by ste už mali mať nastavenú z úvodu návodu. Pred spustením príkazov sa môžete uistiť, že je premenná nastavená správne, napríklad: echo ${DOMAIN}
Premenná ${DOMAIN} sa používa v názve konfiguračného súboru, hodnotách ServerName a ServerAlias a v ceste k webroot.
Upozornenie! - cesty k SSL certifikátu a súkromnému kľúču používajú doménu v tvare example-com. Cesty musia zodpovedať doméne použitej v konfigurácii Lego.

cat > /etc/apache2/sites-available/${DOMAIN}-le-ssl.conf <<EOF
<IfModule mod_ssl.c>
<VirtualHost *:443>
    ServerName ${DOMAIN}
    ServerAlias www.${DOMAIN}

    DocumentRoot /var/www/${DOMAIN}/public
    <Directory /var/www/${DOMAIN}/public>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    SSLEngine on
    SSLCertificateFile /etc/lego/${DOMAIN}/certificates/${DOMAIN//./-}.crt
    SSLCertificateKeyFile /etc/lego/${DOMAIN}/certificates/${DOMAIN//./-}.key

    ErrorLog ${APACHE_LOG_DIR}/${DOMAIN}_ssl_error.log
    CustomLog ${APACHE_LOG_DIR}/${DOMAIN}_ssl_access.log combined
</VirtualHost>
</IfModule>
EOF

a2ensite ${DOMAIN}-le-ssl.conf
apache2ctl configtest
systemctl reload apache2

curl -I https://${DOMAIN}
curl -I https://www.${DOMAIN}

Výsledok: Funkčné HTTPS.

Automatická obnova

Lego dokáže certifikát obnoviť automaticky, ale po inštalácii si systemd jednotky pre pravidelné spúšťanie samo nevytvorí. Na automatickú obnovu treba preto vytvoriť dve jednotky:

• lego-example-com-renew.service – spustí kontrolu a v prípade potreby obnovu certifikátu.
• lego-example-com-renew.timer – zabezpečí, že sa služba spúšťa denne v nastavenom čase.

Pred vložením nahraďte example-com v názve služby/časovača svojím vlastným názvom, ak je to potrebné, a nahraďte example.com v ceste ku konfigurácii svojou vlastnou doménou.

cat > /etc/systemd/system/lego-${DOMAIN//./-}-renew.service <<EOF
[Unit]
Description=Renew ACME Certum SSL for example.com using Lego HTTP-01
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/lego --config /etc/lego/${DOMAIN}/lego.yml
EOF

cat > /etc/systemd/system/lego-${DOMAIN//./-}-renew.timer <<EOF
[Unit]
Description=Daily Lego renewal check for ${DOMAIN}

[Timer]
OnCalendar=*-*-* 03:20:00
RandomizedDelaySec=1800
Persistent=true

[Install]
WantedBy=timers.target
EOF

Po vytvorení jednotiek overte ich obsah:

cat /etc/systemd/system/lego-example-com-renew.service
echo "----------------"
cat /etc/systemd/system/lego-example-com-renew.timer

Znovu načítajte nové jednotky, povoľte časovač a overte, že beží:

systemctl daemon-reload
systemctl enable --now lego-${DOMAIN//./-}-renew.timer
systemctl list-timers | grep lego

Výsledok: Časovač je aktívny a systemd naplánoval jeho ďalšie spustenie.

Bezpečný test služby:

systemctl start lego-${DOMAIN//./-}-renew.service
systemctl status lego-${DOMAIN//./-}-renew.service --no-pager
journalctl -u lego-${DOMAIN//./-}-renew.service -n 100 --no-pager

Výsledok: Ak certifikát nie je blízko vypršania platnosti, Lego môže oznámiť, že obnova nie je potrebná. Je to správne správanie.

Zoznam dostupných Lego jednotiek:

ls -l /etc/systemd/system/lego*

systemctl list-timers | grep lego

Výsledok: Oba varianty zobrazia všetky služby a časovače súvisiace s ACME klientom Lego.

Kam ďalej?

• ACME protokol
• ACME klient Lego (WildCard + API DNS)
• ACME klient Certbot
• SSL certifikát - všetko, čo potrebujete vedieť