11 Configuring Oracle GoldenGate Security

This chapter describes how to configure Oracle GoldenGate security.

This chapter includes the following sections:

11.1 Overview of Oracle GoldenGate Security Options

You can use the following security features to protect your Oracle GoldenGate environment and the data that is being processed.

Security Feature	What it Secures	Supported Databases	Description
Data Encryption Two methods are available: Encrypting Data with the Master Key and Wallet Method Encrypting Data with the ENCKEYS Method	Data in the trails or an extract file Data sent across TCP/IP networks	Master key and wallet method is the preferred method on platforms that support it. Not valid for the iSeries, z/OS, and NonStop platforms. `ENCKEYS` method is valid for all Oracle GoldenGate-supported databases and platforms. Blowfish must be used on the iSeries, z/OS, and NonStop platforms.	Encrypts the data in files, across data links, and across TCP/IP. Use any of the following: Any Advanced Encryption Security (AES)^Foot 1 cipher: AES-128 AES-192 AES-256 Blowfish^Foot 2
Credential Store Identity Management See Managing Identities in a Credential Store.	User IDs and passwords (credentials) assigned to Oracle GoldenGate processes to log into a database.	Credential store is the preferred password management method on platforms that support it. Not valid on the iSeries, z/OS, and NonStop platforms.	User credentials are maintained in secure wallet storage. Aliases for the credentials are specified in commands and parameters.
Password Encryption See Encrypting a Password in a Command or Parameter File.	Passwords specified in commands and parameter files that are used by Oracle GoldenGate processes to log into a database.	Valid for all Oracle GoldenGate-supported databases and platforms. Blowfish must be used on the iSeries, z/OS, and NonStop platforms. On other platforms, the credential store is the preferred password-management method.	Encrypts a password and then provides for specifying the encrypted password in the command or parameter input. Use any of the following: AES-128 AES-192 AES-256 Blowfish
Command Authentication See Configuring GGSCI Command Security.	Oracle GoldenGate commands issued through GGSCI.	Valid for all Oracle GoldenGate-supported databases and platforms.	Stores authentication permissions in an operating-system-secured file. Configure a `CMDSEC` (Command Security) file.
Trusted Connection See Using Target System Connection Initiation.	TCP/IP connection to untrusted Oracle GoldenGate host machines that are outside a firewall.	Valid for all Oracle GoldenGate-supported databases and platforms.	Use any of the following: AES-128 AES-192 AES-256 Blowfish
Manager Security	Access rules for Manager.	Valid for all Oracle GoldenGate-supported databases and platforms.	You can secure the following: `GGSCI`: Secures access to the GGSCI command-line interface. `GUI`: Secures access to Oracle GoldenGate from the Activity Console. `MGR \| MANAGER`: Secures access to all inter-process commands controlled by Manager, such as `START`, `STOP`, and `KILL` `REPLICAT`: Secures connection to the Replicat process. `COLLECTOR \| SERVER`: Secures the ability to dynamically create a Collector process.
CryptoEngine	Allows you to select the cryptographic library that better suits your needs: Portability (Classic), Portability and compliance with FIPS-140 standard (FIPS140), or enhanced throughput (Native).	Valid for all Oracle GoldenGate-supported databases and platforms (Classic and FIPS140). Valid for all Oracle GoldenGate-supported databases on Linux.x64 and Windows.x64 (Native).	Selects which cryptographic library the Oracle GoldenGate processes will use.

^Footnote 1

Advanced Encryption Standard (AES) is a symmetric-key encryption standard that is used by governments and other organizations that require a high degree of data security. It offers three 128-bit block-ciphers: a 128-bit key cipher, a 192-bit key cipher, and a 256-bit key cipher. To use AES for any database other than Oracle on a 32-bit platform, the path to the lib sub-directory of the Oracle GoldenGate installation directory must be set with the LD_LIBRARY_PATH or SHLIB_PATH variable (UNIX) or the PATH variable (Windows). Not required for 64-bit platforms.

^Footnote 2

Blowfish encryption: A keyed symmetric-block cipher. The Oracle GoldenGate implementation of Blowfish has a 64-bit block size with a variable-length key size from 32 bits to 256 bits.

Parent topic: Configuring Oracle GoldenGate Security

11.2 Encrypting Data with the Master Key and Wallet Method

To use this method of data encryption, you create a master-key wallet and add a master key to the wallet. This method works as follows, depending on whether the data is encrypted in the trails or across TCP/IP:

Each time Oracle GoldenGate creates a trail file, it generates a new encryption key automatically. This encryption key encrypts the trail contents. The master key encrypts the encryption key. This process of encrypting encryption keys is known as key wrap and is described in standard ANS X9.102 from American Standards Committee.
To encrypt data across the network, Oracle GoldenGate generates a session key using a cryptographic function based on the master key.

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

Encrypting data with a master key and wallet is not supported on the iSeries, z/OS or NonStop platforms.

This section guides you through the following tasks:

Creating the Wallet and Adding a Master Key

Specifying Encryption Parameters in the Parameter File

Renewing the Master Key

Deleting Stale Master Keys

Parent topic: Configuring Oracle GoldenGate Security

11.2.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. (See Working with the GLOBALS File for more information about the GLOBALS file.)
```
WALLETLOCATION directory_path
```
Create a master-key wallet with the CREATE WALLET command in GGSCI.
```
CREATE WALLET
```
Add a master key to the wallet with the ADD MASTERKEY command in GGSCI.
```
ADD MASTERKEY
```
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.
```
INFO MASTERKEY
```
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 and compare the AES hash value with the one that you originally recorded. All wallets must show identical key versions and hash values.
```
INFO MASTERKEY VERSION version
```

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

11.2.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 | BLOWFISH} 
```
- To encrypt data across TCP/IP: 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 | BLOWFISH}

RMTHOSTOPTIONS ENCRYPT {AES128 | AES192 | AES256 | BLOWFISH}
```
Where:
- RMTHOSTOPTIONS is used for Extract including passive extracts. See Using Target System Connection Initiation for more information about passive Extract.
- 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.
- BLOWFISH uses Blowfish encryption with a 64-bit block size and a variable-length key size from 32 bits to 128 bits. Use AES if supported for the platform. Use BLOWFISH for backward compatibility with earlier Oracle GoldenGate versions, and for DB2 on z/OS, DB2 for i, and SQL/MX on NonStop. AES is not supported on those platforms.
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.)
```
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.

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

11.2.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 for more information.

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 must be stopped. This procedure includes steps for performing those tasks in the correct order.

Stop Extract.
```
STOP EXTRACT group
```
On the target systems, issue the following command for each Replicat until it returns At EOF.
```
SEND REPLICAT group STATUS
```
On the source system, stop the data pumps.
```
STOP EXTRACT group
```
On the target systems, stop the Replicat groups.
```
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

11.2.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

11.3 Encrypting Data with the ENCKEYS Method

To use this method of data encryption, you configure Oracle GoldenGate to generate an encryption key and store the key in a local ENCKEYS file. This method makes use of a permanent key that can only be changed by regenerating the algorithm according to the instructions in Populating an ENCKEYS File with Encryption Keys. The ENCKEYS file must be secured through the normal method of assigning file permissions in the operating system.

This procedure generates an AES encryption key and provides instructions for storing it in the ENCKEYS file.

Parent topic: Configuring Oracle GoldenGate Security

11.3.1 Encrypting the Data with the ENCKEYS Method

Generate an encryption key and store it in the ENCKEYS file. See Populating an ENCKEYS File with Encryption Keys. Make certain to copy the finished ENCKEYS file to the Oracle GoldenGate installation directory on any intermediary systems and all target systems.
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 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 one of the following:
```
ENCRYPTTRAIL {AES128 | AES192 | AES256 | BLOWFISH}  
```
```
ENCRYPTTRAIL AES192, KEYNAME keyname
```
- To encrypt data across TCP/IP: In the RMTHOSTOPTIONS parameter in the parameter file of the data pump (or the primary Extract, if no pump is being used), add the ENCRYPT option with the KEYWORD clause. The syntax is one of the following:
```
RMTHOSTOPTIONS host, MGRPORT port, ENCRYPT {AES128 | AES192 | AES256 | BLOWFISH} KEYNAME keyname
```
```
RMTHOSTOPTIONS ENCRYPT {AES128 | AES192 | AES256 | BLOWFISH} KEYNAME keyname
```
Where:
- RMTHOSTOPTIONS is used for Extract. See Using Target System Connection Initiation for more information about passive Extract.
- ENCRYPTTRAIL without options uses AES128 as the default for all database types except the iSeries, z/OS, and NonStop platforms, where BLOWFISH is the default.
- AES128 encrypts with the AES-128 encryption algorithm. Not supported for iSeries, z/OS, and NonStop platforms.
- AES192 encrypts with AES-192 encryption algorithm. Not supported for iSeries, z/OS, and NonStop platforms.
- AES256 encrypts with AES-256 encryption algorithm. Not supported for iSeries, z/OS, and NonStop platforms.
- BLOWFISH uses Blowfish encryption with a 64-bit block size and a variable-length key size from 32 bits to 128 bits. Use AES if supported for the platform. Use BLOWFISH for backward compatibility with earlier Oracle GoldenGate versions, and for DB2 on z/OS, DB2 for i, and SQL/MX on NonStop. AES is not supported on those platforms.
- KEYNAME keyname specifies the logical look-up name of an encryption key in the ENCKEYS file. Not an option of ENCRYPTTRAIL.
  
  Note:
  
  RMTHOST is used unless the Extract is in a passive configuration. See Using Target System Connection Initiation for more information.
If using a static Collector with data encrypted over TCP/IP, append the following parameters in the Collector startup string:
```
-KEYNAME keyname
-ENCRYPT algorithm
```
The specified key name and algorithm must match those specified with the KEYNAME and ENCRYPT options of RMTHOST.

Parent topic: Encrypting Data with the ENCKEYS Method

11.3.2 Decrypting the Data with the ENCKEYS Method

Data that is encrypted over TCP/IP connections is decrypted automatically at the destination before it is written to a trail, unless trail encryption also is specified.

Data that is encrypted in the trail remains encrypted unless the DECRYPTTRAIL parameter is used. DECRYPTTRAIL is required by Replicat before it can apply encrypted data to the target. A data pump passes encrypted data untouched to the output trail, unless the DECRYPTTRAIL and ENCRYPTTRAIL parameters are used. If the data pump must perform work on the data, decrypt and encrypt the data as follows.

To Decrypt Data for Processing by a Data Pump

Add the DECRYPTTRAIL parameter to the parameter file of the data pump. The decryption algorithm and key must match the ones that were used to encrypt the trail (see Encrypting the Data with the ENCKEYS Method).

DECRYPTTRAIL {AES128 | AES192 | AES256 | BLOWFISH}

To Encrypt Data After Processing by a Data Pump

To encrypt data before the data pump writes it to an output trail or file, use the ENCRYPTTRAIL parameter before the parameters that specify those trails or files. Parameters that specify trails or files are EXTTRAIL, RMTTRAIL, EXTFILE, and RMTFILE. The ENCRYPTTRAIL parameter and the trail or file specifications must occur after the DECRYPTTRAIL parameter. See Encrypting the Data with the ENCKEYS Method.

Note:

The algorithm specified with ENCRYPTTRAIL can vary from trail to trail. For example, you can use AES 128 to encrypt a local trail and AES 256 to encrypt a remote trail.

To Decrypt Data for Processing by Replicat

If a trail that Replicat reads is encrypted, add a DECRYPTTRAIL parameter statement to the Replicat parameter file. The decryption algorithm and key must match the ones that were used to encrypt the trail. See Encrypting the Data with the ENCKEYS Method.

Parent topic: Encrypting Data with the ENCKEYS Method

11.3.3 Examples of Data Encryption using the ENCKEYS Method

The following example shows how to turn encryption on and off for different trails or files. In this example, Extract writes to two local trails, only one of which must be encrypted.

In the Extract configuration, trail bb is the non-encrypted trail, so its EXTTRAIL parameter is placed before the ENCRYPTTRAIL parameter that encrypts trail aa. Alternatively, you can use the NOENCRYPTTRAIL parameter before the EXTTRAIL parameter that specifies trail bb and then use the ENCRYPTTRAIL parameter before the EXTTRAIL parameter that specifies trail aa.

Description of encrypt_trail_2.jpg follows

Description of the illustration encrypt_trail_2.jpg

In this example, the encrypted data must be decrypted so that data pump 1pump can perform work on it. Therefore, the DECRYPTTRAIL parameter is used in the parameter file of the data pump. To re-encrypt the data for output, the ENCRYPTTRAIL parameter must be used after DECRYPTTRAIL but before the output trail specification(s). If the data pump did not have to perform work on the data, the DECRYPTTRAIL and ENCRYPTTRAIL parameters could have been omitted to retain encryption all the way to Replicat.

Example 11-1 Extract Parameter File

EXTRACT capt
USERIDALIAS ogg
DISCARDFILE /ogg/capt.dsc, PURGE
-- Do not encrypt this trail.
EXTTRAIL /ogg/dirdat/bb
TABLE SALES.*;
-- Encrypt this trail with AES-192.
ENCRYPTTRAIL AES192
EXTTRAIL /ogg/dirdat/aa
TABLE FIN.*;

Example 11-2 Data Pump 1 Parameter File

EXTRACT 1pump
USERIDALIAS ogg
DISCARDFILE /ogg/1pmp.dsc, PURGE
-- Decrypt the trail this pump reads. Use encryption key mykey1.
DECRYPTTRAIL AES192
-- Encrypt the trail this pump writes to, using AES-192.
RMTHOSTOPTIONS myhost1, MGRPORT 7809
ENCRYPTTRAIL AES192
RMTTRAIL /ogg/dirdat/cc
TABLE FIN.*;

Example 11-3 Data pump 2 Parameter File

EXTRACT 2pump
USERIDALIAS ogg
DISCARDFILE /ogg/2pmp.dsc, PURGE
RMTHOST myhost2, MGRPORT 7809
RMTTRAIL /ogg/dirdat/dd
TABLE SALES.*;

Example 11-4 Replicat1 (on myhost1) Parameter File

REPLICAT 1deliv
USERIDALIAS ogg
ASSUMETARGETDEFS
DISCARDFILE /ogg/1deliv.dsc, PURGE
-- Decrypt the trail this Replicat reads. Use encryption key mykey2.
DECRYPTTRAIL AES192
MAP FIN.*, TARGET FIN.*;

Example 11-5 Replicat 2 (on myhost2) parameter file

REPLICAT 2deliv
USERIDALIAS ogg
ASSUMETARGETDEFS
DISCARDFILE /ogg/2deliv.dsc, PURGE
MAP SALES.*, TARGET SALES.*;

Parent topic: Encrypting Data with the ENCKEYS Method

11.4 Managing Identities in a Credential Store

This section shows how to use an Oracle GoldenGate credential store to maintain encrypted database passwords and user IDs and associate them with an alias. It is the alias, not the actual user ID or password, that is specified in a command or parameter file, and no user input of an encryption key is required. The credential store is implemented as an autologin wallet within the Oracle Credential Store Framework (CSF).

Another benefit of using a credential store is that multiple installations of Oracle GoldenGate can use the same one, while retaining control over their local credentials. You can partition the credential store into logical containers known as domains, for example, one domain per installation of Oracle GoldenGate. Domains enable you to develop one set of aliases (for example ext for Extract, rep for Replicat) and then assign different local credentials to those aliases in each domain. For example, credentials for user ogg1 can be stored as ALIAS ext under DOMAIN system1, while credentials for user ogg2 can be stored as ALIAS ext under DOMAIN system2.

The credential store security feature is not supported on the iSeries, z/OS, and NonStop platforms. For those platforms, as well as any other supported platforms, see Encrypting a Password in a Command or Parameter File.

Using a credential store involves these steps:

Parent topic: Configuring Oracle GoldenGate Security

11.4.1 Creating and Populating the Credential Store

(Optional) To store the credential store in a location other than the dircrd subdirectory of the Oracle GoldenGate installation directory, specify the desired location with the CREDENTIALSTORELOCATION parameter in the GLOBALS file. (See Working with the GLOBALS File for more information about the GLOBALS file.)
From the Oracle GoldenGate installation directory, run GGSCI.
Issue the following command to create the credential store.
```
ADD CREDENTIALSTORE
```
Issue the following command to add each set of credentials to the credential store.
```
ALTER CREDENTIALSTORE ADD USER userid,
  [PASSWORD password]
  [ALIAS alias]
  [DOMAIN domain]
```
Where:
- userid is the user name. Only one instance of a user name can exist in the credential store unless the ALIAS or DOMAIN option is used.
- password is the password. The password is echoed (not obfuscated) when this option is used. For security reasons, it is recommended that you omit this option and allow the command to prompt for the password, so that it is obfuscated as it is entered.
- alias is an alias for the user name. The alias substitutes for the credential in parameters and commands where a login credential is required. If the ALIAS option is omitted, the alias defaults to the user name. If you do not want user names in parameters or command input, use ALIAS and specify a different name from that of the user.
- domain is the domain that is to contain the specified alias. The default domain is Oracle GoldenGate.

For more information about the commands used in this procedure and additional credential store commands, see Reference for Oracle GoldenGate for Windows and UNIX.

Parent topic: Managing Identities in a Credential Store

11.4.2 Specifying the Alias in a Parameter File or Command

The following commands and parameters accept an alias as substitution for a login credential.

Table 11-1 Specifying Credential Aliases in Parameters and Commands

Purpose of the Credential	Parameter or Command to Use
Oracle GoldenGate database login^Foot 3	USERIDALIAS alias
Oracle GoldenGate database login for Oracle ASM instance	TRANLOGOPTIONS ASMUSERALIAS alias
Oracle GoldenGate database login for a downstream Oracle mining database	TRANLOGOPTIONS MININGUSERALIAS alias
Password substitution for `{CREATE \| ALTER} USER` `name` `IDENTIFIED BY` `password`	DDLOPTIONS DEFAULTUSERPASSWORDALIAS alias
Oracle GoldenGate database login from GGSCI	DBLOGIN USERIDALIAS alias
Oracle GoldenGate database login to a downstream Oracle mining database from GGSCI	MININGDBLOGIN USERIDALIAS alias

^Footnote 3

Syntax elements required for USERIDALIAS vary by database type. See Reference for Oracle GoldenGate for Windows and UNIX for more information.

Parent topic: Managing Identities in a Credential Store

11.5 Encrypting a Password in a Command or Parameter File

This section shows how to encrypt a database password that is to be specified in a command or parameter file. This method takes a clear-text password as input and produces an obfuscated password string and a lookup key, both of which can then be used in the command or parameter file. This encryption method supports all of the databases that require a login for an Oracle GoldenGate process to access the database.

Depending on the database, you may be able to use a credential store as an alternative to this method. See Managing Identities in a Credential Store.

Using an encrypted password in a command or parameter file involves these steps:

Parent topic: Configuring Oracle GoldenGate Security

11.5.1 Encrypting the Password

Run GGSCI.
Issue the ENCRYPT PASSWORD command.
```
ENCRYPT PASSWORD password algorithm ENCRYPTKEY {key_name | DEFAULT}
```
Where:
- password is the clear-text login password. Do not enclose the password within quotes. If the password is case-sensitive, type it that way.
- algorithm specifies the encryption algorithm to use:
  - AES128 uses the AES-128 cipher, which has a key size of 128 bits.
  - AES192 uses the AES-192 cipher, which has a key size of 192 bits.
  - AES256 uses the AES-256 cipher, which has a key size of 256 bits.
  - BLOWFISH uses Blowfish encryption with a 64-bit block size and a variable-length key size from 32 bits to 128 bits. Use AES if supported for the platform. Use BLOWFISH for backward compatibility with earlier Oracle GoldenGate versions, and for DB2 on z/OS, DB2 for i, and SQL/MX on NonStop. AES is not supported on those platforms.
- ENCRYPTKEY key_name specifies the logical name of a user-created encryption key in the ENCKEYS lookup file. The key name is used to look up the actual key in the ENCKEYS file. Using a user-defined key and an ENCKEYS file is required for AES encryption. To create a key and ENCKEYS file, see Populating an ENCKEYS File with Encryption Keys.
- ENCRYPTKEY DEFAULT directs Oracle GoldenGate to generate a predefined Blowfish key. This type of key is insecure and should not be used in a production environment if the platform supports AES. Use this option only for DB2 on /OS, DB2 for i, and SQL/MX when BLOWFISH is specified. ENCRYPT PASSWORD returns an error if AES is used with DEFAULT.
  
  If no algorithm is specified, AES128 is the default for all database types except DB2 on z/OS and NonStop SQL/MX, where BLOWFISH is the default.
The following are examples of ENCRYPT PASSWORD with its various options.
```
ENCRYPT PASSWORD mypassword AES256 ENCRYPTKEY mykey1
ENCRYPT PASSWORD mypassword BLOWFISH ENCRYPTKEY mykey1
ENCRYPT PASSWORD mypassword BLOWFISH ENCRYPTKEY DEFAULT
```
The encrypted password is output to the screen when you run the ENCRYPT PASSWORD command. Copy the encrypted password and then see Specifying the Encrypted Password in a Parameter File or Command for instructions on pasting it to a command or parameter.

Parent topic: Encrypting a Password in a Command or Parameter File

11.5.2 Specifying the Encrypted Password in a Parameter File or Command

Copy the encrypted password that you generated with the ENCRYPT PASSWORD command (see Encrypting a Password in a Command or Parameter File), and then paste it into the appropriate Oracle GoldenGate parameter statement or command as shown in Table 11-2. Option descriptions follow the table.

Table 11-2 Specifying Encrypted Passwords in Parameters and Commands

Purpose of the Password	Parameter or Command to Use
Oracle GoldenGate database login^Foot 4	USERID user, PASSWORD password, & algorithm ENCRYPTKEY {keyname \| DEFAULT}
Oracle GoldenGate database login for Oracle ASM instance	TRANLOGOPTIONS ASMUSER SYS@ASM_instance_name, & ASMPASSWORD password, & algorithm ENCRYPTKEY {keyname \| DEFAULT}
Oracle GoldenGate database login for a downstream Oracle mining database	[MININGUSER {/ \| user}[, MININGPASSWORD password]& [algorithm ENCRYPTKEY {key_name \| DEFAULT}]& [SYSDBA]]
Password substitution for `{CREATE \| ALTER} USER` `name` `IDENTIFIED BY` `password`	DDLOPTIONS DEFAULTUSERPASSWORD password & algorithm ENCRYPTKEY {keyname \| DEFAULT}
Oracle TDE shared-secret password	DBOPTIONS DECRYPTPASSWORD password^{Foot 5} algorithm & ENCRYPTKEY {keyname \| DEFAULT}
Oracle GoldenGate database login from GGSCI	DBLOGIN USERID user, PASSWORD password, & algorithm ENCRYPTKEY {keyname \| DEFAULT}
Oracle GoldenGate database login to a downstream Oracle mining database from GGSCI	MININGDBLOGIN USERID user, PASSWORD password,& algorithm ENCRYPTKEY {keyname \| DEFAULT}

^Footnote 4

Syntax elements required for USERID vary by database type. See Reference for Oracle GoldenGate for Windows and UNIX for more information.

^Footnote 5

This is the shared secret.

Where:

user is the database user name for the Oracle GoldenGate process or (Oracle only) a host string. For Oracle ASM, the user must be SYS.
password is the encrypted password that is copied from the ENCRYPT PASSWORD command results.
algorithm specifies the encryption algorithm that was used to encrypt the password: AES128, AES192, AES256, or BLOWFISH. AES128 is the default if the default key is used and no algorithm is specified.
ENCRYPTKEY keyname specifies the logical name of a user-created encryption key in the ENCKEYS lookup file. Use if ENCRYPT PASSWORD was used with the KEYNAME keyname option.
ENCRYPTKEY DEFAULT directs Oracle GoldenGate to use a random key. Use if ENCRYPT PASSWORD was used with the KEYNAME DEFAULT option.

The following are examples of using an encrypted password in parameters and command:

SOURCEDB db1 USERID ogg,&
PASSWORD AACAAAAAAAAAAAJAUEUGODSCVGJEEIUGKJDJTFNDKEJFFFTC, &
AES128, ENCRYPTKEY securekey1

USERID ogg, PASSWORD AACAAAAAAAAAAAJAUEUGODSCVGJEEIUGKJDJTFNDKEJFFFTC, &
BLOWFISH, ENCRYPTKEY securekey1

USERID ogg, PASSWORD AACAAAAAAAAAAAJAUEUGODSCVGJEEIUGKJDJTFNDKEJFFFTC, &
BLOWFISH, ENCRYPTKEY DEFAULT

TRANLOGOPTIONS ASMUSER SYS@asm1, &
ASMPASSWORD AACAAAAAAAAAAAJAUEUGODSCVGJEEIUGKJDJTFNDKEJFFFTC, &
AES128, ENCRYPTKEY securekey1

DBLOGIN USERID ogg, PASSWORD &
AACAAAAAAAAAAAJAUEUGODSCVGJEEIUGKJDJTFNDKEJFFFTC, &
AES128, ENCRYPTKEY securekey1

DDLOPTIONS DEFAULTUSERPASSWORD &
AACAAAAAAAAAAAJAUEUGODSCVGJEEIUGKJDJTFNDKEJFFFTC, &
AES 256 ENCRYPTKEY mykey

DBOPTIONS DECRYPTPASSWORD AACAAAAAAAAAAAJAUEUGODSCVGJEEIUGKJDJTFNDKEJFFFTC, &
AES 256 ENCRYPTKEY mykey

DDLOPTIONS PASSWORD AACAAAAAAAAAAAJAUEUGODSCVGJEEIUGKJDJTFNDKEJFFFTC, &
AES 256 ENCRYPTKEY mykey

Parent topic: Encrypting a Password in a Command or Parameter File

11.6 Populating an ENCKEYS File with Encryption Keys

You must generate and store encryption keys when using the following security features:

ENCRYPTTRAIL (see Encrypting Data with the ENCKEYS Method)
ENCRYPT PASSWORD with ENCRYPTKEY keyname (see Encrypting a Password in a Command or Parameter File)
RMTHOST or RMTHOSTOPTIONS with ENCRYPT (see Encrypting Data with the ENCKEYS Method)

In this procedure you will:

Create one or more encryption keys.
Store the keys in an ENCKEYS lookup file on the source system.
Copy the ENCKEYS file to each target system.

You can define your own key or run the Oracle GoldenGate KEYGEN utility to create a random key.

Parent topic: Configuring Oracle GoldenGate Security

11.6.1 Defining Your Own Key

Use a tool of your choice. The key value can be up to 256 bits (32 bytes) as either of the following:

a quoted alphanumeric string (for example "Dailykey")
a hex string with the prefix 0x (for example 0x420E61BE7002D63560929CCA17A4E1FB)

Parent topic: Populating an ENCKEYS File with Encryption Keys

11.6.2 Using KEYGEN to Generate a Key

Change directories to the Oracle GoldenGate home directory on the source system, and issue the following shell command. You can create multiple keys, if needed. The key values are returned to your screen. You can copy and paste them into the ENCKEYS file.

KEYGEN key_length n

Where:

key_length is the encryption key length, up to 256 bits (32 bytes).
n represents the number of keys to generate.

Example:

KEYGEN 128 4

Parent topic: Populating an ENCKEYS File with Encryption Keys

11.6.3 Creating and Populating the ENCKEYS Lookup File

On the source system, open a new ASCII text file.

For each key value that you generated, enter a logical name of your choosing, followed by the key value itself.

The key name can be a string of 1 to 24 alphanumeric characters without spaces or quotes.
Place multiple key definitions on separate lines.

Do not enclose a key name or value within quotes; otherwise it will be interpreted as text.

Use the following sample ENCKEYS file as a guide.

Encryption key name	Encryption key value
## Key name superkey secretkey superkey1 superkey2 superkey3	Key value 0x420E61BE7002D63560929CCA17A4E1FB 0x027742185BBF232D7C664A5E1A76B040 0x42DACD1B0E94539763C6699D3AE8E200 0x0343AD757A50A08E7F9A17313DBAB045 0x43AC8DCE660CED861B6DC4C6408C7E8A

Encryption key name

Encryption key value

## Key name
superkey
secretkey
superkey1
superkey2
superkey3

Key value
0x420E61BE7002D63560929CCA17A4E1FB
0x027742185BBF232D7C664A5E1A76B040
0x42DACD1B0E94539763C6699D3AE8E200
0x0343AD757A50A08E7F9A17313DBAB045
0x43AC8DCE660CED861B6DC4C6408C7E8A

Save the file as the name ENCKEYS in all upper case letters, without an extension, in the Oracle GoldenGate installation directory.
Copy the ENCKEYS file to the Oracle GoldenGate installation directory on every system. The key names and values in all of the ENCKEYS files must be identical, or else the data exchange will fail and Extract and Collector will abort with the following message:
```
GGS error 118 – TCP/IP Server with invalid data.
```

Parent topic: Populating an ENCKEYS File with Encryption Keys

11.7 Configuring GGSCI Command Security

You can establish command security for Oracle GoldenGate to control which users have access to which Oracle GoldenGate functions. For example, you can allow certain users to issue INFO and STATUS commands, while preventing their use of START and STOP commands. Security levels are defined by the operating system's user groups.

To implement security for Oracle GoldenGate commands, you create a CMDSEC file in the Oracle GoldenGate directory. Without this file, access to all Oracle GoldenGate commands is granted to all users.

Note:

The security of the ggsci program itself is controlled by the security controls of the operating system.

Parent topic: Configuring Oracle GoldenGate Security

11.7.1 Setting Up Command Security

Open a new ASCII text file.
Referring to the following syntax and the example on , create one or more security rules for each command that you want to restrict, one rule per line. List the rules in order from the most specific (those with no wildcards) to the least specific. Security rules are processed from the top of the CMDSEC file downward. The first rule satisfied is the one that determines whether or not access is allowed.
Separate each of the following components with spaces or tabs.
```
command_name command_object OS_group OS_user {YES | NO}
```
Where:
- command_name is a GGSCI command name or a wildcard, for example START or STOP or *.
- command_object is any GGSCI command object or a wildcard, for example EXTRACT or REPLICAT or MANAGER.
- OS_group is the name of a Windows or UNIX user group. On a UNIX system, you can specify a numeric group ID instead of the group name. You can use a wildcard to specify all groups.
- OS_user is the name of a Windows or UNIX user. On a UNIX system, you can specify a numeric user ID instead of the user name. You can use a wildcard to specify all users.
- YES | NO specifies whether access to the command is granted or prohibited.
Save the file as CMDSEC (using upper case letters on a UNIX system) in the Oracle GoldenGate home directory.

The following example illustrates the correct implementation of a CMDSEC file on a UNIX system.

Table 11-3 Sample CMDSEC File with Explanations

File Contents	Explanation
#GG command security	Comment line
STATUS REPLICAT * Smith NO	`STATUS REPLICAT` is denied to user `Smith`.
STATUS * dpt1 * YES	Except for the preceding rule, all users in `dpt1` are granted all `STATUS` commands.
START REPLICAT root * YES	`START REPLICAT` is granted to all members of the `root` group.
START REPLICAT * * NO	Except for the preceding rule, `START REPLICAT` is denied to all users.
* EXTRACT 200 * NO	All `EXTRACT` commands are denied to all groups with ID of 200.
* * root root YES	Grants the `root` user any command.
* * * * NO	Denies all commands to all users. This line covers security for any other users that were not explicitly granted or denied access by preceding rules. Without it, all commands would be granted to all users except for preceding explicit grants or denials.

The following incorrect example illustrates what to avoid when creating a CMDSEC file.

Table 11-4 Incorrect CMDSEC Entries

File Contents	Description
STOP * dpt2 * NO	All `STOP` commands are denied to everyone in group `dpt2`.
STOP * * Chen YES	All `STOP` commands are granted to `Chen`.

The order of the entries in Table 11-4 causes a logical error. The first rule (line 1) denies all STOP commands to all members of group dpt2. The second rule (line 2) grants all STOP commands to user Chen. However, because Chen is a member of the dpt2 group, he has been denied access to all STOP commands by the second rule, even though he is supposed to have permission to issue them.

The proper way to configure this security rule is to set the user-specific rule before the more general rule(s). Thus, to correct the error, you would reverse the order of the two STOP rules.

Parent topic: Configuring GGSCI Command Security

11.7.2 Securing the CMDSEC File

The security of the GGSCI program and that of the CMDSEC file is controlled by the security controls of the operating system. Because the CMDSEC file is a source of security, it must be secured. You can grant read access as needed, but Oracle GoldenGate recommends denying write and delete access to everyone but Oracle GoldenGate Administrators.

Parent topic: Configuring GGSCI Command Security

11.8 Using Target System Connection Initiation

When a target system resides inside a trusted intranet zone, initiating connections from the source system (the standard Oracle GoldenGate method) may violate security policies if the source system is in a less trusted zone. It also may violate security policies if a system in a less trusted zone contains information about the ports or IP address of a system in the trusted zone, such as that normally found in an Oracle GoldenGate Extract parameter file.

In this kind of intranet configuration, you can use a passive-alias Extract configuration. Connections are initiated from the target system inside the trusted zone by an alias Extract group, which acts as an alias for a regular Extract group on the source system, known in this case as the passive Extract. Once a connection between the two systems is established, data is processed and transferred across the network by the passive Extract group in the usual way.

Figure 11-1 Connection Initiation from Trusted Network Zone

Description of "Figure 11-1 Connection Initiation from Trusted Network Zone"

An Oracle GoldenGate user starts the alias Extract on the trusted system, or an AUTOSTART or AUTORESTART parameter causes it to start.
GGSCI on the trusted system sends a message to Manager on the less trusted system to start the associated passive Extract. The host name or IP address and port number of the Manager on the trusted system are sent to the less trusted system.
On the less trusted system, Manager starts the passive Extract, and the passive Extract finds an open port (according to rules in the DYNAMICPORTLIST Manager parameter) and listens on that port.
The Manager on the less trusted system returns that port to GGSCI on the trusted system.
GGSCI on the trusted system sends a request to the Manager on that system to start a Collector process on that system.
The target Manager starts the Collector process and passes it the port number where Extract is listening on the less trusted system.
Collector on the trusted system opens a connection to the passive Extract on the less trusted system.
Data is sent across the network from the passive Extract to the Collector on the target and is written to the trail in the usual manner for processing by Replicat.

Parent topic: Configuring Oracle GoldenGate Security

11.8.1 Configuring the Passive Extract Group

The passive Extract group on the less trusted source system will be one of the following, depending on which one is responsible for sending data across the network:

A solo Extract group that reads the transaction logs and also sends the data to the target, or:
A data pump Extract group that reads a local trail supplied by a primary Extract and then sends the data to the target. In this case, there are no special configuration requirements for the primary Extract, just the data pump.

To create an Extract group in passive mode, use the standard ADD EXTRACT command and options, but add the PASSIVE keyword in any location relative to other command options. Examples:

ADD EXTRACT fin, TRANLOG, BEGIN NOW, PASSIVE, DESC 'passive Extract'
ADD EXTRACT fin, PASSIVE, TRANLOG, BEGIN NOW, DESC 'passive Extract'

To configure parameters for the passive Extract group, create a parameter file in the normal manner, except:

Exclude the RMTHOST parameter, which normally would specify the host and port information for the target Manager.
Use the optional RMTHOSTOPTIONS parameter to specify any compression and encryption rules. For information about the RMTHOSTOPTIONS options, see Reference for Oracle GoldenGate for Windows and UNIX.

For more information about configuring an Extract group, see Configuring Online Change Synchronization.

Parent topic: Using Target System Connection Initiation

11.8.2 Configuring the Alias Extract Group

The alias Extract group on the trusted target does not perform any data processing activities. Its sole purpose is to initiate and terminate connections to the less trusted source. In this capacity, the alias Extract group does not use a parameter file nor does it write processing checkpoints. A checkpoint file is used only to determine whether the passive Extract group is running or not and to record information required for the remote connection.

To create an Extract group in alias mode, use the ADD EXTRACT command without any other options except the following:

ADD EXTRACT group
, RMTHOST {host_name | IP_address}
, MGRPORT port
[, RMTNAME name]
[, DESC 'description']

The RMTHOST specification identifies this group as an alias Extract, and the information is written to the checkpoint file. The host_name and IP_address options specify the name or IP address of the source system. MGRPORT specifies the port on the source system where Manager is running.

The alias Extract name can be the same as that of the passive Extract, or it can be different. If the names are different, use the optional RMTNAME specification to specify the name of the passive Extract. If RMTNAME is not used, Oracle GoldenGate expects the names to be identical and writes the name to the checkpoint file of the alias Extract for use when establishing the connection.

Error handling for TCP/IP connections is guided by the TCPERRS file on the target system. It is recommended that you set the response values for the errors in this file to RETRY. The default is ABEND. This file also provides options for setting the number of retries and the delay between attempts. For more information about error handling for TCP/IP and the TCPERRS file, see Handling Processing Errors.

Parent topic: Using Target System Connection Initiation

11.8.3 Starting and Stopping the Passive and Alias Processes

To start or stop Oracle GoldenGate extraction in the passive-alias Extract configuration, you must start or stop the alias Extract group from GGSCI on the target.

START EXTRACT alias_group_name

or,

STOP EXTRACT alias_group_name

The command is sent to the source system to start or stop the passive Extract group. Do not issue these commands directly against the passive Extract group. You can issue a KILL EXTRACT command directly for the passive Extract group.

When using the Manager parameters AUTOSTART and AUTORESTART to automatically start or restart processes, use them on the target system, not the source system. The alias Extract is started first and then the start command is sent to the passive Extract.

Parent topic: Using Target System Connection Initiation

11.8.4 Managing Extraction Activities

Once extraction processing has been started, you can manage and monitor it in the usual manner by issuing commands against the passive Extract group from GGSCI on the source system. The standard GGSCI monitoring commands, such as INFO and VIEW REPORT, can be issued from either the source or target systems. If a monitoring command is issued for the alias Extract group, it is forwarded to the passive Extract group. The alias Extract group name is replaced in the command with the passive Extract group name. For example, INFO EXTRACT alias becomes INFO EXTRACT passive. The results of the command are displayed on the system where the command was issued.

Parent topic: Using Target System Connection Initiation

11.8.5 Other Considerations when using Passive-Alias Extract

When using a passive-alias Extract configuration, these rules apply:

In this configuration, Extract can only write to one target system.
This configuration can be used in an Oracle RAC installation by creating the Extract group in the normal manner (using the THREADS option to specify the number of redo threads).
The ALTER EXTRACT command cannot be used for the alias Extract, because that group does not do data processing.
To use the DELETE EXTRACT command for a passive or alias Extract group, issue the command from the local GGSCI.
Remote tasks, specified with RMTTASK in the Extract parameter file and used for some initial load methods, are not supported in this configuration. A remote task requires the connection to be initiated from the source system and uses a direct connection between Extract and Replicat.

Parent topic: Using Target System Connection Initiation

11.9 Securing Manager

You can use the Manager parameter, ACCESSRULE, to set security access rules for Manager. It allows GGSCI access from a remote host if you are using passive Extract or Director. ACCESSRULE controls connection access to the Manager process and the processes under its control. You can establish multiple rules by specifying multiple ACCESSRULE statements in the parameter file and control their priority. To establish priority, you can either list the rules in order from most important to least important, or you can explicitly set the priority of each rule with the PRI option.

You must specify one of the following options:

IPADDR, login_ID, or PROGRAM

For example, the following access rules have been assigned explicit priority levels through the PRI option. These rules allow any user to access the Collector process (the SERVER program), and in addition, allow the IP address 122.11.12.13 to access GGSCI commands. Access to all other Oracle GoldenGate programs is denied.

ACCESSRULE, PROG *, DENY, PRI 99
ACCESSRULE, PROG SERVER, ALLOW, PRI 1
ACCESSRULE, PROG GGSCI, IPADDR 122.11.12.13, PRI 1

Another example, the following access rule grants access to all programs to the user JOHN and designates an encryption key to decrypt the password. If the password provided with PASSWORD matches the one in the ENCKEYS lookup file, connection is granted.

ACCESSRULE, PROG *, USER JOHN, PASSWORD OCEAN1, ENCRYPTKEY lookup1

For information about the ACCESSRULE options, see Reference for Oracle GoldenGate for Windows and UNIX

Parent topic: Configuring Oracle GoldenGate Security