Securing Platform Agents

Redwood supplies a communications library based on OpenSSL, which is the same technology that all major UNIX operating system suppliers deliver for such encryption. The name of the file is secure.<suffix>, where <suffix> differs by platform.

This library, along with jtool, is installed when you install a Platform Agent. You can also download a copy for use on non-Platform Agent computers (or more information, see Installing jtool).

To inspect the version of the OpenSSL library used, navigate to the Platform Agent's bin directory in a command window and run jtool -v.

Note: OpenSSL version 1.1.1 has reached its EOL (End of Life). To use a current version of OpenSSL, make sure you are running RunMyJobs 2023 or later.

Using the Secure Library with jtool

Modes in jtool that make outgoing connections (such as jftp) can encrypt and authenticate their network connections.

Most connections simply use HTTPS instead of HTTP. Some protocols, however, such as FTP and SMTP, require a command-line option to activate the use of TLS. For example, jftp has a -protect option. For more information, see jftp andjmail. If you do not use these extra options, the connection will remain in clear text, as it would be without the secure library installed. The following is an 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 example, you may need to connect to an older FTP server that does not support newer TLS modes or modern ciphers. You may want make sure it is not only an encrypted connection, but it is authenticated by a particular root Certificate Authority, 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 Certificate Authority 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.

Note: Some tools do not have command line arguments. For example, jregister is called by the installer. For such tools, use environment variables.

Configuring the Platform Agent

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

Note: A Platform Agent's installer stores a number of configuration files in the net/instance/<instance>, net/hostname/<hostname>, or net/global directory, depending on which instances they apply to.

Agent Initiated Mode

If a Platform Agent is running in Agent Initiated mode, it makes outgoing data connections to the RunMyJobs server. If the agent_initiated_url configuration file contains an https scheme, the outgoing connection to the server will be encrypted. If not, the outgoing connection to the server will be in clear text.

Even though an Agent Initiated Platform Agent does most of its communication with outgoing connections, it still has its own HTTP or HTTPS server, in case the Platform Agent is contacted directly by a browser because the server has the RedirectJobFiles parameter set to true. If you set RedirectJobFiles to true and you want encrypted connections between the browser and the Platform Agent with no warnings, install a key and certificate.

Platform Agent with Anonymous Diffie Hellman Cipher

An anonymous Diffie Hellman (ADH) cipher provides encryption, which is all that you need, because all communication between the Platform 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 authentication. 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 files to, because only legitimate connections will have communicated with the server first. The server then passes a token back to the browser, which the browser presents to the Platform Agent.

To make the Platform Agent an HTTPS server, add a secure_connection file containing the single word true.

List the ADH ciphersuites that you want to enable in the cipherlist file. The simplest way to do this 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

You can also use an RSA or DSA key and certificate combination. These provide authentication of the client and/or the server to the other party, but only if it is explicitly enabled. If you do not enable authentication, there is no security advantage over Anonymous Diffie Hellman as far as the RunMyJobs server is concerned. If you use RedirectJobFiles, Redwood recommends this method because it allows the user's browsers to connect to the Platform Agent server without showing a warning that the connection is potentially unsafe.

To make the Platform Agent an HTTPS server:

  1. Add a file named secure_connection to the directory <install_dir>/net/instance/<instance>/. Put the single word true in this file.
  2. Put a public server certificate in a configuration file named rwscert.pem and put it in the same directory.
  3. Put a private server key in a configuration file named private/rwskey.pem (or private\rwskey.pem on Windows) and put it in the same directory.
  4. If the private server key requires a passphrase, put the passphrase in a configuration file named private/passphrase and put it in the same directory.
  5. If you want to use a cipher list other than the default, list the ciphersuites you want to enable in a configuration file named cipherlist and put it in the same directory.

To use SSL/TLS authentication for the connection between the RunMyJobs server and a 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 to generate one.

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

You can generate a signed SSL certificate as follows.

  1. Create an RSA private key. This will be Triple-DES encrypted and PEM-encoded.

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

  2. Copy the pass-phrase you entered in the above command to private/passphrase.

  3. Create a Certificate Signing Request (CSR) with the server RSA private key (the output will be PEM-encoded). When OpenSSL prompts you for the "CommonName", enter the FQDN of the server. For example, if you generate a CSR for a Platform Agent that will be later accessed via RemoteHostName agent1.internal.lan, enter agent1.internal.lan here.

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

  4. Send the CSR to a Certificate 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.

  5. 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 possible net configuration files and variables.

net configuration file Usage
cipherlist The list of available ciphers.
private/passphrase The passphrase for the private key.
private/rwskey.pem The private key.
dhparam.pem Diffie Hellman parameters for use with DH ciphers.
rwscert.pem The public certificate.
rwstrusted.pem The trusted CA certificates file.
certs/* The trusted CA certificates.
verify_peer_cert The list of connections that should be authenticated. Each can be set to server, client, or both. If this is set to server, clients will verify server certificates. If it is set to client, servers will verify client certificates. If it is set to both, both will verify.
verify_client_names The list of allowed client names.
verify_server_names The list of allowed server names.

Note: All security data files used by the RunMyJobs server should be in PEM format.

Configuring the RunMyJobs Server

Because the RunMyJobs server runs on a Java JVM, it already has the required encryption code. When a 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 Platform Agent. The standard scheduler mechanism of shared keys is still used for authentication.

The following three Process Server parameters enforce encryption by the server and allow additional authentication.

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

Redirecting Process File Retrieval

If the Process Server parameter RedirectJobFiles is set, and you use 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 Platform 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, the browser will show a security exception dialog. Users must explicitly allow the connection in order to view the output.

Thus, if you have a Platform Agent running in HTTPS mode, and you set RedirectJobFiles, make sure the Platform Agent has the correct RSA/DSA key and server certificate that has been granted by a Certification Authority that is allowed by the browsers. If your organization has its own CA infrastructure, ask a security administrators for an HTTPS server certificate. Otherwise, either get a certificate from a CA that is already trusted by the browser, or inform the users that they should accept the security exception.

The table below indicates the possible combinations of settings.

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 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. For more information, see Third-Party Information Disclosure.

Example

To enable secure connections for an installed Platform Agent, follow this procedure.

  1. Retrieve a certificate with a private key for the FQDN of the Platform Agent from a Certificate Authority.
  2. To verify that these are both PEM-encoded, open them in a text editor. If you see -----BEGIN CERTIFICATE----- and/or -----BEGIN PRIVATE KEY-----, the format is connect. If not, 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.
  3. Copy the public certificate to <install_dir>/net/instance/<instance>/rwscert.pem.
  4. Copy the private key to <install_dir>/net/instance/<instance>/private/rwskey.pem.
  5. Set the server root (configuration file server_root) for serving files. Only files in directories and below will be served. For example: echo /tmp > "${install_dir}/net/instance/${instance}/server_root".
  6. Set the contents of the secure_connection file to true. For example: echo true > "${install_dir}/net/instance/${instance}/secure_connection".
  7. List all ciphers you want to use in comma-separated format. The first cipher suite in the list that the server and client agree on is used. See configuration file cipherlist. For example, to accept all cipher suites OpenSSL supports, in the order defined by OpenSSL: echo ALL > ${install_dir}/net/instance/${instance}/cipherlist.
  8. Optionally, create the file dhparam.pem to specify parameters to use with Diffie Hellman ciphers.
  9. Restart the Platform Agent using the native system. On Windows, use service manager. On UNIX, use systemd or SMF.
  10. Navigate to Environment > Process Servers, select the Process Server belonging to the Platform Agent, and expand System Information in the Detail View. The encryption algorithm is displayed under EncryptionAlgorithm.

See Also