6
OCI Functions for C

This chapter describes each Oracle Call Interface (OCI) function in the Oracle Cryptographic Toolkit. Each OCI function description contains the following information:

Purpose	Describes what the function does
Parameter Descriptions	Lists a detailed description of each parameter name along with its description, mode, and type
Comments	Gives detailed information about the OCI function and includes an example
Errors	Lists some of the possible values returned by the function.

Refer to Chapter 2, OCI Programming Basics, in the Programmer's Guide to the Oracle Call Interface^TM for an overview of the steps involved in calling OCI functions.

Refer to Appendix B, "OCI - API Mappings" for a list of OCI functions and the API functions to which they map.

6.1 OCISecurityInitialize

Purpose

OCISecurityInitialize must be called after the user gets a security handle but before any security function is called.

Error Handles

Error handles are passed as parameters to OCI calls. Error handles are allocated at the beginning of an OCI application. The following handles are passed:

Table 6-1 OCISecurityInitialize Handles

Handle Type	Handle Name
OCISecurity	osshandle
OCIError	error_handle

6.2 OCISecurityTerminate

Purpose

OCISecurityTerminate must be called after the user has finished using the security routines.

Parameter Descriptions

Following is a list of parameters and their descriptions.

Table 6-2 OCISecurityTerminate parameters

Parameter Name	Description
OCISecurity	osshandle
OCIError	error_handle

6.3 OCISecurityOpenWallet

Purpose

OCISecurityOpenWallet opens a wallet based on the wallet resource locator (WRL).

Parameter Descriptions

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

Table 6-3 OCISecurityOpenWallet parameters

Parameter Name	Description	Mode	Type
OCISecurity	osshandle
OCIError	error_handle
wrllen	Length of wallet resource locator	[IN]	size_t
wallet_resource_locator	Wallet resource locator	[IN]	text
pwdlen	Length of password	[IN]	size_t
password	Password	[IN]	text
wallet	Initialized wallet structure	[IN]	nzttWallet

Comments

Defaults: The platform specific WRL default is used when the WRL is NZT_DEFAULT_WRL. Use the WRL type specific default (e.g., "oracle:") when only the wallet type is specified.

A wallet is opened and its password is verified by hashing it and comparing the result with the password hash stored with the wallet. The list of personas and their associated identities is built and stored into the wallet structure.

Implication: An Oracle based wallet can be implemented either in a user's private space or in world readable space.

6.4 OCISecurityCloseWallet

Purpose

OCISecurityCloseWallet closes a wallet based on the wallet resource locator (WRL).

Parameter Descriptions

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

Table 6-4 OCISecurityCloseWallet parameters

Parameter Name	Description	Mode	Type
OCISecurity	osshandle
OCIError	error_handle
wallet	Initialized wallet structure	[IN]	nzttWallet

Comments

Closing a wallet also closes all personas associated with that wallet. Any changes you have made to the persona will not automatically be saved.

Implication: An application can modify a persona, but the persona will revert to what it was in the wallet if it is not explicitly saved.

6.5 OCISecurityOpenPersona

Purpose

OCISecurityOpenPersona opens a persona in a wallet.

Parameter Descriptions

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

Table 6-5 OCISecurityOpenPersona parameters

Parameter Name	Description	Mode	Type
OCISecurity	osshandle
OCIError	error_handle
persona	Persona	{IN/OUT}	nzttPersona

Comments

A persona must be selected and opened before a cryptographic engine function can be used. The opened persona then initializes the protection set to either the system defaults or persona specific preferences. The opened persona also contains and maintains any state information necessary for the cryptographic engine functions.

Returns

Following is a list of possible error codes returned by this function.

Table 6-6 OCISecurityOpenPersona errors

Error	Explanation
NZERROR_TK_PASSWORD	Password failed to decrypt persona
NZERROR_TK_BADPRL	Persona resource locator did not work
NZERROR_RIO_OPEN	Could not open persona (see network trace file)

6.6 OCISecurityClosePersona

Purpose

OCISecurityClosePersona closes a persona in a wallet.

Parameter Descriptions

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

Table 6-7 OCISecurityClosePersona parameters

Parameter Name	Description	Mode	Type
OCISecurity	osshandle
OCIError	error_handle
persona	Persona	{IN/OUT}	nzttPersona

Comments

A persona is not stored when it is closed; it only releases the memory associated with the crypto engine.

Returns

Following is a list of possible error codes returned by this function.

Table 6-8 OCISecurityClosePersona errors

Error	Explanation
NZERROR_OK	Success
NZERROR_TK_PASSWORD	Password failed to decrypt persona
NZERROR_TK_BADPRL	Persona resource locator did not work
NZERROR_RIO_OPEN	Could not open persona (see network trace file)

6.7 OCISecuritySign

Purpose

OCISecuritySign creates an attached signature.

Parameter Descriptions

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

Table 6-9 OCISecuritySign parameters

Parameter Name	Description	Mode	Type
OCISecurity	osshandle
OCIError	error_handle
persona	Open persona acting as signer	{IN}	nzttPersona
signature_state	State of the signature	{IN}	nzttces
input_length	Length of this input part	{IN}	sizt_t
input	This input part	{OUT}	ub1
buffer_block	TDU buffer	{IN/OUT}	nzttBufferBlock

Comments

This function generates a signature that consists of a cryptographic checksum of the data to be signed: encrypted with the private key of the signing persona. The original data is then attached to the signature.

6.8 OCISecurityVerify

Purpose

OCISecurityVerify verifies an attached signature.

Parameter Descriptions

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

Table 6-10 OCISecurityVerify parameters

Parameter Name	Description	Mode	Type
OCISecurity	osshandle
OCIError	error_handle
persona	Persona	{IN}	nzttPersona
signature_state	State of verification	{IN}	nzttces
siglen	TDU length	{IN}	size_t
signature	Token Data Unit	{IN}	ub1
extracted_message	Extracted message	{IN/OUT}	nzttBufferBlock
verified	TRUE if signature is verified	{OUT}	boolean
validated	TRUE if signing identity validated	{OUT}	boolean
signing_party_identity	Identity of signing party	{OUT}	nzttIdentity

Comments

The data from the attached signature is used to generate a cryptographic checksum.
Then the signature part of the attached signature is decrypted using the signing identity's public key. The two checksums are then compared to verify they are identical. The signing identity is also validated to verify that it can be trusted and that it has not expired.

Returns

Following is a list of possible error codes returned by this function.

Table 6-11 OCISecurityVerify errors

Error	Explanation
NZERROR_TK_CANTGROW	Needed to grow output buffer but could not
NZERROR_TK_NOTOPEN	Persona is not open
NZERROR_TK_NOTSUPP	Function not supported with persona

6.9 OCISecurityValidate

Purpose

OCISecurityValidate validates an identity.

Parameter Descriptions

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

Table 6-12 OCISecurityValidate parameters

Parameter Name	Description	Mode	Type
OCISecurity	osshandle
OCIError	error_handle
persona	Persona	{IN}	nzttPersona
identity	Identity	{IN}	nzttIdentity
validated	TRUE if identity was validated	{OUT}	boolean

Comments

An identity is validated for trust and to verify that it has not expired.

Returns

Following is a list of possible error codes returned by this function.

Table 6-13 OCISecurityValidate errors

Error	Explanation
NZERROR_TK_NOTOPEN	Persona is not open
NZERROR_TK_NOTSUPP	Function not supported with persona

6.10 OCISecuritySignDetached

Purpose

OCISecuritySignDetached generates a detached signature.

Parameter Descriptions

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

Table 6-14 OCISecuritySignDetached parameters

Parameter Name	Description	Mode	Type
OCISecurity	osshandle
OCIError	error_handle
persona	Persona	{IN}	nzttPersona
signature_state	State of signature	{IN}	nzttces
input_length	Length of this input part	{IN}	size_t
input	This input part	{IN}	ub1
signature	TDU buffer	{IN/OUT}	nzttBufferBlock

Comments

The function is identical to OCISecuritySign, but the data to be signed is not attached to the signature. It generates a signature that consists of a cryptographic checksum of the data to be signed, encrypted with the private key of the signing persona.

Returns

Following is a list of possible error codes returned by this function.

Table 6-15 OCISecuritySignDetached errors

Error	Explanation
NZERROR_TK_NOTSUPP	Function not supported with persona

6.11 OCISecurityVerifyDetached

Purpose

OCISecurityVerifyDetached verifies a detached signature.

Parameter Descriptions

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

Table 6-16 OCISecurityVerifyDetached parameters

Parameter Name	Description	Mode	Type
OCISecurity	osshandle
OCIError	error_handle
persona	Persona	{IN}	nzttPersona
signature_state	State of signature	{IN}	nzttces
data_length	Length of data	{IN}	size_t
data	Data	{IN}	ub1
siglen	Input TDU length	{IN}	size_t
signature	Input TDU	{IN}	ub1
verified	TRUE if signature is verified	{OUT}	boolean
validated	TRUE if signing identity validated	{OUT}	boolean
signing_party_identity	Identity of signing party	{OUT}	nzttIdentity

Comments

This function is identical to OCISecurityVerify, except the signature does not contain the data that will allow it to be verified. The data is provided by the application calling the function.

Returns

Following is a list of possible error codes returned by this function.

Table 6-17 OCISecurityVerifyDetached errors

Error	Explanation
NZERROR_TK_NOTOPEN	Persona is not open
NZERROR_TK_NOTSUPP	Function not supported with persona

6.12 OCISecurityHash

Purpose

OCISecurityHash generates a hash.

Parameter Descriptions

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

Table 6-18 OCISecurityHash parameters

Parameter Name	Description	Mode	Type
OCISecurity	osshandle
OCIError	error_handle
persona	Persona	{IN}	nzttPersona
hash_state	State of hash	{IN}	nzttces
input	Length of this input	{IN}	size_t
input_length	This input	{IN}	ub1
hash	Output TDU	{IN/OUT}	nzttBufferBlock

Comments

This hash is a cryptographic hash, or checksum, of the input.

Returns

Following is a list of some of the possible error codes returned by this function.

Table 6-19 OCISecurityHash errors

Error	Explanation
NZERROR_TK_NOTSUPP	Function not supported with persona

6.13 OCISecuritySeedRandom

Purpose

OCISecuritySeedRandom supplies a seed to the Oracle Cryptographic Toolkit.

Parameter Descriptions

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

Table 6-20 OCISecuritySeedRandom parameters

Parameter Name	Description	Mode	Type
OCISecurity	osshandle
OCIError	error_handle
persona			nzttPersona
seed_length			size_t
seed			ub1

6.14 OCISecurityRandomBytes

Purpose

OCISecurityRandomBytes generates a buffer block for random bytes.

Parameter Descriptions

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

Table 6-21 OCISecurityRandomBytes parameters

Parameter Name	Description	Mode	Type
OCISecurity	osshandle
OCIError	error_handle
persona	Persona	{IN}	nzttPersona
number_of_bytes_desired	Number of bytes desired	{IN}	size_t
random_bytes	Buffer block for bytes	{IN/OUT}	nzttBufferBlock

6.15 OCISecurityRandomNumber

Purpose

OCISecurityRandomNumber generates a random number.

Parameter Descriptions

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

Table 6-22 OCISecurityRandomNumber parameters

Parameter Name	Description	Mode	Type
OCISecurity	osshandle
OCIError	error_handle
persona	Persona	{IN}	nzttPersona
random_number_ptr	Number	{OUT}	uword

6.16 OCISecurityInitBlock

Purpose

OCISecurityInitBlock initializes a buffer block.

Parameter Descriptions

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

Table 6-23 OCISecurityInitBlock parameters

Parameter Name	Description	Mode	Type
OCISecurity	osshandle
OCIError	error_handle
buffer_block	Buffer block	{IN/OUT}	nzttBufferBlock

Comments

The buffer block is initialized to be empty (all members are set to zero/NULL). This block is allocated to memory as needed.

6.17 OCISecurityReuseBlock

Purpose

OCISecurityReuseBlock reuses a previously initialized, and possibly used, block.

Parameter Descriptions

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

Table 6-24 OCISecurityReuseBlock parameters

Parameter Name	Description	Mode	Type
OCISecurity	osshandle
OCIError	error_handle
buffer_block	Buffer block	{IN/OUT}	nzttBufferBlock

Comments

This function sets the used length member of the buffer block to zero (0). It will cause a block to be reused if it already has memory allocated to it.

6.18 OCISecurityPurgeBlock

Purpose

OCISecurityPurgeBlock purges a buffer block of its memory.

Parameter Descriptions

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

Table 6-25 OCISecurityPurgeBlock parameters

Parameter Name	Description	Mode	Type
OCISecurity	osshandle
OCIError	error_handle
buffer_block	Buffer block	{IN/OUT}	nzttBufferBlock

Comments

This command affects only the memory used by the buffer. It does not affect the block itself.

6.19 OCISecuritySetBlock

Purpose

OCISecuritySetBlock sets a buffer block to a known state.

Parameter Descriptions

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

Table 6-26 OCISecuritySetBlock parameters

Parameter Name	Description	Mode	Type
OCISecurity	osshandle
OCIError	error_handle
flags_to_set	Flags to set	{IN}	uword
buffer_length	Length of buffer	{IN}	size_t
used_buffer_length	Used length of buffer	{IN}	size_t
buffer_block	Buffer	{IN}	ub1

Comments

This function allocates memory and stores a pointer in the buffer block.

---