Nginx#

Můžete nakonfigurovat nginx tak, aby používal NetHSM prostřednictvím enginu OpenSSL, který pak používá modul PKCS#11 NetHSM.

Soubor certifikátu musí být na disku, ale soukromý klíč lze použít z NetHSM.

Úplný příklad je k dispozici na pod.

Konfigurace protokolu OpenSSL#

Nastavte engine OpenSSL podle průvodce nastavením OpenSSL Engine.

Nginx zatím zprostředkovatele nepodporuje.

Poznámka

Použití enginu OpenSSL libp11 verze 0.4.12 nebo starší a NetHSM s velkým množstvím klíčů způsobí, že počáteční načítání Nginxu bude pomalé (více než minuta pro 1 tisíc klíčů). Doporučuje se používat verzi 0.4.13 nebo novější nebo sestavit engine ze zdrojových kódů ` <https://github.com/OpenSC/libp11>` __.

Konfigurace 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;
    }
}

Adresa ssl_certificate musí ukazovat na soubor s certifikátem na disku.

ssl_certificate_key může být konfigurace OpenSSL. Zde použijeme engine OpenSSL s modulem PKCS#11 a vybereme soukromý klíč s označením/ID webserver a typem klíče private.

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

Poznámka

Certifikát je nutné vygenerovat samostatně a poté jej nahrát do NetHSM. Pokud se certifikát na disku a klíč v NetHSM neshodují, nginx se nespustí.

libnethsm_pkcs11 Konfigurace#

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

Heslo můžete zabezpečit pomocí proměnné prostředí (viz Setup) nebo jej zadat v konfiguraci nginx:

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

Příklad#

Pokud chcete experimentovat s uvedeným příkladem ` <https://github.com/Nitrokey/nethsm-pkcs11/tree/main/container/nginx>` __, použijte git pro klonování repozitáře nethsm-pkcs11 a spusťte následující příkazy:

Varování

Spuštěním generovacího skriptu se odstraní klíč webserver a nahradí se.

  1. Nakonfigurujte NetHSM, buď skutečný, nebo kontejner. Další informace naleznete v příručce getting-started. Kromě účtu správce budete potřebovat i účet operátora.

  2. Stáhněte si a nainstalujte nejnovější verzi nethsm-pkcs11 ovladače dostupnou odtud.

  3. Nainstalujte engine OpenSSL PKCS11 podle popisu v příručce OpenSSL. Není třeba vytvářet konfigurační soubor.

  4. Upravte proměnné HOST, ADMIN_ACCOUNT a ADMIN_ACCOUNT_PWD v container/nginx/generate.sh tak, aby HOST obsahovala adresu URL a port vašeho NetHSM, ADMIN_ACCOUNT obsahovala uživatelské jméno účtu správce a ADMIN_ACCOUNT_PWD odpovídající heslo. Dále nakonfigurujte absolutní cestu k enginu OpenSSL PKCS11 v OPENSSL_PKCS11_ENGINE_PATH a absolutní cestu ke knihovně NetHSM PKCS11 v NETHSM_PKCS11_LIBRARY_PATH.

  5. Vytvořte konfigurační soubor NetHSM PKCS11 v jednom ze známých umístění ` <pkcs11-setup.html#configuration>` __, např. /etc/nitrokey/p11nethsm.conf. Musí mít nakonfigurovaný účet operátora a používat stejnou instanci NetHSM, která byla zadána v předchozím generovacím skriptu.

  6. Aktualizujte konfiguraci PKCS11 na adrese container/nginx/p11nethsm.conf pomocí adresy URL NetHSM a platných pověření operátora.

  7. Vygenerujte certifikát a klíč.

./container/nginx/generate.sh

  1. Sestavte kontejner.

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

  1. Spusťte kontejner.

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

Testovací stránka NGINX bude k dispozici na adrese https://localhost:9443/. Všimněte si, že váš prohlížeč vás, doufejme, upozorní, že certifikát webových stránek je podepsán sám sebou.