This article discusses the use of SSL certificates to enable:

1. Encryption of data on the wire using the latest TLS cryptographic protocol as of the release of HVR. Current versions support TLS 1.3. Diagrams in this article use the lock icon to indicate encrypted connectivity.

2. Authentication. Diagrams in this article use the icon with the checkbox to indicate certificate-based authentication.

Both scenarios require certificate pairs.

Using certificates when connecting through a proxy is also discussed.

This article does not discuss at-rest encryption. For more information about at-rest encryption refer to the HVR documentation at https://www.hvr-software.com/docs/configuring-hvr/hub-wallet-and-encryption .

Certificate Pairs

HVR uses OpenSSL for encryption.

Older versions of HVR used to install a default key pair hvr.priv_key/hvr.pub_cert in HVR_HOME/lib/cert. This key pair was provided for demonstration purposes only. Do not use this key pair for your production systems because anyone who has ever downloaded HVR may have access to it.

Utility hvrsslgen can be used to generate valid certificate key pairs. These are self-signed certificates, valid for 20 years, and always unique.

The following example generates a key pair oracle_source.priv_key/oracle_source.pub_cert that will be used in the examples in this article:

[oracle@oel7-ora12 cert]$ hvrsslgen -a 2048 oracle_source "Oracle Source location"

hvrsslgen: HVR 5.7.0/5 (linux_glibc2.12-x64-64bit)

hvrsslgen: Generating SSL key pair...

hvrsslgen: Generating SSL key pair... completed.

hvrsslgen: Private key written to 'oracle_source.priv_key'.

hvrsslgen: Public Certificate written to 'oracle_source.pub_cert'.

hvrsslgen: Certificate subject: 'HVR Oracle Source location'

hvrsslgen: Certificate contains 2048 bit RSA Public Key.

hvrsslgen: Certificate valid from Dec 17 23:17:38 2020 GMT

hvrsslgen: Certificate valid until Dec 12 23:17:38 2040 GMT

hvrsslgen: Finished. (elapsed=0.44s)

[oracle@oel7-ora12 cert]$

Refer to the documentation at https://www.hvr-software.com/docs/commands/hvrsslgen for details and options.

For the examples in this article two more certificate pairs are created using an equivalent command: hub.priv_key/hub.pub_cert, and proxy.priv_key/proxy.pub_cert.

You can use key pairs generated outside of HVR as long as they are in the OpenSSL PEM format and not password protected. For HVR to accept a key pair it must have “common name” provided. Any root certificate/certificate chain must be appended to the public certificate in order for the certificate to be accepted. The top level of the chain must be self-signed.

Encrypted Communication

Communication between HVR executables is encrypted both ways when the listener is started using an encryption certificate pair. Such setup also provides protection against a man-in-the-middle attack.

For the encrypted communication to succeed the matching public certificate must be available on the environment that initiates the communication.

HVR Configuration for Network Encryption

In HVR versions 4.x and 5.x the default location for encryption certificates is HVR_HOME/lib/cert. Certificates placed outside of this default location must be referenced using an absolute path. The examples in this article assume certificates are available in the default location.

Depending on your operating system there are different ways to run the HVR listener.

Command hvrremotelistener

Every operating system that supports an HVR agent or hub allows for the listener to be started on the command prompt. Use option –K to reference the certificate key pair. For example (encryption key highlighted):

hvrremotelistener -d -K oracle_source 4343

systemctl Socket

If you configured a socket through systemctl then you must include the reference to the encryption certificate key pair in the service definition. For example (certificate reference highlighted in bold):

[root ~]# cat /etc/systemd/system/hvr@.service

[Unit]

Description=HVR listener service

[Service]

Environment="HVR_HOME=/opt/hvr/hvr_home"

Environment="HVR_CONFIG=/opt/hvr/hvr_config"

User=root

ExecStart=/opt/hvr/hvr_home/bin/hvr -r -K oracle_source

StandardInput=socket

KillMode=process

[Install]

WantedBy=multi-user.target

Linux xinet Daemon

If you configured a service through xinet then you must include the reference to the encryption certificate key pair in the service definition. For example (certificate reference highlighted in bold):

Unix inetd Daemon

If on a Unix system you configured a service through inetd then you must include the reference to the encryption certificate key pair in the call to the hvr executable. For example (certificate reference highlighted in bold):

Windows Service

On Windows you create the remote listener service through the HVR GUI. In the File menu, select HVR Remote Listener. Create a listener on a port that is open on the server. In the Create Windows Service dialog, check Require Certificate Key Pair to enable a listener with encryption enabled.

Connecting to an Encrypted Listener

There are two scenarios for connecting to a listener using encryption.

1. Encryption between the UI and the hub. In this case the public certificate matching the encryption on the listener must be available on the machine running the UI. Transfer the public certificate to the UI machine, or copy the public key’s contents to an equivalent public certificate file on the UI machine.With the certificates copied, use the encryption button at the top part of the dialog when registering a new hub.

   

   The diagram below shows a schematic overview of the implementation.

   

2. Encryption between the hub and the agent. For this scenario the public certificate for the encryption must be on the hub. You must then define an action LocationProperties with argument /SslRemoteCertificate set to the respective public certificate.Make sure to define the correct context for the action – the top part of the dialog – such as the location itself. For example:

The diagram below shows a schematic overview of this implementation.

Certificate-based Authentication

Certificate-based authentication may be used as an alternative to, or on top of username/password authentication.

Certificate-based authentication is available between hub and agent. The UI does not support certificate-based authentication for its connection to the hub.

You must have encryption configured to enable certificate-based authentication. For optimum security use a different certificate key pair for authentication than you use for encryption.

HVR Configuration

To configure certificate-based authentication you must have a certificate key pair on the hub, with the matching public certificate on the agent where the authentication is enforced.

In addition, an access configuration XML file at the agent listener indicates the certificate required for authentication. The XML definition may also limit connectivity down to a domain, an IP range, or even a single IP address or DNS entry.

The following example uses a virtual machine running the Oracle Database on a server oracle-host. Its listener uses the certificate key pair oracle_source generated by hvrsslgen. The matching public certificate is on a hub server hub-server. The hub stores the hub private key/public certificate key pair, with the matching public certificate on the agent.

On the Oracle virtual machine, a file access_conf.xml is created with the following contents.

$ cat access_conf.xml
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE hvraccess SYSTEM "hvraccess.dtd">
<hvraccess>
    <allow>
        <from>
            <host>oracle-host</host>
            <ssl remote_cert="hub"/>
        </from>
    </allow>
</hvraccess>

On the agent server the listener is started using the following options. Note the command below requires both OS user and certificate-based authentication. In a test environment you could consider including the -N option to disable authentication.

hvrremotelistener –d –K oracle_source 4343 access_conf.xml

On the hub, action LocationProperties for this location must now not only include the reference to /SslRemoteCertficate=oracle_source, but also /SslLocalCertificateKeyPair=hub in order for the connection to be established.

The diagram below shows the schematic implementation of this scenario.

Connecting Through a Proxy

The use of a proxy is common between a cloud-based hub and an on-premises agent. A proxy in a DMZ (De-Militarized Zone) may be used to avoid the need to open a firewall port directly to the agent. Instead connectivity goes through the proxy as follows:

hub 🡨🡪 proxy 🡨🡪 agent

This scenario allows for certificate-based authentication on the proxy, and for the agent to authenticate the proxy.

Encryption can be configured separately between hub and proxy, as well as between proxy and agent as needed. The HVR installation includes a file HVR_HOME/lib/hvrproxy_example.xml showcasing some of the options when using a proxy.

The example environment runs:

• Hub: hub-server

• Proxy: proxy-server

• Agent: oracle-host

Encryption between Hub and Proxy

The first proxy example will just enable encryption between hub and proxy, with no encryption between proxy and agent.

hub 🡨 encryption using certificate proxy 🡪 proxy 🡨 no encryption 🡪 agent

This example uses no certificate authentication.

To enable this setup, copy public certificate proxy.pub_cert to the hub server.

On the proxy server, use proxy definition:

[hvr@oel7-oraexpress lib]$ cat proxy_hub_enc.xml 
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE hvraccess SYSTEM "hvraccess.dtd">
<hvraccess>
    <allow>
        <from>
            <host>hub-server</host>
            <ssl />
        </from>
        <to>
            <host>oracle-host</host>
            <port>4343</port>
        </to>
    </allow>
</hvraccess>

Note the proxy definition only allows traffic coming from the hub host with SSL for incoming traffic. Connectivity can only be established to the agent.

Start the proxy running on port 4344:

hvrproxy -d -K proxy 4344 proxy_hub_enc.xml

On the agent, run the remote listener without any encryption certificate. This example requires OS authentication. In a test environment you could consider including the -N option to disable authentication.

hvrremotelistener -d 4343

To establish a connection in this setup, the hub requires an action LocationProperties as follows:

The diagram below shows a schematic overview of this setup.

Encryption between Hub and Proxy with Certificate Authentication

The second proxy example enables encryption between hub and proxy, with certificate authentication enforced for the hub.

hub 🡨 encryption and authentication 🡪 proxy 🡨 no encryption 🡪 agent

On the proxy server we now use a more restrictive proxy definition file:

[hvr@oel7-oraexpress lib]$ cat proxy_hub_enc_cert.xml 
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE hvraccess SYSTEM "hvraccess.dtd">
<hvraccess>
    <allow>
        <from>
            <host>hub-server</host>
            <ssl remote_cert="hub"/>
        </from>
        <to>
            <host>oracle-host</host>
            <port>4343</port>
        </to>
    </allow>
</hvraccess>

Make sure to copy the hub.pub_cert file to the proxy server. Then stop (as needed) and start the proxy:

hvrproxy –k 4344

hvrproxy -d -K proxy 4344 proxy_hub_enc_cert.xml

Still run the remote listener on the agent side without SSL enabled.

hvrremotelistener -d 4343

At this point the following settings are required on the hub.

The diagram below shows a schematic overview of this setup.

On-the-wire Encryption and Certificate Authentication with Proxy

The third proxy example enforces encryption on the wire between hub and proxy as well as between proxy and agent. In addition to this the hub must authenticate with a certificate to the proxy environment.

hub 🡨 encryption and authentication 🡪 proxy 🡨 encryption 🡪 agent

On the proxy server we now use an even more restrictive proxy definition file:

[hvr@oel7-oraexpress lib]$ cat proxy_all_enc_cert.xml 
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE hvraccess SYSTEM "hvraccess.dtd">
<hvraccess>
    <allow>
        <from>
            <host>hub-server</host>
            <ssl remote_cert="hub"/>
        </from>
        <to>
            <host>oracle-host</host>
            <port>4343</port>
            <ssl remote_cert="oracle_source"/>
        </to>
    </allow>
</hvraccess>

Make sure to copy both hub.pub_cert and oracle_source.pub_cert files to the proxy server. Then stop (as needed) and start the proxy:

hvrproxy –k 4344

hvrproxy -d -K proxy 4344 proxy_all_enc_cert.xml

For the agent, optionally configure an access_conf.xml file similar to the following:

[oracle@oel7-ora12 lib]$ cat access_conf.xml 
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE hvraccess SYSTEM "hvraccess.dtd">
<hvraccess>
    <allow>
        <from>
            <host>proxy-server</host>
            <ssl />
        </from>
    </allow>
</hvraccess>

Note incoming traffic must come from the proxy host (proxy-server) and be encrypted. Then stop (as needed) and start the remote listener.

hvrremotelistener –k 4343

hvrremotelistener -d -K oracle_source 4343 access_conf.xml

At this point the LocationProperties are still the same as they were for the second example (see below). However the communication between proxy and agent is now also encrypted.

The diagram below shows a schematic overview of this implementation.

On-the-wire Encryption and Certificate Authentication with Proxy and End Point

The fourth proxy example enforces encryption on the wire between hub and proxy as well as between proxy and agent. In addition to this, the hub must authenticate with a certificate to the proxy environment, and the proxy authenticates with a certificate to the end point. Note the proxy uses the same certificate it uses for encryption on the outgoing connections.

The setup for this example is largely identical to the previous example. The only differences are:

1. Copy proxy.pub_cert to the oracle-host system.

2. Change access_conf.xml on the host as follows:

[oracle@oel7-ora12 lib]$ cat access_conf.xml 
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE hvraccess SYSTEM "hvraccess.dtd">
<hvraccess>
    <allow>
        <from>
            <host>proxy-server</host>
            <ssl remote_cert="proxy"/>
        </from>
    </allow>
</hvraccess>

The diagram below shows a schematic overview of this implementation.