3 Encryption in TimesTen

Features of the ttCreateCerts utility

The ttCreateCerts utility is located in the bin directory of a TimesTen instance. You must set TIMESTEN_HOME before you run ttCreateCerts, which you can accomplish by sourcing the ttenv.sh or ttenv.csh script from the bin directory.

The utility creates three Oracle Wallets: rootWallet, clientWallet, and serverWallet.

This is the syntax for ttCreateCerts:

% ttCreateCerts -h
usage: ttCreateCerts [-dir WALLETDIR] [options...]
       ttCreateCerts [-h | -help]
       ttCreateCerts [-V | -version]
options:
  -f | -force
  -verbose
  -validity DAYS | -valid_from mm/dd/yyyy -valid_until mm/dd/yyyy
  -dryrun
  -sign_alg ALGORITHM (ecdsasha256 ecdsasha384 ecdsasha512)
  -eccurve TYPE  (p256 p384 p521)

Input and option descriptions:

• -dir: Specifies a directory where the wallets are placed, as an absolute path. The specified directory must already exist and cannot already contain wallets produced by ttCreateCerts, unless you use the -force option. The default is timesten_home/conf.

• -h or -help: Shows help (showing the above syntax).

• -V or -version: Displays the TimesTen release number.

• -f or -force: Overwrites any previous wallets in the specified directory.

• -verbose: Shows additional output from execution of the utility.

• -validity: One of two ways to specify the lifetime of the wallets that are created, expressed as a number of days from creation. The default is 3650 days, which can be overridden by setting either -validity or -valid_from and -valid_until.

• -valid_from and -valid_until: The other way to specify the lifetime of the wallets that are created, expressed as a start and an end date in mm/dd/yyyy format.

• -dryrun: Echoes all the commands to be executed by ttCreateCerts to create the certificates as you specified, but without executing them. For options you do not set, you can use this to confirm what the default values are.

• -sign_alg: Specifies the elliptical curve signing algorithm. Supported algorithms are ecdsasha256, ecdsasha384 (default), and ecdsasha512.

• -eccurve: Specifies the size of the elliptical curve. Supported values are p256, p384 (default), and p521.

Using ttCreateCerts

This section provides ttCreateCerts examples that place the wallets in a wallets subdirectory under timesten_home/conf, where timesten_home is the full path to the TimesTen instance home directory.

The following example includes verbose output. (Without the -verbose option, only the last line is shown.)

% ttCreateCerts -verbose -dir timesten_home/conf/wallets
Requested Certificates:
User Certificates:
Subject:        CN=server1,C=US
Trusted Certificates:
Subject:        CN=ecRoot,C=US
Requested Certificates:
User Certificates:
Subject:        CN=client1,C=US
Trusted Certificates:
Subject:        CN=ecRoot,C=US
ttCreateCerts : certificates created in timesten_home/conf/wallets

Here are the results:

% ls timesten_home/conf/wallets
client1.cert  clientWallet  root.cert  rootWallet  server1.cert  serverWallet
% ls timesten_home/conf/wallets/clientWallet
cwallet.sso
% ls timesten_home/conf/wallets/rootWallet
cwallet.sso
% ls timesten_home/conf/wallets/serverWallet
cwallet.sso

See "Certificates for TimesTen Client/Server" and "Certificates for TimesTen replication" for where to copy certificates for TimesTen Client/Server and replication.

The next example is a dry run. No certificates are created (despite the last line). This shows only a snippet of the output:

% ttCreateCerts -dir timesten_home/conf/wallets -dryrun
...
+ /bin/java -Djava.security.egd=file:///dev/./urandom -Xms64m -Xmx512m -cp 
/scratch/classic181430/instances/tt181/install/lib/cryptoj_5_0.jar:
/scratch/classic181430/instances/tt181/install/lib/oraclepki.jar:
/scratch/classic181430/instances/tt181/install/lib/osdt_cert.jar:
/scratch/classic181430/instances/tt181/install/lib/osdt_core.jar 
oracle.security.pki.textui.OraclePKITextUI wallet add -wallet rootWallet -dn 
CN=ecRoot,C=US -sign_alg ecdsasha384 -self_signed -asym_alg ECC -eccurve p384 
-jsafe -validity 3650 -auto_login_only -nologo
...
ttCreateCerts : certificates created in timesten_home/conf/wallets

From this, you can see that the default settings are -sign_alg ecdsasha384, -eccurve p384, and -validity 3650 (days).

Here is another example that sets signing algorithm and size of the elliptical curve:

% ttCreateCerts -dir timesten_home/conf/wallets -sign_alg ecdsasha256 
-eccurve p256
ttCreateCerts : certificates created in timesten_home/conf/wallets

This example specifies that the certificates will expire one year from when they were created:

% ttCreateCerts -dir timesten_home/conf/wallets -validity 365
ttCreateCerts : certificates created in timesten_home/conf/wallets

Or, equivalently:

% ttCreateCerts -dir timesten_home/conf/wallets -valid_from 10/28/2020 
-valid_until 10/28/2021
ttCreateCerts : certificates created in timesten_home/conf/wallets

The next example tries to create wallets in a location where wallets already exist:

% ttCreateCerts -dir timesten_home/conf/wallets
ttCreateCerts: rootWallet is not empty, use -force to overwrite

This example tries again, using the -force option:

% ttCreateCerts -dir timesten_home/conf/wallets -f
ttCreateCerts : certificates created in timesten_home/conf/wallets

Configuration on the server

These server-side attributes for TLS for Client/Server can be set in the server DSN definition in timesten_home/conf/sys.odbc.ini, where timesten_home is the TimesTen instance directory.

• Wallet: Specify the wallet location, as an absolute path, where you placed the certificates that you generated (preferably the same directory path as on the client). There is no default location. If you used ttCreateCerts, this is the full path of the serverWallet directory.

• Encryption: Use one of these 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 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 SSL_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, SSL_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, or both, comma-separated and in order of preference. There is no default setting. 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.

TimesTen also 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.

Table 3-1 shows the results of all possible combinations of encryption settings between client and server, with consideration of the cipher suite settings.

Configuration on the client

These client-side attributes for TLS for Client/Server can be set in the client DSN definition in timesten_home/conf/sys.odbc.ini or a client odbc.ini file, or in a connect string.

• Wallet: Specify the wallet directory, as an absolute path, where you placed the certificates that you generated (preferably the same directory path as on the server). There is no default location. If you used ttCreateCerts, this is the full path of the clientWallet directory.

• Encryption: Use one of these 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 SSL_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256, SSL_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384, or both, comma-separated and in order of preference. There is no default setting. 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.

Switching online to TLS for replication

If you have an existing replication scheme that is not using TLS, use these steps for an online switchover to TLS as replication continues to function:

1. Generate certificates as discussed in "Generation of certificates for TimesTen", then copy them to the desired location on each TimesTen instance as discussed in "Certificates for TimesTen replication".

2. On each instance, set replication_wallet to indicate where the certificates are located.

3. On each instance, set replication_cipher_suite to indicate the cipher suite you are using.

4. On each instance, set replication_ssl_mandatory=0.

   This allows you to update the TimesTen instances to start using TLS one at a time.

5. On each instance (one at a time, in succession), stop and restart the replication agent:

   % ttAdmin -repStop DSN
   % ttAdmin -repStart DSN
   

For example assume there is an active standby pair with databases rep1 on host1 and rep2 on host2, with subscriber rep3 on host3. Complete these steps, as replication continues to function, to use TLS for communications to and from each of the replication agents:

1. Create the certificates on rep1 and place them in the desired wallet directory: /swdir/mywalletloc for example.

2. Copy the wallet directory to the appropriate location (preferably the same location) on rep2 and rep3.

3. Configure TLS on all three instances. For example, in each timesten.conf file:

   replication_wallet=/swdir/mywalletloc
   replication_cipher_suite=SSL_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
   replication_ssl_mandatory=0
   

4. Restart the replication agent on each instance, one at a time.

   On host1:

   % ttAdmin -repStop rep1
   % ttAdmin -repStart repl
   

   On host2:

   % ttAdmin -repStop rep2
   % ttAdmin -repStart rep2
   

   On host3:

   % ttAdmin -repStop rep3
   % ttAdmin -repStart rep3
   

Switching all instances simultaneously to TLS for replication (offline)

If you want TLS to start and be enforced on all instances immediately and simultaneously, you must shut down all replication agents, stopping replication, before setting replication_ssl_mandatory=1 on each instance.

1. Generate certificates as discussed in "Generation of certificates for TimesTen", then copy them to the desired location on each TimesTen instance as discussed in "Certificates for TimesTen replication".

2. On all instances, stop the replication agent:

   % ttAdmin -repStop DSN
   

   Note:

   If you are using Oracle Clusterware, you can accomplish this for all instances with a single command using the ttCWAdmin utility from any instance in the cluster:

   % ttCWAdmin -stop -dsn DSN
   

3. On all instances, set replication_wallet to indicate where the certificates are located.

4. On all instances, set replication_cipher_suite to indicate the cipher suite you are using.

5. On all instances, set replication_ssl_mandatory=1.

   This requires all replication agents to be shut down at once, and all timesten.conf files to be updated while all the replication agents are down.

6. On all instances, restart the replication agent:

   % ttAdmin -repStart DSN
   

   Note:

   If you are using Oracle Clusterware, you can accomplish this for all instances with a single command using the ttCWAdmin utility from any instance in the cluster:

   %  ttCWAdmin -start -dsn DSN