Encrypting Characteristics in UIM

16 Encrypting Characteristics in UIM

To encrypt characteritics in UIM:

Update the data model in Design Studio by selecting the fields.
For information on modeling, see "Settings Tab" in Design Studio Modeling Basics.
Add encryption key.
For information on adding encryption key, see "Adding Encryption Key" in UIM Online Help.
Note:
- The UIM Super Users with SecureDataAccessGroup role are allowed to set Encryption Key in UIM.
- Once characteristic values are encrypted, they are stored in cipher text format in the UIM entity characteristic tables within the database schema. Do not modify the generated cipher text, as any changes can lead to data inconsistencies and may prevent the original plain text values from being correctly retrieved.
- Back up your encryption key before using the service. If the encryption key is lost, access to the encrypted data cannot be recovered.
The UIM Edit, Summary, and Search pages include the following options for users who are members of the SecureDataAccessGroup role:
- A Decrypt icon to view decrypted values.
- In the Search screen, equals and not equals operators to filter encrypted characteristic values.
Update data using the provided scripts. See "Database Scripts for Encryption in ora_uim_dbtools" for more information.

Use the API to encrypt and decrypt data. Following is the sample code provided for encrypting and decrypting data:

import oracle.communications.inventory.api.entity.utils.CharEncryptorUtil;
import javax.naming.AuthenticationException;
import java.util.NoSuchElementException;

public class SampleEncryption {

    public void demonstrateEncryption() {

        try {
            String plainText = "SamplePlainText";

            // Check if current user has SecureDataAccessGroup role
            boolean isAuthorizedUser = CharEncryptorUtil.isSecuredUser();

            // Encrypt the value
            String encryptedValue = CharEncryptorUtil.encrypt(plainText);
            System.out.println("Encrypted Value : " + encryptedValue);

            // Decrypt the value (only if user has required role) 
            if (isAuthorizedUser) {
                String decryptedValue = CharEncryptorUtil.decrypt(encryptedValue);
                System.out.println("Decrypted Value : " + decryptedValue);
            } else {
                System.out.println("User does not have SecureDataAccessGroup role. Decryption not allowed.");
            }

        } catch (NoSuchElementException e) {
            System.out.println("Encryption key not found : " + e.getMessage());
        } catch (AuthenticationException e) {
            System.out.println("User not authorized to decrypt: " + e.getMessage());
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

Use the encryption key rotation scripts. See "Database Scripts for Encryption in ora_uim_dbtools" for more information.

Database Scripts for Encryption in ora_uim_dbtools

Prerequisites:

Oracle Database Full Client (compatible with your Oracle Database server) is installed.

The PATH and ORACLE_HOME environment variables are set:

export ORACLE_HOME=<Oracle_Client_Path>
export PATH=$ORACLE_HOME/bin:$PATH

The temp_dir_schema directory is created, and the ora_uim_dbtools.jar file is extracted into it.
The UIM schema is backed up.

Note:
This is a database activity that must be performed during scheduled downtime.

To perform encryption in ora_uim_dbtools:

Load the following encryption script:

<full_path>/temp_dir_schema/characteristicsencrypt/loadEncryptionFunction.sh

When you are prompted, enter the database SID and the UIM DB user id and password for the UIM schema which you want to update.
Encrypt the existing data and perform rollback as follows:
1. Follow the steps described in the Load Encryption Functions section.
2. Encrypt the existing data:
  Run the following SQL PLUS script, specifying the full path to the file. For example, use the @scriptFileName command where scriptFileName is the full path and name of the file.
```
@<full_path>/temp_dir_schema/characteristicsencrypt/CharacteristicsEncryptorScript.sql
```
3. Rollback to the original data:
  If you observe any data inconsistency issues after encrypting data using the CharacteristicsEncryptorScript.sql script (above), run the following command to roll back the values in the ENTITY_CHAR tables to their original state.
```
@<full_path>/temp_dir_schema/characteristicsencrypt/CharacteristicsRollBackScript.sql
```
4. Drop the backup tables:
  After successfully encrypting and validating the data, drop the backup tables to free up space:
```
@<full_path>/temp_dir_schema/characteristicsencrypt/dropEncBackUpTables.sql
```
  Note:
  Once the backup tables are dropped, rollback is no longer possible.
5. (Optional) Follow Unload Encryption Functions section to unload encrypt functions.
For decryption in BI Reports:
If you want to decrypt the cipher text to show in BI Reports, perform the following steps:
1. Perform the steps mentioned in Load Encryption Functions section.
2. Run the following SQL PLUS script by providing the full path of the file. For example, use the @scriptFileName command where scriptFileName is the full path and name of the file:
```
@<full_path>/temp_dir_schema/characteristicsencrypt/biReportsDecryptionUtil.sql
```
3. Verify that the DB function UIM_DECRYPT is accessible and working:
Encryption key rotation scripts:
If you need to change the existing encryption key, the encrypted characteristics must be re-encrypted using the new key.

Before rotating the encryption key, ensure that you have backed up the UIM schema. After completing the backup, follow these steps to rotate the encryption key.
1. Perform the steps mentioned in Load Encryption Functions section.
2. Run the following SQL PLUS script by providing the full path of the file. For example, use the @scriptFileName command where scriptFileName is the full path and name of the file:
```
@<full_path>/temp_dir_schema/characteristicsencrypt/CharacteristicsKeyRotationScript.sql
```
3. Rollback to the original data:
  To restore the original (plain text) data, run the following:
```
@<full_path>/temp_dir_schema/characteristicsencrypt/CharacteristicsRollBackScript.sql
```
4. Drop the backup tables:
  After successfully encrypting and validating the data, drop the backup tables to free up space:
```
@<full_path>/temp_dir_schema/characteristicsencrypt/dropEncBackUpTables.sql
```
  Note:
  Once the backup tables are dropped, rollback is no longer possible.
5. Follow Unload Encryption Functions section to unload the Encrypt functions.
Unload encryption functions:
Remove the Encrypt and Decrypt functions from the UIM schema as follows:
```
<full_path>/temp_dir_schema/characteristicsencrypt/unLoadEncryptionFunction.sh
```
Note:
If you plan to use the UIM_Decrypt function in BI Reports, do not perform this step.
Update in the Query Parameters section and sample in REST API.
See UIM REST API Guide for information about how characteristic values are decrypted in REST responses. See UIM Web Services Developer's Guide for information about decrypted values in Service Fulfillment Webservices Responses.