HP UX Security Products and Features Software 40

Common Data Security Architecture (CDSA) White Paper

Certiﬁcate Library Services (CL) API

Revokes the input certiﬁcate by adding a record of the certiﬁcate to the CRL. The CRL entry consists of OID/values provided by the application. The new record is signed using the revoker’s certiﬁcate and the updated CRL is returned to the calling application. The CL deﬁnes which ﬁelds must or cannot be set using this function. This operation is valid only if the CRL has not been signed. Once the CRL has been signed, entries can not be added or removed.

CL_CrlRemoveCert ( )

Reinstates the input certiﬁcate by removing the record representing the certiﬁcate from the CRL, then returning updated CRL to the calling application. This operation is valid only if the CRL has not been signed. Once the CRL has been signed, entries can not be added or removed.

CL_CrlSign ( )

Creates a digital signature for the entire CRL using the signer’s certiﬁcate. The cryptographic context handle indicates the algorithm and parameters to be used for signing.

CL_CrlVerify ( )

Veriﬁes the signer certiﬁcate’s signature on the subject CRL. The cryptographic context handle indicates the algorithm and parameters to be used for veriﬁcation.

CL_IsCertInCrl ( )

Searches the CRL for a record corresponding to the input certiﬁcate.

CL_CrlGetFirstFieldValue ( )

Returns the ﬁrst ﬁeld in the CRL that matches the input OID. If an application requests a multiply-occurring OID, a results handle and a count of the number of matching instances are returned with the ﬁrst instance of the OID. The application uses the results handle to obtain the additional matching instances by repeated calls to CL_CrlGetNextFieldValue. CRL queries can be performed on both signed and unsigned CRLs.

CL_CrlGetNextFieldValue ( )

Returns the next ﬁeld associated with the input results handle, which had been obtained by calling CSSM_CL_CrlGetFirstFieldValue.

CL_CrlAbortQuery ( )

Releases a handle assigned by the CL_CrlGetFirstFieldValue function to identify the results of a CRL query, thus allowing the CL to release all intermediate state information associated with the query operation.

CL_CrlDescribeFormat ( )

Returns a list of the types of ﬁelds in the CRL format supported by the CL module.

40

Chapter 1

Contents

Contents 1. Common Data Security Architecture (CDSA) White Paper A.Sample Install Program B.Generating the Credential File C.Sample Add-inModule Code D.Functions Needed for Add-inModule Integrity E.Trouble Shooting HP CDSA Common Data Security Architecture (CDSA) White Paper Glossary of CDSA Terms and Acronyms Glossary of CDSA Terms and Acronyms Page Page Page Page Page Page HP’s Implementation of CDSA Page CDSA Components in HP-UX Page Use CSSM_CL* APIs for developing applications using the CL shared library Use CL_* APIs for developing CL add-inmodules CDSA in the Context of Other Security Applications CDSA, shown relative to higher-levelprotocols and user applications End User Applications Higher-LevelSecurity Protocols (PKCS, SSL, S/MIME, IPSEC, SET, et al.) Common Security Services Manager (CSSM) APIs Crypotgraphy Certificate HP’s Paradigm Shift Common Security Services Manager (CSSM) API Common Security Services Manager (CSSM) API CSSM Module Information Files Page Public/Private Key Algorithms Symmetric Key Algorithm Figure 1-6Symmetric Key Algorithm [1] RC2 or RC4 [2] [3] Page Cryptography Service Provider (CSP) API [1] hash [2] [3] Interaction between CSP and Applications CSP Operations Page Page Extensibility Functions Supported Functions and Algorithms Algorithm IDs, shown with keysize speciﬁcation in bits: —CSSM_ALGID_CDMF; The effective key size of a 64-bitCDMF key is 40 bits —CSSM_ALGID_RC2; <=40, in any multiple of 8, between 8 and —CSSM_ALGID_RC4; <=40, in any multiple of 8, between 8 and •Digital Signature and Validation Algorithm ID: —CSSM_ALGID_MD5WithRSA —CSSM_ALGID_SHA1WithRSA —CSSM_ALGID_SHA1WithDSA •Parameter Generation Algorithm ID: Page What is a Certiﬁcate Certiﬁcate Revocation List (CRL) and Operations Interaction between Certiﬁcate Library and Application Operations on Certiﬁcates Certiﬁcate Operations Certiﬁcate Revocation List Operations Page output = CSSM_CL_PassThrough(CLHandle, PassThroughID, Input); INTEL_X509V3_PASSTHROUGH_ENCODE_CERTIFICATE INTEL_X509V3_PASSTHROUGH_DECODE_CERTIFICATE INTEL_X509V3_PASSTHROUGH_FREE_CERTIFICATE INTEL_X509V3_PASSTHROUGH_CREATE_ENCODED_NAME INTEL_X509V3_PASSTHROUGH_ENCODE_NAME INTEL_X509V3_PASSTHROUGH_DECODE_NAME INTEL_X509V3_PASSTHROUGH_FREE_NAME INTEL_X509V3_PASSTHROUGH_TRANSLATE_DERNAME_TO_STRING INTEL_X509V3_PASSTHROUGH_ENCODE_EXTENSION INTEL_X509V3_PASSTHROUGH_ENCODE_EXTENSIONS INTEL_X509V3_PASSTHROUGH_DECODE_EXTENSIONS INTEL_X509V3_PASSTHROUGH_FREE_EXTENSIONS INTEL_X509V3_PASSTHROUGH_ALGID_TO_ALGOID INTEL_X509V3_PASSTHROUGH_ALGOID_TO_ALGID INTEL_X509V3_PASSTHROUGH_DECODE_ALGID INTEL_X509V3_PASSTHROUGH_FREE_ALGID INTEL_X509V3_PASSTHROUGH_OPEN_FILE INTEL_X509V3_PASSTHROUGH_CLOSE_FILE INTEL_X509V3_PASSTHROUGH_WRITE_CERT_TO_FILE INTEL_X509V3_PASSTHROUGH_ENCODE_SIGNED_CRL INTEL_X509V3_PASSTHROUGH_DECODE_SIGNED_CRL INTEL_X509V3_PASSTHROUGH_FREE_SIGNED_CRL INTEL_X509V3_PASSTHROUGH_ENCODE_TBS_CERTLIST INTEL_X509V3_PASSTHROUGH_DECODE_TBS_CERTLIST INTEL_X509V3_PASSTHROUGH_DECODE_REVOKED_CERTLIST INTEL_X509V3_PASSTHROUGH_FREE_REVOKED_CERTLIST INTEL_X509V3_PASSTHROUGH_ENCODE_REVOKED_CERT_ENTRY INTEL_X509V3_PASSTHROUGH_DECODE_REVOKED_CERT_ENTRY INTEL_X509V3_PASSTHROUGH_FREE_REVOKED_CERT_ENTRY INTEL_X509V3_PASSTHROUGH_CSSMKEY_TO_SPKI INTEL_X509V3_PASSTHROUGH_SPKI_TO_CSSMKEY The Role of Add-InModules in the CDSA Framework Design Criteria for Add-InModules Global Unique Identiﬁer (GUID) Initializer Code to Register Services with CSSM Add-InModule Install Program To Install an Add-InLibrary How to Create a CDSA Add-InModule for HP-UX How to Create a CDSA Add-InModule for HP-UX Example: Page Implementing Integrity Checking in Add-InModules Programming Self-CheckFunctions into the Initializer ISL_SelfCheck ISL_SelfCheck does the following: ISL_SelfCheck •Retrieves self-checkcredentials from /usr/lib/cdsa/meta-inf •Veriﬁes the add-inmodule ISL_RetrieveSelfCheckCredentials GetModulePath The credential name has the form /usr/lib/cdsa/meta-inf/some-add-in.dsa ISL_RetrieveSelfCheckKey To make this function, the add-inprovider needs to ask HP to: •create a DSA public/private key pair for the add-inprovider •embed the public key in the function whose prototype is shown below The private key will be used in the signing process to create a credential ﬁle Programming AddInAuthenticate() to Perform Bilateral Authentication Please contact HP when you have need for these functions Sample Code Showing Bilateral Authentication in AddInAuthenticate() Page Completing the Development of a CSP that Performs Integrity Checking Page The Credential File X.509 Certiﬁcate Chain The Validation Sequence Integrity Check prior to Loading .DSA file, containing signer's DSA signature DSA Did the Signer's .SF file, containing hash of data in .MF file Are .MF or .SF file SHA-1 has been The Self Check Bilateral Authentication In-Memoryvs. Static Checking Further References Page Sample Install Program Appendix A Page Page Page Page Page Page Page Page Generating the Credential File HP Signing Policy for CSP Add-InVendors for CDSA Version HP Signing Policy for CSP Add-InVendors for CDSA Version C Sample Add-inModule Code Appendix C Page Page Page Page Page Page Page Page Page Page Page Page Page Page Page Page Page Page D Functions Needed for Add-inModule Integrity IMPORTANT E Trouble Shooting HP CDSA CDSA API Errors CDSA API Errors Appendix E Page Page Page Page Page Page Page Page Page CDSA Start Up Errors when calling CSSM_ModuleAttach CDSA Start Up Errors when calling CSSM_ModuleAttach Page Debugging Core Dumps Using DDE to Debug CDSA Applications Migrating to CDSA Appendix F The following CDSA 1.2 data structures may be changed or obsoleted in CDSA 2.0: CSSM core data structures: CL data structures: DL data structures: CSP data structures: TP data structures: G ZIP format Appendix G Page Page H The Private Key File