Configuring and Using Cryptograhic Keys

To protect the integrity of sensitive data in Enterprise Manager, a signing on verification method known as the emkey is used. Encryption key is the master key that is used to encrypt/decrypt sensitive data, such as passwords and preferred credentials that are stored in the Repository. The emkey is generated during repository creation time and is originally stored in repository database. During installation of the first OMS, emkey is copied to the Credential Store and removed from the repository database, that is emkey is secured out-of-the-box. A backup is created in OMS_ORACLE_HOME/sysman/config/emkey.ora.

If the emkey is corrupted and the backup emkey.ora file is lost, all the encrypted information in repository becomes useless. Hence, it is strongly recommended to create a backup of this file on some other machine, so that in case the OMS machine crashes or emkey gets corrupted, the backed up file can be used for recovering the environment.

When starting up, OMS reads the emkey from Credential Store and repository. If the emkey is not found or is corrupted, it fails to start. By storing the key separately from Enterprise Manager schema, we ensure that the sensitive data such as Named Credentials in the Repository remain inaccessible to the schema owner and other SYSDBA users (Privileged users who can perform maintenance tasks on the database) in the Repository. Moreover, keeping the key separate from the schema will ensure that sensitive data remain inaccessible while Repository backups are accessed. Further, the schema owner should not have access to the OMS/Repository Oracle homes.

Repository Encryption Algorithm

The Advanced Encryption Standard (AES) algorithm is used to encrypt data in the Enterprise Manager Repository. The encryption key size is 256 bits.

Earlier, Triple Data Encryption Standard (3DES) was the encryption algorithm used to encrypt repository data.

Configuring the emkey

The emkey is an encryption key that is used to encrypt and decrypt sensitive data in Enterprise Manager such as host passwords, database passwords and others. The emkey.ora file is a copy of emkey should be kept in a safe location for restoration purposes.

During startup, the Oracle Management Service checks the status of the emkey. If the emkey has been properly configured, the OMS uses it for encrypting and decrypting data. If the emkey has not been configured properly, the following error message is displayed.

Example 2-12 emctl start oms Command

Oracle Enterprise Manager 24ai Release 1
Copyright (c) 1996, 2024 Oracle Corporation.  All rights reserved.
emctl start oms
Starting HTTP Server ...
Starting Oracle Management Server ...
Checking Oracle Management Server Status ...
Oracle Management Server is not functioning because of the following reason:
The Em Key is not configured properly. Run "emctl status emkey" for more details.

emctl Commands

The emctl commands related to emkey are given below:

emctl status emkey
emctl config emkey -copy_to_credstore
emctl config emkey -remove_from_repos
emctl config emkey -copy_to_file_from_credstore -admin_host <host> -admin_port <port> -admin_user <username> [-admin_pwd <pwd>] [-repos_pwd <pwd>] -emkey_file <emkey file>
emctl config emkey -copy_to_file_from_repos (-repos_host <host> -repos_port <port> -repos_sid <sid> | -repos_conndesc <conn desc>) -repos_user <username> [-repos_pwd <pwd>] [-admin_pwd <pwd>] -emkey_file <emkey file>
emctl config emkey -copy_to_credstore_from_file -admin_host <host> -admin_port <port> -admin_user <username> [-admin_pwd <pwd>] [-repos_pwd <pwd>] -emkey_file <emkey file>

emctl config emkey -copy_to_repos_from_file (-repos_host <host> -repos_port <port> -repos_sid <sid> | -repos_conndesc <conn desc>) -repos_user <username> [-repos_pwd <pwd>] [-admin_pwd <pwd>] -emkey_file <emkey file>

Examples: Use example 1 if your environment is configured with a service name. for all else use example 2.

Example 1
emctl config emkey -copy_to_repos_from_file -repos_conndesc '"(DESCRIPTION=(ADDRESS_LIST=(ADDRESS=(PROTOCOL=TCP)(HOST=<>)(PORT=<>)))(CONNECT_DATA=(SERVICE_NAME=<>)))"' -repos_user <> [-repos_pwd <pwd> ] [-admin_pwd <pwd>] -emkey_file < emkey file>

Example 2
emctl config emkey -copy_to_repos_from_file -repos_host <host> -repos_port <port> -repos_sid <sid> -repos_user <username> [-repos_pwd <pwd> ] [-admin_pwd <pwd>] -emkey_file <emkey file>

emctl status emkey

This command shows the health or status of the emkey. Depending on the status of the emkey, the following messages are displayed:

When the emkey has been correctly configured in the Credential Store and Repository, the following message is displayed.
When the emkey has been correctly configured in the Credential Store and has been removed from the Management Repository, the following message is displayed.
When the emkey is corrupted in the Credential Store and removed from the Management Repository, the following message is displayed.

Example 2-13 emctl status emkey - Example 1

Oracle Enterprise Manager 24ai Release 1
Copyright (c) 1996, 2024 Oracle Corporation.  All rights reserved.
The EmKey is configured properly, but is not secure. Secure the EMKey by running "emctl config emkey -remove_from_repos"

Example 2-14 emctl status emkey - Example 2

Oracle Enterprise Manager 24ai Release 1
Copyright (c) 1996, 2024 Oracle Corporation.  All rights reserved.
The EMKey is configured properly.

Example 2-15 emctl status emkey - Example 3

Oracle Enterprise Manager 24ai Release 1
Copyright (c) 1996, 2024 Oracle Corporation.  All rights reserved.
The EMKey is not configured properly or is corrupted in the credential store and does not exist in the Management Repository. To correct the problem:
1) Get the backed up emkey.ora file.
2) Configure the emkey by running "emctl config emkey -copy_to_credstore_from_file"

emctl config emkey -copy_to_credstore

This command copies the emkey from the Management Repository to the Credential Store.

Example 2-16 Sample Output of the emctl config emkey -copy_to_credstore Command

emctl config emkey -copy_to_credstore
Oracle Enterprise Manager 24ai Release 1  
Copyright (c) 1996, 2024 Oracle Corporation.  All rights reserved.
The EMKey has been copied to the Credential Store.

emctl config emkey -copy_to_file_from_credstore

This command copies the emkey from the Credential Store to a specified file.

Example 2-17 Sample Output of the emctl config emkey -copy_to_file_from_credstore Command

emctl config emkey -copy_to_file_from_credstore -admin_host <host> -admin_port
<port> -admin_user <username> [-admin_pwd <pwd>] [-repos_pwd <pwd>] -emkey_file
<emkey file>
Oracle Enterprise Manager 24ai Release 1  
Copyright (c) 1996, 2024 Oracle Corporation.  All rights reserved.
The EMKey has been copied to file.

emctl config emkey -copy_to_file_from_repos

This command copies the emkey from the Management Repository to a specified file.

Example 2-18 Sample Output of the emctl config emkey -copy_to_file_from_repos Command

emctl config emkey -copy_to_file_from_repos (-repos_host <host> -repos_port <port>
-repos_sid <sid> | -repos_conndesc <conn desc>) -repos_user <username> [-repos_pwd
<pwd>] [-admin_pwd <pwd>] -emkey_file <emkey file>
Oracle Enterprise Manager 24ai Release 1  
Copyright (c) 1996, 2024 Oracle Corporation.  All rights reserved.
The EMKey has been copied to file.

Note: Either repos_host, repos_port, repos_sid OR repos_conndesc needs to be specified.

emctl config emkey -copy_to_credstore_from_file

The command removes the emkey from the repository: It secures the emkey, which is the out-of-the-box configuration.

Example 2-19 Sample Output of the emctl config emkey -copy_to_credstore_from_file Command

emctl config emkey -copy_to_credstore_from_file -admin_host <host> -admin_port <port> -admin_user <username> [-admin_pwd <pwd>] [-repos_pwd <pwd>] -emkey_file <emkey file>
Oracle Enterprise Manager 24ai Release 1  
Copyright (c) 1996, 2024 Oracle Corporation.  All rights reserved.
The EMKey has been copied to the Credential Store.

emctl config emkey -copy_to_repos_from_file

This command copies the emkey from a specified file to the repository.

Example 2-20 Sample Output of the emctl config emkey -copy_to_repos_from_file Command

emctl config emkey -copy_to_repos_from_file (-repos_host <host> -repos_port <port>
-repos_sid <sid> | -repos_conndesc <conn desc>) -repos_user <username> [-repos_pwd
<pwd>] [-admin_pwd <pwd>] -emkey_file <emkey file>
Oracle Enterprise Manager 24ai Release 1  
Copyright (c) 1996, 2024 Oracle Corporation.  All rights reserved.
The EMKey has been copied to the Management Repository. This operation will cause
the EMKey to become unsecure.
After the required operation has been completed, secure the EMKey by running "emctl config emkey -remove_from_repos".

emctl config emkey -remove_from_repos

This command removes the emkey from the repository.

Example 2-21 Sample Output of emctl config emkey -remove_from_repos Command

emctl config emkey -remove_from_repos
Oracle Enterprise Manager 24ai Release 1  
Copyright (c) 1996, 2024 Oracle Corporation.  All rights reserved.
The EMKey has been removed from the Management Repository.

Note:

If the emkey is corrupted in the Credential Store, you will not be able to remove it from the Management Repository.

Install and Upgrade Scenarios

This section explains the install and upgrade scenarios for emkey.

Installing the Management Repository

A new emkey is generated as a strong random number when the Management Repository is created.

Installing the First Oracle Management Service

When the Oracle Management Service is installed, the Installer copies the emkey to Credential Store and removes it from repository (emkey is secured out-of-box).

Upgrading from 10.2 or 11.1 to 12.1

The Management Repository is upgraded as usual. When upgrading the OMS, the omsca (OMS Configuration Assistant) copies the emkey to Credential Store and removes from repository. omsca reads the emkey from emkey.ora file present in the old OMS Oracle Home and copies it to Credential Store.

Recreating the Management Repository

When the Management Repository is recreated, a new emkey is generated. This new key will not be in synchronization with the emkey existing in the Credential Store. Follow these steps to synchronize the key:

Copy the new emkey to Credential Store by using the emctl config emkey -copy_to_credstore command.
Take a backup by entering the emctl config emkey -copy_to_file_from_repos command or the emctl config emkey -copy_to_file_from_credstore command.
Secure the emkey by using the emctl config emkey -remove_from_repos command.