Nginx#

Puede configurar nginx para utilizar NetHSM a través del motor OpenSSL que, a su vez, utiliza el módulo PKCS#11 de NetHSM.

El archivo del certificado debe estar en el disco, pero la clave privada puede utilizarse desde el NetHSM.

Encontrará un ejemplo completo en ` <#example>` __.

Configuración de OpenSSL#

Configure el motor OpenSSL siguiendo la guía de configuración del motor OpenSSL ` <openssl.html#engine>` __.

Los proveedores aún no están soportados por Nginx.

Nota

Usar el motor OpenSSL libp11 versión 0.4.12 o anterior y un NetHSM con muchas claves hará que la carga inicial de Nginx sea lenta (más de un minuto para mil claves). Se recomienda usar la versión 0.4.13 o más reciente o construir el motor desde source.

Configuración de 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;
    }
}

El ssl_certificate debe apuntar a un archivo de certificado en el disco.

El ssl_certificate_key puede ser una configuración OpenSSL. Aquí utilizamos el motor OpenSSL con el módulo PKCS#11 y seleccionamos la clave privada con la etiqueta/ID webserver y el tipo de clave private.

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

Nota

Debe generar el certificado por separado y luego subirlo al NetHSM. Si el certificado en el disco y la clave en el NetHSM no coinciden nginx no se iniciará.

libnethsm_pkcs11 Configuración#

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

Para asegurar la contraseña puedes proporcionarla a través de una variable de entorno (ver Setup) o proporcionarla en la configuración de nginx:

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

Ejemplo#

Si quieres experimentar con el ejemplo ` <https://github.com/Nitrokey/nethsm-pkcs11/tree/main/container/nginx>` __ usa git para clonar el repositorio nethsm-pkcs11 y ejecuta los siguientes comandos:

Advertencia

Al ejecutar el script de generación se borra la clave webserver y se sustituye.

  1. Configure un NetHSM, ya sea uno real o un contenedor. Consulte la guía de inicio ` <getting-started.html>` __ para obtener más información. Además de un administrador, vas a necesitar una cuenta de operador.

  2. Descargue e instale la última versión del controlador nethsm-pkcs11 disponible desde aquí.

  3. Instale el motor PKCS11 de OpenSSL como se describe en el Manual de OpenSSL ` <openssl.html>` __. No es necesario crear un archivo de configuración.

  4. Ajuste las variables HOST, ADMIN_ACCOUNT y ADMIN_ACCOUNT_PWD en container/nginx/generate.sh de forma que HOST contenga la URL y el puerto de su NetHSM, ADMIN_ACCOUNT contenga el nombre de usuario de una cuenta de administrador y ADMIN_ACCOUNT_PWD la contraseña correspondiente. Configure además la ruta absoluta del motor PKCS11 de OpenSSL en OPENSSL_PKCS11_ENGINE_PATH y la ruta absoluta de la biblioteca PKCS11 de NetHSM en NETHSM_PKCS11_LIBRARY_PATH.

  5. Cree un archivo de configuración PKCS11 de NetHSM en una de las ubicaciones conocidas de ` <pkcs11-setup.html#configuration>` __, por ejemplo, /etc/nitrokey/p11nethsm.conf. Debe tener configurada una cuenta de operador y utilizar la misma instancia de NetHSM especificada anteriormente en el script generate.

  6. Actualice la configuración PKCS11 en container/nginx/p11nethsm.conf con su URL NetHSMs y credenciales de operador válidas.

  7. Genere el certificado y la clave.

./container/nginx/generate.sh

  1. Construye el contenedor.

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

  1. Ejecuta el contenedor.

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

La página de prueba de NGINX estará disponible en https://localhost:9443/. Tenga en cuenta que su navegador, con suerte, le advertirá de que el certificado de los sitios web es autofirmado.