1. Security Guide
  2. Keeping Oracle NoSQL Database Secure
  3. Guidelines for enabling TLSV1.3 protocol

Guidelines for enabling TLSV1.3 protocol

Update TLS protocol configuration to enable TLSv1.3

Oracle NoSQL Database now supports TLSv1.3 protocol. To run NoSQL Database and application with TLSv1.3, you must use JDK11 or later, JDK8 Update 261 (JDK 8u261) or later. Since 21.3 release, NoSQL Database adds TLSv1.3 protocol to the default TLS protocols of security configuration created via makebootconfig or securityconfig utility. It's recommended to update the TLS protocol of existing security configuration to latest protocol TLSv1.3 since it is the most secure.

Enable TLSv1.3 protocol

This is the procedure to update the existing security configuration to enable protocol TLSv1.3. It assumes the existing security configuration is made by previous NoSQL Database releases, which has TLSv1.2 enabled.
  1. Update login properties of client application. Add TLSv1.3 to oracle.kv.ssl.protocols if it exists. Then restart the client application to make the protocol change to take effect.
    oracle.kv.ssl.protocols="TLSv1.3,TLSv1.2"
  2. Make two copies of existing security configuration directory of the storage node. Keep one as backup, and the other one for updating the protocols.

    Note:

    This step is to update the security configuration of storage node used by NoSQL Database server, as opposed to the client application changes in the previous step.
  3. Update the SSL protocols in the copied security configuration directory.
    java -jar /kv/lib/kvstore.jar securityconfig \
config update -secdir security \
-param "allowProtocols=TLSv1.3,TLSv1.2" \
-param "clientAllowProtocols=TLSv1.3,TLSv1.2"
  4. Verify if protocols in the updated security configuration has TLSv1.3.
    java -jar kv/lib/kvstore.jar securityconfig config 
show -secdir KVROOT/security
    Verify if the protocol has TLSv1.3.
  5. Continuing from your NoSQL development environment, start the Admin CLI. Using the ping command, check if all RNs are up:
    (~/tmp/kvroot/newKey)=> java -jar $KVHOME/lib/kvstore.jar runadmin -host localhost -port 5000 -security
                                  $KVROOT1/security/client.security
Logged in admin as anonymous
kv-> ping
Pinging components of store HSRStore based upon topology sequence #18 10 partitions and 3 storage nodes
Time: 2021-09-04 08:50:02 UTC Version: 21.2.16
Shard Status: healthy:1 writable-degraded:0 read-only:0 offline:0
Admin Status: healthy Zone [name=Austin id=zn1 type=PRIMARY allowArbiters=false] 
RN Status: online:3 offline:0
max DelayMillis:1 max CatchupTimeSecs:0
Storage Node [sn1] on localhost:5000 Zone: [name=Austin id=zn1 type=PRIMARY allowArbiters=false]
Status: RUNNING Ver: 21.2.16 2021-09-04 08:50:02 UTC  UTC Build id: 0d00330822fc Admin [admin1]
Status: RUNNING,MASTER Rep Node [rg1-rn1]
Status: RUNNING,MASTER sequenceNumber:63 haPort:5011
Storage Node [sn2] on localhost:6000 Zone: [name=Austin id=zn1 type=PRIMARY allowArbiters=false]
Status: RUNNING Ver: 21.2.16 2021-09-04 08:50:02 UTC Build id: 0d00330822fc
Rep Node [rg1-rn2] Status: RUNNING,REPLICA sequenceNumber:63 haPort:6010 delayMillis:1 catchupTimeSecs:0
Storage Node [sn3] on localhost:7000 Zone: [name=Austin id=zn1 type=PRIMARY allowArbiters=false]
Status: RUNNING Ver: 21.2.16 2021-09-04 08:50:02 UTC Build id: 0d00330822fc Rep Node [rg1-rn3]
Status: RUNNING,REPLICA sequenceNumber:63 haPort:7010 delayMillis:? catchupTimeSecs:?
  6. Copy the updated security directory to each server node (Storage Node) and replace the old security configuration directory. Then, check that all Replication Nodes are online and restart each Storage Node sequentially. Make sure that the last one you restarted is completely up before continuing to the next SN.
    java -jar $KVHOME/lib/kvstore.jar stop -root
/Users/my_name/tmp/kvroot/kvroot1
(~/hg/kv/kvstore)=> java -jar $KVHOME/lib/kvstore.jar start -root $KVROOT1 &

kv-> ping
Pinging components of store HSRStore based upon topology sequence #18
10 partitions and 3 storage nodes
Time: 2021-09-04 08:52:02 UTC Version: 21.2.16 
Shard Status: healthy:1 writable-degraded:0 read-only:0 offline:0
Admin Status: healthy
Zone [name=Austin id=zn1 type=PRIMARY allowArbiters=false]
RN Status: online:3 offline:0 maxDelayMillis:0 maxCatchupTimeSecs:0
Storage Node [sn1] on localhost:5000    Zone: [name=Austin
id=zn1 type=PRIMARY allowArbiters=false]   

Status: RUNNING   Ver: 21.2.16 2021-09-04 08:52:02 UTC  Build id: 0d00330822fc
        Admin [admin1] Status: RUNNING,MASTER
        Rep Node [rg1-rn1]   Status: RUNNING,REPLICA
sequenceNumber:62 haPort:5011 delayMillis:0 catchupTimeSecs:0

Storage Node [sn2] on localhost:6000 Zone: [name=Austin
id=zn1 type=PRIMARY allowArbiters=false]
Status: RUNNING Ver: 21.2.16 2021-09-04 08:52:02 UTC Build id: 0d00330822fc
      Rep Node [rg1-rn2] Status: RUNNING,MASTER
sequenceNumber:62 haPort:6010

Storage Node [sn3] on localhost:7000 Zone: [name=Austin
id=zn1 type=PRIMARY allowArbiters=false]
Status: RUNNING Ver: 21.2.16 2021-09-04 08:52:02 UTC Build id: 0d00330822fc
      Rep Node [rg1-rn3] Status: RUNNING,REPLICA
sequenceNumber:62 haPort:7010 delayMillis:0 catchupTimeSecs:0

Rep Node [rg1-rn1] Status: RUNNING,REPLICA is up, now restart the next SN
 (~/hg/kv/kvstore)=> java -jar $KVHOME/lib/kvstore.jar stop -root /Users/my_name/tmp/kvroot/kvroot2
kv->ping
Pinging components of store HSRStore based upon topology sequence #18
10 partitions and 3 storage nodes
Time: 2021-09-04 08:52:02 UTC Version: 21.2.16
Shard Status: healthy:0 writable-degraded:1 read-only:0 offline:0
Admin Status: healthy

Zone [name=Austin id=zn1 type=PRIMARY allowArbiters=false]
RN Status: online:2 offline:1 maxDelayMillis:? maxCatchupTimeSecs:?
Storage Node [sn1] on localhost:5000 Zone: [name=Austin id=zn1 type=PRIMARY allowArbiters=false]
Status: RUNNING Ver: 21.2.16 2021-09-04 08:54:02  UTC Build id: 0d00330822fc
        Admin [admin1] Status: RUNNING,MASTER
        Rep Node [rg1-rn1]   Status: RUNNING,REPLICA
sequenceNumber:62 haPort:5011

Storage Node [sn2] on localhost:6000
Zone: [name=Austin id=zn1 type=PRIMARY allowArbiters=false] UNREACHABLE
       Rep Node [rg1-rn2] Status: UNREACHABLE

Storage Node [sn3] on localhost:7000
Zone: [name=Austin id=zn1 type=PRIMARY allowArbiters=false]
Status: RUNNING Ver: 21.2.16 2021-09-04 08:54:02 UTC Build id: 0d00330822fc
       Rep Node [rg1-rn3] Status: RUNNING,REPLICA
sequenceNumber:62 haPort:7010 delayMillis:? catchupTimeSecs:?

(~/hg/kv/kvstore)=> java -jar $KVHOME/lib/kvstore.jar start -root $KVROOT2 & kv->ping
Pinging components of store HSRStore based upon topology sequence #18
10 partitions and 3 storage nodes
Time: 2021-09-04 08:55:02 UTC Version: 21.2.16
Shard Status: healthy:1 writable-degraded:0 read-only:0 offline:0
Admin Status: healthy
Zone [name=Austin id=zn1 type=PRIMARY allowArbiters=false]
RN Status: online:3 offline:0 maxDelayMillis:1 maxCatchupTimeSecs:0
Storage Node [sn1] on localhost:5000 Zone: [name=Austin id=zn1 type=PRIMARY allowArbiters=false]
Status: RUNNING Ver: 21.2.16 2021-09-04 08:55:02 UTC Build id: 0d00330822fc
        Admin [admin1] Status: RUNNING,MASTER
        Rep Node [rg1-rn1]   Status: RUNNING,REPLICA
sequenceNumber:63 haPort:5011
Storage Node [sn2] on localhost:6000
Zone: [name=Austin id=zn1 type=PRIMARY allowArbiters=false]
Status: RUNNING Ver: 21.2.16 2021-09-04 08:55:02 UTC Build id: 0d00330822fc
       Rep Node [rg1-rn2] Status: RUNNING,REPLICA
sequenceNumber:63 haPort:6010 delayMillis:1 catchupTimeSecs:0
Storage Node [sn3] on localhost:7000
Zone: [name=Austin id=zn1 type=PRIMARY allowArbiters=false]
Status: RUNNING Ver: 21.2.16 2021-09-04 08:55:02 UTC Build id: 0d00330822fc
      Rep Node [rg1-rn3] Status: RUNNING,REPLICA
sequenceNumber:63 haPort:7010 delayMillis:1 catchupTimeSecs:0

Update TLS protocol to TLSv1.3 only

This is the procedure to enable TLSv1.3 only in NoSQL Database security configuration. It assumes the existing security configuration has already TLSv1.3 protocol, if not, follow the last procedure to enable TLSv1.3 first.

After this change, all client application only can establish TLS connections with NoSQL Database using TLSv1.3 protocol. Before this change, you must ensure oracle.kv.ssl.protocols in login properties file of the client applications have TLSv1.3 enabled, otherwise follow the section "Enable TLSv1.3 protocol" to enable TLSv1.3 first.
  1. Make two copies of existing security configuration directory. Keep one as backup, and use the other one for updating the protocols.
  2. Update the SSL protocols in the copied security configuration directory.
    java -jar /kv/lib/kvstore.jar securityconfig \
config update -secdir security \
-param "allowProtocols=TLSv1.3" \
-param "clientAllowProtocols=TLSv1.3"
  3. Verify if protocols in the updated security configuration has TLSv1.3 only.
    java -jar kv/lib/kvstore.jar securityconfig config 
show -secdir KVROOT/security

    Verify if protocols has TLSv1.3 only.

  4. Continuing from your NoSQL development environment, start the Admin CLI. Using the ping command, check if all RNs are up:
    (~/tmp/kvroot/newKey)=> java -jar $KVHOME/lib/kvstore.jar
                           runadmin -host localhost -port 5000 -security
$KVROOT1/security/client.security
Logged in admin as anonymous
kv-> ping
Pinging components of store HSRStore based upon topology sequence #18
10 partitions and 3 storage nodes
Time: 2021-09-04 08:56:02 UTC Version: 21.2.16 
Shard Status: healthy:1 writable-degraded:0 read-only:0 offline:0
Admin Status: healthy
Zone [name=Austin id=zn1 type=PRIMARY allowArbiters=false]
RN Status: online:3 offline:0 max
DelayMillis:1 max CatchupTimeSecs:0
Storage Node [sn1] on localhost:5000    Zone: [name=Austin
id=zn1 type=PRIMARY allowArbiters=false]    Status: RUNNING  
Ver: 21.2.16 2021-09-04 08:56:02 UTC  Build id: 0d00330822fc
        Admin [admin1] Status: RUNNING,MASTER
        Rep Node [rg1-rn1]   Status: RUNNING,MASTER
sequenceNumber:63 haPort:5011
Storage Node [sn2] on localhost:6000    Zone: [name=Austin
id=zn1 type=PRIMARY allowArbiters=false]    Status: RUNNING  
Ver: 21.2.16 2021-09-04 08:56:02 UTC  Build id: 0d00330822fc
        Rep Node [rg1-rn2]     Status: RUNNING,REPLICA
sequenceNumber:63 haPort:6010 delayMillis:1 catchupTimeSecs:0
Storage Node [sn3] on localhost:7000    Zone: [name=Austin
id=zn1 type=PRIMARY allowArbiters=false]    Status: RUNNING  
Ver: 21.2.16 2021-09-04 08:56:02 UTC  Build id: 0d00330822fc
        Rep Node [rg1-rn3]     Status: RUNNING,REPLICA
sequenceNumber:63 haPort:7010 delayMillis:? catchupTimeSecs:?
  5. Copy the updated security directory to each server node (Storage Node) and replace the old security configuration directory. Then, check that all Replication Nodes are online and restart each Storage Node sequentially. Make sure that the last one you restarted is completely up before continuing to the next SN.
    java -jar $KVHOME/lib/kvstore.jar stop -root /Users/my_name/tmp/kvroot/kvroot1
(~/hg/kv/kvstore)=> java -jar $KVHOME/lib/kvstore.jar start -root $KVROOT1 &
kv-> ping Pinging components of store HSRStore based upon topology sequence #18 10 partitions
and 3 storage nodes
Time: 2021-09-04 08:56:53 UTC Version: 21.2.16  
Shard Status: healthy:1 writable-degraded:0 read-only:0 offline:0 Admin
Status: healthy Zone [name=Austin id=zn1 type=PRIMARY allowArbiters=false] RN
Status: online:3 offline:0 maxDelayMillis:0 maxCatchupTimeSecs:0 Storage Node [sn1] on localhost:5000
Zone: [name=Austin id=zn1 type=PRIMARY allowArbiters=false] S
Status: RUNNING Ver: 21.2.16 2021-09-04 08:56:53 UTC Build id: 0d00330822fc Admin [admin1]
Status: RUNNING,MASTER Rep Node [rg1-rn1] Status: RUNNING,REPLICA sequenceNumber:62 haPort:5011 delayMillis:0 catchupTimeSecs:0
Storage Node [sn2] on localhost:6000 Zone: [name=Austin id=zn1 type=PRIMARY allowArbiters=false]
Status: RUNNING Ver: 21.2.16 2021-09-04 08:56:53 UTC Build id: 0d00330822fc Rep Node [rg1-rn2]
Status: RUNNING,MASTER sequenceNumber:62 haPort:6010 Storage Node [sn3] on localhost:7000 Zone: 
[name=Austin id=zn1 type=PRIMARY allowArbiters=false] 
Status: RUNNING Ver: 21.2.16 2021-09-04 08:56:53 UTC Build id: 0d00330822fc Rep Node [rg1-rn3]
Status: RUNNING,REPLICA sequenceNumber:62 haPort:7010 delayMillis:0 catchupTimeSecs:0 Rep Node [rg1-rn1]
Status: RUNNING,REPLICA is up, now restart the next SN

(~/hg/kv/kvstore)=> java -jar $KVHOME/lib/kvstore.jar stop -root /Users/my_name/tmp/kvroot/kvroot2
kv->ping Pinging components of store HSRStore based upon topology sequence #18 10 partitions and 3 
storage nodes 
Time: 2021-09-04 08:57:13 UTC Version: 21.2.16  
Shard Status: healthy:0 writable-degraded:1 read-only:0 offline:0 Admin Status: healthy 
Zone [name=Austin id=zn1 type=PRIMARY allowArbiters=false] RN Status: online:2 offline:1 
maxDelayMillis:? maxCatchupTimeSecs:? Storage Node [sn1] on localhost:5000 Zone: 
[name=Austin id=zn1 type=PRIMARY allowArbiters=false]
Status: RUNNING Ver: 21.2.16 2021-09-04 08:57:13 Build id: 0d00330822fc 
Admin [admin1] Status: RUNNING,MASTER Rep Node [rg1-rn1] Status: RUNNING,REPLICA 
sequenceNumber:62 haPort:5011 Storage Node [sn2] on localhost:6000 
Zone: [name=Austin id=zn1 type=PRIMARY allowArbiters=false] 
UNREACHABLE Rep Node [rg1-rn2] Status: UNREACHABLE Storage Node [sn3] on localhost:7000 
Zone: [name=Austin id=zn1 type=PRIMARY allowArbiters=false] 
Status: RUNNING Ver: 21.2.16 2021-09-04 08:57:13 UTC Build id: 0d00330822fc 
Rep Node [rg1-rn3] Status: RUNNING,REPLICA sequenceNumber:62 haPort:7010 
delayMillis:? catchupTimeSecs:?

(~/hg/kv/kvstore)=> java -jar $KVHOME/lib/kvstore.jar start -root $KVROOT2 & kv->ping 
Pinging components of store HSRStore based upon topology sequence #18 10 partitions 
and 3 storage nodes
Time: 2021-09-04 08:57:23 UTC Version: 21.2.16
Shard Status: healthy:1 writable-degraded:0 read-only:0 offline:0 
Admin Status: healthy Zone [name=Austin id=zn1 type=PRIMARY allowArbiters=false] 
RN Status: online:3 offline:0 maxDelayMillis:1 maxCatchupTimeSecs:0 
Storage Node [sn1] on localhost:5000 Zone: [name=Austin id=zn1 type=PRIMARY 
allowArbiters=false]
Status: RUNNING Ver: 21.2.16 2021-09-04 08:57:33 UTC Build id: 0d00330822fc 
Admin [admin1] Status: RUNNING,MASTER Rep Node [rg1-rn1] 
Status: RUNNING,REPLICA sequenceNumber:63 haPort:5011 
Storage Node [sn2] on localhost:6000 Zone: [name=Austin id=zn1 type=PRIMARY 
allowArbiters=false] 
Status: RUNNING Ver: 21.2.16 2021-09-04 08:57:33 UTC Build id: 0d00330822fc 
Rep Node [rg1-rn2] Status: RUNNING,REPLICA sequenceNumber:63 haPort:6010 
delayMillis:1 catchupTimeSecs:0 Storage Node [sn3] on localhost:7000 
Zone: [name=Austin id=zn1 type=PRIMARY allowArbiters=false] 
Status: RUNNING Ver: 21.2.16 2021-09-04 08:57:33 UTC Build id: 0d00330822fc 
Rep Node [rg1-rn3] Status: RUNNING,REPLICA sequenceNumber:63 haPort:7010 
delayMillis:1 catchupTimeSecs:0

    The client applications now only can connect NoSQL Database with TLSv1.3 protocol. It's recommended to check and update oracle.kv.ssl.protocols to have TLSv1.3 only and restart the client applications to ensure they are configured with TLSv1.3 only.