Chapter 21. DBMS_OBFUSCATION

Chapter 21. DBMS_OBFUSCATION_TOOLKIT

Table of Contents

21.2.1. DES3DECRYPT
21.2.2. DES3ENCRYPT
21.2.3. DES3GETKEY
21.2.4. DESDECRYPT
21.2.5. DESENCRYPT
21.2.6. DESGETKEY
21.2.7. MD5

This chapter briefly introduces the DBMS_OBFUSCATION_TOOLKIT package, and describes how to use the procedures and functions of the package.

21.1. Overview

DBMS_OBFUSCATION_TOOLKIT encrypts and decrypts data. This package uses the DES (Data Encryption Standard) or 3DES (Triple DES) algorithm for data encryption and decryption.

DES and 3DES use symmetric key encryption.

Algorithm	Description
DES	Divides data into 64-bit blocks, and uses a 56-bit key for each block. This algorithm was once widely used, but it has been used less recently due to its security vulnerability. Uses symmetric keys.
3DES	Applies the DES algorithm two or three times to a single data block using a 112(562)-bit or 168(563)-bit key. This also uses symmetric-key encryption. Compared to other algorithms that use symmetric-key encryption, this algorithm requires a relatively long time for encryption and decryption.

Algorithm

Description

DES

Divides data into 64-bit blocks, and uses a 56-bit key for each block. This algorithm was once widely used, but it has been used less recently due to its security vulnerability.

Uses symmetric keys.

3DES

Applies the DES algorithm two or three times to a single data block using a 112(56*2)-bit or 168(56*3)-bit key. This also uses symmetric-key encryption.

Compared to other algorithms that use symmetric-key encryption, this algorithm requires a relatively long time for encryption and decryption.

It is important to manage the key in a secure manner for algorithms that use symmetric-key encryption.

Encryption algorithms can manage the key as follows:

Saving the key in the database

Stores the key in a column of a specific table.

The table can be the same or different from the table that contains the encrypted data. When storing the key in the same table, the table must be accessed via a view or the tbPSM program instead of allowing direct access to the table.
Saving the key in an OS file

Stores the key in an OS file, from which the tbPSM program reads the key to encrypt or decrypt data in the database.

Like a password file, the OS file must be secure from other's access.
Direct user entry

Encrypts and decrypts data by transferring the key to the database whenever it is required by the user or application.

To do so, the user must memorize the key, or the key must be included in the application source code. Since the key is transferred to the database server over the network, network security is also required.

21.2. Procedures and Functions

This chapter describes the procedures and functions of the DBMS_OBFUSCATION_TOOLKIT package, in alphabetical order.

21.2.1. DES3DECRYPT

Decrypts encrypted data using the 3DES algorithm. Executes DES decryption two or three times to the given data.

If decryption is executed twice for the given key, the key must be 16 bytes (128 bits), and if executed three times, it must be 24 bytes (192 bits). Otherwise, an exception will occur. The default setting is to execute DES decryption twice. The DES decryption algorithm must be executed as many times as the data was encrypted.

Details about the DES3DECRYPT procedure and function are as follows:

Prototype

Procedure

DBMS_OBFUSCATION_TOOLKIT.DES3DECRYPT 
(
    input               IN          RAW,
    key                 IN          RAW,
    decrypted_data      OUT         RAW,
    which               IN          PLS_INTEGER    DEFAULT 0,
    iv                  IN          RAW            DEFAULT NULL
);

DBMS_OBFUSCATION_TOOLKIT.DES3DECRYPT 
(
    input_string        IN          VARCHAR2,
    key_string          IN          VARCHAR2,
    decrypted_string    OUT         VARCHAR2,
    which               IN          PLS_INTEGER    DEFAULT 0,
    iv_string           IN          VARCHAR2       DEFAULT NULL
);

Function

DBMS_OBFUSCATION_TOOLKIT.DES3DECRYPT 
(
    input               IN          RAW,
    key                 IN          RAW,
    which               IN          PLS_INTEGER    DEFAULT 0,
    iv                  IN          RAW            DEFAULT NULL
) 
RETURN RAW;

DBMS_OBFUSCATION_TOOLKIT.DES3DECRYPT 
(
    input_string        IN          VARCHAR2,
    key_string          IN          VARCHAR2,
    which               IN          PLS_INTEGER    DEFAULT 0,
    iv_string           IN          VARCHAR2       DEFAULT NULL
) 
RETURN VARCHAR2;

Parameter

Parameter	Description
input, input_string	Data to decrypt.
key	Decryption key.
decrypted_data	Decrypted data.
which	0: DES decryption is executed twice. 1: DES decryption is executed three times.
iv	Initialization vector.

Exception

Exception	Description
INVALID_ARGUMENT	Occurs when any parameter is NULL.
INVALID_INPUT	Occurs when the length of input_data is not a multiple of 8.
KEY_TOO_SHORT	Occurs when key is shorter than 8.
INVALID_DES_MODE	Occurs when the value of which is neither 0 nor 1.

Example

DECLARE
    data RAW(256);
    key RAW(16);
    encrypted_data RAW(256);
    decrypted_data RAW(256);
BEGIN
    data := '0102030405AE030D0123456789ABCDEF';
    key := '0A123B8E002CD3FF01DE2389A4567BCF';
    DBMS_OBFUSCATION_TOOLKIT.DES3Encrypt(input => data, key => key, 
            encrypted_data => encrypted_data);
    data := encrypted_data;
    DBMS_OBFUSCATION_TOOLKIT.DES3Decrypt(input => data, key => key, 
            decrypted_data => decrypted_data);
END;

21.2.2. DES3ENCRYPT

Encrypts data using the 3DES algorithm. Executes DES encryption two or three times for the given data.

If encryption is executed twice for the given key, the key should be 16 bytes (128 bits), and if executed three times, it should be 24 bytes (192 bits). Otherwise, an exception will occur. The default setting is to execute DES encryption twice.

Details about the DES3ENCRYPT procedure and function are as follows:

Prototype

Procedure

DBMS_OBFUSCATION_TOOLKIT.DES3ENCRYPT 
(
    input               IN          RAW,
    key                 IN          RAW,
    encrypted_data      OUT         RAW,
    which               IN          PLS_INTEGER    DEFAULT 0,
    iv                  IN          RAW            DEFAULT NULL
);

DBMS_OBFUSCATION_TOOLKIT.DES3ENCRYPT 
(
     input_string        IN          VARCHAR2,
     key_string          IN          VARCHAR2,
     encrypted_string    OUT         VARCHAR2,
     which               IN          PLS_INTEGER    DEFAULT 0,
     iv_string           IN          VARCHAR2       DEFAULT NULL
);

Function

DBMS_OBFUSCATION_TOOLKIT.DES3ENCRYPT 
(
     input               IN          RAW,
     key                 IN          RAW,
     which               IN          PLS_INTEGER    DEFAULT 0,
     iv                  IN          RAW            DEFAULT NULL
) 
RETURN RAW;

DBMS_OBFUSCATION_TOOLKIT.DES3ENCRYPT 
(
    input_string        IN          VARCHAR2,
    key_string          IN          VARCHAR2,
    which               IN          PLS_INTEGER    DEFAULT 0,
    iv_string           IN          VARCHAR2       DEFAULT NULL
) 
RETURN VARCHAR2;

Parameter

Parameter	Description
input, input_string	Data to encrypt.
key	Encryption key.
encrypted_data	Encrypted data.
which	0: DES encryption is executed twice. 1: DES encryption is executed three times.
iv	Initialization vector.

Exception

Exception	Description
INVALID_ARGUMENT	Occurs when any parameter is NULL.
INVALID_INPUT	Occurs when the length of input_data is not a multiple of 8.
KEY_TOO_SHORT	Occurs when key is less than 8 bytes.
INVALID_DES_MODE	Occurs when the value of which is neither 0 nor 1.

Example

DECLARE
    data RAW(256);
    key RAW(16);
    encrypted_data RAW(256);
    decrypted_data RAW(256);
BEGIN
    data := '0102030405AE030D0123456789ABCDEF';
    key := '0A123B8E002CD3FF01DE2389A4567BCF';
    DBMS_OBFUSCATION_TOOLKIT.DES3Encrypt(input => data, key => key, 
            encrypted_data => encrypted_data);
    data := encrypted_data;
    DBMS_OBFUSCATION_TOOLKIT.DES3Decrypt(input => data, key => key, 
            decrypted_data => decrypted_data);
END;

21.2.3. DES3GETKEY

Receives an input value to create a key for the DES3 algorithm.

Details about the DES3GETKEY procedure and function are as follows:

Prototype

Procedure

DBMS_OBFUSCATION_TOOLKIT.DES3GETKEY 
(
    which           IN          PLS_INTEGER     DEFAULT 0,
    seed            IN          RAW,
    key             OUT         RAW
);

DBMS_OBFUSCATION_TOOLKIT.DES3GETKEY 
(
    which           IN          PLS_INTEGER     DEFAULT 0,
    seed_string     IN          VARCHAR2,
    key             OUT         VARCHAR2
);

Function

DBMS_OBFUSCATION_TOOLKIT.DES3GETKEY 
(
    which           IN          PLS_INTEGER     DEFAULT 0,
    seed            IN          RAW
) 
RETURN RAW;

DBMS_OBFUSCATION_TOOLKIT.DES3GETKEY 
(
    which           IN          PLS_INTEGER     DEFAULT 0,
    seed_string     IN          VARCHAR2
) 
RETURN VARCHAR2;

Parameter

Parameter	Description
which	0: DES encryption is executed twice. 1: DES encryption is executed three times.
seed	Input value of 80 or more characters.
key	Encryption key.

Exception

Exception	Description
NO_SEED	Occurs when seed is NULL.
SEED_TOO_SHORT	Occurs when seed contains less than 80 characters.
INVALID_INPUT	Occurs when which is NULL.
INVALID_DES_MODE	Occurs when which is neither 0 nor 1.

Example

DECLARE
    data VARCHAR2(4096);
    key VARCHAR2(4096);
 key_seed VARCHAR2(4096);
    encrypted_data VARCHAR2(4096);
    decrypted_data VARCHAR2(4096);
BEGIN
    data := '0102030405AE030D';
    key_seed := '1234567890'||'1234567890'||'1234567890'||'1234567890';
    key_seed := rpad(key_seed,80);
    key := dbms_obfuscation_toolkit.DES3GetKey(seed_string => key_seed);
    DBMS_OBFUSCATION_TOOLKIT.DES3Encrypt(input_string => data, key_string => key,
            encrypted_string=> encrypted_data);
    data := encrypted_data;
    DBMS_OBFUSCATION_TOOLKIT.DES3Decrypt(input_string => data, key_string => key,
            decrypted_string => decrypted_data);
END;
/

21.2.4. DESDECRYPT

Decrypts encrypted data using the DES algorithm. The key given for decryption must be 8 bytes (64 bits). Otherwise, an exception occurs.

Details about the DESDECRYPT procedure and function are as follows:

Prototype

Procedure

DBMS_OBFUSCATION_TOOLKIT.DESDECRYPT 
(
    input               IN          RAW,
    key                 IN          RAW,
    decrypted_data      OUT         RAW
);

DBMS_OBFUSCATION_TOOLKIT.DESDECRYPT 
(
    input_string        IN          VARCHAR2,
    key_string          IN          VARCHAR2,
    decrypted_string    OUT         VARCHAR2
);

Function

DBMS_OBFUSCATION_TOOLKIT.DESDECRYPT 
(
    input               IN          RAW,
    key                 IN          RAW
) 
RETURN RAW;

DBMS_OBFUSCATION_TOOLKIT.DESDECRYPT 
(
    input_string        IN          VARCHAR2,
    key_string          IN          VARCHAR2
)
RETURN VARCHAR2;

Parameter

Parameter Description
input, input_string Data to decrypt.
key Decryption key.
decrypted_data Decrypted data.

Exception

Exception	Description
INVALID_ARGUMENT	Occurs when any parameter is NULL.
INVALID_INPUT	Occurs when the length of input_data is not a multiple of 8.
KEY_TOO_SHORT	Occurs when key is shorter than 8 bytes.

Example

DECLARE
    data RAW(256);
    key RAW(16);
    encrypted_data RAW(256);
    decrypted_data RAW(256);
BEGIN
    data := '0102030405AE030D';
    key := '0A123B8E002CD3FF';
    DBMS_OBFUSCATION_TOOLKIT.DESEncrypt(input => data, key => key, 
            encrypted_data => encrypted_data);
    data := encrypted_data;
    DBMS_OBFUSCATION_TOOLKIT.DESDecrypt(input => data, key => key, 
            decrypted_data => decrypted_data);
END;

21.2.5. DESENCRYPT

Encrypts data using the DES algorithm. The key given for encryption must be 8 bytes (64 bits). Otherwise, an exception occurs.

Details about the DESENCRYPT procedure and function are as follows:

Prototype

Procedure

DBMS_OBFUSCATION_TOOLKIT.DESENCRYPT 
(
    input               IN          RAW,
    key                 IN          RAW,
    encrypted_data      OUT         RAW
);

DBMS_OBFUSCATION_TOOLKIT.DESENCRYPT 
(
    input_string        IN          VARCHAR2,
    key_string          IN          VARCHAR2,
    encrypted_string    OUT         VARCHAR2
);

Function

DBMS_OBFUSCATION_TOOLKIT.DESENCRYPT 
(
    input               IN          RAW,
    key                 IN          RAW
) 
RETURN RAW;

DBMS_OBFUSCATION_TOOLKIT.DESENCRYPT 
(
    input_string        IN          VARCHAR2,
    key_string          IN          VARCHAR2
) 
RETURN VARCHAR2;

Parameter

Parameter Description
input, input_string Data to encrypt.
key Encryption key.
encrypted_data Encrypted data.

Exception

Exception	Description
INVALID_ARGUMENT	Occurs when any parameter is NULL..
INVALID_INPUT	Occurs when the length of input_data is not a multiple of 8.
KEY_TOO_SHORT	Occurs when key is shorter than 8 bytes.

Example

DECLARE
    data RAW(256);
    key RAW(16);
    encrypted_data RAW(256);
    decrypted_data RAW(256);
BEGIN
    data := '0102030405AE030D';
    key := '0A123B8E002CD3FF';
    DBMS_OBFUSCATION_TOOLKIT.DESEncrypt(input => data, key => key, 
            encrypted_data => encrypted_data);
    data := encrypted_data;
    DBMS_OBFUSCATION_TOOLKIT.DESDecrypt(input => data, key => key, 
            decrypted_data => decrypted_data);
END;

21.2.6. DESGETKEY

Receives an input value to generate a key for the DES algorithm.

Details about the DESGETKEY procedure and function are as follows:

Prototype

Procedure

DBMS_OBFUSCATION_TOOLKIT.DESGETKEY 
(
    seed            IN          RAW,
    key             OUT         RAW
);

DBMS_OBFUSCATION_TOOLKIT.DESGETKEY 
(
    seed_string     IN          VARCHAR2,
    key             OUT         VARCHAR2
);

Function

DBMS_OBFUSCATION_TOOLKIT.DESGETKEY 
(
    seed            IN          RAW
) 
RETURN RAW;

DBMS_OBFUSCATION_TOOLKIT.DESGETKEY 
(
    seed_string     IN          VARCHAR2
) 
RETURN VARCHAR2;

Parameter

Parameter Description
seed Input value of 80 or more characters.
key Encryption key.
Exception

Exception Description
NO_SEED Occurs when seed is NULL.
SEED_TOO_SHORT Occurs when seed contains less than 80 characters.

Parameter	Description
seed	Input value of 80 or more characters.
key	Encryption key.

Example

DECLARE
    data VARCHAR2(4096);
    key VARCHAR2(4096);
 key_seed VARCHAR2(4096);
    encrypted_data VARCHAR2(4096);
    decrypted_data VARCHAR2(4096);
BEGIN
    data := '0102030405AE030D';
    key_seed := '1234567890'||'1234567890'||'1234567890'||'1234567890';
    key_seed := rpad(key_seed,80);
    key := dbms_obfuscation_toolkit.DESGetKey(seed_string => key_seed);
    DBMS_OBFUSCATION_TOOLKIT.DESEncrypt(input_string => data, key_string => key,
            encrypted_string=> encrypted_data);
    data := encrypted_data;
    DBMS_OBFUSCATION_TOOLKIT.DESDecrypt(input_string => data, key_string => key,
            decrypted_string => decrypted_data);
END;
/

21.2.7. MD5

Takes an input value and creates a MD5 algorithm checksum.

Details about the MD5 procedure and function are as follows:

Prototype

Procedure

DBMS_OBFUSCATION_TOOLKIT.MD5 
(
    input           IN          RAW,
    checksum        OUT         RAW
);

DBMS_OBFUSCATION_TOOLKIT.MD5 
(
    input_string            IN          VARCHAR2,
    checksum_string         OUT         VARCHAR2
);

Function

DBMS_OBFUSCATION_TOOLKIT.MD5 
(
    input           IN          RAW
) 
RETURN RAW;

DBMS_OBFUSCATION_TOOLKIT.MD5 
(
    input_string          IN          VARCHAR2
) 
RETURN VARCHAR2;

Parameter

Parameter Description
input or input_string Value to encrypt.
checksum Checksum calculated using the input value.
Exception

Exception Description
NO_DATA_PASSED Occurs when the input value is NULL.

Prev		Next
Chapter 20. DBMS_MVIEW	Home	Chapter 22. DBMS_OUTPUT

Parameter	Description
input or input_string	Value to encrypt.
checksum	Checksum calculated using the input value.