Oracle Cryptographic Toolkit Programmer's Guide
Release 2.0.3

A54082-01

Library

Product

Contents

Index

Prev Next

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 some of the 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 some of the 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 some of the 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 some of the 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 some of the 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 some of the 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 is allocated and stores a pointer in the buffer block.




Prev

Next
Oracle
Copyright © 1997 Oracle Corporation.

All Rights Reserved.

Library

Product

Contents

Index