Nginx¶

Sie können nginx so konfigurieren, dass NetHSM über die OpenSSL-Engine verwendet wird, die dann das PKCS#11-Modul von NetHSM nutzt.

Die Zertifikatsdatei muss sich auf der Festplatte befinden, aber der private Schlüssel kann vom NetHSM aus verwendet werden.

Ein vollständiges Beispiel finden Sie unter ..

OpenSSL-Konfiguration¶

Richten Sie die OpenSSL-Engine ein, indem Sie der Anleitung OpenSSL Engine setup guide <openssl.html#engine> folgen __.

Provider werden von Nginx noch nicht unterstützt.

Bemerkung

Bei Verwendung der libp11 OpenSSL-Engine Version 0.4.12 oder älter und einem NetHSM mit vielen Schlüsseln wird das anfängliche Laden von Nginx langsam (mehr als eine Minute für 1.000 Schlüssel). Es wird empfohlen, Version 0.4.13 oder neuer zu verwenden oder die Engine von source zu bauen.

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

Die ssl_certificate muss auf eine Zertifikatsdatei auf der Festplatte verweisen.

Die ssl_certificate_key kann eine OpenSSL-Konfiguration sein. Hier verwenden wir die OpenSSL-Engine mit dem PKCS#11-Modul und wählen den privaten Schlüssel mit dem Label/ID webserver und dem Schlüsseltyp private.

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

Bemerkung

Sie müssen das Zertifikat separat generieren und es dann auf den NetHSM hochladen. Wenn das Zertifikat auf der Festplatte und der Schlüssel im NetHSM nicht übereinstimmen, kann nginx nicht gestartet werden.

libnethsm_pkcs11 Konfiguration¶

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

To secure the password you can provide it via an environment variable) or provide it in the nginx configuration:

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

Beispiel¶

Wenn Sie mit dem gegebenen Beispiel experimentieren wollen, verwenden Sie git, um das nethsm-pkcs11 Repository zu klonen und führen Sie die folgenden Befehle aus:

Warnung

Die Ausführung des Generierungsskripts löscht den Schlüssel webserver und ersetzt ihn.

Configure a NetHSM, either a real one or a container. See the getting-started guide for more information. Besides an administrator, you are going to need an operator account.
Laden Sie die neueste Version des nethsm-pkcs11-Treibers herunter und installieren Sie sie von hier.
Installieren Sie die OpenSSL PKCS11-Engine wie im OpenSSL Manual <openssl.html> beschrieben. Sie müssen keine Konfigurationsdatei erstellen.
Passen Sie die Variablen HOST, ADMIN_ACCOUNT und ADMIN_ACCOUNT_PWD in container/nginx/generate.sh so an, dass HOST die URL und den Port Ihres NetHSMs, ADMIN_ACCOUNT den Benutzernamen eines Administratorkontos und ADMIN_ACCOUNT_PWD das entsprechende Passwort enthält. Konfigurieren Sie außerdem den absoluten Pfad der OpenSSL PKCS11 Engine in OPENSSL_PKCS11_ENGINE_PATH und den absoluten Pfad der NetHSM PKCS11 Bibliothek in NETHSM_PKCS11_LIBRARY_PATH.
Create a NetHSM PKCS11 configuration file in one of the known locations, e.g., /etc/nitrokey/p11nethsm.conf. It must have configured an operator account and use the same NetHSM instance specified in the generate script before.
Aktualisieren Sie die PKCS11-Konfiguration in container/nginx/p11nethsm.conf mit Ihrer NetHSM-URL und gültigen Betreiber-Anmeldedaten.
Erzeugen Sie das Zertifikat und den Schlüssel.
```
./container/nginx/generate.sh
```

Bauen Sie den Container.

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

Starten Sie den Container.

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

The NGINX test page will be available at https://localhost:9443/. Note that your browser, will warn you that the websites certificate is self-signed.