Skip to content

Deployment orchestration↑

This guide explains how to install the required components to deploy AQtive Guard Protect, configure them to run in your environment, and deploy certificates.

Prerequisites↑

You’ll need the following:

  • A certificate previously enrolled in AQG Protect. Refer to Getting started for details.
  • OpenSSL version 3.0.7 or higher.
  • A version of nginx that supports OpenSSL 3.0.7 or higher.
  • The required scripts, modules, and libraries provided to you in the AQtive Guard Protect release package.

Note

If you didn’t receive the release package, visit our support portal for assistance.

Overview↑

AQtive Guard Protect deployment diagram

This diagram shows the components for deploying AQtive Guard Protect, and the order in which you install them on the desired endpoint. The following sections provide detailed deployment instructions for each component.

  1. Install the AQG Protect Client (1) and AQG Protect CertSync (2) service. This will generate an associated Public Certificate (3) and Protected Private Key Reference (4) for that endpoint.
  2. Install the required third-party PKCS#11 modules, **pkcs11.so** (5) and **libp11.so** (6).
  3. Configure OpenSSL (7) to use these libraries and the Protected Private Key Reference. This allows the Protect Client to communicate with AQtive Guard (8).
  4. Configure your nginx (9) setup to use the updated OpenSSL configuration.

Install AQG Protect dependencies↑

Install the protect-cert-sync service dependencies:

Bash
 sudo apt install opensc python3-asn1crypto

Install the Protect client as a systemd service↑

Before you begin the installation:

  • Locate the certificate in AQtive Guard that you plan to deploy. You’ll need its details to complete the deployment.
  • Create an API token in AQtive Guard.

To install the Protect client as a systemd service, follow these steps:

  1. Copy the cert-sync.sh and uri2pem.py scripts from the release package to /usr/local/bin/.

  2. Make sure the scripts are executable:

    Bash
    sudo chmod 755 /usr/local/bin/cert-sync.sh /usr/local/bin/uri2pem.py

  3. Follow these steps to obtain the workloadId for the certificate to deploy:

    • Select Protect from the main menu.
    • In the Certificates tab, locate the certificate for which you need deployment information.
    • Select Details at the end of the row and copy the workloadId.

  4. Set the workloadID value to the WORKLOAD_ID environment variable:

    Bash
    export WORKLOAD_ID=<workload-id-from-protect>

  5. Set the API token you generated to the AQG_API_TOKEN environment variable:

    Bash
    export AQG_API_TOKEN=<your-api-token>

  6. Run the provided installer script from the release package to install the AQG Protect Client and AQG Protect CertSync service:

    Bash
    chmod +x installer.sh && ./installer.sh

Configure OpenSSL to use Protect↑

To configure OpenSSL for AQG Protect, follow these steps:

  1. Copy the pkcs11.so file from the release package to /usr/lib/x86_64-linux-gnu/ossl-modules/pkcs11.so. This file is the OpenSSL pkcs-provider.

    Important

    Make sure to update the permissions of the pkcs11.so file by running chmod 644 /usr/lib/x86_64-linux-gnu/ossl-modules/pkcs11.so so that other processes can load it.

  2. Copy the libp11client.so file from the release package to /etc/protect/libp11client.so. This file is the PKCS#11 Provider library.

    Important

    Make sure to update the permissions of the libp11client.so file by running chmod 644 /etc/protect/libp11client.so so that other processes can load it.

  3. Configure OpenSSL to detect the new provider by editing the /etc/ssl/openssl.cnf file. In the [provider_sect] section, add the following line:

    pkcs11 = pkcs11_sect # Add this line to enable the PKCS#11 provider

    This section of the file should look like:

    [provider_sect]
default = default_sect
pkcs11 = pkcs11_sect

[default_sect]
activate = 1

[pkcs11_sect]
# This is the provider module we build and install
module = /usr/lib/x86_64-linux-gnu/ossl-modules/pkcs11.so

pkcs11-module-path = /etc/protect/libp11client.so

# This allows us to use the pem encoded uri file for private keys
pkcs11-module-encode-provider-uri-to-pem = true

# We don't store operation state in the pkcs11 interface
pkcs11-module-quirks = no-operation-state
pkcs11-module-allow-export = 1
pkcs11-module-cache-sessions = 0
activate = 1

Test the OpenSSL configuration↑

  1. Set the PROTECT_ADDRESS environment variable to enable communication with the protect-client background service by running:

    Bash
    export PROTECT_ADDRESS=unix:///tmp/pc-sock

  2. Confirm that the protect-cert-sync service has generated the protect.cert.pem and protect.key.pem files in /etc/protect/certs/.

  3. Start an example web server using the generated certificate and key.

    Bash
    openssl s_server -key /etc/protect/certs/protect.key.pem -cert /etc/protect/certs/protect.cert.pem -www

  4. In a separate terminal, test the TLS web server connectivity:

    Bash
    curl -k https://localhost:4433

Configure nginx to use Protect↑

Prerequisites↑

  • Verify that the protect-cert-sync service has generated the protect.cert.pem and protect.key.pem files in /etc/protect/certs/.
  • Make sure that nginx is installed on the system. If not, install it with:
    Bash
    sudo apt install nginx

Configuration↑

To configure nginx to use Protect, follow these steps:

  1. Set Up TLS offloading by editing the /etc/nginx/nginx.conf file. Insert env PROTECT_ADDRESS; at the beginning of the file, and add the ssl_certificate and ssl_certificate_key attributes within the http block.

    Your nginx.conf file should resemble the following structure:

    Nginx Configuration File
    user www-data;
worker_processes auto;
pid /run/nginx.pid;
include /etc/nginx/modules-enabled/*.conf;

env PROTECT_ADDRESS;

events {
    worker_connections 768;
    # multi_accept on;
}

http {

    #...
    #...

    # SSL configuration
    ssl_certificate "/etc/ssl/nginx/protect.cert.pem";     
    ssl_certificate_key "/etc/ssl/nginx/protect.key.pem";

    #...
    #...

}

  2. Configure nginx to listen for TLS traffic by editing the /etc/nginx/sites-enabled/default file. Modify the original HTTP (port 80) listeners to enable TLS traffic on port 443:

    Nginx Configuration File
    listen 443 ssl default_server;
listen [::]:443 ssl default_server;

  3. Provide the Protect environment variable to the nginx service by running sudo systemctl edit nginx.service to add a service-specific environment variable configuration. This command typically creates an override drop-in file (for example /etc/systemd/system/nginx.service.d/override.conf), so you don’t need to edit the main service definition directly.

    Bash
    [Service]
Environment="PROTECT_ADDRESS=unix:///tmp/pc-sock"

  4. Reload the systemd daemon to apply the new service configuration:

    Bash
    sudo systemctl daemon-reload

  5. Start the nginx service:

    Bash
    sudo systemctl start nginx

  6. Test the nginx TLS web server connectivity:

    Bash
    curl -k https://localhost:443

Use a preconfigured Docker-based deployment↑

For automated nginx configuration, we offer a preconfigured Docker image. This image includes a watchdog process that monitors and automatically applies changes from Protect to nginx.

To deploy this nginx image with Protect via Docker:

Bash
docker run --mount type=bind,src=/tmp/pc-sock,dst=/tmp/pc-sock -p 4433:4433 -e PROTECT_ADDRESS=unix:///tmp/pc-sock -e SSL_SERVER_NAME=localhost <DOCKER-IMAGE-PATH>

Note

The <DOCKER-IMAGE-PATH> will be provided to you.

Understanding deployed certificate status↑

Once a certificate has been deployed, it’s State will be Active in the Certificates tab in AQG Protect. The Protect setting indicates whether the certificate is enrolled in Store & Track or Fully managed.