Table of Contents

Preface

Intended Audience

ÆDocument Structure

Related Documents

Reader's Comments

How to Order Additional Documentation

Conventions

1 Introduction to CDSA

What Is CDSA?

CDSA Overview

Common Security Services Manager (CSSM)

Service Provider Modules

Elective Module Managers (EMMs)

Module Directory Services (MDS)

Maintaining CDSA Integrity

Self-Check

Bilateral Authentication

Secure Linkage Check

2 Installation and Initialization

Installation of CDSA on OpenVMS Alpha and I64 Version 8.3 and higher

Installation of CDSA on OpenVMS Alpha and I64 Version 8.2

Installation of CDSA on OpenVMS Alpha Version 7.3-2

Installation of CDSA Version 2.2 on OpenVMS Versions Earlier than Version 8.3

CDSA Version 2.2 Setup and Initialization

Warning Against Uninstalling CDSA from OpenVMS Alpha Version 7.3-1 or Higher

Post-Installation Tasks

Defining CDSA Symbols

Backing up the CDSA Database

3 Secure Delivery

Introduction

PCSI and Secure Delivery

PCSI History File (Product Database)

Fundamentals of Secure Delivery

CDSA Architectureb

The Certificate

The Manifest

CDSA Secure Delivery Programs

Creating Manifests

The Signing Process

The CDSA$SD_SIGN.COM Procedure

The CDSA$REVOKE.EXE File

Validating Files and Authenticating Signers

Validation Examples

The CDSA$VALIDATE_LIBSHR.EXE File

4 CDSA Utility Programs

CDSA$CERTGEN.EXE

SYNOPSIS

OPTIONS

EXAMPLE

CDSA$ISSUER.EXE

SYNOPSIS

OPTIONS

EXAMPLE

CDSA$MDS_INSTALL.EXE

SYNOPSIS

OPTIONS

EXAMPLE

ê

CDSA$MOD_INSTALL.EXE

SYNOPSIS

OPTIONS

EXAMPLE

CDSA$OUTPUT_ERROR.EXE

SYNOPSIS

OPTIONS

EXAMPLES

CDSA$REVOKE.EXE

SYNOPSIS

OPTIONS

RETURN VALUES

CDSA$SIGN.EXE

Integrity Signing

Export Signing

CDSA$VALIDATE.EXE

SYNOPSIS

OPTIONS

DESCRIPTION

EXAMPLE

RETURN VALUES

CDSA$X5092XML.EXE

SYNOPSIS

OPTIONS

EXAMPLE

5 CDSA Programming Concepts

Overview of CDSA Programming on OpenVMS

Compiling a CDSA Program

Linking a CDSA Program

CDSA Integrity Checking

Writing Signed Applications

The Signing Environment

The Signing Tools

The Signing Process

Deploying Signed Applications and Service Provider Modules

CDSA Example Programs

AES Encryption/Decryption Example Program

DES Encryption/Decryption Example Program

MDS Example Program

DES2 Encryption/Decryption Example Program

DES3 Example Program

ADDIN Example Program

DUMMY Example Programs

CDSA API Functions

AC_AuthCompute() - Compute authorization (CDSA)

AC_PassThrough() - Call exported module-specific operations (CDSA)

CDSA_FileValidate() - Validate a manifest file against its target file

CL_CertAbortCache() - Terminate a certificate cache handle (CDSA)

CL_CertAbortQuery() - Terminate a results handle (CDSA)

CL_CertCache() - Cache a copy of a certificate (CDSA)

CL_CertCreateTemplate() - Allocate and initialize memory for a certificate template (CDSA)

CL_CertDescribeFormat() - Return a list of the CSSM_OID values (CDSA)

CL_CertGetAllFields() - Return a list of input certificate values (CDSA)

CL_CertGetAllTemplateFields() - Extract and return values stored in CertTemplate (CDSA)

CL_CertGetFirstCachedFieldValue() - Return values from the cached certificate (CDSA)

CL_CertGetFirstFieldValue() - Return the value of the certificate field (CDSA)

CL_CertGetKeyInfo() - Return the public key and integral information (CDSA)

CL_CertGetNextCachedFieldValue() - Return the value of a certificate field (CDSA)

CL_CertGetNextFieldValue() - Return the value of a certificate field (CDSA)

CL_CertGroupFromVerifiedBundle() - Verify the signature of a bundle (CDSA)

CL_CertGroupToSignedBundle() - Convert a certificate group to a certificate bundle (CDSA)

CL_CertSign() - Sign a certificate (CDSA)

CL_CertVerify() - Verify a signed certificate (CDSA)

CL_CertVerifyWithKey() - Verify with a key (CDSA)

CL_CrlAbortCache() - Terminate a CRL cache handle (CDSA)

CL_CrlAbortQuery() - Terminate a query (CDSA)

CL_CrlAddCert() - Revoke an input certificate (CDSA)

CL_CrlCache() - Cache a copy of a certificate revocation list (CDSA)

CL_CrlCreateTemplate() - Create an unsigned, memory-resident CRL (CDSA)

CL_CrlDescribeFormat() - Return a list of the CSSM_OID values (CDSA)

CL_CrlGetAllCachedRecordFields() - +Return field values from a CRL record (CDSA)

CL_CrlGetAllFields() - Get the field values from the CRL (CDSA)

CL_CrlGetFirstCachedFieldValue() - Get field values from the cached CRL (CDSA)

CL_CrlGetFirstFieldValue() - Get the value of the first CRL field (CDSA)

CL_CrlGetNextCachedFieldValue() - Get the value of the next cached CRL field (CDSA)

CL_CrlGetNextFieldValue() - Get the value of the next CRL field (CDSA)

CL_CrlRemoveCert() - Reinstate a certificate (CDSA)

CL_CrlSetFields() - Set new field values (CDSA)

CL_CrlSign() - Sign a CRL (CDSA)

CL_CrlVerify() - Verify a signed CRL has not been altered (CDSA)

CL_CrlVerifyWithKey() - Verify a CRL with a specific key (CDSA)

CL_FreeFields() - Free fields (CDSA)

CL_FreeFieldValue() - Free field data (CDSA)

CL_IsCertInCachedCrl() - Search cached CRL for a record (CDSA)

CL_IsCertInCrl() - Search CRL for a certificate record (CDSA)

CL_PassThrough() - Extend certificate library functionality (CDSA)

CSP_EventNotify() - Notify service module of a context event

cssm_CcToHandle() - Get the module attach handle (CDSA)

CSSM_ChangeKeyAcl() - Edit a stored ACL associated with the target key (CDSA)

CSSM_ChangeKeyOwner() - Change the owner of a key (CDSA)

CSSM_CSP_ChangeLoginAcl() - Edit a stored CSP ACL login session (CDSA)

CSSM_CSP_ChangeLoginOwner() - Define a new login owner (CDSA)

CSSM_CSP_CreateAsymmetricContext() - Create an asymmetric encryption cryptographic context (CDSA)

CSSM_CSP_CreateDeriveKeyContext() - Create a cryptographic context to derive a symmetric key (CDSA)

CSSM_CSP_CreateDigestContext() - Create a digest cryptographic context (CDSA)

CSSM_CSP_CreateKeyGenContext() - Create a key generation cryptographic context (CDSA)

CSSM_CSP_CreateMacContext() - Create a message authentication code cryptographic context (CDSA)

CSSM_CSP_CreatePassThroughContext() - Create a custom cryptographic context (CDSA)

—CSSM_CSP_CreateDeriveKeyContext() - Create a cryptographic context to derive a symmetric key (CDSA)

CSSM_CSP_CreateDigestContext() - Create a digest cryptographic context (CDSA)

CSSM_CSP_CreateKeyGenContext() - Create a key generation cryptographic context (CDSA)

CSSM_CSP_CreateMacContext() - Create a message authentication code cryptographic context (CDSA)

CSSM_CSP_CreatePassThroughContext() - Create a custom cryptographic context (CDSA)

CSSM_CSP_CreateRandomGenContext() - Create a random number generation cryptographic context (CDSA)

CSSM_CSP_CreateSignatureContext() - Create a signature cryptographic context (CDSA)

CSSM_CSP_CreateSymmetricContext() - Create a symmetric encryption cryptographic context (CDSA)

CSSM_CSP_GetLoginAcl() - Get description of CSP ACL entries (CDSA)

CSSM_CSP_GetLoginOwner() - Get login owner data (CDSA)

CSSM_CSP_Login() - Log user in to the CSP (CDSA)

CSSM_CSP_Logout() - Terminate the login session (CDSA)

CSSM_DeleteContext() - Free the context structure (CDSA)

CSSM_DeleteContextAttributes() - Delete internal data (CDSA)

cssm_DeregisterManagerServices() - Deregister manager services

CSSM_FreeContext() - Free memory associated with the context structure (CDSA)

CSSM_GetAPIMemoryFunctions() - Retrieve the memory function table associated with the security service module

cssm_GetAppMemoryFunctions() - Get service functions (CDSA)

cssm_GetAttachFunctions() - Get SPI function table (CDSA)

CSSM_GetContext() - Get context information (CDSA)

CSSM_GetContextAttribute() - Get context attribute (CDSA)

CSSM_GetKeyAcl() - Get ACL entries by key (CDSA)

CSSM_GetKeyOwner() - Get data describing key owner (CDSA)

CSSM_GetModuleGUIDFromHandle() - Get GUID of the attached module (CDSA)

cssm_GetModuleInfo() - Get the module handle state information

CSSM_GetPrivilege() - Get CSSM privilege value (CDSA)

CSSM_GetSubserviceUIDFromHandle() - Complete a subservice unique identifier structure (CDSA)

CSSM_Init() - Initialize CSSM (CDSA)

CSSM_Introduce() - Identify an executable module (CDSA)

cssm_IsFuncCallValid() - Check secure linkage (CDSA)

CSSM_ListAttachedModuleManagers() - tGet a list of GUIDs for the attached module manager(CDSA)

CSSM_ModuleAttach() - Attach and verify a service provider module (CDSA)

CSSM_ModuleDetach() - Detach application from service provider module (CDSA)

CSSM_ModuleLoad() - Initialize the security service module (CDSA)

CSSM_ModuleUnload() - Deregister event notification callbacks (CDSA)

cssm_ReleaseAttachFunctions() - Release lock on the SP function table (CDSA)

CSSM_SetContext() - Replace all context information (CDSA)

CSSM_SetPrivilege() - Store privilege value in CSSM framework (CDSA)

CSSM_SPI_ModuleAttach() - Attach a service provider module(CDSA)

CSSM_SPI_ModuleDetach() - Notify service module of a context event (CDSA)

CSSM_SPI_ModuleLoad() - Initialize process between CSSM and the add-in service module (CDSA)

CSSM_SPI_ModuleUnload() - Disable events and deregister CSSM event notification (CDSA)

CSSM_Terminate() - Terminate the use of CSSM (CDSA)

CSSM_TP_RetrieveCredResult() - Return the results of the credentials request (CDSA)

CSSM_Unintroduce() - Remove module (CDSA)

CSSM_UpdateContextAttributes() - Update context attribute values (CDSA)

Decode_CDSA_Error() - Accepts a CDSA numeric error code and returns two strings: the ASCII name of the error and a description of the error

DecryptData() - Decrypt buffer data (CDSA)

DecryptDataFinal() - Finalize staged decryption process (CDSA)

DecryptDataInit() - Initialize the staged decrypt function(CDSA)

DecryptDataInitP() - Intialize the staged decrypt function with privilege (CDSA)

DecryptDataP() - Decrypt data with privilege (CDSA)

DecryptDataUpdate() - Continue the staged decryption process (CDSA)

DeriveKey() - Derive new symmetric key (CDSA)

DigestData() - Compute message digest (CDSA)

DigestDataClone() - Clone a staged message digest (CDSA)

DigestDataFinal() - Finalize the staged message digest (CDSA)

DigestDataInit() - Initialize the staged message digest (CDSA)

DigestDataUpdate() - Continue the staged process of digesting (CDSA)

DL_Authenticate() - Provide authentication credentials (CDSA)

DL_ChangeDbAcl() - Edit stored ACL (CDSA)

DL_ChangeDbOwner() - Define a new data base owner (CDSA)

DL_CreateRelation() - Create a new persistent relation (CDSA)

DL_DataAbortQuery() - Terminate DL_DataGetFirst query (CDSA)

DL_DataDelete() - Remove data record (CDSA)

DL_DataGetFirst() - Get first data record (CDSA)

DL_DataGetFromUniqueRecordId() - IGet data record (CDSA)

DL_DataGetNext() - Get next data record (CDSA)

DL_DataInsert() - Create new persistent data record (CDSA)

DL_DataModify() - Modify persistent data record (CDSA)

DL_DbClose() - Close open data store (CDSA)

DL_DbCreate() - Create and open new data store (CDSA)

DL_DbDelete() - Delete all records (CDSA)

DL_DbOpen() - Open a data store (CDSA)

DL_DestroyRelation() - Destroy an existing relation (CDSA)

DL_FreeNameList() - Free the list of the logical data store names (CDSA)

DL_FreeUniqueRecord() - Free data store memory (CDSA)

DL_GetDbAcl() - Get ACL description (CDSA)

DL_GetDbNameFromHandle() - Get data source name (CDSA)

DL_GetDbNames() - Get list of logical data store names (CDSA)

DL_GetDbOwner() - Get data base owner (CDSA)

DL_PassThrough() - Extend data storage module functionality (CDSA)

EncryptData() - Encrypts all buffer data (CDSA)

EncryptDataFinal() - Finalize staged encryption process (CDSA)

EncryptDataInit() - Initialize the staged encrypt funciton (CDSA)

EncryptDataInitP() - Initialize the staged encrypt function with privilege (CDSA)

EncryptDataP() - Encrypt data with privilege (CDSA)

EncryptDataUpdate() - Continue the staged encryption process (CDSA)

FreeKey() - Clean up keys (CDSA)

GenerateAlgorithmParams() - Generate algorithm parameters (CDSA)

GenerateKey() - Generate a symmetric key (CDSA)

GenerateKeyP() - Generate a key with privilege (CDSA)

GenerateKeyPair() - Generate an asymmetric key pair (CDSA)

GenerateKeyPairP() - Generate an asymmetric key pair with privilege (CDSA)

GenerateMac() - Compute a message authentication code (CDSA)

GenerateMacFinal() - Finalize the staged message authentication code (CDSA)

GenerateMacInit() - Initialize the staged message authentication code (CDSA)

GenerateMacUpdate() - Continue the staged process of computing a message authentication code (CDSA)

GenerateRandom() - Generate random data (CDSA)

GetOperationalStatistics() - ôGet operational values of a subservice (CDSA)

GetTimeValue() - Get a CSP time value (CDSA)

MDS_Initialize() - Initiate service context with MDS (CDSA)

MDS_Install() - Create the object directory database (CDSA)

MDS_Terminate() - Terminate the MDS service context (CDSA)

MDS_Uninstall() - Delete the object directory database (CDSA)

MDSUTIL_FreeModuleInfo() - Frees memory associated with the MDSUTIL_GetModuleInfo function.

MDSUTIL_FreeModuleList() - Frees the list of add-in modules that was returned by MDSUTIL_ListModules.

MDSUTIL_GetCredLocationFromGUID() - Returns the location of the add-in module, and the associated credentials file for the add-in module.

MDSUTIL_GetModuleInfo() - Gets information from the MDS registry for the add-in module.

MDSUTIL_GetModuleManagerInfo() - Returns descriptive information about the elective module manager identified by the GUID or the service mask.

MDSUTIL_Init() - Initializes the MDS registry in preparation for a series of MDSUTIL operations.

MDSUTIL_ListModuleManagers() - Returns the number of module managers and a list of GUIDs associated with those module managers.

MDSUTIL_ListModules() - Returns a list containing the GUID/version/name for each of the currently installed service provider modules that provide services in any of the CSSM functional categories selected in the usage mask. The MDSUTIL_FreeModuleList function must be called to deallocate memory containing the list.

MDSUTIL_ModuleInstall() - Updates the MDS registry with information on the add-in module

MDSUTIL_ModuleManagerInstall() - Updates the MDS registry with information about the Extensible Module Manager

MDSUTIL_ModuleManagerUninstall() - Removes from the MDS registry the information associated with the Globally Unique ID of the EMM

MDSUTIL_ModuleUninstall() - Removes from the MDS registry the information associated with GUID

MDSUTIL_Term() - Closes the MDS registry after a series of operations.

ObtainPrivateKeyFromPublicKey() - Convert public key to private key (CDSA)

PassThrough() - Extend crypto functionality (CDSA)

Print_CDSA_Error() - Output the CDSA error strings to SYS$OUTPUT

QueryKeySizeInBits() - Get CSP logical and effective sizes (CDSA)

QuerySize() - Get size of the output data (CDSA)

RetrieveCounter() - Get the value of a tamper resistant clock (CDSA)

RetrieveUniqueId() - Get identifier (CDSA)

SignData() - Sign all buffer data (CDSA)

SignDataFinal() - Complete the final stage of the sign data (CDSA)

SignDataInit() - Initialize the staged sign data (CDSA)

SignDataUpdate() - Continue the staged signing process input buffer data (CDSA)

TP_ApplyCrlToDb() - Update persistent storage (CDSA)

TP_CertCreateTemplate() - Allocate and initialize template memory (CDSA)

TP_CertGetAllTemplateFields() - Get CertTemplate field values (CDSA)

TP_CertGroupConstruct() - Construct credential (CDSA)

TP_CertGroupPrune() - Remove locally issued anchor certificates (CDSA)

TP_CertGroupToTupleGroup() - Create a set of authorization tuples (CDSA)

TP_CertGroupVerify() - Determine if a certificate is trusted (CDSA)

TP_CertReclaimAbort() - Terminate the process of reclaiming certificates (CDSA)

TP_CertReclaimKey() - Get private key associated with a certificate (CDSA)

TP_CertRemoveFromCrlTemplate() - Determine if the revoking certificate group can remove the subject certificate group from the CRL template (CDSA)

TP_CertRevoke() - Determine if the revoking certificate group can revoke the subject certificate group (CDSA)

TP_CertSign() - Determine if signer certificate is trusted (CDSA)

TP_ConfirmCredResult() - Confirm credentials (CDSA)

TP_CrlCreateTemplate() - Create an unsigned memory-resident CRL template (CDSA)

TP_CrlVerify() - Verify integrity of the certificate revocation list (CDSA)

TP_FormRequest() - Get form from authority (CDSA)

TP_FormSubmit() - Submit form to ClearanceAuthority (CDSA)

TP_PassThrough() - Extend trust policy functionality

TP_ReceiveConfirmation() - Poll for confirmation (CDSA)

TP_SubmitCredRequest() - Submit credential request (CDSA)

TP_TupleGroupToCertGroup() - ° Create a set of certificate templates (CDSA)

Terminate() - Clean up module-manager-specific activities (CDSA)

UnwrapKey() - Unwrap the wrapped key (CDSA)

UnwrapKeyP() - Unwrap the wrapped keys with privilege (CDSA)

VerifyData() - Verify input buffer data (CDSA)

VerifyDataFinal() - Finalize the staged verify data (CDSA)

VerifyDataInit() - Initialize the staged verify data (CDSA)

VerifyDataUpdate() - Continue the staged verification (CDSA)

VerifyDevice() - Cause the cryptographic module to perform a self verification and integrity check (CDSA)

VerifyMac() - Verify the message authentication code (CDSA)

VerifyMacFinal() - Finalize the staged message authentication code (CDSA)

VerifyMacInit() - Initialize the staged message authentication code (CDSA)

VerifyMacUpdate() - Continue the staged process of verifying the message authentication code (CDSA)

WrapKey() - Wrap a key using the context (CDSA)

WrapKeyP() - Wrap a key with privilege (CDSA)

Elective Module Manager (EMM) API Functions

DeregisterDispatchTable() - Invalidate CSSM pointers to EMM

EventNotifyManager() - Receive an event notification

Initialize() - Verify module version

ModuleManagerAuthenticate() - Module manager authentication

RefreshFunctionTable() - Gets EMM-defined API function

RegisterDispatchTable() - Provide the EMM with CSSM function pointers

Terminate() - Clean up module-manager-specific activities

Human Recognition Service (HRS) API Functions

HRS_CancelGUICallbacks() - Cancels GUICallbacks

HRS_CancelStreamCallbacks() - Cancels the StreamCallback

HRS_Capture() - Captures samples

HRS_CreateTemplate() - Creates a new enrollment template from a BIR containing raw biometric data

HRS_DbClose() - Closes an open database

HRS_DbCreate() - Creates and opens a new database

HRS_DbDelete() - Deletes all records from a database

HRS_DbDeleteBIR() - Deletes a BIR in an open database

HRS_DbFreeCursor() - Frees memory and resources associated with a cursor

HRS_DbGetBIR() - Retrieves a BIR from an open database

HRS_DbGetNextBIR() - Retrieves the BIR identified by the Cursor parameter

HRS_DbOpen() - Opens the data store

êHRS_DbQueryBIR() - Returns a pointer to the GUID of a BIR in an open database

HRS_DbSetCursor() - Sets the cursor to point to a specified record in a database

HRS_DbStoreBIR() - Stores a BIR in an open database

HRS_EnableEvents() - Enables the events from the attached HRS service provider in the current process

HRS_Enroll() - Captures biometric data for the purpose of enrollment

HRS_FreeBIRHandle() - Frees memory and resources associated with the BIR handle

HRS_GetBIRFromHandle() - Retrieves the BIR associated with a BIR handle

HRS_GetHeaderFromHandle() - Retrieves the BIR header identified by handle

HRS_Identify() - Captures biometric data from the attached device and compares it against the Population

HRS_IdentifyMatch() - Performs an identification (1-to-many) match between a ProcessedBIR and a set of stored BIRs

HRS_Import() - Imports non-realtime raw biometric data to construct a BIR

HRS_Process() - Processes the intermediate data captured via a call to HRS_Capture for the purpose of either verification or identification

HRS_SetGUICallbacks() - Allows the application to establish callbacks so that the application can control the ‘‘look-and-feel’’ of the biometric user interface

HRS_SetPowerMode() - Sets the device to the requested power mode

HRS_SetStreamCallback() - Allows the application to establish a callback for client/server communication

HRS_StreamInputOutput() - Passes a protocol &data unit into the HRS service provider and obtains a response

HRS_Verify() - Captures biometric data from the attached device and compares it against the StoredTemplate

HRS_VerifyMatch() - Performs a verification (1-to-1) match between two BIRs - the ProcessedBIR and the StoredTemplate

A Open Source Notice

Intel Open Source License for CDSA/CSSM Implementation (BSD License with Export Notice)

Glossary

Index