Transport Layer Security for TimesTen Client/Server

When using a client/server connection, you can optionally configure and use TLS for encrypted communication between clients and the server.

TimesTen supports these cipher suites:

SSL_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
SSL_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
SSL_RSA_WITH_AES_128_CBC_SHA256

SSL_RSA_WITH_AES_128_CBC_SHA256 may be needed to decode CA-provided certificates but should not be used for network traffic.

This section discusses TimesTen support for TLS for client/server, covering these topics:

About Using Certificates with Client/Server

For self-signed certificates, TimesTen provides the ttCreateCerts utility for the generation of certificates for TLS. This utility is used by TimesTen during instance creation (in TimesTen Classic) and grid creation (in TimesTen Scaleout).

TimesTen uses Oracle Wallets to store certificates. For general information about these wallets, also referred to as "keystores", refer to How the Keystore for the Storage of TDE Master Encryption Keys Works in Oracle Database Advanced Security Guide.

Note:

The server uses the existing TimesTen user ID and password mechanism to authenticate a user, but TimesTen also supports a form of client authentication where the server validates an identity in the client wallet. This is a way for the server to verify that the connecting client is a legitimate client, but the user still must provide user ID and password credentials.

In TimesTen Classic:

TimesTen can generate certificates and place them on an instance when it is created.
The TimesTen server has its own self-signed root certificate.
The user typically imports, or optionally copies, the client wallet to each client.

In TimesTen Scaleout:

TimesTen generates certificates and places them on the first management instance when a grid is created.
Certificates are distributed to data instances when the grid model is applied.
There is one root certificate authority (CA) per grid, stored in a wallet, and a single private key and certificate used by all instances.
The user imports the client wallet to client systems.

Regarding certificates generated by TimesTen:

Certificates produced are self-signed and stored in an Oracle Wallet.
The root CA has a default expiration time. It is the user’s responsibility to track this. When the root CA expires, all server certificates must be regenerated. When the root CA is regenerated, all clients must re-import it. (The task sections later in this chapter for generating certificates for TimesTen Classic or TimesTen Scaleout also include information about regenerating certificates.)
Clients will store the root certificate (the public key) in a local wallet. There is no need to store the public key on each instance.
Wallets produced are auto-login or single-sign-on (SSO) wallets, without a password. Access to wallets is controlled by file system permissions.
The wallets are platform-independent.
Because the certificates are self-signed, they cannot be revoked. But certificates can be regenerated as needed.

Most discussion in this chapter is for use of self-signed certificates produced through ttCreateCerts (either by TimesTen or directly by the user), but TimesTen also supports the use of certificates signed by a third-party CA. See Using CA-Signed Certificates for Client/Server in TimesTen Classic.

The wallet of each server has its own public/private key identity signed by the root certificate. Each client that connects to a server must have a wallet containing the root certificate of that server. (A client may optionally have multiple wallets for connections to multiple database services.)

Configuration for TLS for Client/Server

There is both server-side and the client-side configuration for TLS for client/server.

Server Attributes for TLS

These are the server connection attributes that determine settings for TLS for client/server.

Also see Task 2: Set Server Configuration for TLS in TimesTen Classic and Task 2: Set Server Configuration for TLS in TimesTen Scaleout.

Wallet: Specify the wallet location, as an absolute path, where certificates were placed (preferably the same directory path as on the client). Assuming ttCreateCerts was used, this is the full path of the serverWallet directory.
Encryption (encryption flag): Use one of the following settings. These descriptions assume matching cipher suite settings between the server and client, where applicable.
- accepted: Enable an encrypted session if required or requested by the client; use an unencrypted session otherwise. This is the default.
- rejected: Demand an unencrypted session. (If the server does not support encryption, TimesTen behaves as if this is the setting on the server.) The connection is rejected if the client requires encryption.
- requested: Request an encrypted session if the client allows it (if the client has any setting other than rejected); use an unencrypted session otherwise.
- required: Demand an encrypted session. Reject the connection if the client rejects encryption.
See Table 3-1 later in this section for a summary of the results of each possible combination of settings of this attribute between the server and client, with consideration of the cipher suite settings.
CipherSuites: This lists the cipher suite or suites that can be used, depending also on the client setting. Specify the desired cipher suites, comma-separated and in order of preference. See Transport Layer Security for TimesTen Client/Server for the list of supported cipher suites. For TLS to be used, the server and client settings must include at least one common suite.
SSLClientAuthentication: Specifies whether TLS client authentication is required (setting of 1) or not (setting of 0, the default). With client authentication, the server validates an identity presented by the client, and requires an identity (public/private key) in the client wallet. Note that regardless of the client authentication setting, server authentication is performed, where the client validates the server.

The server and client must have the same SSLClientAuthentication setting.

Note:

As an alternative to the preceding server connection attributes, these equivalent attributes are available in the instance-level TimesTen configuration file, timesten_home/conf/timesten.conf, on the server. Connection attribute settings take precedence.

server_wallet
server_encryption
server_cipher_suites
ssl_client_authentication

If you have more than one database in a TimesTen instance, these settings apply to all, but can be overridden for each database through the server DSN definition.

TimesTen supports TLS session renegotiation, where new session keys are generated during an active TLS session for more robust security. Session renegotiations are performed according to either how much data has been transferred or how much time has passed. If you want to enable this feature, use one these attributes in the server DSN definition:

SSLRenegotiationSize: Specifies a number of megabytes of data transfer in either direction between the client and server, after which session renegotiation is performed. The default setting is 0, meaning do not renegotiate based on megabytes transferred.
SSLRenegotiationPeriod: Specifies a period of time, in minutes, after which session renegotiation is performed. The default setting is 0, meaning do not renegotiate based on a time period.

If both attributes are set to nonzero values, whichever situation occurs first will result in renegotiation.

The following table shows the results of all possible combinations of encryption flag settings between client and server, with consideration of the cipher suite settings.

Table 3-1 Results of Combinations of Server and Client Encryption Settings

Server Encryption Flag Setting	Client Encryption Flag Setting	Result
`accepted`	`accepted`	Connection accepted, encryption off.
`accepted`	`rejected`	Connection accepted, encryption off.
`accepted`	`requested`	Connection accepted. Encryption on if there is overlap between the cipher suite settings, off if there is not.
`accepted`	`required`	Connection accepted with encryption on if there is overlap between cipher suite settings. Connection rejected if there is not.
`rejected`	`accepted`	Connection accepted, encryption off.
`rejected`	`rejected`	Connection accepted, encryption off.
`rejected`	`requested`	Connection accepted, encryption off.
`rejected`	`required`	Connection rejected.
`requested`	`accepted`	Connection accepted. Encryption on if there is overlap between the cipher suite settings, off if there is not.
`requested`	`rejected`	Connection accepted, encryption off.
`requested`	`requested`	Connection accepted. Encryption on if there is overlap between the cipher suite settings, off if there is not.
`requested`	`required`	Connection accepted with encryption on if there is overlap between cipher suite settings. Connection rejected if there is not.
`required`	`accepted`	Connection accepted with encryption on if there is overlap between cipher suite settings. Connection rejected if there is not.
`required`	`rejected`	Connection rejected.
`required`	`requested`	Connection accepted with encryption on if there is overlap between cipher suite settings. Connection rejected if there is not.
`required`	`required`	Connection accepted with encryption on if there is overlap between cipher suite settings. Connection rejected if there is not.

Note:

If automatic client failover is enabled and a failover occurs, encryption attribute settings from the original connection will continue to be used. The failover server must have the same encryption settings as the original server. (See Using Automatic Client Failover in Oracle TimesTen In-Memory Database Operations Guide for information about automatic client failover.)

Client Attributes for TLS

These are the client connection attributes to determine settings for TLS for client/server.

Also see Task 3: Set Client Configuration for TLS in TimesTen Classic and Task 3: Set Client Configuration for TLS in TimesTen Scaleout.

Note:

If an attribute is set in both the client DSN definition and the connect string, the connect string setting takes precedence.

Wallet: Specify the wallet directory, as an absolute path, where certificates were placed (preferably the same directory path as on the server). If ttCreateCerts was used, this is the full path of the clientWallet directory.
Encryption (encryption flag): Use one of the following settings. These descriptions assume matching cipher suite settings between the server and client, where applicable.
- accepted: Enable an encrypted session if required or requested by the server; use an unencrypted session otherwise. This is the default.
- rejected: Demand an unencrypted session. (If the client does not support encryption, TimesTen behaves as if this is the setting on the client.) The connection is rejected if the server requires encryption.
- requested: Request an encrypted session if the server allows it (if the server has any setting other than rejected); use an unencrypted session otherwise.
- required: Demand an encrypted session. The connection is rejected if the server rejects encryption.
See Table 3-1 for a summary of the results of each possible combination of settings of this attribute between the server and client, with consideration of the cipher suite settings.
CipherSuites: This lists the cipher suite or suites that can be used, depending also on the server setting. Specify the desired cipher suites, comma-separated and in order of preference. See Transport Layer Security for TimesTen Client/Server for the list of supported cipher suites. For TLS to be used, the server and client settings must include at least one common suite.
SSLClientAuthentication: Specifies whether TLS client authentication is required (setting of 1) or not (setting of 0, the default). With client authentication, the server validates an identity presented by the client, and requires an identity (public/private key) in the client wallet. Note that regardless of the client authentication setting, server authentication is performed, where the client validates the server.

The server and client must have the same SSLClientAuthentication setting.

Note:

As an alternative to the preceding client connection attributes, these equivalent attributes are available in the instance-level TimesTen configuration file, timesten_home/conf/timesten.conf, on the client. Connection attribute settings take precedence.

client_wallet
client_cipher_suites
server_encryption
ssl_client_authentication

If you have more than one client DSN in a TimesTen instance, these settings apply to all, but can be overridden for each client through the client DSN definition.

Using TLS for Client/Server in TimesTen Classic

These are the steps to use TLS for client/server in TimesTen Classic with certificates generated by TimesTen.

Alternatively, you can use CA-signed certificates from a third party. See Using CA-Signed Certificates for Client/Server in TimesTen Classic.

Task 1: Generate Certificates and Set TLS Attributes with ttInstanceCreate

You can arrange for certificates to be created when you run the ttInstanceCreate utility (from the installation bin directory).

Note:

Certificates generated by ttInstanceCreate can be used for replication as well as for client/server.
You can also use the TimesTen ttCreateCerts utility manually to generate certificates. This is useful, for example, if you need to regenerate certificates for any reason, such as expiration, or if you have multiple databases on a single TimesTen instance and want to use different certificates for each database. See ttCreateCerts in the Oracle TimesTen In-Memory Database Reference .

Set –serverEncryption (the encryption flag) and –serverCipherSuites (the cipher suite or suites to use) on the ttInstanceCreate command line. See Server Attributes for TLS for descriptions of encryption and cipher suites attributes. See Transport Layer Security for TimesTen Client/Server for a list of cipher suites you can use in TimesTen.

This command, to create an instance named tt221, will generate certificates in the instance conf directory, timesten_home/conf.

% installation_dir/bin/ttInstanceCreate -name tt221 -location instances_dir -serverEncryption required -serverCipherSuites SSL_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
Creating instance in instances_dir/tt221 ...
INFO: Creating certificates, this may take some time ...
ttCreateCerts : certificates created in instances_dir/tt221/conf
...
Instance created successfully.

This generates wallets with a root certificate, server certificate, and client certificate and adds the following entries to the instance timesten.conf file (the latter two by default):

server_encryption=required
server_cipher_suites=SSL_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
client_wallet=timesten_home/conf/clientWallet
server_wallet=timesten_home/conf/serverWallet

From the timesten_home/conf directory, what follows shows the serverWallet and clientWallet directories that are created when you run ttInstanceCreate. Each contains a wallet, cwallet.sso. (Ignore the .cert files and rootWallet directory.)

% ls
client1.cert  root.cert   server1.cert  sys.odbc.ini       timesten.conf
clientWallet  rootWallet  serverWallet  sys.ttconnect.ini

Note:

If you want to change the -serverEncryption and -serverCipherSuites settings for the instance at a later time, you can do so using the ttInstanceModify utility, which also has those options. You can copy or move the wallet to a different location and specify the new location of the server wallet using the ttInstanceModify -serverWallet option.

After you have generated certificates, you can list information about them using the -certificateList option of the TimesTen ttAdmin utility, but to use ttAdmin you must specify a database on the command line that is defined in the sys.odbc.ini file in the timesten_home/conf directory.

The utility looks in the timesten_home/conf directory unless the wallets were moved elsewhere, as would be indicated by the Wallet connection attribute in sys.odbc.ini or by server_wallet in the instance-level timesten.conf configuration file.

This example is for a database mydb. Start the TimesTen daemon before you run ttAdmin.

% ttDaemonAdmin -start
TimesTen Daemon (PID: 733500, port: 6624) startup OK.
% ttAdmin -certificateList mydb
NAME                                               HOLDER                  EXPIRATION
timesten_home/conf/serverWallet/cwallet.sso        CN=server1,C=US         Fri Jul 30 23:08:02 UTC 2032

Task 2: Set Server Configuration for TLS in TimesTen Classic

You can configure TLS for the server in the following ways.

The encryption flag and cipher suite(s) are specified in the ttInstanceCreate command as shown earlier. Later, there are additional TLS configuration attributes you can set as well. In particular, set the wallet location.
At the instance level, you can add or update TLS attributes in the timesten.conf file in the timesten_home/conf directory, such as through the server_wallet, server_cipher_suites, and server_encryption attributes. (Recall that initial values for server_cipher_suites and server_encryption were set through ttInstanceCreate.) Values in timesten.conf serve as default values for any database on the instance.
At the database level, server attributes for TLS can be set in the server DSN definition in timesten_home/conf/sys.odbc.ini. For a given database, these settings override the instance-level settings in timesten.conf.

This excerpt from a server DSN definition specifies where ttInstanceCreate placed the server wallet directory:

[mydb]
Driver=timesten_home/install/lib/libtten.so
DataStore=databases_dir/mydb
...
Wallet=timesten_home/conf/serverWallet

Alternatively, you can copy or move the wallet directory to a different location and specify that location in the Wallet setting. Make sure that you also update the new wallet directory in timesten.conf file with either using the ttInstanceModify -serverWallet utility or modify the server_wallet attribute in the timesten.conf file.

See Server Attributes for TLS for information about available configuration attributes.

Task 3: Set Client Configuration for TLS in TimesTen Classic

Configure TLS for the client in the client DSN definition. Manually set Encryption (the encryption flag), CipherSuites (the cipher suite(s) to use), and Wallet (pointing to the client wallet directory) in the client DSN definition in sys.odbc.ini on the server.

For example, for a database mydb:

[mydbCS]
TTC_SERVER=mydb_CS
TTC_SERVER_DSN=mydb
Wallet=timesten_home/conf/clientWallet
Encryption=required
CipherSuites=SSL_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

Also be aware of these alternatives:

You can manually set attribute values in an odbc.ini file on the client, instead of exporting and importing settings from the server.

You can set attribute values in the connect string for a particular connection, such as from the ttIsql utility:

Command> connect "Driver=...;DataStore=...;Encryption=required;CipherSuites=SSL_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384";

You can set equivalent attributes at the instance level in the TimesTen configuration file, timesten_home/conf/timesten.conf, on the client. These settings, including server_encryption, client_cipher_suites, and client_wallet, would be used as default values. Any connection attribute settings for a particular connection take precedence.

See Client Attributes for TLS for information about available configuration attributes.

Task 4: Export Certificates and Configuration in TimesTen Classic

The ttAdmin utility has a –clientExportAll option that outputs a ZIP file containing the client wallet, a sys.odbc.ini file that can be used in accessing the database, and other files (such as tnsnames.ora file) as applicable.

Run ttAdmin from the timesten_home/bin directory on the server. On the command line, specify the desired ZIP file path and name and the client DSN. The wallet in the output ZIP file includes the CA public key (to verify server certificates) and a client certificate for mutual authentication.

With the following command line for a database mydb, the ttAdmin utility will create a file exports.zip and place it in the timesten_home/info directory.

% ttAdmin -clientExportAll timesten_home/info/exports.zip mydbCS
Client definitions exported to timesten_home/info/exports.zip

The exports.zip file contains the following sys.odbc.ini file and a directory based on the client DSN name, mydbCSWallet for this example. That directory contains the client wallet, cwallet.sso, that was created by ttInstanceCreate:

[mydbCS]
TTC_SERVER=mydb_CS
TTC_SERVER_DSN=mydb
# Wallet=timesten_home/conf/clientWallet
Encryption=required
CipherSuites=SSL_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
Wallet=mydbCSWallet

Task 5: Import Certificates and Configuration in TimesTen Classic

Run the ttClientImport utility from the client to import the contents of the export ZIP file created by the ttAdmin -clientExportAll command.

Typically, copy the export ZIP file from the server to a desired location on the client, then specify that location on the ttClientImport command line. The ttClientImport utility imports the wallet and sys.odbc.ini file (and anything else) that were exported. The utility places the wallet directory, mydbCSWallet for this example (based on the client DSN name), under a wallets directory under timesten_home/conf.

% ttClientImport path/exports.zip
Client definitions imported.

The sys.odbc.ini file on the client is updated to add the client DSN with its TLS settings. (If there is an existing client DSN with the same name, it is replaced.) The generic wallet path in the exported sys.odbc.ini file is updated according to the known actual wallet path, with the wallets/mydbCSWallet subdirectory path.

[mydbCS]
TTC_SERVER=mydb_CS
TTC_SERVER_DSN=mydb
# Wallet=timesten_home/conf/clientWallet
Encryption=required
CipherSuites=SSL_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
Wallet=timesten_home/conf/wallets/mydbCSWallet
# Wallet=mydbCSWallet

From the timesten_home/conf directory on the client:

% ls
sys.odbc.ini  sys.ttconnect.ini  timesten.conf  wallets
% ls wallets
mydbCSWallet
% ls wallets/mydbCSWallet
cwallet.sso

Once the import is completed, assuming client and server configuration with compatible encryption flag and cipher suite settings, you can connect to the server through TLS. See Checking Operation of TLS for Client/Server.

See ttAdmin and ttClientImport in Oracle TimesTen In-Memory Database Reference for additional information about those utilities.

Using TLS for Client/Server in TimesTen Scaleout

These are the steps to use TLS for client/server in TimesTen Scaleout with certificates generated by TimesTen.

Task 1: Generate Certificates and Set TLS Attributes with ttGridAdmin gridCreate and instanceCreate

Certificates are always generated when you use the ttGridAdmin gridCreate command to define a grid.

Tip:

In TimesTen Scaleout, do not use the ttInstanceCreate –serverEncryption and –serverCipherSuites options when you create the first management instance. In ttInstanceCreate, those options are for TimesTen Classic only.

The gridCreate command supports the -serverEncryption and –serverCipherSuites options for TLS. Settings are used by default for any database and client connectable definitions on the grid. (See Server Attributes for TLS for information about TLS attributes.)

For example:

% ttGridAdmin gridCreate grid1 -k 2 -internalAddress intsys1.example.com -externalAddress extsys1.example.com -membershipConfig membership_dir/membership.conf -host mgthost -serverEncryption required -serverCipherSuites SSL_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
Grid grid1 created

When gridCreate is executed, a wallet is placed on the first management instance in a location according to the gridCreate –walletDir setting, or under timesten_home/info by default.

After you generate certificates, you can use the ttGridAdmin certificateList command to display information about them. The default expiration date is 3650 days from creation.

% ttGridAdmin certificateList
NAME          HOLDER           EXPIRATION
clientWallet  CN=client1,C=US  Sun Sep 12 20:42:40 UTC 2032
rootWallet    CN=ecRoot,C=US   Sun Sep 12 20:42:24 UTC 2032
serverWallet  CN=server1,C=US  Sun Sep 12 20:42:32 UTC 2032

Each time you define a data instance for the grid, you can optionally specify a -walletDir setting to determine where certificates will be placed on that instance. (Otherwise, the location established during grid creation is used, which is generally advisable.) For example:

% ttGridAdmin instanceCreate -host datahost1 -location instances_dir -name instance_1 -daemonport 16010 -csport 16012 -walletDir wallets_dir/wallets1
Instance instance_1 on Host datahost1 created in Model

Certificates are copied to data instances when the grid model is applied, in a wallets subdirectory either under the location specified by the instanceCreate –walletDir option, or under timesten_home/info by default. Following are the contents of the wallets directory on a data instance. (Ignore the rootWallet directory.)

% ls wallets
clientWallet  rootWallet  serverWallet
% ls wallets/clientWallet
cwallet.sso
% ls wallets/serverWallet
cwallet.sso

If you need to regenerate certificates at any time, such as after expiration, you can do so through the ttGridAdmin certificateRegen command, which runs ttCreateCerts, connects to all data instances, and copies the new wallet to each data instance.

% ttGridAdmin certificateRegen
Certificates generated

After certificate regeneration, clients cannot connect until the new wallets have been exported from the server and imported into the client. See Task 5: Import Certificates and Configuration in TimesTen Scaleout.

When you use certificateRegen, you can also set new values for the encryption flag and cipher suites. These would serve as default values for any database or connectable that is subsequently defined.

See Regenerate the Certificates (certificateRegen) in Oracle TimesTen In-Memory Database Reference.

Task 2: Set Server Configuration for TLS in TimesTen Scaleout

When you want to use TLS in a grid, you typically specify the server encryption flag and cipher suite(s) to use when you define the grid with the ttGridAdmin gridCreate command, as shown earlier. These will be default values for any database on the grid. You can also specify a wallet location for each data instance with the ttGridAdmin instanceCreate command. Later, there are additional TLS configuration attributes you can set as well.

For a database in the grid, you can specify encryption settings specific to that database by setting connection attributes in the database definition file, dbname.dbdef, that you specify for the ttGridAdmin dbdefCreate command.

This is a typical .dbdef file, mydb.dbdef, for a database that will be named mydb.

DatabaseCharacterSet=AL32UTF8
PermSize=128
TempSize=128
DataStore=databases_dir/mydb
ConnectionCharacterSet=AL32UTF8

This is where, for this particular database, you can specify alternative settings for the server encryption flag (using the Encryption attribute) or the cipher suites (using the CipherSuites attribute), or specify settings for any additional attributes described in Server Attributes for TLS. For example, to require authentication of the client:

SSLClientAuthentication=1

(If you use SSLClientAuthentication, you must have the same settings for the server and the client.)

Once the grid model is applied, as result of the gridCreate -serverEncryption and -serverCipherSuite settings and the instanceCreate -walletDir setting shown in Task 1: Generate Certificates and Set TLS Attributes with ttGridAdmin gridCreate and instanceCreate, the following settings are included in the sys.odbc.ini file on data instance instance_1 for mydb.

[mydb]
DatabaseCharacterSet=AL32UTF8
PermSize=128
TempSize=128
DataStore=databases_dir/mydb
ConnectionCharacterSet=AL32UTF8
...
CipherSuites=SSL_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
...
Encryption=required
...
Wallet=wallets_dir/wallets1/wallets/serverWallet
...
SSLClientAuthentication=1

You can change settings later, if desired, by using the ttGridAdmin dbdefExport and dbdefModify commands as described in Modify the Connection Attributes in a Database Definition in Oracle TimesTen In-Memory Database Scaleout User's Guide.

Task 3: Set Client Configuration for TLS in TimesTen Scaleout

For a TimesTen Scaleout client, you can set TLS attributes in the .connect configuration file that you specify in the ttGridAdmin connectableCreate command that creates the connectable.

See Client Attributes for TLS for a description of available attributes. For example, to require authentication of the client:

SSLClientAuthentication=1

(If you use SSLClientAuthentication, you must have the same settings for the server and the client.)

Once the connectable is defined and the grid model is applied, as result of the gridCreate -serverEncryption and -serverCipherSuite settings and the instanceCreate -walletDir setting for the data instance, the following settings are included in the sys.odbc.ini file on data instance instance_1 for client/server connections to a database mydb:

[mydbcs]
ConnectionCharacterSet=AL32UTF8
TTC_Timeout=360
...
CipherSuites=SSL_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
Encryption=required
Wallet=wallets_dir/wallets1/wallets/clientWallet
...
SSLClientAuthentication=1

You can change settings later, if desired, by using the ttGridAdmin connectableExport and connectableModify commands as described in Modify the Connection Attributes in a Connectable in Oracle TimesTen In-Memory Database Scaleout User's Guide.

Task 4: Export Certificates and Configuration in TimesTen Scaleout

The ttGridAdmin utility has a gridClientExportAll command that outputs a ZIP file containing a wallet, a sys.odbc.ini file that can be used to access the database, and other files (such as tnsnames.ora) as applicable. The wallet includes the CA public key and a client certificate for mutual authentication.

Run the gridClientExportAll command from the management instance, specifying the desired ZIP file path and name on the command line. The ttGridAdmin utility obtains certificates that were created during grid creation by the gridCreate command. This example places the output ZIP file, clientexport.zip, in the timesten_home/info directory on the management instance:

% ttGridAdmin gridClientExportAll timesten_home/info/clientexport.zip
Definitions exported to timesten_home/info/clientexport.zip

Contents of the ZIP file include:

A directory containing the client wallet
A sys.ocbc.ini file to be used on the client for connecting to the database, including the TLS settings
A JSON file with information about the TimesTen release, the grid, and TLS settings
Other files (such as tnsnames.ora) as applicable

Task 5: Import Certificates and Configuration in TimesTen Scaleout

Run the ttClientImport utility from the client to import the contents of the export ZIP file created by the ttGridAdmin -gridClientExportAll command.

Once you've exported the certificates to a ZIP file, copy the ZIP file to a desired location on each client, then run ttClientImport to import the contents. This includes the wallet and sys.odbc.ini file that were exported. The utility places the wallet in a directory based on the grid name, timesten_home/conf/wallets/gridnameWallet.

% ttClientImport path/clientexport.zip
Client definitions imported.

In our example, the grid name is grid1. The client DSN entry in the sys.odbc.ini file on the client is updated to add the TLS and wallet settings:

[mydbcs]
TTC_SERVER_DSN=MYDB
# External address/port info for datahost1.instance_1
TTC_SERVER1=extsys1.example.com/16012
...
CipherSuites=SSL_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
Encryption=required
# Wallet=wallet_dir/wallets/clientWallet
ConnectionCharacterSet=AL32UTF8
TTC_Timeout=360
Wallet=timesten_home/conf/wallets/grid1Wallet

See Export sys.odbc.ini for Client/Server Connections Outside Grid (gridClientExport) and ttClientImport in Oracle TimesTen In-Memory Database Reference for details about syntax and options for those utilities.

Using CA-Signed Certificates for Client/Server in TimesTen Classic

Most of the discussion about using TLS in this chapter is for use of self-signed certificates produced by the ttCreateCerts utility, but TimesTen also supports using certificates signed by a third-party certificate authority (CA). This section describes the process for that.

Topics:

Overview for Using CA-Signed Certificates

To use certificates signed by a certificate authority with TimesTen, you must create and populate a server wallet and a client wallet.

It is assumed that you have obtained a private key and a certificate request (.csr file), typically using openssl; you have sent the certificate request to a certificate authority (CA); and the CA has returned a signed certificate with signing chain.

Starting with .pem files that contain x509 certificates, concatenate the certificates in order from the certificate provided by the CA to the root. (If your certificates are not in .pem format, use openssl or some other appropriate utility to convert them.) In the discussion in the sections that follow, assume the result is called complete.pem and the private key is in privkey.pem. Then you will package the certificates into a pkcs12 file.

At the end of this process, the server wallet will contain the following:

The entire certificate chain. This consists of the certificate from the CA, the intermediate certificates, and the root certificate.
The private key of the certificate from the CA.

And the client wallet will contain the following:

The certificate chain excluding the CA certificate. This consists of the intermediate certificates and the root certificate.

Create the Server Wallet

To use CA-signed certificates with TimesTen, you must manually import certificates into the server wallet and the client wallet. Complete the following steps for the server wallet.

Starting with .pem files that contain x509 certificates, concatenate the certificates in order from the certificate received from the CA to the root. For example:
```
% cat cert.pem certsigner1.pem certsigner2.pem root.pem > complete.pem
```
Package the certificates into a pkcs12 file, as in the following example. Use any password in the openssl command. It will not be in the Oracle Wallet. In this example, the concatenated certificates are in complete.pem and the private key is in privkey.pem.
```
% openssl pkcs12 -export -in complete.pem -inkey privkey.pem -out server.p12 -password pass:mypwd
```
Using the TimesTen ttCreateCerts utility, create an empty auto_login_only Oracle Wallet. (See ttCreateCerts in the Oracle TimesTen In-Memory Database Reference for information about ttCreateCerts and the -run option.)
```
% ttCreateCerts -run "wallet create -wallet serverWallet -auto_login_only"
```

Put the certificates and private key into the wallet. For example:

% ttCreateCerts -run "wallet import_pkcs12 -wallet serverWallet -auto_login_only -pkcs12file server.p12 -pkcs12pwd mypwd"

Verify the server wallet. This includes confirming that the intermediate and root certificates are “Trusted Certificates” and the new certificate is a “User Certificate”. (A “User Certificate” means that TimesTen has the private key for it.) Output should be of the basic form shown.

% ttCreateCerts -run "wallet display -wallet path/serverWallet"
Requested Certificates:
User Certificates:
Subject:        CN=www.example.com,O=xxxxxxxxxxxxxx,L=xxxxxxxxxxxxxx,ST=xxxxxxxxxxxxxx,C=US
Trusted Certificates:
Subject:        CN=xxxxxxxxxxxxxx SHA-256 Private Root,O=xxxxxxxxxxxxxx,C=US
Subject:        CN=xxxxxxxxxxxxxx SHA-256 Private Intermediate,O=xxxxxxxxxxxxxx,C=US

Create the Client Wallet

To use CA-signed certificates with TimesTen, you must manually import certificates into the server wallet and the client wallet. Complete the following steps for the client wallet.

Create an empty auto_login_only Oracle Wallet for the client wallet. (See ttCreateCerts in the Oracle TimesTen In-Memory Database Reference for information about ttCreateCerts and the -run option.)
```
% ttCreateCerts -run "wallet create -wallet clientWallet -auto_login_only"
```

Add the intermediate signers, as applicable, and then the root certificate, one by one.

% ttCreateCerts -run "wallet add -wallet  clientWallet -auto_login_only -trusted_cert -cert intsig1.pem"
...
% ttCreateCerts -run "wallet add -wallet  clientWallet -auto_login_only -trusted_cert -cert intsigN.pem"
% ttCreateCerts -run "wallet add -wallet  clientWallet -auto_login_only -trusted_cert -cert root.pem"

Verify the client wallet. This includes confirming that the root certificate is a “Trusted Certificate” and that there is no “User Certificate” in the wallet. Output should be of the basic form shown.

% ttCreateCerts -run "wallet display -wallet path/clientWallet"
Requested Certificates:
User Certificates:
Trusted Certificates:
Subject:        CN=xxxxxxxxxxxxxx SHA-256 Private Intermediate,O=xxxxxxxxxxxxxx,C=US
Subject:        CN=xxxxxxxxxxxxxx SHA-256 Private Root,O=xxxxxxxxxxxxxx,C=US

Once you have populated the client and server wallets, assuming client and server configuration with compatible encryption flag and cipher suite settings, you can connect to the server through TLS. See Checking Operation of TLS for Client/Server.

Checking Operation of TLS for Client/Server

If TLS is configured on both the server and the client with sufficiently matching settings of Encryption and CipherSuite, TLS is used as soon as the connection is established.

You can confirm this by calling sqlgetconnectattr tt_tls_session from ttIsqlCS on the client. A return value of 1 indicates TLS is being used.

The following set of examples shows the results of several combinations of encryption settings on the server and client.

Scenario 1: Encryption is requested on the server and on the client with the same cipher suite settings. The connection is successful and TLS is used.

Server DSN definition:

[mydb]
Driver=timesten_home/install/lib/libtten.so
DataStore=/db/databases/mydb
PermSize=512
TempSize=128
LogBufMB=256
LogFileSize=256
LogDir=/db/logs
DatabaseCharacterSet=AL32UTF8
OracleNetServiceName=ttorcl
Wallet=timesten_home/conf/mywallets/serverWallet
Encryption=requested
CipherSuites=SSL_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

Client DSN definition:

[mydbCS]
TTC_SERVER=myserverhost.example.com
TTC_SERVER_DSN=mydb
UID=myuser
PWD=welcome
Wallet=timesten_home/conf/mywallets/clientWallet
Encryption=requested
CipherSuites=SSL_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

Connect, executing ttIsqlCS from the timesten_home/bin directory (output formatted for readability):

% ttIsqlCS mydbCS
 
Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
Type ? or "help" for help, type "exit" to quit ttIsql.
 
connect "DSN=mydbCS";
Connection successful: DSN=mydbCS;TTC_SERVER=myserverhost.example.com;
TTC_SERVER_DSN=mydb;UID=myuser;DATASTORE=/db/databases/mydb;
DATABASECHARACTERSET=AL32UTF8;CONNECTIONCHARACTERSET=US7ASCII;LOGFILESIZE=256;
LOGBUFMB=256;LOGDIR=/db/logs;PERMSIZE=512;TEMPSIZE=128;
ORACLENETSERVICENAME=ttorcl;(SERVER)ENCRYPTION=Requested;
(SERVER)WALLET=file:timesten_home/conf/mywallets/serverWallet;
(client)Encryption=Requested;
(client)Wallet=/timesten_home/conf/mywallets/clientWallet;
(client)CipherSuites=SSL_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384;
(Default setting AutoCommit=1)

Confirm TLS is enabled:

Command> sqlgetconnectattr tt_tls_session;
TT_TLS_SESSION = 1 (SQL_TRUE)

Scenario 2: Encryption is requested on the server and on the client but with mismatched cipher suite settings. The connection is successful but a warning message indicates that TLS is not used. (Except for what is shown here, settings are the same as in Scenario 1.)

From the server DSN definition:

CipherSuites=SSL_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

From the client DSN definition:

CipherSuites=SSL_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

Connect:

% ttIsqlCS mydbCS
 
Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
Type ? or "help" for help, type "exit" to quit ttIsql.
 
connect "DSN=mydbCS";
 
Warning 01000: Unable to create requested TLS session; unencrypted session 
created. Check Wallet and CipherSuites on client and server. SSL error: SSL 
Fatal Alert
 
Connection successful: 
...

Scenario 3: Encryption is accepted on the server and on the client. This is not sufficient to result in TLS usage, as noted in Table 3-1. The connection is successful but TLS is not used. (Except for what is shown here, settings are the same as in Scenario 1.)

From the server DSN definition:

Encryption=accepted

From the client DSN definition:

Encryption=accepted

Connect:

% ttIsqlCS mydbCS
 
Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
Type ? or "help" for help, type "exit" to quit ttIsql.
 
connect "DSN=mydbCS";
Connection successful: 
...
Command> sqlgetconnectattr tt_tls_session;
TT_TLS_SESSION = 0 (SQL_FALSE)

Scenario 4: Encryption is required on the client but rejected on the server. The connection attempt is unsuccessful. (Except for what is shown here, settings are the same as in Scenario 1.)

From the server DSN definition:

Encryption=rejected

From the client DSN definition:

Encryption=required

Attempt to connect:

% ttIsqlCS mydbCS
 
Copyright (c) 1996, 2022, Oracle and/or its affiliates. All rights reserved.
Type ? or "help" for help, type "exit" to quit ttIsql.
 
connect "DSN=mydbCS";
HY000: Connection rejected: inconsistent encryption attributes
The command failed.
Done.