Database Objects
CDP includes database objects that enable accessing some features of the CipherTrust Manager directly from the Oracle Enterprise Manager. These objects include the tables, views, sequences, procedures, and functions document.
User Defined Functions (UDFs) enable interfacing with the NAE Server directly by accessing the procedures in CDP. These UDFs can be used to get session status, retrieve information from the properties file, generate random binary values, convert data types, and encrypt and decrypt data.
Encryption and Decryption UDFs
The encryption and decryption UDFs enable accessing the cryptographic functionality of the NAE Server from the database.
There are two types of cryptographic UDFs:
| UDF | Description |
|---|---|
| Command line | The command line UDFs take the key name, algorithm name, and IV as parameters and apply these values to the input data. The names of these UDFs include the prefix ‘cl’. The input parameters are detailed below. |
| Name | The name UDFs take the schema, table name, column name, and IV as parameters and use these values to recall the encryption metadata (key name, algorithm, and IV). That metadata is then applied to the input data. The names of these UDFs include the prefix ‘nm’. The input parameters are detailed below. Name UDF operations are not permitted while online encryption/key rotation is in progress. |
| Parameter Name | Data Type | Description |
|---|---|---|
| inputData | varies by UDF | The value to be encrypted or decrypted. The data type is abbreviated in the UDF name. This parameter is used for both the command line and the name UDFs. |
| keyName | varchar2 | The name of the key to use to encrypt or decrypt the data. This key must exist on the NAE Server, and the requester must have permission to use the key for the operation requested. This parameter is used for the command line UDFs. Note:For FPE, non-versioned keys are used. |
| algorithmName | varchar2 | For Standard Encryption: A string representing the algorithm, the mode in which the key is used (CBC or ECB), and what kind of padding to use. The format of standard encryption algorithm is AES/CBC/PKCS5Padding. The formats of is FPE are: — FPE/AES/CARD10:TweakAlgorithm:TweakData(orFPEencryptionFormat) —CARD62:TweakAlgorithm:TweakData For example, FPE/AES/CARD10:SHA1:1122 is an algorithm name for FPE, where FPE/AES/CARD10 is algorithm and SHA1 is tweak algorithm and 1122 is tweak data. Note: This parameter is used for the command line UDFs. |
| schemaName | varchar2 | The schema on which the table resides. This parameter is used for the name UDFs. |
| tableName | varchar2 | The table on which the column resides. This parameter is used for the name UDFs. |
| columnName | varchar2 | The column to be operated on. This parameter is used for the name UDFs. |
| iv | raw | The value to use as the Initialization Vector (IV) for data being encrypted or decrypted with a symmetric key (DES, DES-EDE, or AES algorithms) in the CBC mode. For other algorithms or symmetric keys used in the ECB mode, this value is ignored. For operations, which use DES or DES-EDE keys, the IV must be eight-byte; for AES keys, the IV must be sixteen-byte. If an IV is specified here, it must be base 16 encoded. This parameter is used for both the command line and the name UDFs. Note: — The IV value for standard encryption can be null or empty for command line UDFs. For such cases, the value of the IV associated with the Key is used as default value of the IV. —The value of IV for FPE encryption will be of 112 s-integers. |
UDFs are broadly classified into:
You will normally not call these UDFs directly; they are integrated into the data encryption functionality. However, if you want to call these UDFs directly, refer to Examples of Direct UDFs Calls.
Data Type Conversion UDFs
Thales encryption and decryption UDFs automatically convert the input data into RAW using the conversion UDFs shown below. Normally, these UDFs are not called directly, they are integrated into the data migration functionality
The following table describes the process of converting various data types before the encryption UDFs are applied.
| Data Type | Conversion Method |
|---|---|
| VARCHAR2, CHAR, NVARCHAR2, and NCHAR | Converted directly into RAW. |
| NUMBER | Converted into a string and then converted into RAW. |
| DATE | Converted into a standard 31-byte string format, then converted into RAW. |
The following table lists the conversion UDFs.
| Name | Description |
|---|---|
| ingnumbertoraw | Converts a NUMBER value into a RAW value. |
| ingrawtonumber | Converts a RAW value into a NUMBER value. |
| ingdatetoraw | Converts a DATE value into a RAW value. |
| ingrawtodate | Converts a RAW value into a DATE value. |
| ingstringtoraw | Converts a string into a RAW value. |
| ingrawtostring | Converts a RAW value into a string value. |
| ingnstringtoraw | Converts an nstring value into a RAW value. |
| ingrawtonstring | Converts a RAW value into an nstring value. |
Examples of data type conversion UDFs
To convert a number (1000) to a raw value, execute the command:
SQL> select ingnumbertoraw (1000) from dual;
Output:
INGNUMBERTORAW(1000)
----------------------------------------------------
31303030
To convert a string (TestString) to a raw value, execute the command:
SQL> select ingstringtoraw ('TestString') from dual;
Output:
INGSTRINGTORAW('TESTSTRING')
---------------------------------------------------
54657374537472696E67
Generate Random (ing_gn_rndm)
This UDF generates a random binary value of the specified number of bytes. This function is used mainly to generate random IVs. A number of bytes between 1 and 2000 can be requested.
| Parameter Name | Data Type | In/Out | Description |
|---|---|---|---|
| numBytes | number | In | The byte length of the binary value. |
| Return Value | raw | Out | The resulting number. |
Example
SELECT ing_gn_rndm (8)
FROM dual; ------------------
ING_GN_RNDM(8)
F3E3B728F8B5AFA7
