ACME-klienten Lego - WildCard SSL

En detaljerad guide för att driftsätta ett stjärnformat WildCard SSL-certifikat via ACME-klienten Lego och API DNS-validering med webbhotellet VEDOS. Förfarandet är avsett för certifikat av typen example.com och *.example.com, där förnyelse bör vara automatisk utan att manuellt ange TXT-poster. Guiden använder ett ACME-certifikat från certifikatutfärdaren Certum. Certifikatet som används tjänar endast som exempel – driftsprincipen och ACME-driftsättningsförfarandet är desamma för alla certifikatutfärdare.

Guiden använder syntax som verifierats på Lego 5.2.2. Lego v5 ändrade vissa parametrar jämfört med äldre versioner, så vid ett fel som flag provided but not defined verifiera rätt syntax med lego accounts register --help, lego run --help eller lego --help.

Grundläggande begrepp

• ACME – protokoll för automatiserat utfärdande och förnyelse av SSL/TLS-certifikat.
• Lego – en ACME-klient skriven i Go. Den kan utföra DNS-validering via många DNS-leverantörer (lista över DNS-leverantörer som stöds).
• DNS-01 – validering via DNS TXT-posten _acme-challenge. Den krävs för WildCard-certifikat.
• EAB kid + hmac – External Account Binding (EAB)-uppgifter från certifikatutfärdaren. De kopplar Certbot till ett konto eller en produkt.
• VEDOS WAPI – VEDOS API-gränssnittet genom vilket Lego skapar och tar bort DNS TXT-poster.
• Systemd service - en konfigurationsfil som talar om för Linux-systemet hur en applikation ska startas och hållas igång även efter en serveromstart.

I alla visade exempel, ersätt domänen example.com med din egen domän.

Installation av 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

Efter en lyckad installation rekommenderar vi att du tar bort de tillfälliga filerna.

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

DNS API-leverantör

Denna guide använder DNS API från domänregistratorn Vedos, som erbjuder ett API för att hantera DNS för registrerade domäner. För Vedos webbhotell behöver du aktivera WAPI och även fylla i de tillåtna IP-adresserna och WAPI-lösenordet.

VPS-serverns IP-adresser

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

I fältet Tillåtna IP-adresser anger du alla utgående IP-adresser för din server, vanligtvis både IPv4 och IPv6. Värdena separeras med ett mellanslag. VEDOS tillåter API-begäranden endast från de listade IP-adresserna.
Viktigt: Om du endast tillåter IPv4 och någon API-begäran går ut via IPv6 kan utfärdandet av certifikatet lyckas, men rensningen av TXT-poster misslyckas med felet Access not allowed from this IP address.

Rekommenderade värden för DNS-leverantören VEDOS

Apache, webroot

Den grundläggande Apache-inställningen är en stödjande del. DNS-validering körs via DNS API, inte via HTTP, men Apache-vhosten behövs för att leverera webbplatsen efter att certifikatet har utfärdats.

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-konfigurationsfiler

Det rekommenderade tillvägagångssättet för Lego v5 är att lagra inställningarna i en konfigurationsfil. Systemd-tjänsten behöver då inte innehålla ett långt kommando med domäner, DNS-leverantören och hooks.

Konfigurationsfilen .env

.env-filen är en textkonfigurationsfil där miljövariabler lagras, till exempel åtkomstuppgifter, API-nycklar eller applikationsinställningar. För tydlighetens skull kan du namnge filen provider-domain.env. Filen vedos-example.com.env kommer att innehålla VEDOS WAPI-inloggningsuppgifterna, så vi lagrar den i /etc/lego och ställer in begränsade behörigheter på den.

DOMAIN="example.com"

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

I konfigurationen nedan, ersätt WEDOS_LOGIN med din VEDOS-inloggning och WEDOS_WAPI_PASSWORD med lösenordet som genererats i VEDOS WAPI. Du kan lämna värdena för timeout och interval som de är.

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

Konfigurationsfilen lego.yml

.yml-filen är en textkonfigurationsfil i YAML-format, som används för en tydlig notation av inställningar, parametrar och strukturerade data. Innan du sparar YAML-konfigurationen, ersätt example.com med din egen domän, *.example.com med wildcard-namnet, vas@email.cz med din kontakt-e-post och värdena KID / HMAC med uppgifterna från din ACME-certifikatorder. Namn som certum-example eller example-com-wildcard är interna etiketter; du kan lämna dem, men med flera domäner är det lämpligt att byta namn på dem enligt domänen.

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

Utfärdande av certifikat

Innan du kör, ersätt example.com i sökvägen med domänen du använde när du skapade katalogen. Den första körningen skapar ACME-kontot, ställer in DNS TXT-posterna via DNS API, utför DNS-01-validering och sparar certifikatet.

Medan Lego väntar kan den skriva ut:

Detta innebär att Lego kontrollerar DNS var 30:e sekund och väntar högst 1 timme. Efter framgång, verifiera filerna:

Katalogen certificates/ innehåller det utfärdade .crt, .key, certifikatutfärdarens mellanliggande certifikat och metadata.

Alternativt CLI-förfarande för 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'

Driftsätta certifikatet till Apache

Innan du skapar HTTPS-vhosten, ersätt example.com med din egen domän i filnamnet, värdena ServerName och ServerAlias, webroot-sökvägarna och certifikatsökvägarna. Dessa sökvägar måste matcha domänen som används i Lego-konfigurationen.

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

Automatisk förnyelse

Lego kan förnya certifikatet, men efter installationen skapar den inte en systemd-timer på egen hand. Regelbunden körning ställs in via en egen service och timer. Innan du infogar, ersätt example-com i service/timer-namnet med ditt eget säkra namn utan punkter, till exempel mojedomena-cz, och ersätt example.com i konfigurationssökvägen med din egen domän.

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

Säkert test av tjänsten:

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

Om certifikatet inte är nära utgången kan Lego rapportera att förnyelse inte behövs. Detta är korrekt beteende.

Vanliga fel

Okänd parameter i Lego

I Lego v5 är EAB-parametrarna --eab.kid och --eab.hmac. Parametrarna hör alltid till ett specifikt underkommando.

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

Rensning av TXT-poster misslyckas på en otillåten IP

Lägg även till serverns IPv6-adress till de tillåtna IP-adresserna i VEDOS WAPI. Certifikatet kan utfärdas korrekt, men TXT-posterna kommer att finnas kvar i DNS efter valideringen.

Verifieringschecklista

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

Vart går du härnäst?

• ACME-protokollet
• ACME-klienten Lego
• ACME-klienten Certbot
• SSL-certifikat - Allt du behöver veta