1. Cloud Control Security Guide
  2. Configure TLSv1.2 for Communication with the Enterprise Manager Repository

E Configure TLSv1.2 for Communication with the Enterprise Manager Repository

By enabling the TLSv1.2 protocol for communication with the Enterprise Manager Repository, the Oracle Management Service communicates with the repository in a secured mode using TLS to encrypt communication traffic and allow the Enterprise Manager Repository to authenticate itself to the Oracle Management Service. Starting from Release Update 08, Enterprise Manager supports One-way or Two-way SSL configured database:

  • One-way SSL: In one-way SSL, the client only validates the server certificate to ensure that it receives data from the intended server. i.e., no man in the middle attack.
  • Two-way SSL: In two-way SSL, both client and server authenticate each other to ensure that both parties involved in the communication are trusted. Both parties share their public certificates to each other and then validation is performed.

To enable TLSv1.2 protocol for communication with the Enterprise Manager Repository, follow these steps:

Note:

PKCS12 is the only wallet format supported.

Step 1: Configure TLSv1.2 for the Enterprise Manager Repository

Because the Enterprise Manager Repository resides within an Oracle database, the best practices for configuring SSL on an Oracle database also apply to the Enterprise Manager Repository. Refer to the Oracle Database Security Guide to obtain detailed information on configuring SSL.

  • For a sample configuration on an Advanced Networking Option - Version 11.2.0.1 and later and Oracle Net Services - Version 12.2.1.2.0 and later, refer to MOS Note ID 1448841.1. For more information see Configuring Transport Layer Security Authentication

  • In the sqlnet.ora and the listener.ora file, ensure that the SSL_VERSION parameter is set to 1.2 for configuring TLSv1.2.

  • In the sqlnet.ora file, ensure that the SSL_CLIENT_AUTHENTICATION parameter is set to FALSE.

    Note:

    The SSL_CLIENT_AUTHENTICATION parameter is set to FALSE for 1-way SSL configuration. For 2-way SSL configuration, the SSL_CLIENT_AUTHENTICATION parameter is set to TRUE.
  • Update the WALLET_LOCATION in the sqlnet.ora and the listener.ora file:
    WALLET_LOCATION = (SOURCE = (METHOD = FILE)(METHOD_DATA = (DIRECTORY = C:\new135wallet\client\wallet)))

  • Verify the configuration by making an SSL connection using the SQLPLUS and the TCPS connect descriptors before proceeding to the next step.

    To ensure that the connect descriptors are correct, you can test the connection by running the following command:

    ./sqlplus sysman/<sysman_pwd>@"(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCPS)(HOST=<REPOS_HOST/SCAN_HOST>)(PORT=<TCPS_PORT>)))(CONNECT_DATA= (SID=<SID/SERVICE>)))"

Note:

It is important to keep both TCP and TCPS listeners up until the Oracle Management Service connect descriptor is changed to use TCPS, as show in Step 2.

Step 2: Configure blackouts for Enterprise Manager Repository-related targets

In order to suppress alerts until the target configurations are complete, place all targets related to the Enterprise Manager Repository (oracle_database , oracle_emrep, oracle_oms ,and metadata_repository target types) under blackout.

Step 3: Configuring the Oracle Management Service to connect to the TLSv1.2-enabled Enterprise Manager Repository

Perform the following sequence of steps in a rolling manner—start with the Primary Oracle Management Service first and then proceed with the remaining Oracle Management Services.

  1. Change the connect descriptor to use only TCPS.

    Obtain the existing connect descriptor using the command: emctl config oms -list_repos_details

    Execute the following using the changed TCPS protocol and port.
    emctl config oms -store_repos_details -repos_conndesc <connect descriptor> -repos_user <username>
      [-repos_pwd <pwd>] -repos_truststore <truststore file> [-repos_truststore_pwd <pwd>]
      [-repos_truststore_type <type>] [-repos_keystore <keystore file>] [-repos_keystore_pwd <pwd>]
      [-repos_keystore_type <type>]

    Depending on how the database is configured, with one-way SSL or two-way SSL, different commands need to be executed:

    Note:

    In the case of multi-OMS execute the above step on all other additional OMSs.

    1. If the Database is configured with one-way SSL (SSL_CLIENT_AUTHENTICATION=FALSE), from the OMS host, run: 

      $MW_HOME/bin/emctl config oms -store_repos_details -repos_user sysman -repos_pwd <sysman password> -repos_conndesc " <DB CONNECT STRING with TCPS port> " -repos_truststore <truststore file path> -repos_truststore_pwd <password> -repos_truststore_type PKCS12

      Example:

      $MW_HOME/bin/emctl config oms -store_repos_details -repos_user sysman -repos_pwd password -repos_conndesc "(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCPS)(HOST=myhost.us.example.com)(PORT=7777)))(CONNECT_DATA=(SID=orcln1)))" -repos_truststore 
/scratch/new135wallet/truststore/wallet/ewallet.p12 -repos_truststore_pwd password -repos_truststore_type PKCS12

    2. If the Database is configured with Two-way SSL (SSL_CLIENT_AUTHENTICATION=TRUE), from the OMS box, run: 

      $MW_HOME/bin/emctl config oms -store_repos_details -repos_user sysman -repos_pwd <sysman password> -repos_conndesc " <DB CONNECT STRING with TCPS port> " -repos_truststore <truststore file path> -repos_truststore_pwd password -repos_truststore_type <truststore_type> -repos_keystore <keystore file path> -repos_keystore_pwd password -repos_keystore_type PKCS12

      Example:

      $MW_HOME/bin/emctl config oms -store_repos_details -repos_user sysman -repos_pwd password repos_conndesc "(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCPS)(HOST=myhost.us.example.com)(PORT=7777)))(CONNECT_DATA=(SID=orcln1)))" -repos_truststore /scratch/new135wallet/truststore/wallet/ewallet.p12 -repos_truststore_pwd password -repos_truststore_type PKCS12 -repos_keystore /scratch/new135wallet/client/wallet/ewallet.p12 -repos_keystore_pwd password -repos_keystore_type PKCS12

  2. Change the Connect Descriptor of Services to use only TCPS, which only needs to be done once.

    Note:

    If the repository database is used as RAC and if the services are created for subsystems, then modify the connect descriptor to use the TCPS configuration. For more information regarding EM sizing guidelines, see Sizing Your EM Deployment.

    If there are other services created for subsystems such as Ping, Events, Jobs and Loader, modify its connect descriptor to use the new TCPS configuration details.

    Execute the following on the Primary Oracle Management Service first.

    • For the Ping subsystem connect descriptor, execute the following command to see any value is set:

      emctl get property -name "oracle.sysman.core.omsAgentComm.ping.connectionService.connectDescriptor"

      If any value is already set, run the following command to set new a Connect Descriptor:

      emctl set property -name "oracle.sysman.core.omsAgentComm.ping.connectionService.connectDescriptor " -value "(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCPS)(HOST=<REPOS_HOST/SCAN_HOST>)(PORT=<TCPS_PORT>)))(CONNECT_DATA=(SERVICE_NAME=ping)))"

    • For the Event subsystem connect descriptor, execute the following command to see any value is set:

      emctl get property -name "oracle.sysman.core.events.connectDescriptor"

      If any value is already set, run the following command to set new a Connect Descriptor:

      emctl set property -name "oracle.sysman.core.events.connectDescriptor" -value "(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCPS)(HOST=<REPOS_HOST/SCAN_HOST>)(PORT=<TCPS_PORT>)))(CONNECT_DATA=(SERVICE_NAME=event)))"

    • For the Jobs subsystem connect descriptor, execute the following command to see any value is set:

      emctl get property -name "oracle.sysman.core.jobs.conn.service"

      If any value is already set, run the following command to set new a Connect Descriptor:

      emctl set property -name "oracle.sysman.core.jobs.conn.service" -value "(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCPS)(HOST=<REPOS_HOST/SCAN_HOST>)(PORT=<TCPS_PORT>)))(CONNECT_DATA=(SERVICE_NAME=emjob)))"

    • For the Loader subsystem connect descriptor, execute the following command to see any value is set:

      emctl get property -name "oracle.sysman.core.pbs.gcloader.connectDescriptor"

      If any value is already set, run the following command to set new a Connect Descriptor:

      emctl set property -name "oracle.sysman.core.pbs.gcloader.connectDescriptor" -value "(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCPS)(HOST=<REPOS_HOST/SCAN_HOST>)(PORT=<TCPS_PORT>)))(CONNECT_DATA=(SERVICE_NAME=loader)))"

Once you executed the commands in Step 3 on the Primary Oracle Management Service, repeat them for all remaining Oracle Management Services .

Step 4: Bounce all Oracle Management Services

Execute the following on all Oracle Management Services, starting with the Primary Oracle Management Service:

emctl stop oms –all

Disable the TCP listener in the listener.ora file of Enterprise Manager Repository and bounce the listener again to enable only the TCPS connection.

Start the primary Oracle Management Service. 

emctl start oms

Note:

If the Oracle Management Services do not start, you will need to do one of the following:

Add “SQLNET.RECV_TIMEOUT=100000“ to the database sqlnet.ora file.

OR

Apply database patch 20544797 (preferred method).

It is required to set the SSL credentials in "Management Services and Repository" target. Next, set the SSL credentials for the "Management Services and Repository" target. Make sure that the Central Agent running on the Oracle Management Service host is version 13c Release 5 Update 8 (13.5.0.8) or later and then execute:

$MW_HOME/bin/emctl config emrep -set_ssl_creds

Once the Primary Oracle Management Service is up, start the remaining Oracle Management Services one at a time.

To confirm Oracle Management Service's Connect Descriptor has been changed to TCPS successfully, execute the below command:

emctl config oms -list_repos_details

Step 5: Reconfigure the Agents monitoring the Enterprise Manager Repository

Reconfigure the Agent that is monitoring the Repository Database target. If RAC is configured for the repository, you will need to reconfigure the Agents that monitor the Database instances of the RAC.

Execute the following commands to reconfigure the Agent(s) running on the repository database host:

  • If the Repository Database is configured for 1-way SSL, execute:
    AGENT_HOME/bin/emctl setproperty agent -name connectionTrustStoreLocation -value <wallet_base>/truststore/wallet/ewallet.p12
AGENT_HOME/bin/emctl setproperty agent -name connectionTrustStorePassword -value password
AGENT_HOME/bin/emctl setproperty agent -name connectionTrustStoreType -value PKCS12
  • If the Repository Database is configured for 2-way SSL, execute:
    
AGENT_HOME/bin/emctl setproperty agent -name connectionTrustStoreLocation -value <wallet_base>/truststore/wallet/ewallet.p12
AGENT_HOME/bin/emctl setproperty agent -name connectionTrustStorePassword -value password
AGENT_HOME/bin/emctl setproperty agent -name connectionTrustStoreType -value PKCS12
AGENT_HOME/bin/emctl setproperty agent -name connectionKeyStoreLocation -value <wallet_base>/client/wallet/ewallet.p12.
AGENT_HOME/bin/emctl setproperty agent -name connectionKeyStorePassword -value password
AGENT_HOME/bin/emctl setproperty agent -name connectionKeyStoreType -value PKCS12

Step 6: Reconfigure the targets referencing the Enterprise Manager Repository connection

Identify the targets referencing the repository connection in the target XML of the Primary Oracle Management Service central Agent monitoring the Enterprise Manager Repository. Also, identify the targets in target XML of the local physical host Agent if it is deployed on the Enterprise Manager Repository host.

Execute the following EMCLI command for each of the targets identified:
emcli modify_target -name="<Target Name>" -type="<target_type>" -properties="<Property>:<Property Value>;<Property>:<Property Value>" -on_agent

Note:

Make sure you use the target_name, target_type, property and property value format gathered from the Agent’s targets.xml file.

Examples:

emcli modify_target -name="database1.mycompany.com" -type="oracle_database" -properties="Port:<TCPS_PORT>;Protocol:TCPS" -on_agent
emcli modify_target -name="/EMGC_GCDomain/GCDomain/EMGC_ADMINSERVER/mds-owsm" -type="metadata_repository" -properties="JdbcUrl|jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCPS)(HOST=<REPOS_HOST/SCAN_HOST>)(PORT=<TCPS_PORT>)))(CONNECT_DATA=(SID=<SID>)));DatabaseName|@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCPS)(HOST=<REPOS_HOST/SCAN_HOST>)(PORT=<TCPS_PORT>)))(CONNECT_DATA=(SID=<SID>)))" -on_agent -subseparator=properties="|"
emcli modify_target -name="/EMGC_GCDomain/GCDomain/EMGC_ADMINSERVER/mds-sysman_mds" -type="metadata_repository" -properties="JdbcUrl|jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCPS)(HOST=<REPOS_HOST/SCAN_HOST>)(PORT=<TCPS_PORT>)))(CONNECT_DATA=(SID=<SID>)));DatabaseName|@(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCPS)(HOST=<REPOS_HOST/SCAN_HOST>)(PORT=<TCPS_PORT>)))(CONNECT_DATA=(SID=<SID>)))" -on_agent -subseparator=properties="|"

Step 7: End blackouts for Management Repository-related targets

Bring the Enterprise Manager Repository-related targets out of blackout and verify that the targets have Target Up status in Enterprise Manager Console.