LINEBURG


<< . .

 5
( 9)



. . >>

if (OCI_SUCCESS != OCISecurityInitialize(security_handle, error_handle))
{
goto exit;
}




4-6 Oracle Cryptographic Toolkit Programmer™s Guide
A Programming Example




/*
* Open the wallet. Since NZT_DEFAULT_WRL is used as the wallet
* WRL, the platform specific default wallet will be used. Note,
* as well, that this wallet has no password (NZT_NO_PASSWORD).
*/
if (OCI_SUCCESS
!= OCISecurityOpenWallet(security_handle, error_handle,
strlen(NZT_DEFAULT_WRL), NZT_DEFAULT_WRL,
strlen(NZT_NO_PASSWORD), NZT_NO_PASSWORD,
&wallet))
{
goto exit;
}

/*
* Use the first persona in the wallet.
*/
persona = &wallet->list_nzttWallet[0];

/*
* Open the persona and prepare it for use.
*/
if (OCI_SUCCESS
!= OCISecurityOpenPersona(security_handle, error_handle, persona))
{
goto exit;
}

/*
* Create a detached signature for the phrase. This means that
* when the signature is verified, the original phrase will need to
* be provided since it is not attached to the signature. The
* variable signature contains the output.
*/
if (OCI_SUCCESS
!= OCISecuritySignDetached(security_handle, error_handle, persona,
NZTTCES_END, strlen((char *)phrase),
phrase, &signature))
{
goto exit;
}

exit:
DISCARD OCISecurityPurgeBlock(security_handle, error_handle, &signature);




Using the Oracle Cryptographic Toolkit 4-7
A Programming Example




DISCARD OCISecurityCloseWallet(security_handle, error_handle, &wallet);

/*
* Free the various handles (if allocated). Delay freeing the error
* handle so that errors can be generated until the last possible
* moment.
*/
if (security_handle)
{
DISCARD OCISecurityTerminate(security_handle, error_handle);
DISCARD OCIHandleFree((dvoid *)security_handle, OCI_HTYPE_SECURITY);
}

if (error_handle)
{
DISCARD OCIHandleFree((dvoid *)error_handle, OCI_HTYPE_ERROR);
}

if (env_handle)
{
DISCARD OCIHandleFree((dvoid *)env_handle, OCI_HTYPE_ENV);
}

return 0;
}




4-8 Oracle Cryptographic Toolkit Programmer™s Guide
5
Random Number Generator

This chapter discusses the Oracle Cryptographic Toolkit random number genera-
tor. The following topics are covered:
“Overview”
s


“Functions”
s


“Example”
s




Random Number Generator 5-1
Overview



5.1 Overview
The random number generator is built on top of the Oracle Cryptographic Toolkit.
This tool is intended for users who want to generate random data for their applica-
tions.


5.2 Functions
The random number generator is composed of the following:

PROCEDURE Initialize (seed IN BINARY_INTEGER)
This procedure is used before the random number generator package is called. The
procedure takes a seed which initializes the random number generator. The seed
can be any value between -9999999999 and 9999999999.

Note: You must call this procedure before using any of the other
procedures or functions. Otherwise, an exception will be raised.


PROCEDURE Seed (seed IN BINARY_INTEGER)
This procedure resets the seed used by the random number generator.

FUNCTION Random RETURN BINARY_INTEGER
The function returns a random number between -9999999999 and 9999999999.

PROCEDURE Terminate
This procedure must be called when the package is no longer needed.


5.3 Example
The following code fragment is an example of how to use the random number gen-
erator package.
DECLARE
i BINARY_INTEGER;
BEGIN
dbms_random.initialize(19254);
i := dbms_random.random;
INSERT INTO some_table VALUES(i);
dbms_random.terminate;
END;




5-2 Oracle Cryptographic Toolkit Programmer™s Guide
Example




Note: It is not currently possible to use the return value of RAN-
DOM directly in a SQL statement. The following is not allowed, for
example:
INSERT_INTO some_table VALUES(DBMS_RANDOM.RANDOM);




Random Number Generator 5-3
Example




5-4 Oracle Cryptographic Toolkit Programmer™s Guide
Part II
Reference

Part II, Reference, contains the following chapters:
“OCI Functions for C”
s


“PL/SQL Functions”
s
6
OCI Functions for C

This chapter describes each Oracle Call Interface (OCI) function in the Oracle Cryp-
tographic Toolkit. Each OCI function description contains the following informa-
tion:



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.




OCI Functions for C 6-1
OCISecurityInitialize



6.1 OCISecurityInitialize
1Purpose
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 Oracle Cryptographic Toolkit Programmer™s Guide
OCISecurityTerminate




6.2 OCISecurityTerminate
Purpose
OCISecurityTerminate must be called after the user has ¬nished 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




OCI Functions for C 6-3
OCISecurityOpenWallet



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 speci¬c WRL default is used when the WRL is
NZT_DEFAULT_WRL. Use the WRL type speci¬c default (e.g., “oracle:”) when
only the wallet type is speci¬ed.
A wallet is opened and its password is veri¬ed 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 Oracle Cryptographic Toolkit Programmer™s Guide
OCISecurityCloseWallet




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.




OCI Functions for C 6-5
OCISecurityOpenPersona



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 speci¬c 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 ¬le)




6-6 Oracle Cryptographic Toolkit Programmer™s Guide
OCISecurityClosePersona




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 ¬le)

<< . .

 5
( 9)



. . >>

Copyright Design by: Sunlight webdesign