7
PL/SQL Functions

This chapter describes the PL/SQL interface to the Oracle Cryptographic Toolkit. The PL/SQL procedures and functions are grouped into the following five functional categories:

Section 7.1, "General Purpose Procedures"

Section 7.2, "Digital Signature"

Section 7.3, "Data Encryption"

Section 7.4, "Hash"

Section 7.5, "Random Number Generation"

Each PL/SQL function description contains the following information:

Table 7-1 PL/SQL Procedure and Function Descriptions

Purpose	Describes what the procedure or function does
Parameter Descriptions	Lists a detailed description of each parameter name along with its mode and type

7.1 General Purpose Procedures

The following functions and procedures are available to applications. They are contained within the DBMS_CRYPTO_TOOLKIT package. Consult the file DBMS_OCTK.SQL for a full listing of functions and procedures.

Initialize

Initialize starts the Oracle Cryptographic Toolkit operation. No additional parameters are required.

Terminate

Terminate ends the Oracle Cryptographic Toolkit operation. No additional parameters are required.

OpenWallet

OpenWallet opens a wallet based on a given wallet resource locator (WRL). There are two versions of this procedure: one enables an application to use its own data structure for the wallet, and the other lets the application use the wallet data structure that comes with the Oracle Cryptographic Toolkit.

Table 7-2 PROCEDURE OpenWallet

Parameter Name	Mode	Type
password	IN	VARCHAR2
wallet	IN OUT	Wallet
persona_list	OUT	Persona_List
wallet_resource_locator	IN	VARCHAR2

7.1.1 Procedures Used by Applications Which Use the Wallet Kept by the Oracle Cryptographic Toolkit

The following functions and procedures are used by applications which want to use the wallet kept by the Oracle Cryptographic Toolkit.

OpenWallet

OpenWallet opens a wallet based on a given wallet resource locator (optional). There are two versions of this procedure. This version opens the wallet that is kept internally by the package.

Table 7-3 PROCEDURE OpenWallet

Parameter Name	Mode	Type
password	IN	VARCHAR2
persona_list	OUT	Persona_List
wallet_resource_locator	IN	VARCHAR2

CloseWallet

CloseWallet closes a wallet. This version uses the wallet that is kept internally by the package. No parameters are needed for the function.

Table 7-4 PROCEDURE CloseWallet

Parameter Name	Mode	Type

DestroyWallet

DestroyWallet deletes a wallet bases on a given wallet resource locator. The wallet resource locator is optional.

Table 7-5 PROCEDURE DestroyWallet

Parameter Name	Mode	Type
password	IN	VARCHAR2
wallet_resource_locator	IN	VARCHAR2

StorePersona

StorePersona stores a given persona in the specified wallet.

Table 7-6 PROCEDURE StorePersona

Parameter Name	Mode	Type
persona	IN	Persona

OpenPersona

OpenPersona opens a persona within a wallet.

Table 7-7 PROCEDURE OpenPersona

Parameter Name	Mode	Type
persona	IN	Persona

ClosePersona

ClosePersona closes a persona within a wallet.

Table 7-8 PROCEDURE ClosePersona

Parameter Name	Mode	Type
persona	IN	Persona

RemovePersona

RemovePersona removes a persona from a wallet.

Table 7-9 PROCEDURE RemovePersona

Parameter Name	Mode	Type
persona	IN	Persona

CreatePersona

CreatePersona creates a persona.

Table 7-10 PROCEDURE CreatePersona

Parameter Name	Mode	Type
cipher_type	IN	Cipher
private_information	IN OUT	Private_Persona_Information
prl	IN OUT	VARCHAR2
alias	IN	VARCHAR2
longer_description	IN	VARCHAR2
persona	OUT	Persona

RemoveIdentity

RemoveIdentity destroys an identity.

Table 7-11 PROCEDURE RemoveIdentity

Parameter Name	Mode	Type
identity	OUT	Identity

CreateIdentity

CreateIdentity creates an identity.

Table 7-12 CreateIdentity

Parameter Name	Mode	Type
identitytype	IN	Identity_Type
public_identity	IN	VARCHAR2
alias	IN	VARCHAR2
longer_description	IN	VARCHAR2
trust_qualifier	IN	VARCHAR2
identity	OUT	Identity

AbortIdentity

AbortIdentity aborts an identity.

Table 7-13 AbortIdentity

Parameter Name	Mode	Type
identity	IN OUT	Identity
persona	IN

StoreTrustedIdentity

StoreTrustedIdentity stores an identity as a trustpoint within a wallet.

Table 7-14 StoreTrustedIdentity

Parameter Name	Mode	Type
identity	IN OUT	Identity

Validate

Validate uses the trusted identities associated with a persona to validate an identity.

Table 7-15 Validate

Parameter Name	Mode	Type
persona	IN	Persona
identity	IN	Identity
validated	OUT	BOOLEAN

7.2 Digital Signature

Use the following routines to create and verify digital signatures. There are two versions of each routine: one for raw data and another for strings. The routines are as follows:

Section 7.2.1, "Sign"

Section 7.2.2, "Verify"

Section 7.2.3, "SignDetached"

Section 7.2.4, "VerifyDetached"

7.2.1 Sign

Purpose

The Sign routine creates an attached signature.

Parameter Descriptions

Following is a list of parameters, their descriptions, modes, and types.

Table 7-16 Sign parameters for raw data

Parameter Name	Mode	Type
persona	IN	Persona
input	IN	RAW
signature	OUT	RAW
signature_state	IN	Crypto_Engine_State

Table 7-17 Sign parameters for string data

Parameter Name	Mode	Type
persona	IN	Persona
input_string	IN	VARCHAR2
signature	OUT	RAW
signature_state	IN	Crypto_Engine_State

7.2.2 Verify

Purpose

The Verify routine verifies an attached signature.

Parameter Descriptions

Following is a list of parameters, their descriptions, modes, and types.

Table 7-18 Verify parameters for raw data

Parameter Name	Mode	Type
persona	IN	Persona
signature	IN	RAW
extracted_message	OUT	RAW
verified	OUT	BOOLEAN
validated	OUT	BOOLEAN
signing_party_identity	OUT	Identity
signature_state	IN	Crypto_Engine_State

Table 7-19 Verify parameters for string data

Parameter Name	Mode	Type
persona	IN	Persona
signature	IN	RAW
extracted_message_string	OUT	VARCHAR2
verified	OUT	BOOLEAN
validated	OUT	BOOLEAN
signing_party_identity	OUT	Identity
signature_state	IN	Crypto_Engine_State

7.2.3 SignDetached

Purpose

The SignDetached routine generates a detached signature.

Parameter Descriptions

Following is a list of parameters, their descriptions, modes, and types.

Table 7-20 SignDetached parameters for raw data

Parameter Name	Mode	Type
persona	IN	Persona
input	IN	RAW
signature	OUT	RAW
signature_state	IN	Crypto_Engine_State

Table 7-21 SignDetached parameters for string data

Parameter Name	Mode	Type
persona	IN	Persona
input_string	IN	VARCHAR2
signature	OUT	RAW
signature_state	IN	Crypto_Engine_State

7.2.4 VerifyDetached

Purpose

The VerifyDetached routine verifies a detached signature.

Parameter Descriptions

Following is a list of parameters, their descriptions, modes, and types.

Table 7-22 VerifyDetached parameters for raw data

Parameter Name	Mode	Type
persona	IN	Persona
data	IN	RAW
signature	IN	RAW
verified	OUT	BOOLEAN
validated	OUT	BOOLEAN
signing_party_identity	OUT	Identity
signature_state	IN	Crypto_Engine_State

Table 7-23 VerifyDetached parameters for string data

Parameter Name	Mode	Type
persona	IN	Persona
data_string	IN	VARCHAR2
signature	IN	RAW
verified	OUT	BOOLEAN
validated	OUT	BOOLEAN
signing_party_identity	OUT	Identity
signature_state	IN	Crypto_Engine_State

7.3 Data Encryption

Use the following routines to encrypt and decrypt data. There are two versions of each routine: one for raw data and another for strings. The routines are as follows:

Section 7.3.1, "PKEncrypt" (for one recipient)

Section 7.3.2, "PKEncrypt" (for multiple recipients)

Section 7.3.3, "PKDecrypt"

Section 7.3.4, "Encrypt"

Section 7.3.5, "Decrypt"

Section 7.3.6, "Envelope" (for one recipient)

Section 7.3.7, "Envelope" (for multiple recipients)

Section 7.3.8, "DeEnvelope"

7.3.1 PKEncrypt

Purpose

The following routine performs public key encryption of data for one recipient.

Parameter Descriptions

Following is a list of parameters, their descriptions, modes, and types.

Table 7-24 PKEncrypt parameters for raw data

Parameter Name	Mode	Type
persona	IN	Persona
recipient	IN	Identity
input	IN	RAW
encrypted_data	OUT	RAW
encryption_state	IN	Crypto_Engine_State

Table 7-25 PKEncrypt parameters for string data

Parameter Name	Mode	Type
persona	IN	Persona
recipient	IN	Identity
input_string	IN	VARCHAR2
encrypted_string	OUT	VARCHAR2
encryption_state	IN	Crypto_Engine_State

7.3.2 PKEncrypt

Purpose

The following routine performs public key encryption of data for multiple recipients.

Parameter Descriptions

Following is a list of parameters, their descriptions, modes, and types.

Table 7-26 PKEncrypt parameters for raw data

Parameter Name	Mode	Type
persona	IN	Persona
number_of_recipients	IN	POSITIVE
recipient_list	IN	Identity_Array
input	IN	RAW
encrypted_data	OUT	RAW
encryption_state	IN	Crypto_Engine_State

Table 7-27 PKEncrypt parameters for string data

Parameter Name	Mode	Type
persona	IN	Persona
number_of_recipients	IN	Identity_Array
recipient_list	IN	VARCHAR2
input_string	IN	VARCHAR2
encrypted_string	OUT	VARCHAR2
encryption_state	IN	Crypto_Engine_State

7.3.3 PKDecrypt

Purpose

The following routine performs public key decryption of data.

Parameter Descriptions

Following is a list of parameters, their descriptions, modes, and types.

Table 7-28 PKDecrypt parameters for raw data

Parameter Name	Mode	Type
persona	IN	Persona
input	IN	RAW
decrypted_data	OUT	RAW
decryption_state	IN	Crypto_Engine_State

Table 7-29 PKDecrypt parameters for string data

Parameter Name	Mode	Type
persona	IN	Persona
input_string	IN	VARCHAR2
decrypted_string	OUT	VARCHAR2
decryption_state	IN	Crypto_Engine_State

7.3.4 Encrypt

Purpose

The following routine encrypts data for multiple recipients.

Parameter Descriptions

Following is a list of parameters, their descriptions, modes, and types.

Table 7-30 Encrypt parameters for raw data

Parameter Name	Mode	Type
persona	IN	Persona
input	IN	RAW
encrypted_data	OUT	RAW
encryption_state	IN	Crypto_Engine_State

Table 7-31 Encrypt parameters for string data

Parameter Name	Mode	Type
persona	IN	Persona
input_string	IN	VARCHAR2
encrypted_string	OUT	VARCHAR2
encryption_state	IN	Crypto_Engine_State

7.3.5 Decrypt

Purpose

The following routine decrypts data for recipients.

Parameter Descriptions

Following is a list of parameters, their descriptions, modes, and types.

Table 7-32 Decrypt parameters for raw data

Parameter Name	Mode	Type
persona	IN	Persona
encrypted_data	IN	RAW
decrypted_data	OUT	RAW
decryption_state	IN	Crypto_Engine_State

Table 7-33 Decrypt parameters for string data

Parameter Name	Mode	Type
persona	IN	Persona
encrypted_string	IN	VARCHAR2
decrypted_string	OUT	VARCHAR2
decryption_state	IN	Crypto_Engine_State

7.3.6 Envelope

Purpose

The following Envelope routine envelops data for one recipient.

Parameter Descriptions

Following is a list of parameters, their descriptions, modes, and types.

Table 7-34 Envelope parameters for raw data

Parameter Name	Mode	Type
persona	IN	Persona
recipient	IN	Identity
input	IN	RAW
enveloped_data	OUT	RAW
encryption_state	IN	Crypto_Engine_State

Table 7-35 Envelope parameters for string data

Parameter Name	Mode	Type
persona	IN	Persona
recipient	IN	Identity
input_string	IN	VARCHAR2
enveloped_string	OUT	VARCHAR2
encryption_state	IN	Crypto_Engine_State

7.3.7 Envelope

Purpose

The following Envelope routine envelops data for multiple recipients.

Parameter Descriptions

Following is a list of parameters, their descriptions, modes, and types.

Table 7-36 Envelope parameters for raw data

Parameter Name	Mode	Type
persona	IN	Persona
number_of_recipients	IN	POSITIVE
recipient_list	IN	Identity_Array
input	IN	RAW
enveloped_data	OUT	RAW
encryption_state	IN	Crypto_Engine_State

Table 7-37 Envelope parameters for string data

Parameter Name	Mode	Type
persona	IN	Persona
number_of_recipients	IN	POSITIVE
recipient_list	IN	Identity_Array
input_string	IN	VARCHAR2
enveloped_string	OUT	VARCHAR2
encryption_state	IN	Crypto_Engine_State

7.3.8 DeEnvelope

Purpose

The following DeEnvelope routine unwraps and decrypts data.

Parameter Descriptions

Following is a list of parameters, their descriptions, modes, and types.

Table 7-38 DeEnvelope parameters for raw data

Parameter Name	Mode	Type
persona	IN	Persona
enveloped_data	IN	RAW
output_data	OUT	RAW
verified	OUT	BOOLEAN
validated	OUT	BOOLEAN
sender_identity	OUT	Identity
decryption_state	IN	Crypto_Engine_State

Table 7-39 DeEnvelope parameters for string data

Parameter Name	Mode	Type
persona	IN	Persona
enveloped_string	IN	VARCHAR2
output_string	OUT	VARCHAR2
verified	OUT	BOOLEAN
validated	OUT	BOOLEAN
sender_identity	OUT	Identity
decryption_state	IN	Crypto_Engine_State

7.4 Hash

Use the following routines to generate checksums. There are two versions of each routine: one for raw data and another for strings. The routines are as follows:

Section 7.4.1, "KeyedHash"

Section 7.4.2, "Hash"

7.4.1 KeyedHash

Purpose

The following KeyedHash routine generates a public key checksum.

Parameter Descriptions

Following is a list of parameters, their descriptions, modes, and types.

Table 7-40 KeyedHash parameters for raw data

Parameter Name	Mode	Type
persona	IN	Persona
input	IN	RAW
keyed_hash	OUT	RAW
hash_state	IN	Crypto_Engine_State

Table 7-41 KeyedHash parameters for string data

Parameter Name	Mode	Type
persona	IN	Persona
input_string	IN	VARCHAR2
keyed_hash	OUT	RAW
hash_state	IN	Crypto_Engine_State

7.4.2 Hash

Purpose

The following Hash routine generates a checksum.

Parameter Descriptions

Following is a list of parameters, their descriptions, modes, and types.

Table 7-42 Hash parameters for raw data

Parameter Name	Mode	Type
persona	IN	Persona
input	IN	RAW
hash	OUT	RAW
hash_state	IN	Crypto_Engine_State

Table 7-43 Hash parameters for string data

Parameter Name	Mode	Type
persona	IN	Persona
input_string	IN	VARCHAR2
hash	OUT	RAW
hash_state	IN	Crypto_Engine_State

7.5 Random Number Generation

Use the DBMS_RANDOM package to generate random numbers. The routines contained within the package are as follows.

SeedRandom

The following SeedRandom routine supplies a seed to the Oracle Cryptographic Toolkit's random number generator.

Parameter Descriptions

Following is a list of parameter names, their modes, and types.

Table 7-44 SeedRandom parameters for numeric data

Parameter Name	Mode	Type
seed	IN	BINARY_INTEGER

Random

The following routine generates a random number between -9999999999 and 9999999999. This function returns a BINARY_INTEGER.

---