End-to-End SSL Encryption

JADE uses the Microsoft Secure Channel (Schannel) Security Package to provide SSL/TLS capability.

To use SSL, JADE integrates with the Windows Certificate Store to access the X.509 certificates used to establish a secure connection. JADE looks only in the local machine personal certificate store (to be exact, the
CERT_SYSTEM_STORE_LOCAL_MACHINE\ MY store). This enables you to store certificates securely and utilize industry‑standard tools to maintain them.

JADE will not take on the role of maintaining either the certificate store or any certificates.

Currently, JadeSsl (JADE's Schannel SSL/TLS integration) is offered only on the connections listed below. Every TCP/IP connection that JADE makes or allows you to make will eventually be secured by JadeSsl, with the connection of the thin client to the application server (currently secured by OpenSSL) being replaced last. When this occurs, OpenSSL will no longer be distributed with JADE.

Specialized Settings

JadeSsl lets the operating system make the decisions about the specifics of the security to offer; that is, which protocols, cipher suites, and so on. If you require fine‑grained control of these settings, you can control them using the information provided by Microsoft in the following documentation: Transport Layer Security (TLS) registry settings (https://docs.microsoft.com/en-us/windows-server/security/tls/tls-registry-settings).

Configuration

JADE provides Secure Sockets Layer (SSL) encryption between:

To use JADE SSL, put the following in your jade.ini or jadehttp.ini file

[JadeSsl]
ConfigurationStore=[path of the JADE SSL configuration file]

The JADE SSL configuration file is an initialization file‑like language. It does not support two‑level section names as the jade.ini file does. Because almost all JADE instances you control will be able to use the same configuration, the SSL configuration is designed to go in a separate file to which any JADE instance can point. This way, there is less configuration to manage for each JADE instance. The ConfigurationStore parameter can also point to the initialization file in which it is defined, although in this case the restriction on two‑level section names still applies.

The JADE SSL configuration file has the following format. 

[Connections]
Default=[configuration section n]
JadeHttpToClient=[configuration section n+1]
SDS=[configuration section n]
ClientToRap=[configuration section n]

The [Connections] section contains the names of each type of connection that JADE will make. The special Default connection type is used for connections that are not specified in the list. Both sides of the connection will look at the same connection name, but do not have to look in the same physical file on the device.

[configuration section n]
UseEncryption=[true|false]
RequireClientAuthentication=[true|false]
ServerCertificateToSendName=[Any|certificate name]
ClientCertificateToSendName=[Any|None|certificate name]
AcceptableClientCertificateToReceiveNames=[Any|a certificate name,another certificate name]

The name of the connection configuration section can be anything you like but must match one of the values in the [Connections] section for JADE to find it. JADE will then read that configuration for the type of connection it is creating. This provides you with a way to configure your system with the least amount of configuration to maintain.

If the value of the UseEncryption parameter is false (the default value), other parameter values in this section are not used.

If the value of the RequireClientAuthentication parameter is true, the server requires the client to send a certificate to authenticate itself. The default value of this parameter is false.

The terms client and server correspond to roles taken in the connection. The server role is taken by the side that accepts incoming connections. For example, in an SDS connection, the primary takes the server role; in a presentation client connection, the application server takes the server role.

The ServerCertificateToSendName parameter specifies the name of the certificate the server will send to the client to authenticate itself. You must specify this parameter. The default value of Any indicates that JADE will select the first suitable certificate from the certificate store; that is, a trusted server authentication certificate with the name of the device.

If you are not using client authentication, only the server must send a certificate. Therefore, only the computer the server is on must have a certificate.

The ClientCertificateToSendName parameter specifies the name of the certificate the client will send to the server to authenticate itself. This parameter is required only if the server requires it. The Any value indicates that JADE will select the first suitable certificate from the certificate store; that is, a trusted client authentication certificate. The default value of None indicates that JADE will not attempt to send a client certificate. In this case, if the server requires a certificate, the connection will fail.

The AcceptableClientCertificateToReceiveNames parameter is a comma‑separated list of certificate names the server will accept if client authentication is required. If you specify the default value of Any, the server will accept any trusted client authentication certificate. If you want to restrict this further (for example, by service name), the server will look at this list. We therefore introduce the distinction between trusted and acceptable certificates. Certificates can be trusted or acceptable. All acceptable certificates must be trusted, but not all trusted certificates must be acceptable.

Any user who runs JADE requires read access to the private key of the certificate.

The following are configuration examples.

[Connections]
Default=Config1
JadeHttpToClient=Config2
SDS=Config3
ClientToRap=Config4
[Config1]
;This configuration does not use encryption
UseEncryption=false
[Config2]
;This configuration enables encryption and looks for a default certificate 
;to send. The client will not send a certificate unless asked. This is the 
;minimal configuration to enable SSL. If JADE can't find a default 
;certificate, the connection will fail. Use SslConfigurationTool.exe to 
;verify this configuration before starting JADE. This configuration may 
;cease working if you are relying on certificates you don't control, but is 
;good for test clusters where you don't want to specify the name of the 
;computer but do have certificates installed.
UseEncryption=true
[Config3]
;This configuration is the same as [Config2], except that a specific certificate ;name will be sent to the client. This is more stable than the above [Config2]. 
UseEncryption=true
RequireClientAuthentication=false
ServerCertificateToSendName=subdomain.domain.tld
[Config4]
;This configuration requires that the client send a certificate with the names 
;subdomainClientCertificateName or subdomainClientCertificateNameSpecial. 
;This configuration says that the client will only attempt to send certificates ;with the name subdomainClientCertificateName.
UseEncryption=true
RequireClientAuthentication=true
ServerCertificateToSendName=subdomain.domain.tld
ClientCertificateToSendName=subdomainClientCertificateName
AcceptableClientCertificateToReceiveNames=
subdomainClientCertificateName,subdomainClientCertificateNameSpecial
[Config5]
;This configuration is the partner for the [Config4] configuration, but is only ;read by clients. Clients that use this configuration will only send certificates ;with the name subdomainClientCertificateNameSpecial.
UseEncryption=true
ClientCertificateToSendName=subdomainClientCertificateNameSpecial

The following is a jade.ini JADE initialization file configuration example.

[JadeSsl]
ConfigurationStore=[path of the JADE SSL configuration file]

The following is an example of the SSL configuration file.

[Connections]
Default=[configuration section n]
JadeHttpToClient=[configuration section n+1]
SDS=[configuration section n]
ClientToRap=[configuration section n]
[configuration section n]
UseEncryption=[true|false]
RequireClientAuthentication=[true|false]
ServerCertificateToSendName=[Any|certificate name]
ClientCertificateToSendName=[Any|None|certificate name]
AcceptableClientCertificateToReceiveNames=[Any|a certificate name,another certificate name]

SslConfigurationTool.exe

The industry knows that if encryption is hard, people don't use it. One of our goals has therefore been to make configuring the system as simple as possible. To this end, we provide the SslConfigurationTool.exe utility, which reads your JADE initialization file and the SSL configuration store to which it points, and attempts to validate your configuration by setting up a secure connection using the settings it has found. You can instruct the SSL configuration tool to take either the server or client role in a connection (allowing you to test across machines), or both roles simultaneously (for intra‑machine connections or other testing).

The command line syntax is as follows (this application does not support overriding configuration store options on the command line).

SslConfigurationTool Action=[ValidateConfiguration|
                             SelectCertificateFromUI|
                             ListCertificates|
                             TryForDefaultConfiguration]

All errors and warnings (and successes!) are logged to the SslConfigurationTool.log file and is created in the same folder.

When Action=ValidateConfiguration is specified:

The ValidateConfiguration action is the main use case for this tool, and it attempts to set up a secure connection as JADE would. The connection type to set up is defined by the ConnectionName option, and corresponds to the Connections options in the SSL Configuration file. The tool then attempts to set up a secure connection as a server or a client, or as both ends, depending on the value of the ConnectionSide option. The tool uses the ServerPortNumber and ServerHostname values to attempt to set up the connection. You can omit one or both of these options, as the tool has default values of port 27657 and the fully qualified domain name of the computer. To make things easy, the server side of the connection ignores the ServerHostname option and always listens for all incoming TCP/IP connections on the specified port.

When the SelectCertificateFromUI action is specified, the tool attempts to make a secure connection using a certificate that you select from a dialog. The name of the certificate will be logged in a way that you can enter straight into the SSL Configuration options, which is useful because there are sometimes many names on a certificate. You can optionally specify the following command line arguments.

When the ListCertificates action is specified, the tool lists the available certificates and their trust status. Although it is more useful to look at certificates using the Microsoft Management Console, this action logs the names of the certificates.

When the TryForDefaultConfiguration action is specified, the tool tries to establish a secure connection using the "Any" ServerCertificateToSendName policy, and logs the name of the selected certificate. Client authentication is not attempted. You can optionally specify the following command line arguments.

Example

The following command line example tells the tool to test the configuration linked to in the file F:\workspace\end-to-end-ssl\jade-db\samplejade.ini as if it were starting up a web‑enabled application on the same machine as that on which IIS is running, and use port 6547.

SslConfigurationTool.exe JadeIniFile="F:\workspace\end‑to‑end‑ssl\jade‑db\samplejade.ini" Action=ValidateConfiguration ConnectionName=JadeHttpToClient ConnectionSide=BothSides ServerPortNumber=6547

2020.0.01 and higher