Oracle Cryptographic Toolkit Programmer's Guide Release 2.0.4 A54082-02 |
Library | Product | Contents | Index

# 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 InterfaceTM 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.

Prev | Next
| Copyright © 1997 Oracle Corporation. All Rights Reserved. |
Library | Product | Contents | Index