Nginx¶

Du kan konfigurere nginx til at bruge NetHSM via OpenSSL-motoren, som så bruger NetHSM’s PKCS#11-modul.

Certifikatfilen skal være på disken, men den private nøgle kan bruges fra NetHSM.

Et komplet eksempel er tilgængeligt nedenfor.

OpenSSL-konfiguration¶

Opsæt OpenSSL-motoren ved at følge OpenSSL Engine setup guide.

Providers er endnu ikke understøttet af Nginx.

Bemærk

Brug af libp11 OpenSSL-motoren version 0.4.12 eller ældre og en NetHSM med mange nøgler vil gøre den indledende indlæsning af Nginx langsom (mere end et minut for 1.000 nøgler). Det anbefales at bruge version 0.4.13 eller nyere eller at bygge motoren fra source.

Nginx-konfiguration¶

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 skal pege på en certifikatfil på disken.

ssl_certificate_key kan være en OpenSSL-konfiguration. Her bruger vi OpenSSL-motoren med PKCS#11-modulet og vælger den private nøgle med etiketten/ID webserver og nøgletypen private.

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

Bemærk

Du skal generere certifikatet separat og derefter uploade det til NetHSM. Hvis certifikatet på disken og nøglen i NetHSM ikke stemmer overens, vil nginx ikke starte.

libnethsm_pkcs11 Konfiguration¶

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

For at sikre adgangskoden kan du angive den via en -miljøvariabel) eller angive den i nginx-konfigurationen:

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

Eksempel¶

Hvis du vil eksperimentere med det givne eksempel, skal du bruge git til at klone nethsm-pkcs11 repository og køre følgende kommandoer:

Advarsel

Når du kører genereringsscriptet, slettes nøglen webserver, og den erstattes.

Konfigurer en NetHSM, enten en rigtig eller en container. Se getting-started guide for flere oplysninger. Udover en administrator skal du også bruge en operatørkonto.
Download og installer den nyeste version af nethsm-pkcs11-driveren , der er tilgængelig her.
Installer OpenSSL PKCS11-motoren som beskrevet i OpenSSL Manual. Du behøver ikke at oprette en konfigurationsfil.
Juster variablerne HOST, ADMIN_ACCOUNT og ADMIN_ACCOUNT_PWD i container/nginx/generate.sh, så HOST indeholder din NetHSMs URL og port, ADMIN_ACCOUNT indeholder en administratorkontos brugernavn og ADMIN_ACCOUNT_PWD den tilsvarende adgangskode. Konfigurer desuden den absolutte sti til OpenSSL PKCS11-motoren i OPENSSL_PKCS11_ENGINE_PATH og den absolutte sti til NetHSM PKCS11-biblioteket i NETHSM_PKCS11_LIBRARY_PATH.
Opret en NetHSM PKCS11-konfigurationsfil på en af de kendte placeringer, f.eks. /etc/nitrokey/p11nethsm.conf. Den skal have konfigureret en operatørkonto og bruge den samme NetHSM-instans, som er angivet i genereringsscriptet før.
Opdater PKCS11-konfigurationen i container/nginx/p11nethsm.conf med din NetHSMs URL og gyldige operatørlegitimationsoplysninger.
Generer certifikatet og nøglen.

./container/nginx/generate.sh

Byg beholderen.

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

Kør containeren.

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

NGINX-testsiden vil være tilgængelig på https://localhost:9443/. Bemærk, at din browser forhåbentlig vil advare dig om, at hjemmesidens certifikat er selvsigneret.