Securing Communications for Platform Agents and System Tools

Redwood supplies a communications library based on OpenSSL, which is the same technology that all major UNIX operating system suppliers deliver for such encryption. This page documents the functionality as present in the most recent release. A section that documents how the settings have evolved over time and which settings are supported in which version can be found at the end of this subject.

Inspecting the Version of OpenSSL

You have an OpenSSL client exposed; note that only vulnerabilities that affect the client are potential vulnerabilities in the agent. To inspect the version of the OpenSSL library used, issue jtool -v. Do not hesitate to contact Redwood support services if you are in doubt.

Install New Agents

When you download the software from "Configuration > Software" or the platform agent wizard it will automatically include the secure library.

Using the library with JTOOL

jtool that make outgoing connections such as jftp are able to encrypt and authenticate their network connections. Most connections simply use HTTPS instead of HTTP and that is all that needs to be changed. Some protocols such as FTP or SMTP require a command line option to activate the use of TLS. For instance jftp has a -protect option. See the jftp and jmail section for more information. If you do not use these extra options the connection will remain in clear text, as it would be without the secure library installed.

Example of using JFTP with encrypted connection:

jftp put -protect -key mykey.pem -binary host user password filein fileout

Some secure connections may require additional configuration. For instance, you may need to connect to an old FTP server that does not support newer TLS modes or modern ciphers. You may want to ensure that it is not only an encrypted connection but it is authenticated by a particular root CA, or the client must be authenticated by the server using a particular client certificate.

The table below documents the TLS arguments and variables that are available:

Command line option	Environment variable	Usage
-tlsv1_3 or -tls13	JCS_SSL_METHOD=tlsv1_3	Use TLS v1.3 secured connection
-tlsv1_2 or -tls12	JCS_SSL_METHOD=tlsv1_2	Use TLS v1.2 secured connection
-tlsv1_1 or -tls11	JCS_SSL_METHOD=tlsv1_1	Use TLS v1.1 or better secured connection
-tlsv1 or -tls	JCS_SSL_METHOD=tlsv1	Use TLS v1.0 or better secured connection (default)
-sslv3 or -ssl	JCS_SSL_METHOD=sslv3	Use SSL v3 or better secured connection
-cipherlist <text>	JCS_SSL_CIPHERLIST	Set list of available ciphers
-passphrase <text>	JCS_SSL_PASSPHRASE	Set passphrase for private key
-key <file>	JCS_SSL_KEYPATH	Set private key
-cert <file>	JCS_SSL_CERTIFICATE_PATH	Set public certificate
-ca <file,path>	JCS_SSL_TRUSTED_CERTIFICATE_FILE or JCS_SSL_TRUSTED_CERTIFICATE_PATH	Set trusted CA certificates file or path
-[no]verify	JCS_SSL_VERIFY_CERT={server,client,both}	(Do not) verify peer (server and/or client) certificate
-verify-names <namelist>	JCS_SSL_VERIFY_SERVER_NAMES or JCS_SSL_VERIFY_CLIENT_NAMES	Verify peer (server or client) certificate hostname against list

tip

Some tools do not have the command line arguments, such as jregister since it is called by the installer; you use the environment variables for these tools.

Configuring the Platform Agent

There are two major modes that a platform agent can operate in: Server Initiated (on-site environments) or Agent Initiated (cloud environments) mode. If the agent is running in Server Initiated mode it runs a HTTP or HTTPS server and will be contacted by the server when data needs to be transferred. If the agent is running in Agent Initiated mode it will contact the server over HTTP or HTTPS for the principal data communication.

Configuration of the platform agent is done using the installers. These set a number of configuration files that can also be created manually. The configuration files are stored in the net/instance/<instance>, net/hostname/<hostname> or net/global directory, depending on which instances they should apply to.

Agent Initiated mode

A platform agent will make outgoing data connections to the Redwood Server if it is running in AgentInitiated mode. In that case it will have an agent_initiated_url configuration file; if that contains a https scheme the outgoing connection to the server will be encrypted; if it contains a http scheme the outgoing connection to the server will be in clear text.

Even though the major communication is done using outgoing connections, the agent still has a HTTP or HTTPS server available. This is so because the agent might be contacted directly by browsers when the server has the RedirectJobFiles parameter set to true. If you set RedirectJobFiles and want encrypted connections between the browser and the agent you should therefore still install a key and certificate in order for the browser to be able to connect without warnings.

Platform Agent with Anonymous Diffie Hellman cipher

An anonymous Diffie Hellman (ADH) cipher will provide encryption; this is all that is required as all communication between the agent and its connection partners is authenticated using other mechanisms.

Note that many references state that HTTPS connections without certificates are unsafe. This is true if the client is connecting to a server on the internet and the client and server do not have any other means of authenticating who they are. In this case the platform agent definitely knows who the server is, and shares an authentication key with it. It also knows which browsers it will serve up files to, since only legitimate connections will have communicated with the server first, which then passes a token back to the browser that the browser presents to the platform agent.

• To make the platform agent a HTTPS server, add a file secure_connection. Put the single word true in this file.
• Decide on the ADH ciphersuites that you want to enable, and put this in the file cipherlist. The simplest form is to put the word ALL in this file. Use the jftp -tls -cipherlist ALL command to see which ciphers are available.

Platform Agent with RSA or DSA cipher

An RSA or DSA key and certificate combination can also be used. They provide authentication of the client and/or the server to the other party, but only if this is explicitly enabled. If you do not enable authentication, there is no security advantage over Anonymous Diffie Hellman as far as the Redwood Server is concerned. If you use RedirectJobFiles it is recommended to use this configuration method as it will allow the user's browsers to connect to the platform agent server without showing a dialog that the connection is potentially unsafe, which might confuse the user.

• To make the platform agent a HTTPS server, add a file secure_connection. Put the single word true in this file.
• Put a public server certificate in a configuration file named rwscert.pem.
• Put a private server key in a configuration file named private/rwskey.pem (or private\rwskey.pem on Microsoft Windows).
• If the private server key requires a passphrase, put the passphrase in a configuration file named private/passphrase.
• Decide on the ciphersuites that you want to enable, and put this in a configuration file named cipherlist if you want to use a different cipher list than the default.

To use SSL/TLS authentication for the connection between Redwood Server and platform agent configure the server's CheckAgentHostname and/or CheckAgentCertificate process server parameters, as discussed below.

For testing purposes you can use a self-signed SSL certificate. Run the following openssl command (not supplied) to generate these.

cd ${AGENT_INSTALL}/net/instance/default
openssl req -new -x509 -nodes -out rwscert.pem -keyout private/rwskey.pem

A signed SSL certificate can be generated as follows:

• Create a RSA private key (will be Triple-DES encrypted and PEM formatted).

cd ..../net/instance/default
openssl genrsa -des3 -out private/rwskey.pem 1024

• Copy the pass-phrase you entered in the above command to private/passphrase.
• Create a Certificate Signing Request (CSR) with the server RSA private key (output will be PEM formatted). Make sure you enter the FQDN ("Fully Qualified Domain Name") of the server when OpenSSL prompts you for the "CommonName", i.e. when you generate a CSR for an agent which will be later accessed via RemoteHostName agent1.internal.lan, enter "agent1.internal.lan" here.

openssl req -new -key private/rwskey.pem -out request.csr

• You now have to send this Certificate Signing Request (CSR) to a Certifying Authority (CA) to be signed. Once the CSR has been signed, you will have a real Certificate. You can have a CSR signed by a commercial CA, or you can create your own CA to sign it.
• Copy the request.crt file to rwscert.pem in the appropriate directory.
• The request.csr file is no longer needed.

The table below documents the full list of net configuration files and variables that are possible

net configuration file	Usage
cipherlist	List of available ciphers.
private/passphrase	Passphrase for private key.
private/rwskey.pem	Private key.
dhparam.pem	Diffie Hellman parameters for use with DH ciphers.
rwscert.pem	Public certificate.
rwstrusted.pem	Trusted CA certificates file.
certs/*	Trusted CA certificates.
verify_peer_cert	Which connections should be authenticated. Value 'server', 'client' or 'both'. When set to server, clients will verify server certificates, when set to client, servers will verify client certificates, when set to both, both will verify.
verify_client_names	List of allowed client names.
verify_server_names	List of allowed server names.

note

All security data files used by Redwood Server should be in PEM format.

Configuring the Central Redwood Server

Since Redwood Server runs on a Java JVM, it already possesses the required encryption code. When the process server talks to a platform agent that is configured to use TLS it will automatically upgrade to the HTTPS protocol. This provides encryption when it is set up in the agent. The standard scheduler mechanism of shared keys is still used for authentication.

There are three process server parameters that enforce encryption by the server, and allow additional authentication.

Parameter	Use	Default
SecureConnection	If set to true the server will refuse to talk to an agent that is not using an encrypted connection. If set to false it will allow the platform agent to make this decision	false
CheckAgentHostname	Should the JVM check the hostname in the certificate presented by the platform agent? If set to true, the RemoteHostName used to connect to the platform agent must be the same FQDN as that presented in the agent's certificate	false
CheckAgentCertificate	Should the JVM check the certificate presented by the platform agent? If set to true, the JVM truststore must contain the agent's public certificate and the root CA certificate	false

Redirecting the Process File Retrieval

If the Process Server parameter RedirectJobFiles is set, and the user uses the GUI to retrieve a process file, the server will respond with a HTTP 302 redirect, and the browser will then contact the platform agent directly. If the agent is running a HTTPS server this means that the browser sees that it is connecting to an encrypted server.

If the server, in this case the platform agent, does not have a valid server certificate for the hostname that the browser is connecting to, browsers will show a security exception dialog. Users have to explicitly allow the connection in order to view the output.

Thus, if you have a platform agent running in HTTPS mode and set RedirectJobFiles you will generally want to ensure that the platform agent has a correct RSA/DSA key and server certificate that has been granted by a Certification Authority that is allowed by the browsers. If your company has its own CA infrastructure you should ask the security administrators for a HTTPS server certificate. Otherwise, either get a certificate from a CA that is already trusted by the browser(s) or inform the users that they should accept the security exception.

The table below indicates the possible combinations

Agent Parameters	Server Parameters	Server/agent encrypted?	Browser/agent encrypted?
-	-	No	Via server
-	RedirectJobFiles	No	No
secure_connection	-	Yes	Via server
secure_connection	RedirectJobFiles	Yes	Yes
agent_initiated_url with https	-	Yes	Via server
agent_initiated_url with http	-	No	Via server
agent_initiated_url with https	RedirectJobFiles	Yes	No
agent_initiated_url with http	RedirectJobFiles	No	No
secure_connection + agent_initiated_url with https	-	Yes	Via server
secure_connection + agent_initiated_url with http	-	No	Via server
secure_connection + agent_initiated_url with https	RedirectJobFiles	Yes	Yes
secure_connection + agent_initiated_url with http	RedirectJobFiles	No	Yes

note

Where the table says "Browser/agent encrypted via server" no direct connection exists, and encryption is decided by the "Server/agent encrypted" column. Server/agent encryption does not require a key or certificate; ADH will suffice. Browser/agent encryption when the value is yes requires a key and certificate.

License

The library is based on OpenSSL and is licensed according to a dual Apache style license. We reproduce the entire license in the Third-party section.

Example

Enabling Secure Connections on Platform Agents

1. Retrieve a certificate with a private key for the FQDN of the platform agent from a CA, ensure both are PEM ¹ formatted, copy the public certificate to <install_dir>/net/instance/<instance>/rwscert.pem, copy the private key to <install_dir>/net/instance/<instance>/private/rwskey.pem.
2. Set the server root (configuration file server_root ²) for serving files, only files in directories and any below will be served. For example, echo /tmp > "${install_dir}/net/instance/${instance}/server_root".
3. Enable secure connection (configuration file secure_connection ³) by setting its contents to true. For example, echo true > "${install_dir}/net/instance/${instance}/secure_connection".
4. List all ciphers you wish to use (comma-separated, the first cipher suite in the list that the server and client agree on is used, see configuration file cipherlist ⁴). For example, echo ALL > ${install_dir}/net/instance/${instance}/cipherlist to accept all cipher suites OpenSSL supports, in the order defined by OpenSSL.
5. Optionally, create configuration file dhparam.pem ⁵ to specify parameters to use with Diffie Hellman ciphers.
6. Restart the platform agent using the native system, Service manager on Windows, systemd, SMF ... on UNIX.
7. In Redwood Server, navigate to Environment > Process Servers, choose the process server belonging to the agent, expand System Information in the details pane, notice that the encryption algorithm is displayed in EncryptionAlgorithm.

Footnotes

1. Open the file in notepad, if you see -----BEGIN CERTIFICATE----- and/or -----BEGIN PRIVATE KEY-----, you have the correct file. Try openssl rsa -inform DER -outform PEM -in mykey.crt -out rwskey.pem for the key and openssl x509 -inform DER -outform PEM -text -in mykey.crt -out rwscert.pem for the certificate to convert them or ask your CA admin for the correct formats.
2. See server_root configuration file for more information.
3. See secure_connection configuration file for more information.
4. See cipherlist configuration file for more information.
5. See dhparam.pem configuration file for more information.

See Also

• Redwood Note 80286