ACME klijent Lego - WildCard SSL

Detaljan vodič za implementaciju zvjezdastog WildCard SSL certifikata putem ACME klijenta Lego i API DNS validacije s VEDOS web hostingom. Postupak je namijenjen za certifikate tipa example.com i *.example.com, gdje bi obnavljanje trebalo biti automatsko bez ručnog unosa TXT zapisa. Vodič koristi ACME certifikat od certifikacijskog tijela Certum. Korišteni certifikat služi samo kao primjer – načelo rada i postupak ACME implementacije jednaki su za sva certifikacijska tijela.

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

Osnovni pojmovi

• ACME – protokol za automatizirano izdavanje i obnavljanje SSL/TLS certifikata.
• Lego – ACME klijent napisan u Go. Može provoditi DNS validaciju putem mnogih DNS pružatelja (popis podržanih DNS pružatelja).
• DNS-01 – validacija putem DNS TXT zapisa _acme-challenge. Potrebna je za WildCard certifikate.
• EAB kid + hmac – External Account Binding (EAB) podaci od certifikacijskog tijela. Povezuju Certbot s računom ili proizvodom.
• VEDOS WAPI – VEDOS API sučelje putem kojeg Lego stvara i briše DNS TXT zapise.
• Systemd service - konfiguracijska datoteka koja Linux sustavu govori kako pokrenuti aplikaciju i održavati je pokrenutom čak i nakon ponovnog pokretanja poslužitelja.

U svim prikazanim primjerima zamijenite domenu example.com svojom vlastitom domenom.

Instalacija Lega

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 uspješne instalacije preporučujemo uklanjanje privremenih datoteka.

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

DNS API pružatelj

Ovaj vodič koristi DNS API registrara domena Vedos, koji nudi API za upravljanje DNS-om registriranih domena. Za Vedos web hosting potrebno je aktivirati WAPI te također ispuniti dopuštene IP adrese i WAPI lozinku.

IP adrese VPS poslužitelja

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

U polje Dopuštene IP adrese unesite sve izlazne IP adrese svog poslužitelja, obično i IPv4 i IPv6. Vrijednosti se odvajaju razmakom. VEDOS dopušta API zahtjeve samo s navedenih IP adresa.
Važno: Ako dopustite samo IPv4, a neki API zahtjev izađe putem IPv6, izdavanje certifikata može uspjeti, ali čišćenje TXT zapisa neće uspjeti uz pogrešku Access not allowed from this IP address.

Preporučene vrijednosti za VEDOS DNS pružatelja

Apache, webroot

Osnovno postavljanje Apachea pomoćni je dio. DNS validacija radi putem DNS API-ja, a ne putem HTTP-a, ali Apache vhost potreban je za posluživanje web stranice nakon izdavanja certifikata.

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 konfiguracijske datoteke

Preporučeni pristup za Lego v5 jest pohranjivanje postavki u konfiguracijsku datoteku. Systemd service tada ne mora sadržavati dugu naredbu s domenama, DNS pružateljem i hookovima.

Konfiguracijska datoteka .env

Datoteka .env je tekstualna konfiguracijska datoteka u kojoj se pohranjuju varijable okruženja, primjerice pristupne vjerodajnice, API ključevi ili postavke aplikacije. Radi preglednosti datoteku možete nazvati provider-domain.env. Datoteka vedos-example.com.env sadržavat će VEDOS WAPI vjerodajnice za prijavu, pa je pohranjujemo u /etc/lego i postavljamo joj ograničene dozvole.

DOMAIN="example.com"

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

U konfiguraciji ispod zamijenite WEDOS_LOGIN svojom VEDOS prijavom i WEDOS_WAPI_PASSWORD lozinkom generiranom u VEDOS WAPI. Vrijednosti 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

Konfiguracijska datoteka lego.yml

Datoteka .yml je tekstualna konfiguracijska datoteka u YAML formatu, koja se koristi za pregledan zapis postavki, parametara i strukturiranih podataka. Prije spremanja YAML konfiguracije zamijenite example.com svojom vlastitom domenom, *.example.com wildcard nazivom, vas@email.cz svojim kontakt e-mailom te vrijednosti KID / HMAC podacima iz vaše narudžbe ACME certifikata. Nazivi poput certum-example ili example-com-wildcard interne su oznake; možete ih ostaviti, ali kod više domena preporučljivo ih je preimenovati prema domeni.

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 certifikata

Prije pokretanja zamijenite example.com u putanji domenom koju ste koristili pri stvaranju direktorija. Prvo pokretanje stvara ACME račun, postavlja DNS TXT zapise putem DNS API-ja, provodi DNS-01 validaciju i sprema certifikat.

Tijekom čekanja Lego može ispisati:

To znači da Lego provjerava DNS svakih 30 sekundi i čeka najviše 1 sat. Nakon uspjeha provjerite datoteke:

Direktorij certificates/ sadrži izdani .crt, .key, intermediate certifikate certifikacijskog tijela 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'

Implementacija certifikata na Apache

Prije stvaranja HTTPS vhosta zamijenite example.com svojom vlastitom domenom u nazivu datoteke, vrijednostima ServerName i ServerAlias, putanjama webroota i putanjama certifikata. Te putanje moraju odgovarati domeni korištenoj 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 certifikat, ali nakon instalacije sam ne stvara systemd timer. Redovito izvršavanje postavlja se putem prilagođene usluge i timera. Prije umetanja zamijenite example-com u nazivu service/timer svojim vlastitim sigurnim nazivom bez točaka, primjerice mojedomena-cz, i zamijenite example.com u putanji konfiguracije svojom vlastitom 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

Siguran test usluge:

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

Ako certifikat nije blizu isteka, Lego može javiti da obnavljanje nije potrebno. To je ispravno ponašanje.

Uobičajene pogreške

Nepoznat parametar u Legu

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

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

Čišćenje TXT zapisa ne uspijeva na nedopuštenom IP-u

Dodajte i IPv6 adresu poslužitelja u dopuštene IP adrese u VEDOS WAPI. Certifikat može biti ispravno izdan, ali TXT zapisi ostat će u DNS-u nakon validacije.

Kontrolni popis za provjeru

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

Kamo dalje?

• ACME protokol
• ACME klijent Lego
• ACME klijent Certbot
• SSL certifikat - sve što trebate znati