ACME klijent Lego - WildCard SSL

Detaljan vodič za postavljanje zvezdastog WildCard SSL sertifikata putem ACME klijenta Lego i API DNS validacije sa VEDOS veb hostingom. Postupak je namenjen za sertifikate tipa example.com i *.example.com, gde obnavljanje treba da bude automatsko bez ručnog unošenja TXT zapisa. Vodič koristi ACME sertifikat od sertifikacionog tela Certum. Korišćeni sertifikat služi samo kao primer – princip rada i postupak ACME postavljanja su isti za sva sertifikaciona tela.

Vodič koristi sintaksu proverenu na Lego 5.2.2. Lego v5 je promenio neke parametre u odnosu na starije verzije, pa u slučaju greške poput flag provided but not defined proverite ispravnu sintaksu pomoću lego accounts register --help, lego run --help ili lego --help.

Osnovni pojmovi

• ACME – protokol za automatizovano izdavanje i obnavljanje SSL/TLS sertifikata.
• Lego – ACME klijent napisan u Go. Može izvršavati DNS validaciju kroz mnoge DNS provajdere (lista podržanih DNS provajdera).
• DNS-01 – validacija putem DNS TXT zapisa _acme-challenge. Neophodna je za WildCard sertifikate.
• EAB kid + hmac – External Account Binding (EAB) podaci od sertifikacionog tela. Oni povezuju Certbot sa nalogom ili proizvodom.
• VEDOS WAPI – VEDOS API interfejs preko kojeg Lego kreira i briše DNS TXT zapise.
• Systemd service - konfiguracioni fajl koji govori Linux sistemu kako da pokrene aplikaciju i održi je u radu čak i nakon ponovnog pokretanja servera.

U svim prikazanim primerima zamenite domen example.com sopstvenim domenom.

Instalacija 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

Nakon uspešne instalacije, preporučujemo uklanjanje privremenih fajlova.

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

DNS API provajder

Ovaj vodič koristi DNS API od registra domena Vedos, koji nudi API za upravljanje DNS-om registrovanih domena. Za Vedos veb hosting, potrebno je da aktivirate WAPI i takođe popunite dozvoljene IP adrese i WAPI lozinku.

IP adrese VPS servera

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

U polje Dozvoljene IP adrese unesite sve izlazne IP adrese vašeg servera, obično i IPv4 i IPv6. Vrednosti se razdvajaju razmakom. VEDOS dozvoljava API zahteve samo sa navedenih IP adresa.
Važno: Ako dozvolite samo IPv4, a neki API zahtev izađe putem IPv6, izdavanje sertifikata može uspeti, ali čišćenje TXT zapisa neće uspeti sa greškom Access not allowed from this IP address.

Preporučene vrednosti za VEDOS DNS provajder

Apache, webroot

Osnovno podešavanje Apache je pomoćni deo. DNS validacija se odvija kroz DNS API, ne putem HTTP, ali je Apache vhost potreban za serviranje veb sajta nakon izdavanja sertifikata.

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

Lego konfiguracioni fajlovi

Preporučeni pristup za Lego v5 je čuvanje podešavanja u konfiguracionom fajlu. Systemd service tada ne mora da sadrži dugu komandu sa domenima, DNS provajderom i hukovima.

Konfiguracioni fajl .env

Fajl .env je tekstualni konfiguracioni fajl u kojem se čuvaju promenljive okruženja, na primer akreditivi za pristup, API ključevi ili podešavanja aplikacije. Radi preglednosti, fajl možete nazvati provider-domain.env. Fajl vedos-example.com.env će sadržati VEDOS WAPI akreditive za prijavu, pa ga čuvamo u /etc/lego i postavljamo mu ograničene dozvole.

DOMAIN="example.com"

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

U konfiguraciji ispod, zamenite WEDOS_LOGIN vašim VEDOS loginom, a WEDOS_WAPI_PASSWORD lozinkom generisanom u VEDOS WAPI. Vrednosti timeout i interval možete ostaviti kakve jesu.

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

Konfiguracioni fajl lego.yml

Fajl .yml je tekstualni konfiguracioni fajl u YAML formatu, koji se koristi za pregledan zapis podešavanja, parametara i strukturiranih podataka. Pre čuvanja YAML konfiguracije, zamenite example.com sopstvenim domenom, *.example.com wildcard imenom, vas@email.cz vašim kontakt e-mailom, a vrednosti KID / HMAC podacima iz vaše porudžbine ACME sertifikata. Imena poput certum-example ili example-com-wildcard su interne oznake; možete ih ostaviti, ali kod više domena je preporučljivo preimenovati ih prema domenu.

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

Izdavanje sertifikata

Pre pokretanja, zamenite example.com u putanji domenom koji ste koristili pri kreiranju direktorijuma. Prvo pokretanje kreira ACME nalog, postavlja DNS TXT zapise kroz DNS API, izvršava DNS-01 validaciju i čuva sertifikat.

Tokom čekanja, Lego može ispisati:

To znači da Lego proverava DNS svakih 30 sekundi i čeka najviše 1 sat. Nakon uspeha, proverite fajlove:

Direktorijum certificates/ sadrži izdate .crt, .key, intermediate sertifikate sertifikacionog tela i metapodatke.

Alternativni CLI postupak za 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'

Postavljanje sertifikata na Apache

Pre kreiranja HTTPS vhost-a, zamenite example.com sopstvenim domenom u imenu fajla, vrednostima ServerName i ServerAlias, putanjama do webroot-a i putanjama do sertifikata. Ove putanje moraju odgovarati domenu korišćenom u Lego konfiguraciji.

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

Automatsko obnavljanje

Lego može obnoviti sertifikat, ali nakon instalacije ne kreira sam systemd tajmer. Redovno izvršavanje se podešava putem prilagođenog servisa i tajmera. Pre umetanja, zamenite example-com u imenu servisa/tajmera sopstvenim bezbednim imenom bez tačaka, na primer mojedomena-cz, i zamenite example.com u putanji konfiguracije sopstvenim domenom.

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

Bezbedan test servisa:

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

Ako sertifikat nije blizu isteka, Lego može prijaviti da obnavljanje nije potrebno. Ovo je ispravno ponašanje.

Česte greške

Nepoznat parametar u Lego

U Lego v5 EAB parametri su --eab.kid i --eab.hmac. Parametri uvek pripadaju određenoj podkomandi.

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

Čišćenje TXT zapisa ne uspeva na nedozvoljenoj IP adresi

Dodajte i IPv6 adresu servera u dozvoljene IP adrese u VEDOS WAPI. Sertifikat može biti ispravno izdat, ali će TXT zapisi ostati u DNS-u nakon validacije.

Kontrolna lista za proveru

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

Kuda dalje?

• ACME protokol
• ACME klijent Lego
• ACME klijent Certbot
• SSL sertifikat - Sve što treba da znate