Control-D/WebAccess Server SSL Settings

Control‑D works with the Secure Sockets Layer (SSL) and Transport Layer Security (TLS) protocols, which ensures safe and secure communication between Control-D and the Control-D/WebAccess Server. SSL for Control-D authenticates and secures communications for the Control-D/WebAccess Server Web Application and Control-D/WebAccess Server Desktop.

You can enable SSL and configure Control-D/WebAccess Server SSL settings when you do the following:

• Connect the Control-D/WebAccess Server to Control-D Mainframe, as described in Connecting Control-D/WebAccess Server to Control-D Mainframe.

• Customize the Control-D/WebAccess Server, as described in Customizing the Control-D/WebAccess Server.

Encryption with IOAGATE synchronization

Control-D/WebAccess Server and IOAGATE must use the same key file and the same encryption algorithm.

You must manually transmit the generated key file, as described in Generating a Key File, to Control-D Mainframe to establish secure communication. The Control-D/WebAccess Server initiates a checksum request IOAGATE to ensure both sides use an identical key file and encryption algorithm. This process includes verifying the checksum of the key file and confirming the configured encryption algorithm is consistent.

Tt is crucial to use the same key file and maintain uniformity in the encryption algorithm across all connections when multiple Control-D/WebAccess Server hosts connect to the same IOAGATE and port. This ensures secure and consistent communication between the Control-D/WebAccess Server and the Mainframe.

The following procedures describe how to complete the encryption process.

• Generating a Key File

• Generating New Certificates

• Generating Signed Certificates

• Running the update_ssl_settings Utility

Generating a Key File

This procedure describes how to generate a key file, with the bmc-eca-keygen.exe key generator application, which enables you to authenticate, encrypt, or decrypt data, and securing access to information or communication.

Begin

1. Navigate to the following location:

   <installation_folder>\bin

2. Select the bmc-eca-keygen.exe file.

3. From the command line, type the following command:

   bmc-eca-keygen.exe action repository_nameencryption_algorithm variable

4. The bmc-eca-keygen.exe key generator application window appears.

5. For each field, define the required parameters, as described in Key File Parameters.

6. Press Enter.

7. Ensure that the native platform security secures key files.

   The key file is saved in the <installation_folder>\config folder.

Key File Parameters

The following table describes the key file parameters.

Parameter	Description
action	Determines one of the following actions to do: Valid values: GENERATE: Generates a key file. SET: Manually sets a file with one key. SHOW: Displays a key file.
repository_name	Defines the name of the Control-D repository configured in the Control-D/WebAccess Server Desktop.
encryption_algorithm	Determines one of the following encryption algorithms: Valid values: DES: Data Encryption Standard (DES). TDES: Triple Data Encryption Standard (TDES).
variable	Determines the value on the action parameter. Valid values: GENERATE: Determines the number of keys to generate (1-9999). SET: Type a 16 HEXA character (0-9, A-F) key. SHOW: Not applicable.

Generating New Certificates

This procedure describes how to apply your own certificates signed by approved third-parties, which first runs the Manage_SSL_BYO script and then runs the script generated in the deployment directories.

Before you begin

You must already have the signed certificate, its private key, and its CA chain in one of the following formats:

• PEM (Privacy Enhanced Mail) files for each of the following: Certificate, Private Key, and Trusted Root CAs, as described in Generating Signed Certificates.

• PCKS#12 file with the Certificate, private key, and CAs. If the PKCS#12 contains multiple certificates and key pairs, then you must also have available the name of the pair to use, as described in Generating a PKCS12 keystore.

Begin

1. Create a temporary folder in the root directory of the computer where the Control-D/WebAccess Server Web Application resides.

2. In the directories of the deployed components, add one of the following scripts to import your SSL certificates and keys.

   • PEM Format:

     Copy

     Manage_SSL_BYO -input pem
     -component {component name}
     -output {Manage_SSL output deployment directory}
     -output_keystores_password {Component keystore password}
     -certificate {certificate pem file}
     -private_key {certificate private key pem file}
     -password {password for private key pem file}
     -ca_certificates {CA certificate chain PEM file}
     

   • PKCS12 Format

     Copy

     Manage_SSL_BYO -input pkcs12
     -component {component name}
     -output {Manage_SSL output deployment directory}
     -output_keystores_password {Component keystore password}
     -file {pkcs#12 file to import from}
     -password {password of pkcs#12 file}
     [-cert_and_key_name {name of the certificate and private key to import}]

3. Supported -component values include:

   CONTROL-D_WebAccessServer

4. Replace placeholders, such as {component name} and {Manage_SSL output deployment directory} with the appropriate values for your environment.

Certificate copies for Control-D/WebAccess Server

The following table describes the keystore files for Control-D/WebAccess Server to send the directory content to the Control-D Mainframe administrator.

Key store file	Details
IOAGATE.pck12	Exports the certificate for Control-D/WebAccess Server with the key-pair for the IOAGATE in PKCS#12 format to use. The password for the PCKS#12 file is ctm_zos_1202. The default files are located in the following directory: <Installation Path>/config/ssl/ioagte
cacert.pem	Exports the certificate of the Site CA that signed the certificate in PEM format when you define CLIAUTH=YES in IOAGATE, which uses client authentication.

Generating Signed Certificates

This procedure describes how to generate a signed certificate for Control-D/WebAccess Server. BMC recommends that you bring your own certificate.

Begin

1. Navigate to one of the following directories:

   • UNIX: <Product Home Directory>/data/SSL/config

   • Windows: <Product Home Directory>\Data\SSL\config

2. In the csr_params.cfg file, in the [dn] section, change the value of the following fields to the required values:

   • C: example_country.

   • ST: example_state.

   • L: example_locality.

   • O: example_organization.

   • OU: example_unit.

   • CN: example.example.com .

   • emailAddress: [email protected].

3. Ensure that the certificate suffices, by doing the following:

   1. Add the following commands at the end of the file:

      [ req_ext ]

      keyUsage = digitalSignature, keyEncipherment

      extendedKeyUsage = serverAuth, clientAuth

   2. In the [ req ] section, add the following command:

      req_extensions = req_ext

      The csr_params.cfg file is a standard openssl configuration file. Include any requirements from the certificate in this file.

      For more information, see https://www.openssl.org.

4. Create the private key and certificate signing request file by running the following command:

   <Installation Path>/bin/openssl req -new -newkey rsa:2048 -nodes -keyout your_domain.key -out your_domain.csr

5. Define a password.

   The password must be exactly eight characters.

6. Use the Certificate Signing Request (CSR) file to obtain the certificate file and the certificate chain file with a .pem extension, from an external recognized CA. PEM format define that these certificates are ASCII encoded X.509 certificates.

   Common suffixes for PEM files are .pem, .crt, .cer, or ca-bundle.

Generating a PKCS12 keystore

This procedure describes how to generate a PKCS12 certificate keystore, which enables you to generate a signed certificate.

Begin

1. Create the .pkcs12 keystore file by running the following command:

   openssl pkcs12 -in <certificate pem filename> -inkey <private key filename> -export -passout pass:<new keystore password> -passin pass:<private key password> -CAfile <certificate chain pem filename|certificate authority pem filename> [-chain] -out <keystore pkcs12 name>

   The password must be exactly eight characters.

2. If the CA is trusted using a certificate chain, do the following:

   1. Define the -chain flag.

   2. Point the -CAfile flag to the certificate chain .pem file.

3. If the CA is not trusted, do the following: 

   1. Do not define the -chain flag.

   2. Point the -CAfile flag to the root certificate authority .pem filename.

The pkcs12 keystore file is appears in the <Installation Path>/config/ssl directory.

Using an Encrypted Password

This procedure describes how to use your own encrypted password for Control-D/WebAccess Server for <Installation Path>/config/ssl/bmc-ctd-wa-server.jks file to encrypt the encrypt_jks_password.

Begin

1. Do one of the following:

   • Windows: Open a command prompt window and navigate to the bin folder, located in the installation folder where Control-D/WebAccess Server is installed.

   • UNIX: Log into a Control-D/WebAccess Server administrator account.

2. Type the following command:

   encrypt_jks_password <password>

   An encrypted password of JKS file appears.