6.5.4. Integration with Nginx - 5.2 English - 57404

Nginx is a web server that can also be used as a reverse proxy, load balancer, mail proxy and HTTP cache.

To integrate the AOCL-Cryptography library with Nginx for both server-side and client-side operations, a custom build of Nginx with a custom OpenSSL is required. The default Nginx package provided by the system typically relies on the system’s OpenSSL library. To ensure that both the server and client can utilize the AOCL-Cryptography provider, the system’s Nginx service should be disabled, and a custom version of Nginx must be built with a compatible OpenSSL version.

Version Requirements:

• OpenSSL: >= 3.1.3 (Recommended: 3.3.0)

• Nginx: >= 1.18.0 (Tested example: 1.22.x / 1.24.x)

• AOCL-Cryptography provider library: libopenssl-compat.so present in your AOCL install/build.

Nginx Configuration

1. Building and Configuring Custom Nginx

   • Stop and disable any system nginx first (server node):

     $ sudo systemctl stop nginx || true
     $ sudo systemctl disable nginx || true
     

   • Build Nginx:

     $ wget https://nginx.org/download/nginx-1.22.1.tar.gz
     $ tar -xvf nginx-1.22.1.tar.gz
     $ cd nginx-1.22.1
     $ ./configure --prefix=/opt/custom-nginx --with-http_ssl_module --with-openssl=/path/to/openssl-3.3.0
     $ make
     $ make install
     

   • Export paths (server + client):

     $ export PATH=/path/to/nginx/sbin:/path/to/openssl/bin:$PATH
     $ export LD_LIBRARY_PATH=/path/to/openssl/lib:$LD_LIBRARY_PATH
     

   • Verify Nginx Build:

     $ nginx -V 2>&1 | grep -i openssl
     

     Expected: configure arguments include --with-openssl=<path/to/openssl-3.3.0>.

2. Configure OpenSSL for AOCL Provider

   • Ensure AOCL-Cryptography is installed & configure the provider as described in AOCL Provider Setup.

   • Set the OPENSSL_CONF environment variable to point to your configuration file before starting Nginx.

     $ export OPENSSL_CONF=/opt/custom-openssl/ssl/openssl.cnf
     

3. Generate Certificate Signing Request (CSR)

   • Generate a CSR and private key using either RSA or ECDSA.

   • A CSR has information of an organization, FQDN of a server, country name, and email address.

   • The Certificate Authority (CA) will use the data from CSR to validate information and issue an SSL/TLS certificate.

   1. RSA (2048-bit) Example:

      $ sudo mkdir -p /path/to/custom-nginx/conf/ssl
      $ openssl req -new -newkey rsa:2048 -nodes -keyout /path/to/custom-nginx/conf/ssl/server_rsa.key -out /path/to/custom-nginx/conf/ssl/server_rsa.csr \
          -subj "/C=US/ST=State/L=City/O=Org/OU=Unit/CN=your.server.name"
      

   2. ECDSA (P-256) Example:

      $ openssl ecparam -name prime256v1 -genkey -noout -out /path/to/custom-nginx/conf/ssl/server_ec.key
      $ openssl req -new -key /path/to/custom-nginx/conf/ssl/server_ec.key -out /path/to/custom-nginx/conf/ssl/server_ec.csr \
          -subj "/C=US/ST=State/L=City/O=Org/OU=Unit/CN=your.server.name"
      

   • Choose the certificate/key pair (RSA or ECDSA) to reference in nginx.conf.

4. Server Configuration (nginx.conf)

   • Point ssl_certificate / ssl_certificate_key to your generated cert/key. Typical minimal TLS server block:

     server {
        listen              443 ssl;
        server_name         <Hostname_or_IP_address>;
        ssl_certificate     /path/to/ssl/server.crt;
        ssl_certificate_key /path/to/ssl/server.key;
        ssl_protocols       TLSv1.2 TLSv1.3;
        ssl_ciphers         ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384;
        location / { root /var/www/html; index index.html; }
     }
     

   • Start the Nginx service and test the configuration.

     $ sudo /path/to/custom-nginx/sbin/nginx
     $ sudo /path/to/custom-nginx/sbin/nginx -t
     $ sudo /path/to/custom-nginx/sbin/nginx -s reload
     $ nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
     $ nginx: configuration file /etc/nginx/nginx.conf test is successful
     

5. Verify Provider Engagement

   • From client: openssl list -providers (ensure AOCL present)

   • sslscan: A command-line tool to verify the SSL/TLS configuration of a Nginx web server. It provides details about supported ciphers, protocols, and signature algorithms.

     $ sslscan --no-failed <nginx_server_name/website_address>
     

     

   • To verify that your custom OpenSSL’s libcrypto is loaded by nginx:

     $ sudo lsof -p $(pidof nginx | cut -d' ' -f1) | grep libcrypto
     

   • perf: Confirm that AOCL-Cryptography functions are being invoked.

     $ sudo perf record -g -p $(pgrep -d ',' nginx)