This chapter provides instructions for customizing PrivX components to suit the needs of your environment.

SSL/TLS Security

This section describes the configuration topics related to SSL/TLS security.

Setting Up a Trusted Server Certificate

Freshly set-up PrivX servers are equipped with self-signed server certificates. For production deployments we recommend replacing the self-signed server certificate with a server certificate issued by a trusted Certificate Authority (CA).

Note

The self-signed server certificate should only be trusted in evaluation deployments. In production environments, we strongly recommend that you acquire and use a trusted server certificate. You can obtain a trusted server certificate by enrolling the certificate-signing request with your corporate CA.

  1. The initial setup has generated a certificate-signing request (CSR), which can be enrolled with a trusted CA for a trusted server certificate. The CSR is located at the following path on the PrivX server:

    /etc/nginx/ssl/nginx.csr

    Enroll this CSR with your CA. In response, the CA should provide you with the following:

    • The server certificate.

    • The CA-certificate chain of the CA itself.

    Note

    Note to certificate-signing authorities: The PrivX CSR contains subjectAltName definitions for DNS and IP addresses. These are critical to PrivX operation and must be preserved in the signed server certificate.

  2. Copy the PEM (Base64) encoded server-certificate file to the ssl_certificate location on the PrivX instance. By default, the location is:

    /etc/nginx/ssl/nginx.crt

    Ensure that the server-certificate file has correct ownership, permissions, and SELinux context:

    # chown root:nginx /etc/nginx/ssl/nginx.crt
    # chmod 0640 /etc/nginx/ssl/nginx.crt
    # restorecon /etc/nginx/ssl/nginx.crt
  3. Update the trust anchor for PrivX microservices. To do this, run the following command (replace /path/to/ca_chain.crt with the path to the CA-certificate-chain file):

    # /opt/privx/scripts/init_nginx.sh update-trust /path/to/ca_chain.crt

    Note

    In single-server deployments, provide the CA chain of the PrivX-server certificate. In HA deployments, provide the CA chain of the load-balancer certificate.

    init_nginx.sh requires PEM-encoded certificate files to have Unix line endings. If the command fails, ensure correct line endings in the CA-certificate-chain file, then rerun the command.

  4. Finally, restart the Nginx and PrivX services to start using the new server certificate:

    # systemctl restart nginx
    # systemctl restart privx

Setting Up a Trusted CA Certificate

PrivX Authorizer issues access certificates using its own CA, which is self-signed by default. For production deployments we recommend replacing the Authorizer CA with one signed by a trusted certificate authority.

Note

The following procedures use <key_id> and <cert_id> to substitute for PrivX-CA-key ID and the Authorizer-certificate ID respectively. Be careful not to mix them up.

To set up PrivX Authorizer with a trusted CA certificate:

  1. Gain root-terminal access to a PrivX server, and display the PrivX-CA-key ID by running:

    # /opt/privx/bin/keyvault-tool -name "PrivX CA Key" list-asymmetric
  2. Generate a Certificate-Signing Request (CSR) for the CA private key (replace <key_id> with the PrivX-CA-key ID):

    # /opt/privx/bin/cert-tool -command create -type authorizer-ca \
    -subject "OU=PrivX Authorizer CA/CN=PrivX CA" \
    -key <key_id> -csr -csrout privx-im-ca.csr

    This creates the CSR to the file privx-im-ca.csr in your current working directory.

  3. Request a trusted CA to sign the CSR with the following constraints:

    • keyUsage must include: Digital Signature, Key Agreement, Certificate Sign, CRL Sign

    • basicConstraints must be: CA:TRUE, pathlen:0

    After the trusted CA provides you with the signed certificate, you may verify its constraints with (replace privx-im-ca.crt  with the path to the signed certificate):

    $ openssl x509 -text -noout -in privx-im-ca.crt 
  4. Replace the Authorizer certificate. First, obtain the ID of the current Authorizer certificate:

    # /opt/privx/bin/cert-tool -command list -type authorizer-ca

    Then delete the current Authorizer certificate (replace <cert_id> with the Authorizer-certificate ID):

    # /opt/privx/bin/cert-tool -command delete -id <cert_id>

    Finally, import the signed certificate (replace <key_id> with the PrivX-CA-key ID, replace privx-im-ca.crt  with the path to the signed certificate):

    # /opt/privx/bin/cert-tool -command import -type authorizer-ca \
    -key <key_id> -in privx-im-ca.crt
  5. On all PrivX servers, restart the PrivX services to apply the changes:

    # systemctl restart privx

    Subsequent certificates issued by PrivX are signed using the new trusted Authorizer CA certificate.

Allowed SSL Protocols and Ciphers for GUI Connections

Connections to the PrivX GUI are secured using TLS. The allowed SSL protocols and SSL ciphers may be adjusted if some browsers cannot establish connections to the PrivX GUI, or if you want to harden the PrivX instance.

The allowed SSL protocols and SSL ciphers are defined in the Nginx configuration file /etc/nginx/conf.d/privx.conf, by the parameters ssl_protocols and ssl_ciphers respectively, similarly to the following:

...
http {
    sendfile on;
    server_tokens off;

    ssl_protocols  TLSv1.2;
    ssl_ciphers 'AESGCM+EECDH:AESGCM+EDH:AES+EECDH: ... ';

    tcp_nodelay on;
...

After any adjustments to Nginx settings, restart the Nginx web server to apply the changes:

# systemctl restart nginx

Rotating Encryption Keys

This section provides instructions for rotating PrivX cryptographic keys, which should be done regularly for improved security. You can rotate the following keys:

  • PrivX CA keys, which issue certificates for certificate-based access.

  • Authentication keys, which issue PrivX-user access and session tokens.

To rotate PrivX CA keys:

  1. Run the rotation script from a PrivX server in the deployment:

    # /opt/privx/scripts/rotate_privx_ca.sh

    The old PrivX CA certificates are deleted and new ones are generated. The script will then restart PrivX.

  2. On hosts with certificate authentication enabled, configure trust for the new PrivX CA. To do this:

To rotate PrivX authentication keys:

  1. Run the rotation command on a PrivX server in the deployment:

    # /opt/privx/bin/keyvault-tool rotate-auth-keys

    This generates new authentication keys.

  2. On all PrivX servers, restart the PrivX services:

    # systemctl restart privx

Note

PrivX-user logins may fail during the time between authentication-key generation and restarting PrivX services.

PrivX Log Settings

By default, regular and audit events are logged to syslog. Audit events use the namespace SSH-PRIVX-AUDIT, and other (info/debug/error) messages use the namespace SSH_PRIVX.

You can adjust the locations to which PrivX writes logs, and the log level of each microservice.

The log locations are configured by settings defined in /opt/privx/etc/shared-config.toml

# Should we send PrivX system events to logs under /var/log/privx
# send_regular_events_to_stdout = false
send_regular_events_to_stdout = false

# Should we send PrivX audit events to syslog
# send_regular_events_to_syslog = true
send_audit_events_to_syslog = true

# Should we send PrivX system events to syslog
# send_regular_events_to_syslog = true
send_regular_events_to_syslog = true

To enable debug output for a microservice:

  1. Edit /opt/privx/scripts/<microservice_name>.sh (replace <microservice_name> with the name of the microservice) and set the SSH_TRACE parameter:

    dir="/opt/privx/bin"
    cmd="SSH_LOG_LEVEL=DEBUG SSH_TRACE=6 /opt/privx/bin/auth"
    user="privx"
  2. By default, the system-logging service rsyslog is configured to show INFO-level messages only, which blocks DEBUG messages. To configure rsyslog to show DEBUG-level messages, find the following line in the rsyslog configuration file, /etc/rsyslog.conf:

    *.info;mail.none;authpriv.none;cron.none    /var/log/messages

    And change it to, for example:

    *.debug;mail.none;authpriv.none;cron.none    /var/log/messages

    Restart rsyslog to apply the changes:

    systemctl restart rsyslog
  3. Restart the privx service to apply any changes to configuration files:

    # systemctl restart privx

PrivX-Extender Configuration

This section describes configuration topics for PrivX Extenders.

Configuring Extender Log Location

By default PrivX Extender logs info and errors to /var/log/privx/privx-extender.log

If you want to enable logging to syslog, specify the rsyslog address and protocol in /opt/privx/etc/extender-config.toml, similar to the following:

syslog_protocol="tcp"
syslog_address="localhost:514"

Restart PrivX Extender to apply the changes. In addition make sure rsyslog is enabled on the extender host:

systemctl restart privx-extender
systemctl restart rsyslog

Proxying Native-Client Connections

To allow proxying native-client connections via PrivX Extenders:

  1. On all your PrivX servers, enable the forwarder_enabled setting in /opt/privx/etc/ssh-proxy.toml

    And restart PrivX services to apply the changes:

    systemctl restart privx

    Caution

    The forwarder relays all the data it receives (not just the native-client connections), and should not be enabled in high-security networks.

  2. Session recording must be disabled on hosts that are to be accessed using proxied native-client connections. For more detailed instructions about toggling session recording, see the section called “Session Recording Setup”.

  3. (Optional) To simplify native-client commands, specify the required connection parameters in the users' client configuration (typically at /etc/ssh/ssh_config or ~/.ssh/config). You can do this using Host blocks that at least specify:

    • The target HostName in extender-name/target-host-address format.

    • The ProxyCommand: privx-nc -x $PRIVX_AGENT_PROXY %h %p

    For example:

    Host bilberry
        HostName example-extender/bilberry.example.com
        ProxyCommand privx-nc -x $PRIVX_AGENT_PROXY %h %p

After setup, you can connect to target hosts as follows:

  1. As the native-client user, start the PrivX agent (if not already started) and use it to log into PrivX.

  2. If you have specified the required parameters in your SSH-client configuration, you can connect simply using the appropriate Host block. For example:

    $ ssh target-user@bilberry
    $ sftp target-user@bilberry
    $ scp source/file/path target-user@bilberry:/target/file/path

    Otherwise, you must additionally provide the ProxyCommand and the name of the PrivX Extender, similar to the following:

    $ ssh -o "ProxyCommand privx-nc -x $PRIVX_AGENT_PROXY %h %p" \
    target-user@example-extender/bilberry.example.com
    $ sftp -o "ProxyCommand privx-nc -x $PRIVX_AGENT_PROXY %h %p" \
    target-user@example-extender/bilberry.example.com
    $ scp -o "ProxyCommand privx-nc -x $PRIVX_AGENT_PROXY example-extender/%h %p"\
    source/file/pathtarget-user@bilberry.example.com:/target/file/path

Custom Load-Balancer Support

If you are using a custom load balancer, ensure that its session-affinity cookie (also known as a sticky-session cookie) is accepted by all your PrivX Extenders:

  1. Add the name of the session-affinity cookie to the known_lb_cookies setting. The setting is located in the following configuration file on the Extender:

    /opt/privx/etc/extender-config.toml
  2. Restart the Extender with:

    # systemctl restart privx-extender

Note

If your PrivX HA deployment also includes PrivX Carriers and PrivX Web Proxies, configure those to accept your session-affinity cookie as well, as per instructions in the section called “Custom Load-Balancer Support”.

PrivX-Carrier and Web Proxy Configuration

This section describes configuration topics for the PrivX Carrier and PrivX Web Proxy.

Allowing HTTP/HTTPS Targets at Unusual Ports

This section describes modifying the allowed target ports for PrivX Web Proxies. These instructions assume you to have some familiarity with Squid configuration.

By default PrivX only allows access to HTTP/HTTPS targets running on certain ports. The allowed ports are available toward the start of your Squid configuration file.

To allow access to targets at nonstandard ports:

  1. Verify and set the allowed target ports on your Web-Proxy machines in /opt/privx/etc/squid.conf

    • For HTTP and HTTPS targets, ensure the target port is included in the Safe_ports list. You can add the target port by adding a similar line immediately after other acl Safe_ports directives (replace <target_port> with the port of your HTTP/HTTPS service):

      acl Safe_ports port <target_port>
    • Additionally for HTTPS targets, ensure the target port is included in the SSL_ports list. You can add the target port by adding a similar line immediately after other acl SSL_ports directives (replace <target_port> with the port of your HTTPS service):

      acl SSL_ports port <target_port>

    For example, to allow access to HTTPS target running on port 9443, you would need to add the port to SSL_ports:

    acl SSL_ports port 443
    acl SSL_ports port 9443
    acl Safe_ports port 80          # http
    acl Safe_ports port 21          # ftp
    acl Safe_ports port 443         # https
    acl Safe_ports port 1025-65535  # unregistered ports
    acl CONNECT method CONNECT

    Port 9443 is already included in Safe_ports by default.

  2. Restart the squid service to apply the changes:

    # systemctl restart squid

Access Restrictions for Web Connections

You can control access to specific websites for specific PrivX roles. With this you can prevent users from accessing arbitrary websites by entering URLs, and via links on web targets.

Role-based access control is configured via Squid on PrivX Web Proxies. These instructions assume you have some familiarity with Squid configuration. This section provides some basic examples about access control. For more comprehensive descriptions about Squid's access-control settings, see their vendor documentation at https://wiki.squid-cache.org/SquidFaq/SquidAcl

To control access for a PrivX role, you will typically need to specify the following in the Squid configuration:

  • Define an acl matching the members of the PrivX role. You can determine PrivX users' roles from their User-Agent header.

  • Define acls for the restricted address(es).

  • Define rules allowing/denying matching members to access restricted address(es).

For example, to only allow privx-admin members to access while denying all other PrivX users access to www.example.com, perform the following on all your PrivX Web Proxies:

  1. Add rules like the following to the Squid configuration at /opt/privx/etc/squid.conf

    # Match all PrivX users belonging to the privx-admin role
    acl is_privx_admin req_header User-Agent Role\=privx-admin
    
    # Define restricted address(es)
    acl restricted_to_certain_privx_roles ssl::server_name www.example.com
    
    # Allow privx-admins to access restricted address(es)
    http_access allow is_privx_admin restricted_to_certain_privx_roles
    
    # Deny others access to restricted address(es)
    http_access deny restricted_to_certain_privx_roles
  2. Restart the squid service to apply the changes:

    # systemctl restart squid

Trusting Sites with Self-Signed Certificates

Configure trust for any web targets that use self-signed certificates, for the following benefits:

  • PrivX users connecting to web targets no longer receive security warnings about insecure server certificates.

  • Support websocket connections from the web target.

Note

We recommend setting up web targets before configuring trust for them. For more information about setting up targets in PrivX, see the section called “Setting up Known Targets”.

To trust a web target:

  1. On your PrivX Web Proxy, add the CA-certificate chain of the web target to the system trust anchors: Save the CA-certificate-chain file under

    /etc/pki/ca-trust/source/anchors/

    Then run:

    # update-ca-trust extract

    Restart the Squid service to apply the changes:

    # systemctl restart squid
  2. (Optional) Perform this step if you need to enable websocket connections from the web target.

    On your PrivX Carrier, add the CA-certificate chain of the web target to your PrivX-Carrier configuration at:

    /opt/privx/etc/carrier-config.toml

    Then restart the Carrier and Docker services to apply the changes:

    # systemctl restart privx-carrier
    # systemctl restart docker

Changing Web Proxy Port Numbers

To change the Web Proxy ports, you need to edit the following:

Note

In the following examples, replace the port numbers 18080 and 18443 with the ports you want to use.

  • On the Carrier host, change the ports in the /opt/privx/etc/carrier-container.toml file:

    [web_container]
    
    # Web proxy ports for HTTP and HTTPS. The port numbers and Carrier host IP \
    address should match the Squid configuration file in /opt/privx/etc/squid.conf
    # Proxy server IP address is configured via PrivX UI.
    http_proxy_port = 18080
    https_proxy_port = 18443

    After editing the file, restart the Carrier service:

    # systemctl restart privx-carrier
  • On the Web Proxy host, edit the Squid configuration file in /opt/privx/etc/squid.conf to match the port numbers you entered previously:

    http_port 18080
    http_port 18443 ssl-bump cert=/opt/privx/squid_cert/squid.crt \
    key=/opt/privx/squid_cert/squid.key generate-host-certificates=on \
    dynamic_cert_mem_cache_size=4MB

    After editing the file, restart the Web Proxy and Squid services:

    # systemctl restart privx-web-proxy squid
  • The Web Proxy host's firewall should allow access to the ports you have specified. Run:

    # firewall-cmd --permanent --add-port=18443/tcp
    # firewall-cmd --permanent --add-port=18080/tcp
    # firewall-cmd --reload

Custom Load-Balancer Support

If you are using a custom load balancer in a PrivX HA deployment, you will need to ensure that its session-affinity cookie (also known as a sticky-session cookie) is accepted by all your PrivX Carriers and PrivX Web-Proxies:

  1. Add the name of the session-affinity cookie to the known_lb_cookies setting. The setting is located in the following configuration files, for Carriers and Web-Proxies respectively:

    /opt/privx/etc/carrier-config.toml
    /opt/privx/etc/web-proxy-config.toml
  2. Restart the Carrier and Web-Proxy services. On your Carriers, run:

    # systemctl restart privx-carrier

    And on your Web-Proxies, run:

    # systemctl restart privx-web-proxy

Note

If your PrivX HA deployment also includes Extenders, configure those to accept your session-affinity cookie as well, according to the instructions at the section called “Custom Load-Balancer Support”.

Setting Custom Instance Names

You can set a custom instance name to better distinguish between multiple PrivX servers. Custom instance names are displayed in the PrivX GUI, and added to the audit events generated from the server.

Custom instance name in the GUI header and audit events

Figure 5.1. Custom instance name in the GUI header and audit events


To set a custom instance name for a PrivX server:

  1. Gain root-terminal access to the PrivX server.

  2. Edit the shared configuration at:

    /opt/privx/etc/shared-config.toml

    In this file, set the custom instance name with privx_instance_name. For example:

    # A custom PrivX instance name to be shown in the header
    privx_instance_name = "PrivX Example Deployment 01"

    Save your changes to the file.

  3. Restart the PrivX services to apply the changes:

    # systemctl restart privx

Resetting the Superuser Password

If you have forgotten the PrivX superuser's password, you can reset it as follows:

  1. On a PrivX server, obtain an encrypted version of your new password (replace example_password with your new password):

    # /opt/privx/bin/keyvault-tool bcrypt <example_password>
  2. Access the PrivX database using psql with write permissions. Change the superuser password (Replace encrypted_password and superuser with the encrypted password and your superuser-account name respectively):

    # UPDATE localuser SET password='encrypted_password' WHERE username='superuser'

    You can now log into PrivX as superuser using the new password.