Configure TLS for Client/Server

You can configure TLS for Client/Server to ensure secure network communication between TimesTen clients and servers. See Transport Layer Security for TimesTen Client/Server in the Oracle TimesTen In-Memory Database Security Guide for detailed information.

There are both server-side and client-side configuration requirements for using TLS for Client/Server. These requirements are detailed in these sections:

Configuration Requirements for the Server

These sections discuss the configuration requirements for the server. The sections also include an example of how to configure TLS for the server in your Kubernetes cluster.

Overview of Metadata Files and Kubernetes Facilities

The /ttconfig/csWallet metadata file is required for TLS support for Client/Server. (The /ttconfig directory is located in the containers of your TimesTen databases.) This file must contain the cwallet.sso file (the Oracle wallet) that was generated when you created the TLS certificates. This file is the Oracle wallet required for the server. Recall that this file was located in the /scratch/ttuser/instance_dir/instance1/conf/serverWallet directory. See Create TLS Certificates for Replication and Client/Server for information on creating these certificates. This wallet contains the credentials that are used for configuring TLS encryption between your TimesTen database and your Client/Server applications.

There are also server-side connection attributes that must be set. You can define these attributes in the db.ini metadata file. After the db.ini file is placed in the /ttconfig directory of the TimesTen containers, the Operator copies the contents of the db.ini file to the timesten_home/conf/sys.odbc.ini file located in the TimesTen containers. (Note that timesten_home is the TimesTen instance directory. This instance directory is /tt/home/timesten/instances/instance1 in your TimesTen containers.)

These required server-side attributes are: Wallet, CipherSuites, and Encryption. See Create a ConfigMap for the Server-Side Attributes for information on these attributes. Also see Server Attributes for TLS in the Oracle TimesTen In-Memory Database Security Guide.

In addition to the csWallet and the db.ini metadata files, you may use other supported metadata files. See About Configuration Metadata Details for information on these supported metadata files.

You can include these metadata files in one or more Kubernetes facilities (for example, in a Kubernetes Secret, in a ConfigMap, or in an init container). This ensures the metadata files are populated in the /ttconfig directory of the TimesTen containers. Note that there is no requirement as to how to get the metadata files into this /ttconfig directory. See Populate the /ttconfig Directory.

The following example includes the csWallet metadata file in a Kubernetes Secret. It also creates the db.ini, the adminUser, and the schema.sql metadata files and includes these metadata files in a ConfigMap.

Create a Kubernetes Secret for the csWallet Metadata File

This section creates the cs-tls Kubernetes Secret. The cs-tls Secret will contain the csWallet metadata file.

On your Linux development host:

From the directory of your choice, create an empty subdirectory. This example creates the serverWallet subdirectory. (The serverWallet directory is used in the remainder of this example to denote this directory.)
```
% mkdir -p serverWallet
```
Copy the cwallet.sso file into the serverWallet directory that you just created. Recall that the cwallet.sso file was generated when you used the ttCreateCerts utility to create the TLS certificates. Also recall that this file was located in the /scratch/ttuser/instance_dir/instance1/conf/serverWallet directory. See "Create TLS Certificates for Replication and Client/Server" for information.
```
% cp /scratch/ttuser/instance_dir/instance1/conf/serverWallet/cwallet.sso 
serverWallet/cwallet.sso
```
Create the Kubernetes Secret.
In this example:
- The name of the Secret is cs-tls. Replace cs-tls with a name of your choosing. (cs-tls is represented in bold.)
- The name of the metadata file required for TLS for Client/Server is csWallet (represented in bold).
- The location of the wallet directory is serverWallet (in this example, represented in bold). If you use a different directory, replace serverWallet with the name of your directory.
- The name of the Oracle wallet: cwallet.sso (represented in bold).
Use the kubectl create command to create the Secret:
```
% kubectl create secret generic cs-tls 
--from-file=csWallet=serverWallet/cwallet.sso
secret/cs-tls created
```

You have successfully created and deployed the cs-tls Kubernetes Secret. The csWallet/cwallet.sso file will later be available in the /ttconfig directory of the TimesTen containers. In addition, the file will be available in the /tt/home/timesten/csWallet directory of the TimesTen containers.

Create a ConfigMap for the Server-Side Attributes

This section creates the cs-tls ConfigMap. This ConfigMap contains the db.ini, the adminUser, and the schema.sql metadata files.

On your Linux development host:

From the directory of your choice, create an empty subdirectory for the metadata files. This example creates the cm_csTLS subdirectory. (The cm_csTLS directory is used in the remainder of this example to denote this directory.)
```
% mkdir -p cm_csTLS
```
Navigate to the ConfigMap directory.
```
% cd cm_csTLS
```
Create the db.ini file in this ConfigMap directory (cm_csTLS, in this example). In this db.ini file, define the server-side attributes for TLS for Client/Server. These server-side attributes will later be included in the sys.odbc.ini file located in the timesten_home/conf directory in your TimesTen containers. (Note that timesten_home is the TimesTen instance directory. This instance directory is tt/home/timesten/instances/instance1 in your TimesTen containers.)
These are the required server-side attributes for TLS for Client/Server:
- wallet: This is the directory in your TimesTen containers that contains the server wallet. Specify /tt/home/timesten/csWallet.
- ciphersuites: This is the cipher suite setting. Valid values are SSL_ECDHE_ECDSA_WITH_AES_128_GCM_256 or SSL_ECDHE_ECDSA_WITH_AES_256_GCM_384, or both, comma separated and in order of preference. There is no default setting. For TLS to be used, the server and the client settings must include at least one common suite. This example specifies SSL_ECDHE_ECDSA_WITH_AES_128_GCM_256. See Server Attributes for TLS in the Oracle TimesTen In-Memory Database Security Guide for information on the cipher suite settings.
- encryption: This is the encryption setting for the server. This example specifies the required setting. See Server Attributes for TLS in the Oracle TimesTen In-Memory Database Security Guide for information on the valid encryption settings.
This example also specifies the PermSize and the DatabaseCharacterSet connection attributes.
```
vi db.ini

PermSize=200
DatabaseCharacterSet=AL32UTF8
wallet=/tt/home/timesten/csWallet
ciphersuites=SSL_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
encryption=required
```
Create the adminUser file in this ConfigMap directory (cm_csTLS, in this example). In this adminUser file, create the sampleuser user with the samplepw password.
```
vi adminUser

sampleuser/samplepw
```
Create the schema.sql file in this ConfigMap directory (cm_csTLS, in this example). In this schema.sql file, define the s sequence and the emp table for the sampleuser user. The Operator will automatically initialize your database with these object definitions.
```
vi schema.sql

create sequence sampleuser.s;
create table sampleuser.emp (
  id number not null primary key,
  name char(32)
);
```
Create the ConfigMap. The files in the cm_csTLS directory are included in the ConfigMap and, later, will be available in the TimesTen containers.
In this example:
- The name of the ConfigMap is cs-tls. Replace cs-tls with a name of your choosing. (cs-tls is represented in bold in this example.)
- This example uses cm_csTLS as the directory where the files that will be copied into the ConfigMap reside. If you use a different directory, replace cm_csTLS with the name of your directory. (cm_csTLS is represented in bold in this example.)
Use the kubectl create command to create the ConfigMap:
```
% kubectl create configmap cs-tls --from-file=cm_csTLS
configmap/cs-tls created
```

Use the kubectl describe command to verify the contents of the ConfigMap. (cs-tls, in this example.)

% kubectl describe configmap cs-tls
Name:         cs-tls
Namespace:    mynamespace
Labels:       <none>
Annotations:  <none>
 
Data
====
db.ini:
----
PermSize=200
DatabaseCharacterSet=AL32UTF8
wallet=/tt/home/timesten/csWallet
ciphersuites=SSL_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256
encryption=required
 
 
schema.sql:
----
create sequence sampleuser.s;
create table sampleuser.emp (id number not null primary key, name char (32));
 
adminUser:
----
sampleuser/samplepw
 
Events:  <none>

You have successfully created and deployed the cs-tls ConfigMap.

Create a TimesTenClassic Object

This section creates the TimesTenClassic object. See Define and Create a TimesTenClassic Object and About the TimesTenClassic Object Type for detailed information on the TimesTenClassic object.

Perform these steps:

Create an empty YAML file. You can choose any name, but you may want to use the same name you used for the name of the TimesTenClassic object. (In this example, cstls.) The YAML file contains the definitions for the TimesTenClassic object. See TimesTenClassicSpecSpec for information on the fields that you must specify in this YAML file as well as the fields that are optional.
In this example, the fields of particular interest for TLS Client/Server are:
- dbSecret: This example uses one Kubernetes Secret (called cs-tls) for the csWallet metadata file.
- dbConfigMap: This example uses one ConfigMap (called cs-tls). The db.ini file is contained in the cs-tls ConfigMap. Recall that the db.ini file contains the server-side attributes for TLS for Client/Server.
In addition, this example includes:
- name: Replace cstls with the name of your TimesTenClassic object.
- storageClassName: Replace oci-bv with the name of the storage class used to allocate PersistentVolumes to hold TimesTen.
- storageSize: Replace 250Gi with the amount of storage that should be requested for each Pod to hold TimesTen. Note: This example assumes a production environment and uses a value of 250Gi for storageSize. For demonstration purposes, a value of 50Gi is adequate. See the storageSize and the logStorageSize entries in "Table 17-3" for information.
- image: Replace container-registry.oracle.com/timesten/timesten:22.1.1.19.0 with the location and name of your image.
- imagePullSecret: Replace sekret with the image pull secret that Kubernetes should use to fetch the TimesTen image.
```
% vi cstls.yaml

apiVersion: timesten.oracle.com/v1
kind: TimesTenClassic
metadata:
  name: cstls
spec:
  ttspec:
    storageClassName: oci-bv
    storageSize: 250Gi
    image: container-registry.oracle.com/timesten/timesten:22.1.1.19.0
    imagePullSecret: sekret
    dbConfigMap:
    - cs-tls
    dbSecret:
    - cs-tls
```
Use the kubectl create command to create the TimesTenClassic object from the contents of the YAML file (in this example, cstls.yaml). Doing so begins the process of deploying your active standby pair of TimesTen databases in the Kubernetes cluster.
```
% kubectl create -f cstls.yaml
timestenclassic.timesten.oracle.com/cstls created
```

You have successfully created the TimesTenClassic object in the Kubernetes cluster. The process of deploying your TimesTen databases begins, but is not yet complete.

Monitor Deployment of the TimesTenClassic Object

Use the kubectl get and the kubectl describe commands to monitor the progress of the active standby pair as it is provisioned.

Use the kubectl get command and review the STATE field. Observe the value is Initializing. The active standby pair provisioning has begun, but is not yet complete.
```
% kubectl get ttc cstls
NAME    STATE          ACTIVE   AGE
cstls   Initializing   None     15s
```
Use the kubectl get command again to see if value of the STATE field has changed. In this example, the value is Normal, indicating the active standby pair of databases are now provisioned and the process is complete.
```
% kubectl get ttc cstls
NAME    STATE    ACTIVE    AGE
cstls   Normal   cstls-0   3m30s
```

Use the kubectl describe command to view the active standby pair provisioning in detail.

Note the following have been correctly set in the cstls TimesTenClassic object definition:

The cs-tls Secret has been correctly referenced in the dbSecret field (represented in bold).
The cs-tls Configmap has been correctly referenced in the dbConfigMap field (represented in bold).

Note: Note all of the output is shown in this example.

% kubectl describe ttc cstls
Name:         cstls
Namespace:    mynamespace
Labels:       <none>
Annotations:  <none>
API Version:  timesten.oracle.com/v1
Kind:         TimesTenClassic
Metadata:
  Creation Timestamp:  2021-10-17T19:08:03Z
  Generation:          1
  Resource Version:    75491472
  Self Link: 
/apis/timesten.oracle.com/v1/namespaces/mynamespace/timestenclassics/cstls
  UID:                 150128b3-10ac-11eb-b019-d681454a288b
Spec:
  Ttspec:
    Db Config Map:
      cs-tls
    Db Secret:
      cs-tls
    Image:               container-registry.oracle.com/timesten/timesten:22.1.1.19.0
    Image Pull Policy:   Always
    Image Pull Secret:   sekret
    Storage Class Name:  oci
    Storage Size:        250Gi
...
Events:
  Type  Reason       Age    From       Message
  ----  ------       ----   ----       -------
  -     Create       4m21s  ttclassic  Service cstls created
  -     Create       4m21s  ttclassic  StatefulSet cstls created
  -     Create       4m21s  ttclassic  Secret tt150128b3-10ac-11eb-b019-d681454a288b created
  -     StateChange  3m5s   ttclassic  Pod cstls-1 Daemon Up
  -     StateChange  3m5s   ttclassic  Pod cstls-0 Agent Up
  -     StateChange  3m5s   ttclassic  Pod cstls-0 Release 22.1.1.19.0
  -     StateChange  3m5s   ttclassic  Pod cstls-1 Agent Up
  -     StateChange  3m5s   ttclassic  Pod cstls-1 Release 22.1.1.19.0
  -     StateChange  3m5s   ttclassic  Pod cstls-0 Daemon Up
  -     StateChange  116s   ttclassic  Pod cstls-0 Database Loaded
  -     StateChange  116s   ttclassic  Pod cstls-0 Database Updatable
  -     StateChange  116s   ttclassic  Pod cstls-0 CacheAgent Not Running
  -     StateChange  116s   ttclassic  Pod cstls-0 RepAgent Not Running
  -     StateChange  116s   ttclassic  Pod cstls-0 RepState IDLE
  -     StateChange  116s   ttclassic  Pod cstls-0 RepScheme None
  -     StateChange  115s   ttclassic  Pod cstls-0 RepAgent Running
  -     StateChange  115s   ttclassic  Pod cstls-0 RepScheme Exists
  -     StateChange  115s   ttclassic  Pod cstls-0 RepState ACTIVE
  -     StateChange  96s    ttclassic  Pod cstls-1 Database Loaded
  -     StateChange  96s    ttclassic  Pod cstls-1 Database Not Updatable
  -     StateChange  96s    ttclassic  Pod cstls-1 CacheAgent Not Running
  -     StateChange  96s    ttclassic  Pod cstls-1 RepAgent Not Running
  -     StateChange  96s    ttclassic  Pod cstls-1 RepScheme Exists
  -     StateChange  96s    ttclassic  Pod cstls-1 RepState IDLE
  -     StateChange  90s    ttclassic  Pod cstls-1 RepAgent Running
  -     StateChange  84s    ttclassic  Pod cstls-1 RepState STANDBY
  -     StateChange  84s    ttclassic  TimesTenClassic was Initializing, now Normal

Your active standby pair of TimesTen databases are successfully deployed (as indicated by Normal.)

Configuration Requirements for the Client

These sections cover the client requirements for TLS.

Copy a Client Wallet

When you used the ttCreateCerts utility to create TLS certificates, the cwallet.sso wallet file located in the /scratch/ttuser/instance_dir/instance1/conf/ clientWallet directory was generated. This file must be copied to the application container that is running your TimesTen client instance. See "Create TLS Certificates for Replication and Client/Server" for information on creating the TLS certificates.

This example uses the kubectl cp command to copy the /scratch/ttuser/instance_dir/instance1/conf/clientWallet/cwallet.sso file from your Linux development host to the application container running your TimesTen client instance.

Use the kubectl exec -it command to invoke the shell in the application container that contains your TimesTen client instance. (cstls-0, in this example).
```
% kubectl exec -it cstls-0 -c tt -- /bin/bash
```
From the shell just invoked, and from the directory of your choice, create an empty subdirectory. This example creates the clientWallet subdirectory.
```
% mkdir -p clientWallet
```
From your Linux development host, use the kubectl cp command to copy the cwallet.sso file from the /scratch/ttuser/instance_dir/instance1/conf/clientWallet directory on your Linux development host to the clientWallet directory that you just created. (This directory is located in the application container that is running your TimesTen client instance.) Recall that the cwallet.sso file was generated when you used the ttCreateCerts utility to create the TLS certificates. See Create TLS Certificates for Replication and Client/Server for information.
```
% kubectl cp /scratch/ttuser/instance_dir/instance1/conf/clientWallet/
cwallet.sso cstls-0:clientWallet/cwallet.sso -c tt
```
From your shell, verify the cwallet.sso file is located in the clientWallet directory.
```
% ls clientWallet
cwallet.sso
```

You have successfully copied the cwallet.sso client wallet file to the application container that is running your TimesTen client instance.

Configure Client-Side Attributes

You must set client-side attributes for TLS for Client/Server. The attributes can be set in the client DSN definition in timesten_home/conf/sys.odbc.ini or in an appropriate Client/Server connection string. See About Using Client/Server Drivers for additional information.

These are the required client-side attributes for TLS for Client/Server:

wallet: This is the directory that contains the cwallet.sso client wallet file. This directory is located in your application container that is running the TimesTen client instance. There is no default directory. In this example, recall that the clientWallet directory was created to denote this directory. (See Copy a Client Wallet for information.) For purposes of this example, the full path to the clientWallet directory is /tt/home/timesten/clientWallet. Therefore, in this example, /tt/home/timesten/clientWallet is used to denote this directory.
ciphersuites: This is the cipher suite setting. Valid values are SSL_ECDHE_ECDSA_WITH_AES_128_GCM_256 or SSL_ECDHE_ECDSA_WITH_AES_256_GCM_384, or both, comma separated and in order of preference. There is no default setting. For TLS to be used, the server and the client settings must include at least one common suite. This example specifies SSL_ECDHE_ECDSA_WITH_AES_128_GCM_256. See Configuration for TLS for Client/Server in the Oracle TimesTen In-Memory Database Security Guide for information on the cipher suite settings.
encryption: This is the encryption setting for the client. This example specifies the required setting. See Configuration for TLS for Client/Server in the Oracle TimesTen In-Memory Database Security Guide for information on the valid encryption settings.

This example uses a connection string to connect to the cstsl database as the sampleuser user. The sampleuser user was created by the Operator and already exists in the cstsl database. The example then uses the sqlgetconnectattr command from ttIsqlCS on the client to verify TLS is configured correctly on the Server and on the Client and TLS is being used.

Connect to the database.

% ttIsqlcs -connstr "TTC_SERVER1=cstls-0.cstls.mynamespace.svc.cluster.local;
TTC_SERVER2=cstls-1.cstls.mynamespace.svc.cluster.local;
TTC_SERVER_DSN=cstls;UID=sampleuser;PWD=samplepw;
WALLET=tt/home/timesten/clientWallet;
CIPHERSUITES=SSL_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256;
ENCRYPTION=required";
 
Copyright (c) 1996, 2023, Oracle and/or its affiliates. All rights reserved.
Type ? or "help" for help, type "exit" to quit ttIsql.
 
 
 
connect "TTC_SERVER1=cstls-0.cstls.mynamespace.svc.cluster.local;
TTC_SERVER2=cstls-1.cstls.mynamespace.svc.cluster.local;
TTC_SERVER_DSN=cstls;UID=sampleuser;PWD=********;
WALLET=tt/home/timesten/clientWallet;
CipherSuites=SSL_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256;
ENCRYPTION=REQUIRED;";
Connection successful: 
DSN=;TTC_SERVER=cstls-0.cstls.mynamespace.svc.cluster.local;
TTC_SERVER_DSN=cstls;UID=sampleuser;
DATASTORE=/tt/home/timesten/datastore/cstls;DATABASECHARACTERSET=AL32UTF8;
CONNECTIONCHARACTERSET=AL32UTF8;AUTOCREATE=0;PERMSIZE=200;
DDLREPLICATIONLEVEL=3;FORCEDISCONNECTENABLED=1;(SERVER)ENCRYPTION=Required;
(SERVER)WALLET=file:/tt/home/timesten/csWallet;(client)Encryption=Required;
(client)Wallet=/tt/home/timesten/clientWallet;
(client)CipherSuites=SSL_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256;
(Default setting AutoCommit=1)

Use the sqlgetconnectattr command in ttIsqlCS to verify TLS is being used. A return value of 1 indicates TLS is being used.
```
Command> sqlgetconnectattr tt_tls_session;
TT_TLS_SESSION = 1 (SQL_TRUE)
```

You have successfully connected to the database and verified that TLS for Client/Server is being used.