1. System Administrator's Guide
  2. Implementing Security
  3. Enabling Secure Communication between BRM Components

22 Enabling Secure Communication between BRM Components

Learn how to configure secure connections between Oracle Communications Billing and Revenue Management (BRM) applications by using protocols such as Secure Sockets Layer (SSL) or Transport Layer Security (TLS).

Note:

The term SSL is often used to refer to either of these protocols or a combination of the two (SSL/TLS). BRM uses SSL/TLS to provide secure communication between system components.

Topics in this document:

Working with SSL/TLS Certificates and Oracle Wallets

The Oracle wallet is a password-protected container that stores SSL/TLS authentication and signature credentials, such as private keys, and certificates. You must create an Oracle wallet containing a trusted server certificate for the CM. You can create either an Oracle wallet with SSL/TLS authentication and credentials for each PCM client or one Oracle wallet whose SSL/TLS authentication and credentials are shared by a group of PCM clients. BRM C PCM and Java PCM clients use TLS 1.2 when establishing the SSL connection. BRM server components accept only TLS 1.2 connection from PCM clients.

BRM provides server and client Oracle wallets and trusted certificates that are compatible with the default cipher suite, SSL_RSA_WITH_AES_128_CBC_SHA. You can use the server and client Oracle wallets and trusted certificates and set your CM and PCM clients to the following directories:

  • To use the server Oracle wallets and trusted certificate, set the CM to BRM_home/wallet/server, where BRM_home is the directory in which the BRM software is installed. The server Oracle wallet contains the trusted server certificate and a certificate authority (CA) certificate.

  • To use the client Oracle wallet and trusted certificate, set the PCM client to BRM_home/wallet/client. The client Oracle wallet contains the trusted certificate and a certificate authority (CA) certificate.

Note:

By default, a sample Oracle wallet named cwallet.sso is installed for Java PCM clients. For more information, see "Enabling SSL/TLS for Java PCM Clients".

SSL/TLS uses signed certificates to check and verify two applications on a network. In BRM, trusted certificates are used to check and verify the identification of the CM and the PCM client. Each PCM client and CM Oracle wallet must contain a trusted certificate and a CA certificate. The CA certificate signs a certificate to make it trusted and checks certificates from other applications to make sure that they come from a trusted CA source.

A sample CA certificate is in the BRM_home/wallet/root directory. You can use the sample CA certificate, set up your own CA certificate, or use a CA certificate from a third party.

Creating an Oracle Wallet and a Server Certificate

Before you enable SSL/TLS in BRM, an Oracle wallet containing a trusted server certificate must be created for each CM, DM, and EM.

To create an Oracle wallet and server certificate:

  1. Go to the BRM_home/ThirdPartyApps directory.

  2. Run the source command on the source.me file:

    For Bash shell:

    source source.me.sh

    For C shell:

    source source.me.csh

  3. Run the following command:

    pin_create_server_cert

    An Oracle wallet and trusted server certificate are created in the BRM_home/wallet/server directory. The pin_create_server_cert script uses the sample CA certificate to sign the server certificate.

    The pin_create_server_cert utility generates a TLS certificate for testing. Enter the certificate details as shown in Table 22-1.

    Table 22-1 TLS certificate details

    Certificate Details Certificate Value

    Enter Certificate DN

    Enter the distinguished name that you want to use in the certificate. For example, CN=hostname.

    When the utility prompts for the distinguished name, the host name should match with the configured host name in the dm_pointer entry in the BRM_home/sys/cm/pin.conf file. Otherwise, the TLS connection fails.

    Enter RSA key size

    The default value is 2048 bits.

    Enter Certificate Signature Algorithm

    The default value is sha256.

    Enter the wallet root password

    Password for BRM_home/wallet/root.

    Enter the wallet server password

    Password for BRM_home /wallet/server.

    Once the wallet is created run the following command to view the generated server wallet.

    orapki wallet display -wallet BRM_home/wallet/server

    Note:

    If a directory already exists in the BRM_home/wallet/server directory, the utility prompts to remove or rename the directory before executing the command.

    The requested certificate is successfully created.

  4. (Optional) To enable two-way server and client authentication between the CM and the PCM client, create a trusted client certificate using the orapki utility and the sample CA certificate, and enable two-way server and client authentication for the CM.

    The sample CA certificate is in the BRM_home/wallet/root directory. For more information about the orapki utility, see Oracle Database Advanced Security Administrator's Guide.

    For example:

    1. Go to BRM_home/bin.

    2. Create a certificate request by running the following command:

      orapki wallet add -wallet BRM_home/wallet/client -keysize 1024 -dn cn=test_client,dc=us,dc=oracle,dc=com -pwd password

    3. Export the certificate request to a file by running the following command:

      orapki wallet export -wallet BRM_home/wallet/client -dn cn=test_client,dc=us,dc=oracle,dc=com -request BRM_home/wallet/client/ccreq.txt -pwd password 

      where the -request parameter specifies the file name.

    4. Create a trusted certificate by running the following command:

      orapki cert create -wallet BRM_home/wallet/root -request BRM_home/wallet/client/ccreq.txt -cert BRM_home/wallet/client/ccert.txt -validity 3650 -pwd password

      where the -validity parameter specifies the number of days that the certificate is valid.

    5. Add the client certificate into the client wallet by running the following command:

      orapki wallet add -wallet BRM_home/wallet/client -user_cert -cert BRM_home/wallet/client/ccert.txt -pwd password

    6. Enable two-way server and client authentication for the CM. For more information on how to enable two-way authentication between server and client, see "Enabling SSL/TLS in Connection Managers".

Using the orapki Utility to Create Oracle Wallets and Certificates

You can use the orapki utility to create Oracle wallets and certificates and to import certificates into Oracle wallets. The orapki utility is in the BRM_home/bin directory.

For more information about the orapki utility, see Oracle Database Advanced Security Administrator's Guide.

To create an Oracle wallet by using the orapki utility:

  1. Go to the BRM_home/bin directory.

  2. Run the following command:

    orapki wallet create -wallet wallet_location -auto_login -pwd password

    where:

    • wallet_location is the directory in which the Oracle wallet is to be created.

      Note:

      Ensure that there are no blank spaces within the wallet_location directory name or path.

    • password is the password used to make changes to the Oracle wallet.

      Passwords for the orapki utility must adhere to the following rules:

      • Contain a minimum of eight characters

      • Include at least one numeric character, one uppercase character, and one special character

      • Differ from the previous four passwords

      • Not include any part of the user ID

      Note:

      For security reasons, Oracle recommends that you do not specify the password at the command line. Instead, enter the password when prompted to do so.

    All SSL/TLS Oracle wallets must have the auto_login parameter enabled. The auto_login parameter opens the wallet without the need for a password. If you wish to make changes to the wallet, a password must be provided.

BRM-Supported Cipher Suites

Cipher suites contain authentication, encryption, and MAC algorithms that are used to protect information during key exchange, bulk encryption, and message authentication. BRM lists the cipher suites it supports, in order of preference.

During the SSL/TLS handshake between the PCM client and the CM, the PCM client sends the supported cipher suite list to the CM. The CM selects a cipher suite and returns its selection to the PCM client.

Table 22-2 lists the SSL/TLS cipher suites that are supported for C and C++ based BRM programs such as the CM and Oracle DM.

Table 22-2 Supported TLS Cipher Suites for BRM C/C++ Programs

TLS Program IANA Cipher Suite Name BRM C/C++ Cipher Name

TLSv1.2

TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

SSL_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

TLSv1.2

TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

SSL_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

TLSv1.2

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

SSL_ECDHE_RSA_WITH_AES_128_GCM_SHA256

TLSv1.2

TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

 SSL_ECDHE_RSA_WITH_AES_256_GCM_SHA384

Table 22-3 lists the SSL/TLS cipher suites that are supported for Java-based BRM programs such as EAI Manager.

Table 22-3 Supported TLS Cipher Suites for BRM Java Programs

TLS Program IANA Cipher Suite Name BRM Java Cipher Name

TLSv1.2

TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256

TLSv1.2

TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384

TLSv1.2

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

TLSv1.2

TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384

TLSv1.3

TLS_AES_128_GCM_SHA256

TLS_AES_128_GCM_SHA256

TLSv1.3

TLS_AES_256_GCM_SHA384

TLS_AES_128_GCM_SHA256

Enabling or Disabling SSL/TLS for BRM Components

By default, SSL/TLS is enabled for all BRM components.

To enable or disable SSL/TLS for all BRM components at one time:

  1. Go to the BRM_home/setup/scripts directory.

  2. Do one of the following:

    • To enable SSL/TLS between the clients and the CM, and disable SSL/TLS between the CM and DM/EM, run the following command:

      perl sslConfig.pl 2  

    • To enable SSL/TLS, run the following command:

      perl sslConfig.pl 1  

    • To disable SSL/TLS, run the following command:

      perl sslConfig.pl 0

Enabling or Disabling SSL/TLS for BRM Clients

By default, SSL/TLS is enabled for all BRM clients.

To enable or disable SSL/TLS for a BRM client:

  1. Open the BRM_client_home/application_Name/Infranet.properties file in a text editor.

    where:

    • BRM_client_home is the directory in which the BRM client application is installed.

    • application_Name is the name of the BRM client application.

  2. Do one of the following:

    • To enable SSL/TLS, set the following entry to true: 

      infranet.pcp.ssl.enabled=true

    • To enable SSL/TLS, set the following entry to false: 

      infranet.pcp.ssl.enabled=false

Enabling SSL/TLS in Connection Managers

By default, SSL/TLS is enabled in the CMs. If you disabled SSL/TLS during the BRM server installation, you can enable SSL/TLS in the CMs.

Note:

If you have multiple CMs on the same machine or if you are creating a new CM, each CM needs its own Oracle wallet. See "Creating an Oracle Wallet and a Server Certificate".

To enable SSL/TLS in a CM:

  1. Open the BRM_home/sys/cm/pin.conf file in a text editor.

  2. Add the following entry:

    - cm enable_ssl 1

  3. (Optional) To enable two-way server and client authentication between the CM and the PCM client, add the following entry:

    - cm ssl_auth 2-way

    For information on how to create a trusted server certificate to use when enabling two-way authentication, see "Creating an Oracle Wallet and a Server Certificate".

  4. (Optional) If your server Oracle wallet is not in the default directory (BRM_home/wallet/server), add the following entry: 

    - cm wallet wallet_location

    where wallet_location is the full path to the directory in which your server Oracle wallet resides.

    Note:

    Ensure that there are no blank spaces within the wallet_location directory name or path.

  5. (Optional) To add cipher suites, do one of the following:

    • To add one cipher suite, add the following entry:

      - cm  cipher cipher_suite

      where cipher_suite is the name of the cipher suite.

      For example: 

      - cm cipher SSL_RSA_WITH_AES_256_SHA384

    • To add multiple cipher suites, separate each cipher suite by a comma.

      For example:

      - cm cipher SSL_RSA_WITH_AES_256_GCM_SHA384,SSL_RSA_WITH_AES_128_GCM_SHA256

  6. Save and close the file.

  7. Stop and restart the CM.

Enabling SSL/TLS in Data Managers

By default, SSL/TLS is enabled in the DMs. If you disabled SSL/TLS during the BRM server installation, you can enable SSL/TLS in the DMs.

Note:

If you have multiple DMs on the same machine or if you are creating a new DM, each DM needs its own Oracle wallet. See "Creating an Oracle Wallet and a Server Certificate".

To enable SSL/TLS in a DM:

  1. Open the BRM_home/sys/data_manager/pin.conf file in a text editor, where data_manager is the folder for the DM you want to enable secure communication for.

  2. Add the following entry:

    - dm enable_ssl 1

  3. (Optional) To enable two-way authentication between the CM and the DM, add the following entry:

    - dm ssl_auth 2-way

    For information on how to create a trusted server certificate to use when enabling two-way authentication, see "Creating an Oracle Wallet and a Server Certificate".

  4. (Optional) If your server Oracle wallet is not in the default directory (BRM_home/wallet/server), add the following entry: 

    - dm wallet wallet_location

    where wallet_location is the full path to the directory in which your server Oracle wallet resides.

    Note:

    Ensure that there are no blank spaces within the wallet_location directory name or path.

  5. (Optional) To add cipher suites, do one of the following:

    • To add one cipher suite, add the following entry:

      - dm  cipher cipher_suite

      where cipher_suite is the name of the cipher suite.

      For example: 

      - cm cipher SSL_RSA_WITH_AES_256_SHA384

    • To add multiple cipher suites, separate each cipher suite by a comma.

      For example:

      - dm cipher SSL_RSA_WITH_AES_256_GCM_SHA384,SSL_RSA_WITH_AES_128_GCM_SHA256

  6. Save and close the file.

  7. Stop and restart the DM.

Enabling SSL/TLS for C and C++ PCM Clients

By default, the ability to use SSL/TLS with C and C++ PCM clients is enabled. If you disabled SSL/TLS during the BRM clients installation, you can enable SSL/TLS for the C and C++ PCM clients.

To enable SSL/TLS for C and C++ PCM clients:

  1. Open the pin.conf file of the PCM client application in a text editor.

  2. Add the following entry:

    - nap enable_ssl 1

  3. (Optional) To enable two-way server and client authentication between the CM and C and C++ PCM clients, add the following entry:

    - nap ssl_auth 2-way

  4. (Optional) If your client Oracle wallet is not in the default directory, add the following entry:

    - nap wallet wallet_location

    where wallet_location is the full path to the directory in which your client Oracle wallet resides.

    Note:

    Ensure that there are no blank spaces within the wallet_location directory name or path.

  5. (Optional) To add cipher suites for C and C++ PCM clients, do one of the following:

    • To add one cipher suite, add the following entry:

      - nap cipher cipher_suite

      where cipher_suite is the name of the cipher suite.

      For example: 

      - nap cipher SSL_RSA_WITH_AES_256_SHA384

    • To add multiple cipher suites, separate each cipher suite by a comma.

      For example:

      - nap cipher SSL_RSA_WITH_AES_256_GCM_SHA384,SSL_RSA_WITH_AES_128_GCM_SHA256

  6. Save and close the file.

  7. Stop and restart the CM.

Enabling SSL/TLS for Java PCM Clients

By default, the ability to use SSL/TLS with Java PCM clients is enabled. When you install a Java client application, a sample Oracle wallet named cwallet.sso is installed in the directory in which you install the Java client application. If you disabled SSL/TLS during the BRM clients installation, you can enable SSL/TLS for the Java PCM clients.

Note:

Only administrators with write permissions can make changes to the Infranet.properties file.

To enable SSL/TLS for Java PCM clients, do the following for each Java PCM client:

  1. Open the Java Infranet.properties file in a text editor.

    Table 22-4 lists the default location of the Infranet.properties file for each Java PCM client.

    Table 22-4 BRM Client Infranet.properties File Default Locations

    Client Name Directory Path

    Business Configuration Center

    Windows 8.1 and Windows 10 — C:\Program Files (x86)\Common Files\Portal Software\Infranet.properties

    Business Operations Center

    Windows 7 and Windows 8.1 — C:\Program Files (x86)\Portal Software\BusinessOperationCenter\RevenueAssuranceCenter\lib\Infranet.properties

    Collections Configuration

    C:\Program Files (x86)\Portal Software\CollectionsConfiguration\Lib\Infranet.properties

    Customer Center

    Windows 7 and Windows 8.1 — C:\Program Files (x86)\Portal Software\CustomerCenter\lib\Infranet.properties

    Developer Center

    C:\Program Files (x86)\Common Files\Portal Software\Infranet.properties

    IP Address Administration Center

    C:\Program Files (x86)\Portal Software\IPAddressAdministrationCenter\Infranet.properties

    Number Administration Center

    C:\Program Files (x86)\Common Files\Portal Software\Infranet.properties

    Permissioning Center

    C:\Program Files (x86)\Portal Software\PermissioningCenter\lib\Infranet.properties

    Pricing Center

    Windows 7 and Windows 8.1 — C:\Program Files (x86)\Portal Software\PricingCenter\lib\Infranet.properties

    SIM Administration Center

    C:\Program Files (x86)\Common Files\Portal Software\Infranet.properties

    Suspense Management Center

    C:\Program Files (x86)\Portal Software\SuspenseManagementCenter\lib\Infranet.properties

    Voucher Administration Center

    C:\Program Files (x86)\Common Files\Portal Software\Infranet.properties

  2. Search for the following line:

    - infranet.pcp.ssl.enabled=false

  3. Change false to true. 

    - infranet.pcp.ssl.enabled=true

  4. (Optional) To enable two-way server and client authentication between the CM and Java PCM clients, add the following entry:

    - infranet.pcp.ssl.client_auth = true

  5. (Optional) If the Java PCM client Oracle wallet is not in the default location, add the following entry:

    - infranet.pcp.ssl.wallet.location=wallet_location/wallet

    where wallet_location is the full path to the directory in which your Java PCM client Oracle wallet resides.

    Note:

    Ensure that there are no blank spaces within the wallet_location directory name or path.

  6. (Optional) If your Java PCM client Oracle wallet name is different from the sample Java PCM client Oracle wallet name, add the following entry:

    - infranet.pcp.ssl.wallet.filename=wallet_name.sso

    where wallet_name is the name of your Java PCM client Oracle wallet.

  7. (Optional) Change the timeout setting for the SSL/TLS handshake between the CM and Java PCM clients by setting the infranet.pcp.ssl.handshake.timeout entry to the appropriate number of milliseconds: 

    - infranet.pcp.ssl.handshake.timeout=timeout_in_milliseconds

    The default timeout is 30000 milliseconds.

  8. (Optional) To add cipher suites for Java PCM clients, do one of the following:

    • To add one cipher suite, specify the name of the cipher suite in the following entry:

      - infranet.pcp.ssl.handshake.ciphersuites=cipher_suite

      where cipher_suite is the name of the cipher suite.

      For example: 

      - infranet.pcp.ssl.handshake.ciphersuites=TLS_RSA_WITH_AES_256_GCM_SHA384

    • To add multiple cipher suites, separate each cipher suite by a comma.

      For example:

      - infranet.pcp.ssl.handshake.ciphersuites=TLS_RSA_WITH_AES_128_CBC_SHA,TLS_RSA_WITH_AES_256_GCM_SHA384

  9. Save and close the file.

  10. Verify that the BRM_home/jars/oraclepki.jar, BRM_home/jars/osdt_cert.jar, BRM_home/jars/osdt_core.jar, and BRM_home/jars/commons-logging-1.2.jar files are in the CLASSPATH.

Enabling SSL for Web Start Deployment

You must enable SSL for the following Web Start deployments:

  • Customer Center

  • Pricing Center

  • Suspense Management Center

To enable SSL for a Web Start deployment:

  1. Package your SSL wallet files and Infranet.properties file into a separate JAR file (for example, named wallet.jar) and digitally sign it.

    The following shows a sample directory structure for the wallet.jar file: 

            wallet.jar
            |_ com/oracle/wallet/cwallet.sso
            |_ com/oracle/wallet/ewallet.p12
             _ Infranet.propeties

  2. Copy the JAR file to the Client_Application_home/3plibs directory, where Client_Application_home is the directory in which you installed Customer Center, Pricing Center, or Suspense Management Center on your Web server. For example: C:/Program Files/Apache Group/Tomcat/webapps/ROOT/CustomerCenter.

  3. Create a new Java Network Launch Protocol (JNLP) file, such as brmwallet.jnlp, and copy it to the Client_Application_home directory in which the client_application_en.jnlp file is located.

    where client_application is one of the following:

    • CustomerCenter

    • PricingCenter

    • SuspenseManagement

    The following shows sample content in a JNLP file:

    <?xml version="1.0" encoding="utf-8"?> 
    <jnlp spec="1.0+" codebase="__CODE_BASE_URL__" href="brmwallet.jnlp"> 
        <information> 
            <title>SSL Wallet Certificates</title> 
            <vendor>Oracle Corporation</vendor> 
        </information> 
        <security> 
            <all-permissions/> 
        </security> 
        <resources> 
            <jar href="3plibs/wallet.jar" /> 
        </resources> 
        <component-desc/> 
    </jnlp>

  4. In the Client_Application_home/client_application_en.jnlp file, add these two JNLP file extensions under the resources element: 

    <resources>
   <extension name="brmwallet" href="brmwallet.jnlp"/> 
</resources>

  5. Update the location and name of the wallet file by adding the following entries to the Infranet.properties file: 

    - infranet.pcp.ssl.wallet.location=wallet_location/wallet
- infranet.pcp.ssl.wallet.filename=wallet_name.sso

    where:

    • wallet_location is the wallet path within the JAR file that you created, such as com/oracle/wallet.

      Note:

      Ensure that there are no blank spaces within the wallet_location directory name or path.

    • wallet_name is the name of the wallet file, such as cwallet.sso.

  6. Launch the Web Start for Customer Center, Pricing Center, or Suspense Management Center and connect to a SSL-enabled BRM system.

Enabling SSL/TLS for Java Server Processes

By default, the ability to use SSL/TLS with Java server processes is enabled in BRM. If you disabled SSL/TLS during the BRM installation, you can enable SSL/TLS for Java server processes.

Note:

Only administrators with write permissions can make changes to the Infranet.properties file.

To enable SSL/TLS for Java server processes:

  1. Open the Infranet.properties file for your Java server process in a text editor.

    Table 22-5 lists the default location of the Infranet.properties file for each Java server process.

    Table 22-5 Java Server Process Infranet.properties File Default Locations

    Process Name Directory Path

    EAI Java Server or eai_js

    BRM_home/sys/eai_js/Infranet.properties

    BRM invoice formatter

    BRM_home/sys/formatter/Infranet.properties

    pin_job_executor utility

    BRM_home/apps/pin_job_executor/Infranet.properties

    Kafka DM

    BRM_home/sys/dm_kafka/Infranet.properties

  2. Do one of the following:

    • To enable TLSv1.2, set the following property to true: 

      - infranet.pcp.ssl.enabled=true

    • To enable TLSv1.3, set the following property to true: 

      - infranet.pcp.ssl.enable_tlsv13=true

  3. (Optional) To enable two-way server and client authentication between the CM and the Java server process, add the following entry:

    - infranet.pcp.ssl.client_auth = true

  4. (Optional) If the Java server process Oracle wallet is not in the default location, add the following entry:

    - infranet.pcp.ssl.wallet.location=wallet_location/wallet

    where wallet_location is the directory in which your Java server process Oracle wallet resides.

    Note:

    Ensure that there are no blank spaces within the wallet_location directory name or path.

  5. (Optional) If your Java server process Oracle wallet name is different from the sample the Java server process Oracle wallet name, add the following entry:

    - infranet.pcp.ssl.wallet.filename=wallet_name.sso

    where wallet_name is the name of your Java server process Oracle wallet.

  6. (Optional) To add cipher suites for Java server process, do one of the following:

    • To add one cipher suite, specify the name of the cipher suite in the following entry:

      - infranet.pcp.ssl.handshake.ciphersuites=cipher_suite

      where cipher_suite is the name of the cipher suite.

      For example: 

      - infranet.pcp.ssl.handshake.ciphersuites=TLS_RSA_WITH_AES_256_GCM_SHA384

    • To add multiple cipher suites, separate each cipher suite by a comma.

      For example:

      - infranet.pcp.ssl.handshake.ciphersuites=TLS_RSA_WITH_AES_128_GCM_SHA256,TLS_RSA_WITH_AES_256_GCM_SHA384

  7. Save and close the file.

Enabling SSL/TLS in Connection Manager Master Processes

By default, SSL/TLS is enabled in CMMPs. If you disabled SSL/TLS during the BRM server installation, you can enable SSL/TLS in CMMPs.

If you have multiple CMMPs on the same machine or if you are creating a new CMMP, each CMMP needs its own Oracle wallet. See "Creating an Oracle Wallet and a Server Certificate".

When enabling SSL/TLS in CMMP, all the CMs listed in the redirects parameter in the CMMP's pin.conf file must be SSL/TLS enabled.

To enable SSL/TLS in a CMMP:

  1. Open the BRM_home/sys/cmmp/pin.conf file in a text editor.

  2. Add the following entry:

    - cm enable_ssl 1

  3. (Optional) To enable two-way server and client authentication between the CMMP and the PCM client, add the following entry:

    - cm ssl_auth 2-way

    For information on how to create a trusted server certificate to use when enabling two-way authentication, see "Creating an Oracle Wallet and a Server Certificate".

  4. (Optional) If your server Oracle wallet is not in the default directory (BRM_home/wallet/server), add the following entry: 

    - cm wallet wallet_location

    where wallet_location is the full path to the directory in which your server Oracle wallet resides.

    Note:

    Ensure that there are no blank spaces within the wallet_location directory name or path.

  5. (Optional) To add cipher suites, do one of the following:

    • To add one cipher suite, add the following entry:

      - cm  cipher cipher_suite

      where cipher_suite is the name of the cipher suite.

      For example: 

      - cm cipher SSL_RSA_WITH_AES_256_SHA384

    • To add multiple cipher suites, separate each cipher suite by a comma.

      For example:

      - cm cipher SSL_RSA_WITH_3DES_EDE_CBC_SHA,SSL_RSA_WITH_AES_256_GCM_SHA384

  6. Save and close the file.

  7. Stop and restart the CMMP.

Enabling SSL/TLS for Payment Tool

By default, the ability to use SSL/TLS with Payment Tool is disabled. When you install Payment Tool, a sample Oracle wallet named cwallet.sso is installed in the C:\Program Files\Common Files\Portal Software\wallet\client directory.

To enable SSL/TLS for Payment Tool on Windows:

Note:

  • Only administrators with write permissions can make changes to the PaymentTool.ini file.

  • After enabling SSL/TLS in the PaymentTool.ini file, run Payment Tool in the administrator mode.

To enable SSL/TLS for Payment Tool:

  1. Create a directory for the Payment Tool Oracle wallet (wallet_location).

    Note:

    Ensure that there are no blank spaces within the wallet_location directory name or path.

  2. Copy the cwallet.sso file from the C:\Program Files\Common Files\Portal Software\wallet\client directory to wallet_location.

  3. Open the C:\Windows\PaymentTool.ini file in a text editor.

  4. Add the following entry:

    EnableSSL=1
SSLWallet=wallet_location

  5. (Optional) To add cipher suites for Payment Tool, do one of the following:

    • To add one cipher suite, add the following entry:

      SSLCipher=cipher_suite

      where cipher_suite is the name of the cipher suite. For example: 

      SSLCipher=SSL_RSA_WITH_RC4_128_MD5

    • To add multiple cipher suites, separate each cipher suite by a comma. For example:

      SSLCipher=SSL_RSA_WITH_3DES_EDE_CBC_SHA,SSL_RSA_WITH_RC4_128_MD5

    By default, BRM uses SSL_RSA_WITH_AES_128_CBC_SHA. For information on cipher suites supported by BRM, see "BRM-Supported Cipher Suites".

  6. Save and close the file.

Enabling SSL/TLS with Custom Applications

For custom applications, use the login flist as input to the PCM_CONTEXT_OPEN opcode.

Table 22-6 lists the fields and values that you must set in the login flist to enable SSL/TLS.

Table 22-6 Login flist Fields for SSL/TLS

Field Data Type Value

PIN_FLD_ENABLE_SSL

PIN_FLDT_INT

To enable SSL/TLS, use 1.

To disable SSL/TLS, use 0.

PIN_FLD_SSL_CIPHER

PIN_FLDT_STR

Cipher suite, or cipher suites separated by a comma.

PIN_FLD_SSL_WALLET

PIN_FLDT_STR

Path to the Oracle wallet directory.

Enabling SSL/TLS for Paymentech DM

By default, the TLS connection between Paymentech (dm_fusa) and answer simulator is disabled. However, by default, the TLS connection between CM and Paymentech is enabled.

To enable SSL/TLS for dm_fusa:

  1. Open the BRM_home/sys/dm_fusa/pin.conf file in a text editor.

  2. Add the following entry:

    - dm_fusa fusa_tls_enabled 1

  3. Save and close the file.

  4. Stop and restart the Paymentech DM.

Enabling SSL/TLS for Paymentech Answer Simulator

By default, SSL/TLS is disabled for answer simulator.

To enable SSL/TLS for answer simulator in pin.conf:

  1. Open the BRM_HOME/apps/fusa_server/pin.conf file in a text editor.
  2. Add the following entry:
    - answer answer_tls_enabled 1
  3. Save and close the file.
  4. Stop and restart the Paymentech answer simulator.

Verifying Server Host Name

When SSL/TLS is enabled for secure communication between the BRM components, depending on whether the component is acting as the SSL/TLS client or as the SSL/TLS server, BRM verifies the host name configured in the SSL/TLS certificate in the following manner:

  • When the C and C++ PCM clients connect to the CM as an SSL/TLS server, the server host name configured in the server certificate from the CM will be verified with the cm_ptr parameter in the client's pin.conf file.

  • When the Java PCM clients connect to the CM as an SSL/TLS server, the server host name configured in the server certificate from the CM will be verified with the host name in the connection URL.

  • When the CM is the client to a DM as the SSL/TLS server, the server host name configured in the server certificate from the DM will be verified with the dm_pointer parameter in the CM's pin.conf file.

  • When the CM is the client to an EM as the SSL/TLS server, the server host name configured in the server certificate from the EM will be verified with the em_pointer parameter in the CM's pin.conf file.

  • When CMMP is used for connection between the Java PCM clients and the CM, the CMMP redirects the connection to the CM. The server host name configured in the server certificate from the CM will be verified with the host name in the connection URL.

If the host name does not match, the connection is terminated.

SSL/TLS Client Certificate Authentication

BRM server components such as the DM and EM maintain a list of trusted certificates and trusted CA certificates in the server wallet. When SSL/TLS two-way authentication is enabled for the server component, you can verify the client certificate containing the host name details with the list of trusted certificates and trusted CA certificates present in the server wallet. After SSL/TLS handshake, if the certificate is used by a trusted CA, the connection is allowed. If the certificate is not used by a trusted CA, the connection is terminated.

If you want to allow only the certificates used by Oracle CA and not any other CA, ensure that other CAs are not present in the server wallet.

Creating Debugging Logs for SSL/TLS

You can use the PIN_SSL_DEBUG environment variable to log messages that contain debugging information related to SSL/TLS and to generate SSL/TLS trace logs.

To create debugging logs for SSL/TLS:

  1. Set the PIN_SSL_DEBUG environment variable with the hexadecimal value described in Table 22-7. For example, to log messages that contain debugging information for SSL/TLS initialization, set PIN_SSL_DEBUG to 0x0001: 

    PIN_SSL_DEBUG     0x0001

  2. To create multiple logs and trace files, use the OR function on the hexadecimal values described in Table 22-7. For example, to log messages that contain debugging information related to SSL/TLS initialization and to generate SSL/TLS trace files, set PIN_SSL_DEBUG to 0x0031: 

    PIN_SSL_DEBUG     0x0031

    Table 22-7 PIN_SSL_DEBUG Values

    Value Description

    0x0001

    Logs messages that contain debugging information related to SSL/TLS initialization.

    0x0002

    Logs messages that contain debugging information related to read.

    0x0004

    Logs messages that contain debugging information related to write.

    0x0030

    Generates SSL/TLS trace files for the CM and C and C++ PCM clients.

    Note: Trace logs are generated in the working directories of the respective binaries.