Nginx¶

È possibile configurare nginx per utilizzare NetHSM tramite il motore OpenSSL che utilizza il modulo PKCS#11 di NetHSM.

Il file del certificato deve essere sul disco, ma la chiave privata può essere utilizzata dal NetHSM.

Un esempio completo è disponibile sotto.

Configurazione di OpenSSL¶

Configurare il motore OpenSSL seguendo la guida alla configurazione di OpenSSL Engine.

I provider non sono ancora supportati da Nginx.

Nota

L’uso del motore OpenSSL libp11 versione 0.4.12 o precedente e di un NetHSM con molte chiavi renderà il caricamento iniziale di Nginx lento (più di un minuto per mille chiavi). Si consiglia di utilizzare la versione 0.4.13 o più recente o di creare il motore da ` <https://github.com/OpenSC/libp11>`__.

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

Il campo ssl_certificate deve puntare a un file di certificato sul disco.

ssl_certificate_key può essere una configurazione OpenSSL. Qui si utilizza il motore OpenSSL con il modulo PKCS#11 e si seleziona la chiave privata con l’etichetta/ID webserver e il tipo di chiave private.

ssl_certificate_key «engine:pkcs11:pkcs11:object=webserver;type=private»;

Nota

È necessario generare il certificato separatamente e poi caricarlo su NetHSM. Se il certificato su disco e la chiave nel NetHSM non corrispondono, nginx non si avvia.

libnethsm_pkcs11 Configurazione¶

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

Per proteggere la password è possibile fornirla tramite una variabile d’ambiente ` <pkcs11-setup.html#passwords>`__) o fornirla nella configurazione di nginx:

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

Esempio¶

Se volete sperimentare l’esempio ` <https://github.com/Nitrokey/nethsm-pkcs11/tree/main/container/nginx>`__ usate git per clonare il repository nethsm-pkcs11 ed eseguite i seguenti comandi:

Avvertimento

L’esecuzione dello script generate cancella la chiave webserver e la sostituisce.

Configurare un NetHSM, sia esso reale o un contenitore. Per ulteriori informazioni, consultare la guida per iniziare. Oltre a un amministratore, è necessario un account operatore.
Scaricare e installare l’ultima versione del driver nethsm-pkcs11 disponibile qui.
Installare il motore OpenSSL PKCS11 come descritto nel Manuale OpenSSL ` <openssl.html>`__. Non è necessario creare un file di configurazione.
Regolare le variabili HOST, ADMIN_ACCOUNT e ADMIN_ACCOUNT_PWD in container/nginx/generate.sh in modo che HOST contenga l’URL e la porta del NetHSM, ADMIN_ACCOUNT contenga il nome utente dell’account amministratore e ADMIN_ACCOUNT_PWD la password corrispondente. Configurare inoltre il percorso assoluto del motore OpenSSL PKCS11 in OPENSSL_PKCS11_ENGINE_PATH e il percorso assoluto della libreria PKCS11 di NetHSM in NETHSM_PKCS11_LIBRARY_PATH.
Creare un file di configurazione NetHSM PKCS11 in una delle posizioni note, ad esempio, /etc/nitrokey/p11nethsm.conf. Deve essere configurato un account operatore e utilizzare la stessa istanza di NetHSM specificata nello script di generazione precedente.
Aggiornare la configurazione PKCS11 in container/nginx/p11nethsm.conf con l’URL di NetHSMs e le credenziali valide dell’operatore.
Generare il certificato e la chiave.

./container/nginx/generate.sh

Costruire il contenitore.

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

Eseguire il contenitore.

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

La pagina di test NGINX sarà disponibile all’indirizzo https://localhost:9443/. Si spera che il browser avverta che il certificato del sito web è autofirmato.