Encrypting Data with the Master Key and Wallet Method

22 Encrypting Data with the Master Key and Wallet Method

To use this method of data encryption, you create a local master key wallet, add a master key to the wallet, and then use this master key for data encryption.

This method depends on whether the data is encrypted in the trails or across TCP/IP.

For the Classic Architecture, to encrypt data across the network, Oracle GoldenGate generates a session key using a cryptographic function based on the master key. However, the Distribution Server ogg protocol doesn't support this method.

Oracle GoldenGate uses an auto-login wallet (file extension .sso), which is an obfuscated container that does not require human intervention to supply the necessary passwords.

Note:

Encrypting data with a master key and wallet is not supported on the NonStop platforms.

With the master key and wallet method of encryption, you may need to perform the following tasks:

Parent topic: Securing Oracle GoldenGate

22.1 Creating the Wallet and Adding a Master Key

The wallet is created in a platform-independent format. The wallet can be stored on a shared file system that is accessible by all systems in the Oracle GoldenGate environment. Alternatively, you can use an identical wallet on each system in the Oracle GoldenGate environment. If you use a wallet on each system, you must create the wallet on one system, typically the source system, and then copy it to all of the other systems in the Oracle GoldenGate environment. This must also be done every time you add, change, or delete a master key.

This procedure creates the wallet on the source system and then guides you through copying it to the other systems in the Oracle GoldenGate environment.

(Optional) To store the wallet in a location other than the dirwlt subdirectory of the Oracle GoldenGate installation directory, specify the desired location with the WALLETLOCATION parameter in the GLOBALS file.
The wallet location for MA is:
```
OGG_DEPLOYMENT/var/lib/wallet
```
```
WALLETLOCATION directory_path
```
Create a master-key wallet with the CREATE WALLET command in GGSCI.
Open the wallet after it has been created with the OPEN WALLET command.
Add a master key to the wallet with the ADD MASTERKEY command.
Issue the INFO MASTERKEY command to confirm that the key you added is the current version. In a new installation, the version should be 1.
Issue the INFO MASTERKEY command with the VERSION option, where the version is the current version number. Record the version number and the AES hash value of that version.
```
INFO MASTERKEY VERSION version
```
Copy the wallet to all of the other Oracle GoldenGate systems.
Issue the INFO MASTERKEY command with the VERSION option on each system to which you copied the wallet, where the version is the version number that you recorded. For each wallet, make certain the Status is Current. All wallets must show identical key versions.
```
INFO MASTERKEY VERSION version
```

Parent topic: Encrypting Data with the Master Key and Wallet Method

22.2 Specifying Encryption Parameters in the Parameter File

This procedure adds the parameters that are required to support data encryption in the trails and across the network with the master key and wallet method.

In the following parameter files, add the following:
- To encrypt trail data: In the parameter file of the primary Extract group and the data pump, add an ENCRYPTTRAIL parameter statement before any parameter that specifies a trail or file that you want to be encrypted. Parameters that specify trails or files are EXTTRAIL, RMTTRAIL, EXTFILE, and RMTFILE. The syntax is:
```
ENCRYPTTRAIL {AES128 | AES192 | AES256} 
```
- To encrypt data across TCP/IP: You can either modify the parameters file using the RMTHOSTOPIONS ENCRYPT option or use SOCKS5 proxy to deliver data over the network through a SOCKS5 proxy. See Using SOCKS5 Proxy to Deliver Encrypted Data.
  
  In the parameter file of the data pump (or the primary Extract, if no pump is being used), use the ENCRYPT option of the RMTHOSTOPTIONS parameter. The syntax is:
```
RMTHOSTOPTIONS host, MGRPORT port, ENCRYPT {AES128 | AES192 | AES256 }

RMTHOSTOPTIONS ENCRYPT {AES128 | AES192 | AES256 }
```
Where:
- RMTHOSTOPTIONS is used for Extracts.
- ENCRYPTTRAIL without options specifies 256-key byte substitution. This format is not secure and should not be used in a production environment. Use only for backward compatibility with earlier Oracle GoldenGate versions.
- AES128 encrypts with the AES-128 encryption algorithm.
- AES192 encrypts with AES-192 encryption algorithm.
- AES256 encrypts with AES-256 encryption algorithm.
Use the DECRYPTTRAIL parameter for a data pump if you want trail data to be decrypted before it is written to the output trail. Otherwise, the data pump automatically decrypts it, if processing is required, and then reencrypts it before writing to the output trail. (Replicat decrypts the data automatically without any parameter input.) Also see Requirements for Setting up an Encryption Profile.
```
DECRYPTTRAIL
```

Note:

You can explicitly decrypt incoming trail data and then re-encrypt it again for any output trails or files. First, enter DECRYPTTRAIL to decrypt the data, and then enter ENCRYPTTRAIL and its output trail specifications. DECRYPTTRAIL must precede ENCRYPTTRAIL. Explicit decryption and re-encryption enables you to vary the AES algorithm from trail to trail, if desired. For example, you can use AES 128 to encrypt a local trail and AES 256 to encrypt a remote trail. Alternatively, you can use the master key and wallet method to encrypt from one process to a second process, and then use the ENCKEYS method to encrypt from the second process to the third process.

Using SOCKS5 Proxy to Deliver Encrypted Data

Parent topic: Encrypting Data with the Master Key and Wallet Method

22.2.1 Using SOCKS5 Proxy to Deliver Encrypted Data

The SOCKS5 protocol routes packets between a server and a client using a proxy server. The protocol establishes a TCP connection to another server on behalf of the client and then routes the traffic between the client and server, while hiding the identity of the client from the public network.

In Oracle GoldenGate, you can use SOCKS5 proxy to deliver data over the network with the RMHOSTOPTIONS parameter. See RMTHOSTOPTIONS for details.

To create a SOCKS5 proxys with SSH tunneling to securely transmit data over the network, perform the following steps:

On Linux, a SOCKS5 proxy can be set up along with SSH tunneling using the following SSH command:

ssh –i private_key file -v –N –f –D listening IP Address:listening IP port GGCS
      Oracle User@GGCS IP Address socksproxy output file 
-N: No execution command on remote system
-D: Dynamic Port Forwarding
-i: Private Key File
-f: Run the proxy process in the background
-v: Verbose Mode
-C: Compression

The following example shows the SOCKS5 proxy with SSH tunnel connecting to a GoldenGate Cloud Service (GGCS) instance with IP address 129.145.2.34:

ssh -N -f -i opc_rsa.ppk -D 127.0.0.1:1080 opc@129.145.2.34 /tmp/ogg_socksproxy.log

After setting up the SOCKS5 proxy, you can set up Oracle GoldenGate on-premises Pump to deliver data to GGCS using the SOCKSPROXY parameter from the proxy server, as shown in the following example:

RMTHOST 129.145.2.34, COMPRESS, MGRPORT 1021, SOCKSPROXY 127.0.0.1:1080

Parent topic: Specifying Encryption Parameters in the Parameter File

22.3 Renewing the Master Key

This procedure renews the master encryption key in the encryption-key wallet. Renewing the master key creates a new version of the key. Its name remains the same, but the bit ordering changes. As part of your security policy, you should renew the current master key regularly so that it does not get stale.

All renewed versions of a master key remain in the wallet until they are marked for deletion with the DELETE MASTERKEY command and then the wallet is purged with the PURGE WALLET command, see Deleting Stale Master Keys.

Unless the wallet is maintained centrally on shared storage (as a shared wallet), the updated wallet must be copied to all of the other systems in the Oracle GoldenGate configuration that use that wallet. To do so, the Oracle GoldenGate processes need to be stopped. This procedure includes steps for performing those tasks in the correct order.

Stop Extract. You need to stop the TRANLOG Extract group, which is the Extract capturing from the transaction logs.
Note:
If the TRANLOG Extract group is also acting as an Extract pump, then you need to stop the applicable and stop all activity on the database as well.
```
STOP EXTRACT group
```
Check the read RBA of the Extract data pump against the size of the Extract trail by performing the following:
```
INFO EXTRACT SHELL ls -l ./dirdat/[trail identifier]*
```
When the read RBA matches the trail size, then there is no more data to process. When the Extract pump or Extract sends all the trail files to the target, then you should start checking the Replicat to determine when it is at EOF.
On the source system, stop the data pumps.
```
STOP EXTRACT group
```
Check the read RBA of the Replicat against the size of the remote trail.
On the target systems, stop the Replicat when the read RBA matches the size of the remote trail.
```
STOP REPLICAT group
```
On the source system, issue the following command to open the wallet.
```
OPEN WALLET
```
On the source system, issue the following command to confirm the version of the current key. Make a record of the version.
```
INFO MASTERKEY
```
On the source system, issue the following command to renew the master key.
```
RENEW MASTERKEY
```
On the source system, issue the following command to confirm that a new version is current.
```
INFO MASTERKEY
```
Note:

If you are using a shared wallet, go to step 12. If you are using a wallet on each system, continue to the next step.
On the source system, issue the following command, where version is the new version of the master key. Make a record of the hash value.
```
INFO MASTERKEY VERSION version
```
Copy the updated wallet from the source system to the same location as the old wallet on all of the target systems.
On each target, issue the following command, where version is the new version number of the master key. For each wallet, make certain the Status is Current and compare the new hash value with the one that you originally recorded. All wallets must show identical key versions and hash values.
```
INFO MASTERKEY VERSION version
```
Restart Extract.
```
START EXTRACT group
```
Restart the data pumps.
```
START EXTRACT group
```
Restart Replicat.
```
START REPLICAT group
```

Parent topic: Encrypting Data with the Master Key and Wallet Method

22.4 Deleting Stale Master Keys

This procedure deletes stale versions of the master key. Deleting stale keys should be part of the overall policy for maintaining a secure Oracle GoldenGate wallet. It is recommended that you develop a policy for how many versions of a key you want to keep in the wallet and how long you want to keep them.

Note:

For Oracle GoldenGate deployments using a shared wallet, the older versions of the master key should be retained after the master key is renewed until all processes are using the newest version. The time to wait depends on the topology, latency, and data load of the deployment. A minimum wait of 24 hours is a conservative estimate, but you may need to perform testing to determine how long it takes for all processes to start using a new key. To determine whether all of the processes are using the newest version, view the report file of each Extract immediately after renewing the master key to confirm the last SCN that was mined with the old key. Then, monitor the Replicat report files to verify that this SCN was applied by all Replicat groups. At this point, you can delete the older versions of the master key.

If the wallet is on central storage that is accessible by all Oracle GoldenGate installations that use that wallet, you need only perform these steps once to the shared wallet. You do not need to stop the Oracle GoldenGate processes.

If the wallet is not on central storage (meaning there is a copy on each Oracle GoldenGate system) you can do one of the following:

If you can stop the Oracle GoldenGate processes, you only need to perform the steps to change the wallet once and then copy the updated wallet to the other systems before restarting the Oracle GoldenGate processes.
If you cannot stop the Oracle GoldenGate processes, you must perform the steps to change the wallet on each system, making certain to perform them exactly the same way on each one.

These steps include prompts for both scenarios.

On the source system, issue the following command to determine the versions of the master key that you want to delete. Typically, the oldest versions should be the ones deleted. Make a record of these versions.
```
INFO MASTERKEY
```
On the source system, issue the following command to open the wallet.
```
OPEN WALLET
```
Issue the following command to delete the stale master keys. Options are available to delete a specific version, a range of versions, or all versions including the current one. To delete all of the versions, transaction activity and the Oracle GoldenGate processes must be stopped.
```
DELETE MASTERKEY {VERSION version | RANGE FROM begin_value TO end_value}
```
Note:

DELETE MASTERKEY marks the key versions for deletion but does not actually delete them.
Review the messages returned by the DELETE MASTERKEY command to ensure that the correct versions were marked for deletion. To unmark any version that was marked erroneously, use the UNDELETE MASTERKEY VERSION version command before proceeding with these steps. If desired, you can confirm the marked deletions with the INFO MASTERKEY command.
When you are satisfied that the correct versions are marked for deletion, issue the following command to purge them from the wallet. This is a permanent deletion and cannot be undone.
```
PURGE WALLET
```
Next steps:
- If the wallet resides on shared storage, you are done with these steps.
- If there is a wallet on each system and you cannot stop the Oracle GoldenGate processes, repeat the preceding steps on each Oracle GoldenGate system.
- If there is a wallet on each system and you can stop the Oracle GoldenGate processes, continue with these steps to stop the processes and copy the wallet to the other systems in the correct order.
Stop Extract.
```
STOP EXTRACT group
```
In GGSCI, issue the following command for each data pump Extract until each returns At EOF, indicating that all of the data in the local trail has been processed.
```
SEND EXTRACT group STATUS
```
Stop the data pumps.
```
STOP EXTRACT group
```
On the target systems, issue the following command for each Replicat until it returns At EOF.
```
SEND REPLICAT group STATUS
```
Stop the Replicat groups.
```
STOP REPLICAT group
```
Copy the updated wallet from the source system to the same location as the old wallet on all of the target systems.
Restart Extract.
```
START EXTRACT group
```
Restart the data pumps.
```
START EXTRACT group
```
Restart Replicat.
```
START REPLICAT group
```

Parent topic: Encrypting Data with the Master Key and Wallet Method