Using the Vault Facility with the XA Open String

The XA open string required to connect to a database instance might contain sensitive information. When it does, you can hide that sensitive information using the Micro Focus Vault Facility, which enables the storage of data in a secure external source. You can use the vault facility to securely hide entire open strings, or pieces of an open string.

Note: For complete details on using the Micro Focus Vault Facility, see Vault Facility.

The ESXAEXTCFG COBOL program

We provide the ESXAEXTCFG.CBL COBOL program and writeSecrets.bat batch file to use with the vault facility and RM switch modules to obfuscate XA open strings. These files are located by default in the %ProgramFiles(x86)%\Micro Focus\Enterprise Developer\src\enterpriseserver\xa directory.

The steps required are as follows:

Start an Enterprise Developer command prompt.
Copy ESXAEXTCFG.CBL and writeSecrets.bat from the default location to any location where you have WRITE permission.
From the directory containing the copied ESXAEXTCFG.CBL and writeSecrets.bat files, insert the data into the vault by editing writeSecrets.bat, replacing canned values with those used on your system, and then running the batch file.
WriteSecrets.bat runs a series of mfsecretsadmin commands that populate the vault. For more information, see The mfsecretsadmin Utility .
Edit ESXAEXTCFG.cbl to use the secret name that was inserted into the vault. Examples for common configurations have been included in the program.
Compile the ESXAEXTCFG.cbl program using the following command to create an external configuration module:
```
build ext
```
on Windows platforms, or
```
./build ext
```
on UNIX platforms.

This generates the ESXAEXTCFG.dll (Windows) or ESXAEXTCFG.so (UNIX) switch module.
Copy the new ESXAEXTCFG module to a directory on your Windows PATH (Windows) or UNIX LIBRARY PATH (UNIX).
Update the XA open string and start the region.

The ESXAEXTCFG.CBL file contains examples for common usage scenarios such as storing the entire XA string in the vault, storing only the password, or storing a combination of the user ID and password. It also documents return code values on entry and on exit, the initial name/value pair table used on entry, and the use of placeholders.

XA open string placeholders

For replacing pieces of the open string with data from the vault, use placeholders to identify the data to be replaced. For example, within the open string, use &PWD& as the placeholder for a password, or &NAME& as a placeholder elsewhere in the open string, where the text between ampersands (&) matches the text in the name/value pair table. Examples of both XA open strings and corresponding configurations have been provided in the ESXAEXTCFG COBOL program.

Note: When pulling the entire XA string from the vault, placeholders are not recognized because the XA string you provide in the Enterprise Server console is overridden by what is pulled from the vault, meaning it can be any value, including blank.