The DBMS_CRYPTO package enables encryption and decryption for common Oracle datatypes, including RAW and large objects (LOBs), such as images and sound. Specifically, it supports BLOBs and CLOBs. In addition, it provides Globalization Support for encrypting data across different database character sets. It also supports asymmetric key functions.

The following cryptographic algorithms are supported:

• Data Encryption Standard (DES), Triple DES (3DES, 2-key and 3-key) (deprecated)

• Advanced Encryption Standard (AES)

• MD5 (deprecated), SHA-1 (deprecated), and SHA-2 and SHA-3 cryptographic hashes

• MD5, SHA-1, and SHA-2 and SHA-3 Message Authentication Code (MAC), SHA-3 KMACXOF

• SM2, SM3, SM4 (SM stands for ShangMi)

Block cipher modifiers are also provided with DBMS_CRYPTO. You can choose from several padding options, including PKCS (Public Key Cryptographic Standard) #5, and from six block cipher chaining modes, including Cipher Block Chaining (CBC).

Table 57-1 summarizes the DBMS_CRYPTO package features.

The DBMS_CRYPTO package replaces DBMS_OBFUSCATION_TOOLKIT, providing greater ease of use and support for a range of algorithms to accommodate new and existing systems. Specifically, 3DES_2KEY are provided for backward compatibility. It is not recommended that you use these algorithms because they do not provide the same level of security as provided by 3DES, AES, MD5, SHA-1, or SHA-2.

These are shown in the following tables.

• When to Use Encrypt and Decrypt Procedures or Functions

• When to Use Hash or Message Authentication Code (MAC) Functions

• About Generating and Storing Encryption Keys

• Conversion Rules

When to Use Encrypt and Decrypt Procedures or Functions

This package includes both ENCRYPT and DECRYPT procedures and functions. The procedures are used to encrypt or decrypt LOB datatypes (overloaded for CLOB and BLOB datatypes). In contrast, the ENCRYPT and DECRYPT functions are used to encrypt and decrypt RAW datatypes. Data of type VARCHAR2 must be converted to RAW before you can use DBMS_CRYPTO functions to encrypt it.

When to Use Hash or Message Authentication Code (MAC) Functions

This package includes two different types of one-way hash functions: the HASH function and the MAC function. Hash functions operate on an arbitrary-length input message, and return a fixed-length hash value. One-way hash functions work in one direction only. It is easy to compute a hash value from an input message, but it is extremely difficult to generate an input message that hashes to a particular value. Note that hash values should be at least 256 bits in length to be considered secure.

You can use hash values to verify whether data has been altered. For example, before storing data, the user runs DBMS_CRYPTO.HASH against the stored data to create a hash value. On returning the stored data, the user can again run the hash function against it, using the same algorithm. If the second hash value is identical to the first one, then the data has not been altered. Hash values are similar to "file fingerprints" and are used to ensure data integrity.

The HASH function included with DBMS_CRYPTO, is a one-way hash function that you can use to generate a hash value from either RAW or LOB data. The MAC function is also a one-way hash function, but with the addition of a secret key. It works the same way as the DBMS_CRYPTO.HASH function, except only someone with the key can verify the hash value.

MACs can be used to authenticate files between users. They can also be used by a single user to determine if her files have been altered, perhaps by a virus. A user could compute the MAC of his files and store that value in a table. If the user did not use a MAC function, then the virus could compute the new hash value after infection and replace the table entry. A virus cannot do that with a MAC because the virus does not know the key.

About Generating and Storing Encryption Keys

The DBMS_CRYPTO package can generate random material for encryption keys, but it does not provide a mechanism for maintaining them. Application developers must take care to ensure that the encryption keys used with this package are securely generated and stored. Also note that the encryption and decryption operations performed by DBMS_CRYPTO occur on the server, not on the client. Consequently, if the key is sent over the connection between the client and the server, the connection must be protected by using network encryption. Otherwise, the key is vulnerable to capture over the wire.

Although DBMS_CRYPTO cannot generate keys on its own, it does provide tools you can use to aid in key generation. For example, you can use the RANDOMBYTES function to generate random material for keys.

When generating encryption keys for DES, it is important to remember that some numbers are considered weak and semiweak keys. Keys are considered weak or semiweak when the pattern of the algorithm combines with the pattern of the initial key value to produce ciphertext that is more susceptible to cryptanalysis. To avoid this, filter out the known weak DES keys. Lists of the known weak and semiweak DES keys are available on several public Internet sites.

Conversion Rules

• To convert VARCHAR2 to RAW, use the UTL_I18N.STRING_TO_RAW function to perform the following steps:

  1. Convert VARCHAR2 in the current database character set to VARCHAR2 in the AL32UTF8 database character.

  2. Convert VARCHAR2 in the AL32UTF8 database character set to RAW.

  Syntax example:

  UTL_I18N.STRING_TO_RAW (string, 'AL32UTF8');
  

• To convert RAW to VARCHAR2, use the UTL_I18N.RAW_TO_CHAR function to perform the following steps:

  1. Convert RAW to VARCHAR2 in the AL32UTF8 database character set.

  2. Convert VARCHAR2 in the AL32UTF8 database character set to VARCHAR2 in the database character set you wish to use.

  Syntax example:

  UTL_I18N.RAW_TO_CHAR (data, 'AL32UTF8');

  See Also:

  UTL_I18N for information about using the UTL_I18N PL/SQL package.

• If you want to store encrypted data of the RAW datatype in a VARCHAR2 database column, then use RAWTOHEX or UTL_ENCODE.BASE64_ENCODE to make it suitable for VARCHAR2 storage. These functions expand data size by 2 and 4/3, respectively.

Example 1: AES Encryption with Cipher Block Chaining and PKCS#5 Compliant Padding

This example shows PL/SQL block encrypting and decrypting pre-defined input_string using 256-bit AES algorithm with Cipher Block Chaining and PKCS#5 compliant padding.

DECLARE
   input_string       VARCHAR2 (200) :=  'Secret Message';
   output_string      VARCHAR2 (200);
   encrypted_raw      RAW (2000);             -- stores encrypted binary text
   decrypted_raw      RAW (2000);             -- stores decrypted binary text
   num_key_bytes      NUMBER := 256/8;        -- key length 256 bits (32 bytes)
   key_bytes_raw      RAW (32);               -- stores 256-bit encryption key
   encryption_type    PLS_INTEGER :=          -- total encryption type

                            DBMS_CRYPTO.ENCRYPT_AES256
                          + DBMS_CRYPTO.CHAIN_CBC
                          + DBMS_CRYPTO.PAD_PKCS5;

   iv_raw             RAW (16);

BEGIN
   DBMS_OUTPUT.PUT_LINE ( 'Original string: ' || input_string);
   key_bytes_raw := DBMS_CRYPTO.RANDOMBYTES (num_key_bytes);
   iv_raw        := DBMS_CRYPTO.RANDOMBYTES (16);
   encrypted_raw := DBMS_CRYPTO.ENCRYPT
      (
         src => UTL_I18N.STRING_TO_RAW (input_string,  'AL32UTF8'),
         typ => encryption_type,
         key => key_bytes_raw,
         iv  => iv_raw
      );

    -- The encrypted value "encrypted_raw" can be used here

    decrypted_raw := DBMS_CRYPTO.DECRYPT
      (
         src => encrypted_raw,
         typ => encryption_type,
         key => key_bytes_raw,
         iv  => iv_raw
      );

   output_string := UTL_I18N.RAW_TO_CHAR (decrypted_raw, 'AL32UTF8');

   DBMS_OUTPUT.PUT_LINE ('Decrypted string: ' || output_string); 
END;

Example 2: PKENCRYPTION and PKDECRYPTION Functions

DECLARE
  ip_str     VARCHAR (200) := 'Secret Message';
  op_str     VARCHAR (200);
  -- Use OpenSSL to generate the private and public key (2048 bit RSA key)
  -- openssl genrsa -out private.pem 2048
  -- openssl rsa -in private.pem -outform PEM -pubout -out public.pem
  pubkey    VARCHAR (2000) := 'public_key';
  prvkey    VARCHAR (2000) := 'private_key';
  enc_raw    RAW (2000);
  dec_raw    RAW (2000);
  eType      PLS_INTEGER := DBMS_CRYPTO.PKENCRYPT_RSA_PKCS1_OAEP_SHA2;
  kType      PLS_INTEGER := DBMS_CRYPTO.KEY_TYPE_RSA;

BEGIN

  DBMS_OUTPUT.PUT_LINE('-------------------------------------------------');
  DBMS_OUTPUT.PUT_LINE('Original String := ' || ip_str);
  DBMS_OUTPUT.PUT_LINE('-------------------------------------------------');
  enc_raw:= DBMS_CRYPTO.PKENCRYPT
  (
    src        => UTL_I18N.STRING_TO_RAW(ip_str,'AL32UTF8'),
    pub_key    => UTL_I18N.STRING_TO_RAW( pubkey, 'AL32UTF8'),
    pubkey_alg => kType,
    enc_alg    => eType
  );

  dec_raw := DBMS_CRYPTO.PKDECRYPT
  (
    src        => enc_raw,
    prv_key    => UTL_I18N.STRING_TO_RAW( prvkey, 'AL32UTF8'),
    pubkey_alg => kType,
    enc_alg    => eType
  );
  op_str := UTL_I18N.RAW_TO_CHAR(dec_raw,'AL32UTF8');
  dbms_output.put_line('-------------------------------------------------');
  dbms_output.put_line('Decrypted String := ' || op_str);
  dbms_output.put_line('-------------------------------------------------');
end;
/

Example 3: SIGN and VERIFY Functions

DECLARE
  ip_str     VARCHAR2 (200) := 'Secret Message';
  -- Use OpenSSL to generate the private and public key (2048 bit RSA key)
  -- openssl genrsa -out private.pem 2048
  -- openssl rsa -in private.pem -outform PEM -pubout -out public.pem
  pubkey    VARCHAR (2000) := 'public_key';
  prvkey    VARCHAR (2000) := 'private_key'; 
  sign_raw   RAW (2000);
  returnval  BOOLEAN := false;
  sType      PLS_INTEGER := DBMS_CRYPTO.SIGN_SHA224_RSA;
  kType      PLS_INTEGER := DBMS_CRYPTO.KEY_TYPE_RSA;
BEGIN
  sign_raw := DBMS_CRYPTO.SIGN
  (
   src        => UTL_I18N.STRING_TO_RAW(ip_str,'AL32UTF8'),
   prv_key    => UTL_I18N.STRING_TO_RAW( prvkey, 'AL32UTF8'),
   pubkey_alg => kType,
   sign_alg   => sType
  );
  returnval := DBMS_CRYPTO.VERIFY
  (
   src        => UTL_I18N.STRING_TO_RAW( ip_str,'AL32UTF8'),
   sign       => sign_raw,
   pub_key    => UTL_I18N.STRING_TO_RAW( pubkey, 'AL32UTF8'),
   pubkey_alg => kType,
   sign_alg   => sType
  );
  DBMS_OUTPUT.PUT_LINE('-------------------------------------------------');
  IF returnval THEN
    DBMS_OUTPUT.PUT_LINE('True');
  ELSE
    DBMS_OUTPUT.PUT_LINE('False');
  END IF;
  DBMS_OUTPUT.PUT_LINE('-------------------------------------------------');
END;
/

Example 4: HASH_SHA3_256 and HASH_SHAKE256 Hash Functions

DECLARE
  ip_str VARCHAR2 (200) := 'Secret Message';
  output_string VARCHAR2 (2000);
  source_text_raw RAW (2000);
  hash_raw RAW (2000);
BEGIN
  source_text_raw := UTL_I18N.STRING_TO_RAW(ip_str,'AL32UTF8');
  hash_raw := dbms_crypto.hash(source_text_raw, dbms_crypto.hash_sha3_256);

  output_string := RAWTOHEX(hash_raw);

  DBMS_OUTPUT.PUT_LINE ('Hash string: ' || output_string);
  DBMS_OUTPUT.PUT_LINE (utl_raw.length(hash_raw);
END;
/


HASH_SHAKE256:

DECLARE
  ip_str VARCHAR2 (200) := 'Secret Message';
  output_string VARCHAR2 (2000);
  source_text_raw RAW (2000);
  hash_raw RAW (2000);
  len PLS_INTEGER := 30;
BEGIN
  source_text_raw := UTL_I18N.STRING_TO_RAW(ip_str,'AL32UTF8');
  hash_raw := dbms_crypto.hash_len(source_text_raw, dbms_crypto.hash_shake256, len);

  output_string := RAWTOHEX(hash_raw);

  DBMS_OUTPUT.PUT_LINE ('Hash string: ' || output_string);
END;
/

Example 5: HMAC_SHA3_256 and SIGN_SHA3_256_RSA Functions

DECLARE
  ip_str VARCHAR2 (200) := 'Secret Message';
  output_string VARCHAR2 (2000);
  source_text_raw RAW (2000);
  hmac_raw RAW (2000);
  testkey RAW (2000);
BEGIN
  source_text_raw := UTL_I18N.STRING_TO_RAW(ip_str,'AL32UTF8');
  -- Use your test key
  testkey := HEXTORAW('');
  hmac_raw := dbms_crypto.mac(source_text_raw, dbms_crypto.HMAC_SHA3_256, testkey);

  output_string := RAWTOHEX(hmac_raw);

  DBMS_OUTPUT.PUT_LINE ('Hmac string: ' || output_string);
END;
/

SIGN_SHA3_256_RSA:

DECLARE
  ip_str VARCHAR2 (200) := 'Secret Message';
  -- Use OpenSSL to generate the private and public key (2048 bit RSA key)
  -- openssl genrsa -out private.pem 2048
  -- openssl rsa -in private.pem -outform PEM -pubout -out public.pem
  pubkey VARCHAR (2000) := 'public_key';
  prvkey VARCHAR (2000) := 'private_key';
  sign_raw RAW (2000);
  returnval BOOLEAN := false;
  sType PLS_INTEGER := DBMS_CRYPTO.SIGN_SHA3_256_RSA;
  kType PLS_INTEGER := DBMS_CRYPTO.KEY_TYPE_RSA;
BEGIN
  sign_raw := DBMS_CRYPTO.SIGN
  (
   src => UTL_I18N.STRING_TO_RAW(ip_str,'AL32UTF8'),
   prv_key => UTL_I18N.STRING_TO_RAW( prvkey, 'AL32UTF8'),
   pubkey_alg => kType,
   sign_alg => sType
  );
  returnval := DBMS_CRYPTO.VERIFY
  (
   src => UTL_I18N.STRING_TO_RAW( ip_str,'AL32UTF8'),
   sign => sign_raw,
   pub_key => UTL_I18N.STRING_TO_RAW( pubkey, 'AL32UTF8'),
   pubkey_alg => kType,
   sign_alg => sType
  );
  DBMS_OUTPUT.PUT_LINE('-------------------------------------------------');
  IF returnval THEN
    DBMS_OUTPUT.PUT_LINE('True');
  ELSE
    DBMS_OUTPUT.PUT_LINE('False');
  END IF;
  DBMS_OUTPUT.PUT_LINE('-------------------------------------------------');
END;
/