Create a Wallet or Certificates for a TLS Connection

Prior to configuring a TLS connection to a non-Autonomous Database during target registration, you need to create one or more wallets or a certificate, depending on whether client authentication is enabled on your target database.

Create a PEM Certificate for a TLS Connection to a Database that has Server Authentication

This example shows you how to create a self-signed PEM certificate that you can use when configuring a TLS connection between Oracle Data Safe and a database that has server authentication. For server authentication, you need to disable client authentication on the database for which the process is shown below. While a self-signed certificate is fine for testing purposes, Oracle recommends that you use a certificate signed by a trusted or internal certificate authority (CA) for production systems.

Ensure that the location to the orapki utility is added to your path. The examples in this procedure use this utility.
From a command window on your server, create a location for your wallet and change to the wallet directory.
```
$ mkdir /mywallets
$ cd /mywallets
```

Create a wallet in the current directory.

$ orapki wallet create -wallet ./ -pwd password -auto_login

View the contents of the wallet.
```
$ orapki wallet display -wallet . -pwd password
```
Notice that there are no certificates in the wallet yet.
Create a self-signed (root) certificate and add it to the wallet.
```
$ orapki wallet add -wallet . -dn "CN=rootca" -keysize 2048 -self_signed -validity 3650 -sign_alg sha256 -pwd password
```
The certificate is added to the wallet for the user with the specified distinguished name (CN=rootca).

The certificate contains a key pair (private key and public key).

-keysize is the size of the private key.

-validity 3650 specifies the number of days, starting from the current date, that the certificate is valid.

-self_signed means that an external certification authority (CA) does not need to sign the private key and public key.

sha256 is the signing algorithm.
View the contents of the wallet and verify that you have a User Certificate and a Trusted Certificate:
```
$ orapki wallet display -wallet . -pwd password
```
Under User Certificates, you should now have CN=rootca.

Under Trusted Certificates, you should now have CN=rootca.

The User Certificate and Trusted Certificate are the same in that they sign themselves (self-signed).
Export the self-signed certificate from the wallet:
```
$ orapki wallet export -wallet . -dn "CN=rootca" -cert root1.crt -pwd password
```
root1.crt is the name of the exported file.

Configure the wallet on the target database by doing the following:

Copy the self-signed certificate to the wallet folder on your target database.

In the listener.ora file on the target database, add a line SSL_CLIENT_AUTHENTICATION = FALSE, enable the port for TCPS (for example, 1553), and define the wallet. Use the following code example as a guideline.

# listener configuration file

CONNECT_TIMEOUT_LISTENER = 0
SSL_CLIENT_AUTHENTICATION = FALSE
LISTENER = (ADDRESS_LIST =
	(ADDRESS=(PROTOCOL=ipc)(KEY=19c))
	(ADDRESS=(PROTOCOL=tcp)(HOST=ipaddress)(PORT=1552))
	(ADDRESS=(PROTOCOL=tcps)(HOST=ipaddress)(PORT=1553))
)
WALLET_LOCATION = 
  (SOURCE =
	(METHOD = FILE)
	(METHOD_DATA =
	   (DIRECTORY = /home/oracle/wallet)
	)
   )

In the sqlnet.ora file on the target database, add a line SSL_CLIENT_AUTHENTICATION = FALSE and add the wallet location. Use the following code example as a guideline.

# sqlnet configuration file for clients

automatic_ipc = off
SQLNET.AUTHENTICATION_SERVICES = (beq, none)
SSL_CLIENT_AUTHENTICATION = FALSE
names.preferred_servers = (DESCRIPTION=(ADDRESS=(PROTOCOL=ipc)(KEY=19c_ns))(CONNECT_DATA=(RPC=ON)))

namesctl.noconfirm = true
WALLET_LOCATION=
	(SOURCE=(METHOD=FILE)(METHOD_DATA=
	  (DIRECTORY=/home/oracle/mywallets)))

From a command window, restart the listener on the target database.
```
$ lsnrctl start
$ lsnrctl stop
```

When you register the target database in Oracle Data Safe, make sure to do the following:
- Select the connection type TLS.
- Set the port number according to the port number you set in the listener.ora file. In this example, the port number is 1553.
- For the server distinguished name, enter the name you used when you created the self-signed certificate in the wallet. In this example, the name is CN=rootca.
- For the wallet or certificate type, select PEM Certificate and select the self-signed certificate that you exported from the wallet. In this example, the file is root1.crt.

Create JKS Wallets for a TLS Connection to a Database that has Mutual Authentication

During target registration, you can configure a TLS connection between Oracle Data Safe and an Oracle database. You are required to upload two JKS wallets: a TrustStore wallet and a KeyStore wallet.

The example discussed here is only for databases that are mutually authenticated. For mutual authentication, you need to enable client authentication on the database for which the process is shown below.

The example discussed here shows you how to create two JKS wallets with self-signed certificates, enable client authentication on your DB system, and configure the listener to accept SSL/TLS encrypted connections.

Oracle Recommendation:

While self-signed certificates are fine for testing purposes, Oracle recommends that you use certificates signed by a trusted or internal certificate authority (CA) for production systems.

Part 1: Create a Database Server Wallet and Certificate

From the command line, access your database server. Then, as shown below, use the orapki utility to create a database server wallet, create a self-signed certificate and load it into the wallet, and export the certificate. Ensure that the location to the orapki utility is added to your path.

Create a directory for your database server wallet.

$ mkdir -p <wallet path>

For example:

$ mkdir -p /u01/app/oracle/myserverwallet

Create an auto-login wallet.

$ orapki wallet create -wallet <wallet path> -pwd <wallet password> -auto_login

For example:

$ orapki wallet create -wallet /u01/app/oracle/myserverwallet -pwd mypassword -auto_login

Create a self-signed certificate and load it into the wallet.

$ orapki wallet add -wallet <wallet path> -pwd <wallet password> -dn "CN=<database hostname>" -keysize 1024 -self_signed -validity 3650

For example:

$ orapki wallet add -wallet /u01/app/oracle/myserverwallet -pwd mypassword -dn "CN=CloudST2.debdev19.oraclecloud.internal" -keysize 1024 -self_signed -validity 3650

Check the contents of the wallet. Notice that the self-signed certificate is both a user certificate and trusted certificate.

$ orapki wallet display -wallet <wallet path> -pwd <wallet password>

For example:

$ orapki wallet display -wallet /u01/app/oracle/myserverwallet -pwd mypassword
 
... 
Requested Certificates:
User Certificates:
Subject:        CN=CloudST2.debdev19.oraclecloud.internal
Trusted Certificates:
Subject:        CN=CloudST2.debdev19.oraclecloud.internal

Export the certificate so that you can load it into the client wallet later.

$ orapki wallet export -wallet <wallet path> -pwd <wallet password>  -dn "CN=<hostname>" -cert <server certificate path>

In this example, you export the certificate into a tmp directory on your database server. The certificate name can be whatever you want, but it needs to have a CRT file extension.

$ orapki wallet export -wallet /u01/app/oracle/myserverwallet -pwd mypassword -dn "CN=CloudST2.debdev19.oraclecloud.internal" -cert /tmp/CloudST2-certificate.crt

Check that the certificate has been exported as expected.

$ cat <server certificate path>

For example:

$ cat /tmp/CloudST2-certificate.crt
-----BEGIN CERTIFICATE-----
MIIB0TCCAToCAQAwDQYJKoZIhvcNAQEEBQAwMTEvMC0GA1UEAxMmQ2xvdWRTVDIuZGViZGV2MTku
b3JhY2xlY2xvdWQuaW50ZXJuYWwwHhcNMTYwNTExMTEyMDI2WhcNMjYwNTA5MTEyMDI2WjAxMS8w
LQYDVQQDEyZDbG91ZFNUMi5kZWJkZXYxOS5vcmFjbGVjbG91ZC5pbnRlcm5hbDCBnzANBgkqhkiG
9w0BAQEFAAOBjQAwgYkCgYEAr6fhuQly2t3i8gugLVzgP2kFGVXVOzqbggEIC+Qazb15JuKs0ntk
En9ERGvA0fxHkAkCtIPjCzQD5WYRU9C8AQQOWe7UFHae7PsQX8jsmEtecpr5Wkq3818+26qU3Jyi
XxxK/rRydwBO526G5Tn5XPsovaw/PYJxF/fIKMG7fzMCAwEAATANBgkqhkiG9w0BAQQFAAOBgQCu
fBYJj4wQYriZIfjij4eac/jnO85EifF3L3DU8qCHJxOxRgK97GJzD73TiY20xpzQjWKougX73YKV
Tp9yusAx/T/qXbpAD9JKyHlKj16wPeeMcS06pmDDXtJ2CYqOUwMIk53cK7mLaAHCbYGGM6btqP4V
KYIjP48GrsQ5MOqd0w==
-----END CERTIFICATE-----

Part 2: Create a Client Wallet and Certificate

You can continue to work from your database server. From the command line, use the orapki utility to create a client wallet, create a self-signed certificate and load it into the wallet, and export the certificate.

Create a directory for your client wallet.

$ mkdir -p <client wallet path>

For example:

$ mkdir -p /u01/app/oracle/myclientwallet

Create another auto-login wallet.

$ orapki wallet create -wallet <client wallet path> -pwd <wallet password> -auto_login

For example:

$ orapki wallet create -wallet /u01/app/oracle/myclientwallet -pwd mypassword -auto_login

Create a self-signed certificate and load it into the wallet.

$ orapki wallet add -wallet <client wallet path> -pwd <wallet password> -dn "CN=<client computer name>" -keysize 1024 -self_signed -validity 3650

For example:

$ orapki wallet add -wallet /u01/app/oracle/myclientwallet -pwd mypassword -dn "CN=myhost.example.com" -keysize 1024 -self_signed -validity 3650

Check the contents of the wallet. Notice that the self-signed certificate is both a user certificate and trusted certificate.
```
$ orapki wallet display -wallet <client wallet path> -pwd <wallet password>
```

Export the certificate so that you can load it into the server wallet later.

$ orapki wallet export -wallet <client wallet path> -pwd <wallet password> -dn "CN=<client computer fullname>" -cert <certificate path>

In this example, we export the certificate into a tmp directory. The certificate name can by anything you like, but it must have a CRT extension.

$ orapki wallet export -wallet /u01/app/oracle/myclientwallet -pwd mypassword -dn "CN=myhost.example.com" -cert /tmp/gbr30139-certificate.crt

Check the certificate.

$ more <certificate path>

For example:

 $ more /tmp/gbr30139-certificate.crt

-----BEGIN CERTIFICATE-----
MIIBsTCCARoCAQAwDQYJKoZIhvcNAQEEBQAwITEfMB0GA1UEAxMWZ2JyMzAxMzkudWsub3JhY2xl
LmNvbTAeFw0xNjA1MTExMTQzMzFaFw0yNjA1MDkxMTQzMzFaMCExHzAdBgNVBAMTFmdicjMwMTM5
LnVrLm9yYWNsZS5jb20wgZ8wDQYJKoZIhvcNAQEBBQADgY0AMIGJAoGBAKH8G8sFS6l0llu+RMfl
7Yt+Ppw8J0PfDEDbTGP5wtsrs/22dUCipU9l+vif1VgSPLE2UPJbGM8tQzTC6UYbBtWHe4CshmvD
EVlcIMsEFvD7a5Q+P45jqNSEtV9VdbGyxaD6i5Y/Smd+B87FcQQCX54LaI9BJ8SZwmPXgDweADLf
AgMBAAEwDQYJKoZIhvcNAQEEBQADgYEAai742jfNYYTKMq2xxRygGJGn1LhpFenHvuHLBvnTup1N
nZOBwBi4VxW3CImvwONYcCEFp3E1SRswS5evlfIfruCZ1xQBoUNei3EJ6O3OdKeRRp2E+muXEtfe
U+jwUE+SzpnzfpI23Okl2vo8Q7VHrSalxE2KEhAzC1UYX7ZYp1U=
-----END CERTIFICATE-----

Part 3: Exchange Client and Server Certificates

Continue to work on the database server. Load the server certificate as a trusted certificate into the client wallet, and load the client certificate into the server wallet. You do this because each side of the connection needs to trust the other.

Load the server certificate into the client wallet.

$ orapki wallet add -wallet <client wallet path> -pwd <wallet password> -trusted_cert -cert <server certificate path>

For example:

$ orapki wallet add -wallet /u01/app/oracle/myclientwallet -pwd mypassword -trusted_cert -cert /tmp/CloudST2-certificate.crt

Check the contents of the client wallet. Notice that the server certificate is now included in the list of trusted certificates.

$ orapki wallet display -wallet <client wallet path> -pwd <wallet password>

For example:

$ orapki wallet display -wallet /u01/app/oracle/myclientwallet -pwd mypassword

...
Requested Certificates:
User Certificates:
Subject:        CN=myhost.example.com
Trusted Certificates:
Subject:        OU=Class 1 Public Primary Certification Authority,O=VeriSign\, Inc.,C=US
Subject:        CN=myhost.example.com
Subject:        CN=GTE CyberTrust Global Root,OU=GTE CyberTrust Solutions\, Inc.,O=GTE Corporation,C=US
Subject:        CN=CloudST2.debdev19.oraclecloud.internal
Subject:        OU=Class 3 Public Primary Certification Authority,O=VeriSign\, Inc.,C=US
Subject:        OU=Class 2 Public Primary Certification Authority,O=VeriSign\, Inc.,C=US

Load the client certificate into the server wallet.

$ orapki wallet add -wallet <server wallet path> -pwd wallet password -trusted_cert -cert <client certificate path>

For example:

$ orapki wallet add -wallet /u01/app/oracle/myserverwallet -pwd mypassword -trusted_cert -cert  /tmp/gbr30139-certificate.crt

Check the contents of the server wallet. Notice that the client certificate is now included in the list of trusted certificates.

$ orapki wallet display -wallet <server wallet path> -pwd <wallet password>

For example:

$ orapki wallet display -wallet /u01/app/oracle/myserverwallet -pwd mypassword

...
Requested Certificates:
User Certificates:
Subject:        CN=CloudST2.debdev19.oraclecloud.internal
Trusted Certificates:
Subject:        CN=CloudST2.debdev19.oraclecloud.internal
Subject:        CN=myhost.example.com

Part 4: Create a JKS Wallet from the PKCS#12 Wallet

In this part, you use the orapki utility to convert the client wallet, which is currently in PKCS#12 format, into a JKS wallet. You do this because Oracle Data Safe requires a JKS wallet and does not support PKCS#12 wallets.

Enter the following command to create a JKS wallet:
```
$ orapki wallet pkcs12_to_jks -wallet  <client wallet location> -pwd <password> [-jksKeyStoreLoc  <jksKSloc> 
-jksKeyStorepwd <jksKSpwd>] [-jksTrustStoreLoc <jksTSloc> -jksTrustStorepwd <jksTSpwd>]
```
where the parameters are as follows:
- <server wallet location> is the p12 server wallet location
- <password> is the wallet password
- <jksKSloc> is the JKS KeyStore location
- <jksKSpwd> is the JKS KeyStore password
- <jksTSloc> is the JKS TrustStore location
- <jksTSpwd> is the JKS TrustStore password
For example:
```
$ orapki wallet pkcs12_to_jks  -wallet /u01/app/oracle/myclientwallet -pwd password -jksKeyStoreLoc /tmp/keystore.jks  
-jksKeyStorepwd password -jksTrustStoreLoc /tmp/truststore.jks  -jksTrustStorepwd password
```
The JKS TrustStore and JKS KeyStore files, truststore.jks and keystore.jks respectively, get created after this command is successfully executed. You upload these files during target registration in Oracle Data Safe.

Note:
The JKS TrustStore and JKS KeyStore file names can be anything you want.
Copy the JKS TrustStore and JKS KeyStore files to your client machine.

Part 5: Configure the Server Network

In this part, you configure the wallet location, enable client authentication, and enable SSL/TLS encrypted connections on the target database.

In the sqlnet.ora file on the database server, add the wallet information and enable client authentication. To do this, open $ORACLE_HOME/network/admin/sqlnet.ora on the database server, and add the following entries. Also, ensure that double encryption is not enabled in sqlnet.ora.
```
WALLET_LOCATION =
   (SOURCE =
     (METHOD = FILE)
     (METHOD_DATA =
       (DIRECTORY = /u01/app/oracle/myserverwallet)
     )
   )

SSL_CLIENT_AUTHENTICATION = TRUE
```

In the listener.ora file on the database server, add the wallet information and configure the listener to accept SSL/TLS encrypted connections. To do this, open $ORACLE_HOME/network/admin/listener.ora file, enter the wallet information, and add a TCPS entry.

For example:

SSL_CLIENT_AUTHENTICATION=TRUE
WALLET_LOCATION =
  (SOURCE =
    (METHOD = FILE)
    (METHOD_DATA =
      (DIRECTORY = /u01/app/oracle/myserverwallet)
    )
  )

LISTENER =
  (DESCRIPTION_LIST =
    (DESCRIPTION =
      (ADDRESS = (PROTOCOL = TCP)(HOST = server1.localdomain)(PORT = 1521))
      (ADDRESS = (PROTOCOL = IPC)(KEY = EXTPROC1521))
      (ADDRESS = (PROTOCOL = TCPS)(HOST = server1.localdomain)(PORT = 1522))
    )
)

Restart the listener.
```
$ lsnrctl stop
$ lsnrctl start
```

Part 6: Configure the TLS Connection During Target Registration in Oracle Data Safe

When you register the target database in Oracle Data Safe, make sure to do the following:

Select the TLS connection type.
Set the port number according to the port number you set in the listener.ora file. In this example, the port number is 1522.
For the server distinguished name, enter the name you used when you created the self-signed certificate for the target database. In this example, the name is CN=CloudST2.debdev19.oraclecloud.internal.
Select JKS wallet type.
Upload the JKS TrustStore file. In this example, it is truststore.jks.
Upload the JKS KeyStore file. In this example, it is keystore.jks.