Nginx#

Du kan konfigurera nginx att använda NetHSM via OpenSSL-motorn som sedan använder NetHSM:s PKCS#11-modul.

Certifikatfilen måste finnas på hårddisken men den privata nyckeln kan användas från NetHSM.

Ett fullständigt exempel finns tillgängligt nedan.

Konfiguration av OpenSSL#

Installera OpenSSL-motorn genom att följa Installationsguide för OpenSSL-motor.

Providers stöds ännu inte av Nginx.

Observera

Om du använder libp11 OpenSSL-motor version 0.4.12 eller äldre och en NetHSM med många nycklar blir den första laddningen av Nginx långsam (mer än en minut för 1 000 nycklar). Vi rekommenderar att du använder version 0.4.13 eller nyare eller att du bygger motorn från källan ` <https://github.com/OpenSC/libp11>`__.

Konfiguration av Nginx#

ssl_engine pkcs11;

server {
    listen       443 ssl;
    server_name  localhost;

    ssl_certificate      /certs/certificate.pem;

    ssl_certificate_key "engine:pkcs11:pkcs11:object=webserver;type=private";

    ssl_session_cache    shared:SSL:1m;
    ssl_session_timeout  10s;
    ssl_session_tickets off;

    ssl_protocols TLSv1.3;
    ssl_prefer_server_ciphers  off;

    # HSTS (ngx_http_headers_module is required) (63072000 seconds)
    add_header Strict-Transport-Security "max-age=63072000" always;

    # OCSP stapling
    ssl_stapling on;
    ssl_stapling_verify on;

    location / {
        root   /usr/share/nginx/html;
        index  index.html index.htm;
    }

    error_page   500 502 503 504  /50x.html;
    location = /50x.html {
        root   /usr/share/nginx/html;
    }
}

ssl_certificate måste peka på en certifikatfil på disken.

ssl_certificate_key kan vara en OpenSSL-konfiguration. Här använder vi OpenSSL-motorn med PKCS#11-modulen och väljer den privata nyckeln med etiketten/ID webserver och nyckeltypen private.

ssl_certificate_key "engine:pkcs11:pkcs11:object=webserver;type=private";

Observera

Du måste generera certifikatet separat och sedan ladda upp det till NetHSM. Om certifikatet på disken och nyckeln i NetHSM inte matchar varandra kommer nginx inte att starta.

libnethsm_pkcs11 Konfiguration#

slots:
  - label: LocalHSM
    description: Local HSM (docker)
    url: "https://192.168.3.161:8443/api/v1"
    operator:
      username: "operator"
      password: "opPassphrase"

För att säkra lösenordet kan du ange det via en miljövariabel) eller ange det i nginx-konfigurationen:

ssl_certificate_key "engine:pkcs11:pkcs11:object=webserver;type=private;pin=opPassphrase";

Exempel#

Om du vill experimentera med exemplet ` <https://github.com/Nitrokey/nethsm-pkcs11/tree/main/container/nginx>`__ använder du git för att klona nethsm-pkcs11 repository och kör följande kommandon:

Varning

När genereringsskriptet körs raderas nyckeln webserver och ersätts med en ny.

  1. Konfigurera en NetHSM, antingen en riktig eller en container. Mer information finns i Getting-started guide. Förutom en administratör kommer du att behöva ett operatörskonto.

  2. Ladda ner och installera den senaste versionen av drivrutinen nethsm-pkcs11 som finns tillgänglig här.

  3. Installera OpenSSL PKCS11-motorn enligt beskrivningen i OpenSSL Manual. Du behöver inte skapa någon konfigurationsfil.

  4. Justera variablerna HOST, ADMIN_ACCOUNT och ADMIN_ACCOUNT_PWD i container/nginx/generate.sh så att HOST innehåller din NetHSMs URL och port, ADMIN_ACCOUNT innehåller ett administratörskontos användarnamn och ADMIN_ACCOUNT_PWD motsvarande lösenord. Konfigurera vidare den absoluta sökvägen för OpenSSL PKCS11-motorn i OPENSSL_PKCS11_ENGINE_PATH och den absoluta sökvägen för NetHSM PKCS11-biblioteket i NETHSM_PKCS11_LIBRARY_PATH.

  5. Skapa en NetHSM PKCS11-konfigurationsfil på en av de kända platserna, t.ex. /etc/nitrokey/p11nethsm.conf. Den måste ha konfigurerat ett operatörskonto och använda samma NetHSM-instans som angavs i genereringsskriptet tidigare.

  6. Uppdatera PKCS11-konfigurationen i container/nginx/p11nethsm.conf med din NetHSMs-URL och giltiga operatörsautentiseringsuppgifter.

  7. Generera certifikat och nyckel.

./container/nginx/generate.sh

  1. Bygg upp behållaren.

docker build -f container/nginx/Dockerfile . -t pkcs-nginx

  1. Kör containern.

docker run -p 9443:443 -p 9080:80 pkcs-nginx

NGINX testsida kommer att finnas tillgänglig på https://localhost:9443/. Observera att din webbläsare, förhoppningsvis, kommer att varna dig för att webbplatsens certifikat är självsignerat.