Nginx#

Je kunt nginx configureren om NetHSM te gebruiken via de OpenSSL engine die dan de PKCS#11 module van NetHSM gebruikt.

Het certificaatbestand moet op de schijf staan, maar de privésleutel kan worden gebruikt vanaf de NetHSM.

Een volledig voorbeeld is beschikbaar onder.

OpenSSL-configuratie#

Stel de OpenSSL engine in door de OpenSSL Engine setup guide te volgen.

Providers worden nog niet ondersteund door Nginx.

Notitie

Het gebruik van de libp11 OpenSSL engine versie 0.4.12 of ouder en een NetHSM met veel sleutels zal het initiële laden van Nginx traag maken (meer dan een minuut voor duizend sleutels). Het wordt aanbevolen om versie 0.4.13 of nieuwer te gebruiken of om de engine te bouwen vanaf source.

Nginx configuratie#

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

De ssl_certificate moet verwijzen naar een certificaatbestand op de schijf.

De ssl_certificate_key kan een OpenSSL configuratie zijn. Hier gebruiken we de OpenSSL engine met de PKCS#11 module en selecteren we de privésleutel met het label/ID webserver en het sleuteltype private.

ssl_certificate_key “engine:pkcs11:pkcs11:object=webserver;type=private”;

Notitie

Je moet het certificaat apart genereren en dan uploaden naar de NetHSM. Als het certificaat op schijf en de sleutel in de NetHSM niet overeenkomen zal nginx niet starten.

libnethsm_pkcs11 Configuratie#

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

Om het wachtwoord te beveiligen kun je het opgeven via een omgevingsvariabele (zie Setup) of het opgeven in de nginx configuratie:

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

Voorbeeld#

Als je wilt experimenteren met het gegeven voorbeeld gebruik dan git om de nethsm-pkcs11 repository te clonen en voer de volgende commando’s uit:

Waarschuwing

Het genereren van het script verwijdert de webserver sleutel en vervangt deze.

  1. Configureer een NetHSM, een echte of een container. Zie de getting-started guide voor meer informatie. Naast een beheerder is er ook een operatoraccount nodig.

  2. Download en installeer de nieuwste versie van het stuurprogramma nethsm-pkcs11 dat beschikbaar is vanaf hier.

  3. Installeer de OpenSSL PKCS11 engine zoals beschreven in de OpenSSL Handleiding. U hoeft geen configuratiebestand te maken.

  4. Pas de variabelen HOST, ADMIN_ACCOUNT en ADMIN_ACCOUNT_PWD in container/nginx/generate.sh zodanig aan dat HOST de URL en poort van je NetHSM bevat, ADMIN_ACCOUNT de gebruikersnaam van een administratoraccount bevat en ADMIN_ACCOUNT_PWD het bijbehorende wachtwoord. Configureer verder het absolute pad van de OpenSSL PKCS11 engine in OPENSSL_PKCS11_ENGINE_PATH en het absolute pad van de NetHSM PKCS11 library in NETHSM_PKCS11_LIBRARY_PATH.

  5. Maak een NetHSM PKCS11-configuratiebestand aan op een van de bekende locaties, bijvoorbeeld /etc/nitrokey/p11nethsm.conf. Er moet een operatoraccount zijn geconfigureerd en dezelfde NetHSM-instantie worden gebruikt die eerder in het generatorscript is opgegeven.

  6. Werk de PKCS11-configuratie bij in container/nginx/p11nethsm.conf met de URL van je NetHSMs en geldige operatorgegevens.

  7. Genereer het certificaat en de sleutel.

./container/nginx/generate.sh

  1. Bouw de container.

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

  1. Voer de container uit.

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

De NGINX testpagina zal beschikbaar zijn op https://localhost:9443/. Merk op dat je browser je hopelijk zal waarschuwen dat het certificaat van de website zelfondertekend is.