ACME klient Lego - WildCard SSL

Podrobný návod na nasadenie hviezdičkového WildCard SSL certifikátu cez ACME klienta Lego a API DNS validáciu s webhostingom VEDOS. Postup je určený pre certifikáty typu example.com a *.example.com, kde by obnova mala prebiehať automaticky bez ručného zadávania TXT záznamov. Návod používa ACME certifikát od certifikačnej autority Certum. Použitý certifikát slúži len ako príklad – princíp fungovania a postup nasadenia ACME sú rovnaké pre všetky certifikačné autority.

Návod používa syntax overenú na Lego 5.2.2. Lego v5 zmenilo oproti starším verziám niektoré parametre, takže v prípade chyby ako flag provided but not defined overte správnu syntax pomocou lego accounts register --help, lego run --help alebo lego --help.

Základné pojmy

• ACME – protokol na automatizované vydávanie a obnovu SSL/TLS certifikátov.
• Lego – ACME klient napísaný v jazyku Go. Dokáže vykonať DNS validáciu cez množstvo DNS poskytovateľov (zoznam podporovaných DNS poskytovateľov).
• DNS-01 – validácia cez DNS TXT záznam _acme-challenge. Je vyžadovaná pre WildCard certifikáty.
• EAB kid + hmac – údaje External Account Binding (EAB) od certifikačnej autority. Prepájajú ACME klienta s účtom alebo produktom.
• VEDOS WAPI – API rozhranie VEDOS, cez ktoré Lego vytvára a maže DNS TXT záznamy.
• 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.

Vo všetkých uvedených príkladoch nahraďte doménu example.com 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

Poskytovateľ DNS API

Tento návod používa DNS API od registrátora domén Vedos, ktorý ponúka API na správu DNS registrovaných domén. Pre webhosting Vedos je potrebné aktivovať WAPI a tiež vyplniť povolené IP adresy a heslo WAPI.

IP adresy VPS servera

curl -4 ifconfig.me
curl -6 ifconfig.me

Do poľa Povolené IP adresy zadajte všetky odchádzajúce IP adresy vášho servera, zvyčajne IPv4 aj IPv6. Hodnoty sa oddeľujú medzerou. VEDOS povoľuje API požiadavky len z uvedených IP adries.
Dôležité: Ak povolíte len IPv4 a niektorá API požiadavka odíde cez IPv6, vydanie certifikátu môže prebehnúť úspešne, ale vyčistenie TXT záznamov zlyhá s chybou Access not allowed from this IP address.

Odporúčané hodnoty pre DNS poskytovateľa VEDOS

Apache, webroot

Základné nastavenie Apache je podporná časť. DNS validácia prebieha cez DNS API, nie cez HTTP, ale Apache vhost je potrebný na poskytovanie webu po vydaní certifikátu.

cd /var/www
apt update
apt install -y apache2
systemctl enable --now apache2
a2enmod rewrite headers ssl
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 *.$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

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, DNS poskytovateľom a hookmi.

Konfiguračný súbor .env

Súbor .env je textový konfiguračný súbor, v ktorom sa ukladajú premenné prostredia, napríklad prístupové údaje, API kľúče alebo nastavenia aplikácie. Pre prehľadnosť môžete súbor pomenovať provider-domain.env. Súbor vedos-example.com.env bude obsahovať prihlasovacie údaje VEDOS WAPI, preto ho ukladáme do /etc/lego a nastavíme mu obmedzené oprávnenia.

DOMAIN="example.com"

mkdir -p /etc/lego/$DOMAIN
nano /etc/lego/vedos-$DOMAIN.env

V konfigurácii nižšie nahraďte WEDOS_LOGIN svojím prihlásením do VEDOS a WEDOS_WAPI_PASSWORD heslom vygenerovaným vo VEDOS WAPI. Hodnoty timeout a interval môžete ponechať tak, ako sú.

WEDOS_USERNAME='WEDOS_LOGIN'
WEDOS_WAPI_PASSWORD='WEDOS_WAPI_PASSWORD'
WEDOS_PROPAGATION_TIMEOUT=3600
WEDOS_POLLING_INTERVAL=30
WEDOS_TTL=300

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, *.example.com wildcard názvom, vas@email.cz svojím kontaktným e-mailom a hodnoty KID / HMAC údajmi z vašej objednávky ACME certifikátu. Názvy ako certum-example alebo example-com-wildcard sú interné označenia; môžete ich ponechať, ale pri viacerých doménach je vhodné premenovať ich podľa domény.

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

storage: /etc/lego/example.com

accounts:
  certum-example:
    server: certum
    email: vas@email.cz
    acceptsTermsOfService: true
    eab:
      kid: KID
      hmacKey: HMAC

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

challenges:
  vedos-dns:
    dns:
      provider: vedos
      envFile: /etc/lego/vedos-example-com.env
      resolvers:
        - 1.1.1.1:53

certificates:
  example-com-wildcard:
    account: certum-example
    challenge: vedos-dns
    domains:
      - example.com
      - "*.example.com"
    renew:
      days: 30

hooks:
  deploy:
    command: systemctl reload apache2

Vydanie certifikátu

Pred spustením nahraďte example.com v ceste doménou, ktorú ste použili pri vytváraní adresára. Prvé spustenie vytvorí ACME účet, nastaví DNS TXT záznamy cez DNS API, vykoná DNS-01 validáciu a uloží certifikát.

Počas čakania môže Lego vypísať:

To znamená, že Lego kontroluje DNS každých 30 sekúnd a čaká najviac 1 hodinu. Po úspechu overte súbory:

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

Alternatívny CLI postup pre Lego v5

lego accounts register \
  --path /etc/lego/example.com \
  --server https://acme.certum.pl/directory \
  --email vas@email.cz \
  --accept-tos \
  --eab \
  --eab.kid 'KID' \
  --eab.hmac 'HMAC'

set -a
. /etc/lego/vedos-example.com.env
set +a

lego run \
  --path /etc/lego/example.com \
  --server https://acme.certum.pl/directory \
  --email vas@email.cz \
  --dns vedos \
  --dns.resolvers 1.1.1.1:53 \
  --domains example.com \
  --domains '*.example.com'

Nasadenie certifikátu do Apache

Pred vytvorením HTTPS vhost nahraďte example.com svojou vlastnou doménou v názve súboru, hodnotách ServerName a ServerAlias, cestách k webroot a cestách k certifikátu. Tieto cesty musia zodpovedať doméne použitej v konfigurácii Lego.

cat > /etc/apache2/sites-available/example.com-le-ssl.conf <<'EOF'
<IfModule mod_ssl.c>
<VirtualHost *:443>
    ServerName example.com
    ServerAlias *.example.com

    DocumentRoot /var/www/example.com/public
    <Directory /var/www/example.com/public>
        Options -Indexes +FollowSymLinks
        AllowOverride All
        Require all granted
    </Directory>

    SSLEngine on
    SSLCertificateFile /etc/lego/example.com/certificates/example.com.crt
    SSLCertificateKeyFile /etc/lego/example.com/certificates/example.com.key

    ErrorLog ${APACHE_LOG_DIR}/example.com_ssl_error.log
    CustomLog ${APACHE_LOG_DIR}/example.com_ssl_access.log combined
</VirtualHost>
</IfModule>
EOF

a2ensite example.com-le-ssl.conf
apache2ctl configtest
systemctl reload apache2

curl -I https://example.com
curl -I https://test.example.com

Automatická obnova

Lego dokáže certifikát obnoviť, ale po inštalácii si nevytvorí systemd časovač samo. Pravidelné spúšťanie sa nastaví cez vlastnú službu a časovač. Pred vložením nahraďte example-com v názve služby/časovača svojím vlastným bezpečným názvom bez bodiek, napríklad mojedomena-cz, a nahraďte example.com v ceste ku konfigurácii svojou vlastnou doménou.

cat > /etc/systemd/system/lego-example-com-renew.service <<'EOF'
[Unit]
Description=Renew Certum WildCard SSL for example.com using Lego and VEDOS DNS
Wants=network-online.target
After=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/lego --config /etc/lego/example.com/lego.yml
EOF

cat > /etc/systemd/system/lego-example-com-renew.timer <<'EOF'
[Unit]
Description=Daily Lego renewal check for example.com

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

[Install]
WantedBy=timers.target
EOF

systemctl daemon-reload
systemctl enable --now lego-example-com-renew.timer
systemctl list-timers | grep lego

Bezpečný test služby:

systemctl start lego-example-com-renew.service
journalctl -u lego-example-com-renew.service -n 100 --no-pager

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.

Bežné chyby

Neznámy parameter v Lego

V Lego v5 sú EAB parametre --eab.kid a --eab.hmac. Parametre vždy patria ku konkrétnemu podpríkazu.

lego accounts register --help
lego accounts list --help
lego run --help

Vyčistenie TXT záznamov zlyhá na nepovolenej IP

Pridajte medzi povolené IP adresy vo VEDOS WAPI aj IPv6 adresu servera. Certifikát môže byť vydaný správne, ale TXT záznamy zostanú v DNS po validácii.

Kontrolný zoznam overenia

dig TXT _acme-challenge.example.com +short
lego --config /etc/lego/example.com/lego.yml
systemctl status lego-example-com-renew.timer
apache2ctl configtest
curl -I https://example.com

Kam ďalej?

• ACME protokol
• ACME klient Lego
• ACME klient Certbot
• SSL certifikát - všetko, čo potrebujete vedieť