LINEBURG


 1
( 9)



. . >>

Oracle® Cryptographic Toolkit


Programmer™s Guide



Release 2.0.4


October 1997
Part No. A54082-02




.
Oracle® Cryptographic Toolkit Programmer™s Guide
Part No. A54082-02

Release 2.0.4
Copyright © 1996, 1997, Oracle Corporation. All rights reserved.

Printed in the U.S.A
Primary Author: Gilbert Gonzalez

Contributing Authors: Andre Srinivasan, Richard Wessman
Contributors: Paul Lambert, Patricia Markee, Kendall Scott, Sandy Venning

The programs are not intended for use in any nuclear, aviation, mass transit, medical, or other inher-
ently dangerous applications. It shall be licensee's responsibility to take all appropriate fail-safe, back
up, redundancy and other measures to ensure the safe use of such applications if the Programs are
used for such purposes, and Oracle disclaims liability for any damages caused by such use of the Pro-
grams.
This Program contains proprietary information of Oracle Corporation; it is provided under a license
agreement containing restrictions on use and disclosure and is also protected by copyright patent and
other intellectual property law. Reverse engineering of the software is prohibited.
The information contained in this document is subject to change without notice. If you ¬nd any problems
in the documentation, please report them to us in writing. Oracle Corporation does not warrant that this
document is error free.

If this Program is delivered to a U.S. Government Agency of the Department of Defense, then it is deliv-
ered with Restricted Rights and the following legend is applicable:

Restricted Rights Legend Programs delivered subject to the DOD FAR Supplement are 'commercial
computer software' and use, duplication and disclosure of the Programs shall be subject to the licensing
restrictions set forth in the applicable Oracle license agreement. Otherwise, Programs delivered subject to
the Federal Acquisition Regulations are 'restricted computer software' and use, duplication and disclo-
sure of the Programs shall be subject to the restrictions in FAR 52..227-14, Rights in Data -- General,
including Alternate III (June 1987). Oracle Corporation, 500 Oracle Parkway, Redwood City, CA 94065.




This product contains security software from RSA Data Security, Inc. Copyright 1994 RSA Data Security,
Inc. All rights reserved. This version supports International Security with RSA Public Key Cryptography,
MD2, MD5, and RC4.
This product contains encryption and/or authentication engines from RSA Data Security, Inc. Copyright
1996 RSA Data Security, Inc. All rights reserved.
Oracle and SQL*Plus are registered trademarks of Oracle Corporation, Redwood City, California. Oracle
Security Server, Oracle Enterprise Manager, Oracle Call Interface, Net8, PL/SQL, and Oracle8 are trade-
marks of Oracle Corporation, Redwood City, California.

All other product or company names are used for identi¬cation purposes only, and may be trademarks of
their respective owners.
Preface

Purpose
The Oracle Cryptographic Toolkit Programmer™s Guide provides independent applica-
tion programmers with programming interfaces to the services provided by the
Oracle Security Server.


Intended Audience
The Oracle Cryptographic Toolkit Programmer™s Guide is designed to be used by both
Oracle and non-Oracle application programmers who require an interface to the
services provided by the Oracle Security Server. This document assumes that the
reader is familiar with the functionality of the Oracle Security Server, as described
in the Oracle Security Server Guide.


Structure
This manual contains three parts, seven chapters, and two appendices.
Part I Concepts
The Concepts chapters contain the following information:
Chapter 1 Overview
Provides de¬nitions of the Oracle Security Server and the Oracle Cryptographic
Toolkit and states the purpose of this Programmer™s Guide
Chapter 2 Data Types
Discusses public functions, data types, and data structures
Chapter 3 Concepts
Discusses general security concepts and Oracle Cryptographic Toolkit concepts




iii
Chapter 4 Using the Oracle Cryptographic Toolkit
Shows you how to program using the Oracle Cryptographic Toolkit
Chapter 5 Random Number Generator
Shows users how to generate random data for their applications
Part II Reference
The Reference chapters contain the following information:
Chapter 6 OCI Functions for C
Describes each Oracle Call Interface (OCI) function in the Oracle Cryptographic
Toolkit
Chapter 7 PL/SQL Functions
Describes each PL/SQL function in the Oracle Cryptographic Toolkit
Part III Appendices
The Appendices contain reference information, including sample C programs,
sample PL/SQL programs, and OCI - API function mappings.
Appendix A Sample PL/SQL Code
Contains sample PL/SQL programs
Appendix B OCI - API Mappings
Lists each OCI function that is directly mapped to an API function
Glossary Lists terms, abbreviations, and de¬nitions used in this guide


Related Documents
For more information, see the following manuals:
Oracle8TM Server Application Developer™s Guide
s


Oracle Security ServerTM Guide
s


Programmer™s Guide to the Oracle Call InterfaceTM
s




iv
Conventions
The following conventions are used in this manual:

Convention Meaning
Code examples and data type names are displayed in monospace
monospace
font.
italic Names of related manuals are displayed in italic font.




v
vi
Send Us Your Comments
Oracle® Cryptographic Toolkit Programmer™s Guide
Part No. A54082-02
Oracle Corporation welcomes your comments and suggestions on the quality and usefulness of this
publication. Your input is an important part of the information used for revision.
Did you ¬nd any errors?
s

Is the information clearly presented?
s

Do you need more information? If so, where?
s

Are the examples correct? Do you need more examples?
s

What features did you like most about this manual?
s




If you ¬nd any errors or have any other suggestions for improvement, please indicate the chapter,
section, and page number (if available).
You can send comments to us in the following ways
electronic mail: ossdoc@us.oracle.com
s

postal service:
s

Oracle Corporation
Documentation Manager: Enterprise Application Services
500 Oracle Parkway
Redwood City CA 94065
USA
If you would like a reply, please give your name, address, and telephone number below.
Contents

Preface............................................................................................................................................................ iii

Send Us Your Comments .................................................................................................................. vii

Part I Concepts

1 Overview
What is the Oracle Security Server?........................................................................................ 2
1.1
Oracle Security Server Features ....................................................................................... 2
1.1.1
What is the Oracle Cryptographic Toolkit?........................................................................... 4
1.2
Oracle Cryptographic Toolkit Functional Layers................................................................. 5
1.3
API Layer............................................................................................................................. 5
1.3.1
Cryptographic Engine Functions..................................................................................... 5
1.3.2
Persona/Identity Functions.............................................................................................. 6
1.3.3
Wallet Functions................................................................................................................. 6
1.3.4
Oracle Cryptographic Toolkit Elements ................................................................................ 7
1.4
Identity................................................................................................................................. 7
1.4.1
Trusted Identity.................................................................................................................. 8
1.4.2
Persona................................................................................................................................. 8
1.4.3
Wallet ................................................................................................................................... 9
1.4.4
Types of Interfaces .................................................................................................................. 10
1.5
Oracle Call Interface ........................................................................................................ 10
1.5.1
PL/SQL Interface ............................................................................................................. 10
1.5.2




ix
2 Data Types
Data Types ..................................................................................................................................
2.1 2
Name Prefixes .....................................................................................................................
2.1.1 2
Crypto Engine State ...........................................................................................................
2.1.2 2
Crypto Engine Functions...................................................................................................
2.1.3 3
Identity Type.......................................................................................................................
2.1.4 3
Cipher Types .......................................................................................................................
2.1.5 3
TDU Formats.......................................................................................................................
2.1.6 4
Validate State ......................................................................................................................
2.1.7 4
Unique ID ............................................................................................................................
2.1.8 4
Timestamp...........................................................................................................................
2.1.9 4
Data Structures...........................................................................................................................
2.2 5
nzttBufferBlock ...................................................................................................................
2.2.1 5
nzttWallet ............................................................................................................................
2.2.2 6
nzttPersona..........................................................................................................................
2.2.3 6
nzttIdentity ..........................................................................................................................
2.2.4 6

3 Concepts
Security Concepts ...................................................................................................................... 2
3.1
Oracle Cryptographic Toolkit Concepts ................................................................................ 4
3.2

4 Using the Oracle Cryptographic Toolkit
Basic Oracle Cryptographic Toolkit Program Flow .............................................................
4.1 2
A Programming Example.........................................................................................................
4.2 2
Using the Oracle Cryptographic Toolkit.........................................................................
4.2.1 3
An Example: Generating a detached signature for an array of bytes.........................
4.2.2 5

5 Random Number Generator
Overview..................................................................................................................................... 2
5.1
Functions..................................................................................................................................... 2
5.2
Example....................................................................................................................................... 2
5.3

Part II Reference



x
6 OCI Functions for C
OCISecurityInitialize................................................................................................................. 2
6.1
OCISecurityTerminate .............................................................................................................. 3
6.2
OCISecurityOpenWallet........................................................................................................... 4
6.3
OCISecurityCloseWallet........................................................................................................... 5
6.4
OCISecurityOpenPersona ........................................................................................................ 6
6.5
OCISecurityClosePersona ........................................................................................................ 7
6.6
OCISecuritySign ........................................................................................................................ 8
6.7
OCISecurityVerify ..................................................................................................................... 9
6.8
OCISecurityValidate ............................................................................................................... 11
6.9
OCISecuritySignDetached...................................................................................................... 12
6.10
OCISecurityVerifyDetached .................................................................................................. 13
6.11
OCISecurityHash..................................................................................................................... 15
6.12
OCISecuritySeedRandom....................................................................................................... 16
6.13
OCISecurityRandomBytes ..................................................................................................... 17
6.14
OCISecurityRandomNumber ................................................................................................ 18
6.15
OCISecurityInitBlock .............................................................................................................. 19
6.16
OCISecurityReuseBlock.......................................................................................................... 20
6.17
OCISecurityPurgeBlock.......................................................................................................... 21
6.18
OCISecuritySetBlock ............................................................................................................... 22
6.19

7 PL/SQL Functions
General Purpose Procedures ................................................................................................... 2
7.1
Procedures Used by Applications That Use the Wallet................................................ 3
7.1.1
Digital Signature........................................................................................................................ 7
7.2
Sign....................................................................................................................................... 8
7.2.1
Verify.................................................................................................................................... 9
7.2.2
SignDetached .................................................................................................................... 10
7.2.3
VerifyDetached................................................................................................................. 11
7.2.4
Hash........................................................................................................................................... 12
7.3
KeyedHash ........................................................................................................................ 13
7.3.1
Hash ................................................................................................................................... 14
7.3.2
Random Number Generation ................................................................................................ 15
7.4




xi
Part III Appendices

A Sample PL/SQL Code
Sample PL/SQL Program ........................................................................................................ 2
A.1

B OCI - API Mappings
Mappings ....................................................................................................................................
B.1 2
Overview .............................................................................................................................
B.1.1 2
OCI - API Mappings ..........................................................................................................
B.1.2 2
OCI - API Mapping Exceptions ...............................................................................................
B.2 3

Glossary
Index




xii
Figures
Relationship between Toolkit and Services...........................................................................
1“1 4
Identity........................................................................................................................................
1“2 8
Persona........................................................................................................................................
1“3 9
Wallet ..........................................................................................................................................
1“4 9
Oracle Cryptographic Toolkit Program Flow .......................................................................
4“1 2


 1
( 9)



. . >>

Copyright Design by: Sunlight webdesign