ACME klijent Lego

ACME klijent Lego neovisan je, besplatan projekt otvorenog koda napisan u jeziku Go. Idealan je za prilagođenu integraciju i skriptiranje i uživa široku podršku registrara domena i DNS pružatelja. Lego je fleksibilan ACME klijent koji se lako integrira u prilagođene sustave i skripte. Osim HTTP-01 validacije, nudi DNS validaciju putem mnogih DNS pružatelja (popis podržanih DNS pružatelja) za dobivanje WildCard SSL certifikata.
Vodič koristi sintaksu provjerenu na verziji Lego 5.*.* i namijenjen je za Debian/Ubuntu s Apacheom 2 i ACME klijentom Lego.

Osnovni pojmovi

• ACME – protokol za automatizirano izdavanje i obnavljanje SSL/TLS certifikata.
• HTTP-01 – ACME metoda validacije koja provjerava vlasništvo nad domenom pomoću privremene datoteke dostupne putem HTTP-a.
• DNS-01 – metoda validacije putem DNS TXT zapisa _acme-challenge.
• EAB kid + hmac – External Account Binding (EAB) podaci od certifikacijskog tijela. Povezuju Certbot s računom ili proizvodom.
• Systemd service - konfiguracijska datoteka koja Linux sustavu govori kako pokrenuti aplikaciju i održavati je pokrenutom čak i nakon ponovnog pokretanja poslužitelja.

Ako se u primjerima pojavi domena example.com, uvijek je zamijenite 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

Apache, webroot

Ovaj postupak stvara osnovnu VirtualHost konfiguraciju za domenu na portu 80. Postavlja DocumentRoot, dozvole za web direktorij, stvara Apache zapisnike, omogućuje konfiguraciju pomoću a2ensite, provjerava njezinu ispravnost (apache2ctl configtest) i ponovno učitava promjene. Na kraju provjerava dostupnost web stranice pomoću HTTP zahtjeva 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"

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 i hookovima.

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, vas@email.cz svojim kontakt e-mailom te vrijednosti KID / HMAC podacima iz vaše narudžbe ACME certifikata.

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

Savjet! Gotovo cjelovit YML sadržaj možete generirati izravno na poslužitelju, a zatim samo popuniti ispravan e-mail, kid i hmacKey. Samo pokrenite naredbu ispod i kopirajte sadržaj sa stranice index.html u datoteku lego.yml.
›› Prikaži/Sakrij pripremljeni 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

Provjera dozvola i vlasnika datoteke:

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

Izdavanje SSL/TLS certifikata

Prije pokretanja provjerite echo ${DOMAIN} ili postavite varijablu DOMAIN na naziv svoje domene DOMAIN="example.com". Alat Lego provodi HTTP-01 validaciju pomoću datoteke privremeno pohranjene u webrootu, provjerava vlasništvo nad domenom i zatim stvara SSL/TLS certifikat. Certifikat, privatni ključ i certifikat izdavatelja (intermediate) bit će pohranjeni u direktoriju /etc/lego/${DOMAIN}/certificates/.

Tijekom generiranja ACME klijent Lego ispisat će informacije o zahtjevu:

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

Provjera generiranih datoteka SSL certifikata

Prikazuje sadržaj direktorija certifikata koji je stvorila usluga Lego, uključujući certifikat, privatni ključ i certifikat izdavatelja za odabranu domenu.

Direktorij certificates/ sadrži izdani .crt, .key, intermediate certifikate certifikacijskog tijela i metapodatke.

Implementacija certifikata na Apache

Ovaj primjer koristi varijablu ${DOMAIN}, koju biste već trebali imati postavljenu od početka vodiča. Prije pokretanja naredbi možete se uvjeriti da je varijabla ispravno postavljena, primjerice: echo ${DOMAIN}
Varijabla ${DOMAIN} koristi se u nazivu konfiguracijske datoteke, vrijednostima ServerName i ServerAlias te putanji do webroota.
Upozorenje! - putanje do SSL certifikata i privatnog ključa koriste domenu u obliku example-com. Putanje moraju odgovarati domeni korištenoj u Lego konfiguraciji.

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}

Rezultat: Ispravan HTTPS.

Automatsko obnavljanje

Lego može automatski obnoviti certifikat, ali nakon instalacije sam ne stvara systemd jedinice za redovito izvršavanje. Za automatsko obnavljanje stoga je potrebno stvoriti dvije jedinice:

• lego-example-com-renew.service – pokreće provjeru i, ako je potrebno, obnavljanje certifikata.
• lego-example-com-renew.timer – osigurava da se usluga pokreće svakodnevno u zadano vrijeme.

Prije umetanja zamijenite example-com u nazivu service/timer svojim vlastitim nazivom ako je potrebno, i zamijenite example.com u putanji konfiguracije svojom vlastitom domenom.

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

Nakon stvaranja jedinica provjerite njihov sadržaj:

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

Ponovno učitajte nove jedinice, omogućite timer i provjerite radi li:

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

Rezultat: Timer je aktivan i systemd je zakazao njegovo sljedeće pokretanje.

Siguran test usluge:

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

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

Popis dostupnih Lego jedinica:

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

systemctl list-timers | grep lego

Rezultat: Obje varijante prikazuju sve usluge i timere povezane s ACME klijentom Lego.

Kamo dalje?

• ACME protokol
• ACME klijent Lego (WildCard + API DNS)
• ACME klijent Certbot
• SSL certifikat - sve što trebate znati