ODBC SSL Clients:For ODBC SSL communication, OE SQL requires a mandatory SSL configuration setting on the Server. The configuration setting establishes the correct set of SSL “ciphers” which are used by SSL to encrypt communication data. Without this setting, SSL communication between an ODBC client and OE SQL will fail.
This configuration setting is accomplished by defining an Environment Variable, with the needed ciphers, before the OpenEdge Broker is started, for the process which starts the Broker.
For example, the Environment Variable can be defined in a startup script which is used to start the Broker.
- The value of the Environment Variable must contain the names of the SSL Ciphers which the Server should use with SSL Clients.
- These Ciphers must not use the Diffie-Hellman (DHE) method.
Environment Variables:
- PSC_SQL_SSLSERVER_CIPHERS
This Environment Variable is used only by OE SQL. If both this Environment Variable and the alternative SSL Environment Variable (PSC_SSLSERVER_CIPHERS) are set, then OE SQL will use this SQL specific Environment Variable.
Example: The following will instruct OE SQL to use the set of ciphers defined in the PSC_SQL_SSLSERVER_CIPHERS Environment Variable.
export PSC_SQL_SSLSERVER_CIPHERS=AES128-SHA256:AES256-SHA256:AES128-GCM-SHA256:
ADH-AES128-SHA256:ADH-AES256-SHA256:ADH-AES128-GCM-SHA256
This Environment Variable sets this SSL configuration for all OE products. It may be useful if multiple OE products need to use this SSL configuration.
Example: The following will instruct all OE Servers to use the set of ciphers in the PSC_SSLSERVER_CIPHERS environment variable
export PSC_SSLSERVER_CIPHERS=AES128-SHA256:AES256-SHA256:DHE-RSA-AES128-SHA256:
AES128-GCM-SHA256:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-SHA256:NULL-SHA256:
ADH-AES128-SHA256:ADH-AES256-SHA256:ADH-AES128-GCM-SHA256
JDBC SSL Clients:For JDBC client applications depending on the JDK version, either the application will need to set client connection options (in the client’s database URL) or the OpenEdge SQL Server needs a configuration setting.
For completeness, this description will also mention JDK versions which do not cause problems and therefore need no amendment.
JDK version preceding JDK1.7.0_95This includes JDK1.7.0_45, shipped with OpenEdge 11.6.1.
One of the following Options need to be used. Without one of these Options, SSL communication between a JDBC client and OE SQL will fail.
The usage of options below should be taken as a working example only and can be modified according customer requirement.
Option 1. Use JDBC Client Connection Options in the database URL
a. CryptoProtocolVersion=TLSv1.2
- JDBC applications running with JDK 1.6/1.7 by default use the TLSv1 protocol
- OE SQL Server uses TLSv1.2 protocol by default.
In order to have the same Protocol between Client and Server the client needs instruction to use the TLSv1.2 Protocol in the connection URL.
b. EnableCipherSuites=TLS_RSA_WITH_AES_128_CBC_SHA256
- JDBC applications running with JDK 1.6/1.7 does not use TLSv1.2 ciphers by default
- OE SQL supports only TLSv1.2 ciphers by default.
In order to have the matching Ciphers between Client and Server the cipher suite (TLSv1.2 ciphers) which the Client should enable and use in the TLS handshake needs to be specified in the connection URL.
Example: Specifying the Protocol and Cipher using the OpenEdge sqlexp tool:
sqlexp -driverUrl "jdbc:datadirect:openedge://<hostname>:<port_number>;databaseName=<dbname>;User=<user>;Password=<paswd>;
EncryptionMethod=ssl;CryptoProtocolVersion=TLSv1.2;EnableCipherSuites=TLS_RSA_WITH_AES_128_CBC_SHA256,
TLS_RSA_WITH_AES_256_CBC_SHA256;validateServerCertificate=false
Set the Environment Variable
PSC_SQL_SSLSERVER_CIPHERS to specify the list of Ciphers that OE SQL Server should use, otherwise the defaults will create a cipher mismatch between Client and Server.
- OE SQL Server uses TLSv1.2 ciphers by default
- JDBC clients running JDK 1.6/1.7 use TLSv1 ciphers by default
Environment Variable PSC_SQL_SSLSERVER_CIPHERS can be used to instruct OE SQL Server to use TLSv1 type of Ciphers, so that SSL connection with such clients is successful. The Environment Variable must be set prior to Broker startup. The JDBC connection Option: “
CryptoProtocolVersion” is also mandatory for a JDBC client.
Example: a simple working example, showing Server and Client settings:
[Server]: export PSC_SQL_SSLSERVER_CIPHERS=AES128-SHA
[Client]:
sqlexp -driverUrl "jdbc:datadirect:openedge://<hostname>:<port_number>;databaseName=<dbname>;User=<user>;Password=passwd>;
EncryptionMethod=ssl;CryptoProtocolVersion=TLSv1.2;validateServerCertificate=false
If the OE-SQL Server has to support both ODBC and JDBC clients (which uses JDK 1.6/JDK 1.7) only a single configuration is required. For example, setting PSC_SQL_SSLSERVER_CPHERS as mentioned in above examples will support both ODBC and JDBC clients.
JDK versions where no adjustments needed:
The following two scenarios, there is no need to configure client/Server for successful TLSv1.2 connection establishment.
1. JDBC applications which are already using JDK 1.8 or will be upgraded to use JDK 1.8.
2. JDBC applications which are using JDK1.7.0_95 or later version, and are using the system property “jdk.tls.client.protocols=TLSv1.2”, when starting the JVM, to enable TLSv1.2 by default. For example, passing “-Djdk.tls.client.protocols=TLSv1.2” as part of JVM startup.
To validate the server certificate during the connection process:
Add the following Options to the JDBC connection string:
TrustStore=<file_name_goes_here>
TrustStorePassword=<password_goes_here>
validateServerCertificate=true
