6.5.4. Integration with Nginx - 6.5.4. Integration with Nginx - 5.3 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.5.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
     $ sudo pkill -TERM nginx || true
     $ sleep 2
     $ sudo pgrep nginx >/dev/null && sudo pkill -KILL 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-cc-opt="-I/path/to/openssl/include" \
         --with-ld-opt="-L/path/to/openssl/lib64 -Wl,-rpath,/path/to/openssl/lib64"
     $ make -j
     $ make install
     

   • Export paths (server + client):

     $ export PATH=/path/to/nginx/sbin:/path/to/openssl/bin:$PATH
     $ export LD_LIBRARY_PATH=/path/to/openssl/lib64:$LD_LIBRARY_PATH
     $ export OPENSSL_CONF=/path/to/openssl/ssl/openssl.cnf
     $ export OPENSSL_MODULES=/path/to/openssl/lib64/ossl-modules
     

     Note

     All four variables are required for the AOCL provider to load correctly at runtime. OPENSSL_MODULES must point to the directory containing the provider libraries. Check whether your OpenSSL install uses lib64/ or lib/.

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

   • Verify Nginx Build:

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

     Expected: configure arguments include the custom OpenSSL paths.

2. 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.

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

   • Test the configuration and start the Nginx service.

   $ sudo env OPENSSL_CONF="$OPENSSL_CONF" OPENSSL_MODULES="$OPENSSL_MODULES" \
       LD_LIBRARY_PATH="$LD_LIBRARY_PATH" \
       /path/to/custom-nginx/sbin/nginx -t -c /path/to/nginx.conf
   $ sudo env OPENSSL_CONF="$OPENSSL_CONF" OPENSSL_MODULES="$OPENSSL_MODULES" \
       LD_LIBRARY_PATH="$LD_LIBRARY_PATH" \
       /path/to/custom-nginx/sbin/nginx -c /path/to/nginx.conf
   

4. Verify Provider Engagement

   • Verify AOCL provider is available (from client, with custom OpenSSL):

     $ openssl list -providers
     

     Expected: AOCL-Crypto <AOCL version> Build <Build id> should be listed.

   • 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>
     

     

   • Verify that the custom OpenSSL libraries and AOCL provider are loaded by nginx:

     $ sudo lsof -p $(pgrep -o nginx) | grep -E "ssl|crypto|alcp"
     

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

     $ sudo perf record -F 99 -p $(pgrep -d ',' nginx) -- sleep 30
     $ sudo perf report