> ## Documentation Index
> Fetch the complete documentation index at: https://docs.futurex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure the NGINX server

> Step-by-step configuration of NGINX server with cryptographic assets.

Perform the following tasks to configure the NGINX server:

1. Set Futurex PKCS #11 environment variables.
2. Create a key pair on the CryptoHub by using **pkcs11-tool**.
3. Generate a CSR by using the NGINX private key.
4. Create a self-signed root certificate authority.
5. Sign the NGINX CSR.
6. Combine the NGINX and CA certificates into a single file.
7. Configure NGINX to use the certificate and its associated private key stored in CryptoHub.
8. Confirm NGINX uses the new TLS certificate and private key (stored on the CryptoHub) for HTTPS connections.

## Set environment variables

Perform the following to set Futurex PKCS #11 environment variables:

<Steps>
  <Step>
    In a terminal, run the following commands to set the required **FXPKCS11** environment variables:

    ```shell expandable lines wrap title="Shell" theme={null}
    export FXPKCS11_MODULE=/path/to/libfxpkcs11.so;

    export FXPKCS11_CFG=/path/to/fxpkcs11.cfg;
    ```

    <Note>
      Be sure to modify the file path to match the location where `libfxpkcs11.so` and `fxpkcs11.cfg` files are stored on your system.
    </Note>
  </Step>
</Steps>

## Create a key pair

Perform the following steps to create a key pair on the CryptoHub by using **pkcs11-tool**:

<Steps>
  <Step>
    In a terminal, run the following command to create a new ECC key pair on the CryptoHub:

    ```text expandable lines wrap title="Text" theme={null}
    pkcs11-tool --module $FXPKCS11_MODULE --login --keypairgen --key-type rsa:2048 --label "nginx_rsa_privatekey" --id "123456"
    ```

    The preceding **pkcs11-tool** command prompts for the user PIN. Enter the CryptoHub identity password configured inside the `<CRYPTO-OPR-PASS>` tag in the `fxpkcs11.cfg` file.

    <Check>
      If successful, the command output displays the keys that pkcs11-tool created on the CryptoHub.
    </Check>
  </Step>
</Steps>

## Generate a CSR

Perform the following steps to generate a CSR by using the NGINX private key:

<Steps>
  <Step>
    In a terminal, run the following command to generate a CSR from the private key created on the CryptoHub for NGINX by using **pkcs11-tool**.

    ```text expandable lines wrap title="Text" theme={null}
    openssl req -new -provider pkcs11 -provider-path $FXPKCS11_MODULE -key "pkcs11:token=Futurex;object=nginx_rsa_privatekey;type=private" -out nginx-cert-req.pem
    ```

    <Note>
      The Common Name of the NGINX certificate should match the IP address or hostname of the virtual host it is configured for.
    </Note>
  </Step>
</Steps>

## Create a CA

<Note>
  This step creates and uses a self-signed root certificate authority (CA) for demonstration. In a production environment, you should use a secure certificate authority, such as the KMES Series 3, for all private key generation and certificate signing operations.
</Note>

Perform the following steps to create a self-signed root certificate authority (CA):

<Steps>
  <Step>
    In a terminal, run the following commands to generate a root private key and self-signed certificate.

    ```text expandable lines wrap title="Text" theme={null}
    openssl genrsa -out ssl-ca-privatekey.pem 2048

    openssl req -new -x509 -key ssl-ca-privatekey.pem -out ssl-ca-cert.pem -days 365
    ```
  </Step>
</Steps>

## Sign the CSR

Perform the following steps to sign the NGINX CSR:

<Steps>
  <Step>
    In a terminal, run the following command to issue a signed NGINX certificate by using the self-signed root CA created in the previous step.

    ```text expandable lines wrap title="Text" theme={null}
    openssl x509 -req -in nginx-cert-req.pem -CA ssl-ca-cert.pem -CAkey ssl-ca-privatekey.pem -CAcreateserial -days 365 -out signed-nginx-cert.pem -extensions v3_leaf
    ```

    <Note>
      The Common Name must be the IP address or hostname of the NGINX server.
    </Note>
  </Step>
</Steps>

## Combine the certificates

To combine the NGINX and CA certificates into a single file, run the following commands in a terminal to combine the NGINX and CA certificates into a single `PEM` file:

```text expandable lines wrap title="Text" theme={null}
cat signed-nginx-cert.pem > combined.pem

cat ssl-ca-cert.pem >> combined.pem
```

## Configure NGINX

This section covers how to modify the configuration file for an NGINX virtual host. Configuration of a virtual host is outside the scope of this guide. Refer to this

[**documentation**](https://www.digitalocean.com/community/tutorial_collections/how-to-install-apache) specific to your operating system if you have not configured a virtual host.

Perform the following steps to configure NGINX to use the certificate and its associated private key stored in CryptoHub:

<Steps>
  <Step>
    Before making any changes, stop your NGINX server by using the following commands:

    ```text expandable lines wrap title="Text" theme={null}
    sudo systemctl stop nginx

    sudo service nginx stop
    ```
  </Step>

  <Step>
    The latest version of**Nginx**(as of September 2025) doesn't support using URI to attain keys using OpenSSL Provider architecture in the `.conf` file. Luckily, `pkcs11-provider` by Latchset has a workaround by using a `.pem` file with URI information enclosed to attain the private key that is stored on CryptoHub.
    Visit the following site and download the Python file `uri2pem.py`.

    <Note>
      Important

      Futurex will provide support for all other aspects of the integration; however, this script is not maintained by Futurex, and we cannot guarantee its functionality or offer troubleshooting support related to it.
    </Note>

    uri2pem.py webiste:

    [**https://github.com/latchset/pkcs11-provider/blob/1362378ad3d5f40013bae7562cf7e5d79149925e/tools/uri2pem.py**](https://github.com/latchset/pkcs11-provider/blob/1362378ad3d5f40013bae7562cf7e5d79149925e/tools/uri2pem.py)

    Set up a Python virtual environment and download the necessary libraries for this script to work:

    ```shell expandable lines wrap title="Shell" theme={null}
    sudo apt install -y python3-venv
    sudo mkdir -p ~/projects/uri2pem
    cd ~/projects/uri2pem
    python3 -m venv .venv
    source .venv/bin/activate
    ```

    Afterwards, use the following commands to make sure they both point to `~/projects/uri2pem/.venv/`

    ```shell expandable lines wrap title="Shell" theme={null}
    which python
    which pip
    ```

    Run the following commands to install the needed Python library, and the script with the URI:

    ```shell expandable lines wrap title="Shell" theme={null}
    pip install asn1crypto
    python uri2pem.py "pkcs11:token=Futurex;object=nginx_rsa_privatekey;type=private" > cert_key.pem 
    ```
  </Step>

  <Step>
    In a text editor, open the configuration file inside the `conf.d/` folder in the NGINX directory for the virtual host you want to configure HTTPS for, and modify it as shown in the following example:

    ```text expandable lines wrap title="Text" theme={null}
    server {
        listen 443 ssl http2;
        server_name my-website.com www.my-website.com;

        # SSL Certificate and Key Paths
        ssl_certificate /path/to/combined.pem;
        ssl_certificate_key /path/to/cert-key.pem

        # SSL Protocols and Ciphers
        ssl_protocols TLSv1.2 TLSv1.3;
        ssl_ciphers 'TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384';

        # Other SSL Settings
        ssl_prefer_server_ciphers off;
        ssl_session_cache shared:SSL:50m;
        ssl_session_timeout 1d;
        ssl_session_tickets off;

        # Security Headers
        add_header Strict-Transport-Security "max-age=31536000" always;

        # Logging
        access_log /var/log/nginx/access.log;
        error_log /var/log/nginx/error.log;

        # Document Root
        root /var/www/html;

        # Index Files
        index index.html index.htm;

        location / {
            try_files $uri $uri/ =404;
        }
    }
    ```

    <Note>
      You must update the paths in `sslcertificate`and `sslcertificate_key` to point to the signed NGINX certificate and the NGINX private key PEM file, which was generated earlier with Python, as stored on your system.
    </Note>
  </Step>

  <Step>
    Check if the **NGINX** configuration files for syntax errors and validity with the following command:

    ```shell expandable lines wrap title="Shell" theme={null}
    sudo nginx -t
    ```

    <Check>
      If there are no issues, the output should look something similar to:

      ```none expandable lines wrap title="None" theme={null}
      nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
      nginx: configuration file /etc/nginx/nginx.conf test is successful
      ```
    </Check>

    Restart your NGINX server with the following command:

    ```shell expandable lines wrap title="Shell" theme={null}
    sudo systemctl restart nginx

    sudo service nginx restart
    ```
  </Step>
</Steps>

## Confirm NGINX configuration

You can complete the following steps with the Firefox web browser. There might be some differences in the actions when using a different browser, but the overall process is the same.

Perform the following steps to confirm NGINX uses the new TLS certificate and private key (stored on the CryptoHub) for HTTPS connections:

<Steps>
  <Step>
    Browse to the IP address of the NGINX website that is running over HTTPS.

    <Check>
      You should see a lock icon to the left of the web address.
    </Check>
  </Step>

  <Step>
    View the certificate that the website served to the browser and confirm it is the certificate configured for the NGINX server.
  </Step>
</Steps>