HP Common Data Security Architecture White Paper

Contents

1. Common Data Security Architecture (CDSA) White Paper

Glossary of CDSA Terms and Acronyms . . . . . . . . . . . . . . . . . . . . . . . . . .4

What Is CDSA? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

HP’s Implementation of CDSA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

CDSA Components in HP-UX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

CDSA in the Context of Other Security Applications . . . . . . . . . . . . .15

HP’s Paradigm Shift. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .17

Common Security Services Manager (CSSM) API . . . . . . . . . . . . . . . . .18

CSSM Module Information Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19

Cryptography Service Provider (CSP) API. . . . . . . . . . . . . . . . . . . . . . . .21

Public/Private Key Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21

Interaction between CSP and Applications . . . . . . . . . . . . . . . . . . . . .26

CSP Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27

Certificate Library Services (CL) API . . . . . . . . . . . . . . . . . . . . . . . . . . .34

What is a Certificate?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34

Operations on Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .37

Introduction to Add-in Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48

The Role of Add-In Modules in the CDSA Framework . . . . . . . . . . . .48

Design Criteria for Add-In Modules . . . . . . . . . . . . . . . . . . . . . . . . . . .49

Global Unique Identifier (GUID). . . . . . . . . . . . . . . . . . . . . . . . . . . . . .49

Initializer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .50

Code to Register Services with CSSM . . . . . . . . . . . . . . . . . . . . . . . . .51

Add-In Module Install Program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .51

How to Create a CDSA Add-In Module for HP-UX . . . . . . . . . . . . . . . .53

Implementing Integrity Checking in Add-In Modules. . . . . . . . . . . . .55

ProgrammingAddInAuthenticate() to Perform Bilateral Authentication
60

CompletingtheDevelopment of a CSP that PerformsIntegrity Checking
63

1

Contents

Validating the CSP Credentials. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

The Credential File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

X.509 Certificate Chain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65

The Validation Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Integrity Check prior to Loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

The Self Check. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69

Bilateral Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

In-Memory vs. Static Checking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70

Concluding Remarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Further References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

A. Sample Install Program

B. Generating the Credential File

HP Signing Policy for CSP Add-In Vendors for CDSA Version 1.2 . . . . 84

C. Sample Add-in Module Code

D. Functions Needed for Add-in Module Integrity

E. Trouble Shooting HP CDSA

CDSA API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108

CDSA Start Up Errors when calling CSSM_ModuleAttach . . . . . . . . 118

Debugging Core Dumps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Using DDE to Debug CDSA Applications . . . . . . . . . . . . . . . . . . . . . 120

F. Migrating to CDSA 2.0

G. ZIP format

H. The Private Key File

2

Common Data Security Architecture (CDSA) White Paper

1 Common Data Security

Architecture (CDSA) White
Paper

This document describes the Common Data Security Architecture (CDSA), which, as of June
1999, is available on the HP-UX 11.0 Application CD. In the future, it will be available as part
of the HP-UX core. The intent of this white paper is to give Independent Software Vendors
(ISVs), system administrators, and users an overview of CDSA and to enable them to take
advantage of its libraries to develop security applications.

The information in this white paper is organized as follows:

• Glossary of CDSA terminology

• Depiction of CDSA, as currently implemented in HP-UX

• Description of the Common Security Services Manager (CSSM), which provides the core
services of CDSA

• Description of the Cryptography Service Provider (CSP) application program interface

• Description of the Certificate Library Services (CL) application program interface

• Explanation of add-in modules, their use, design criteria, and rules for manufacture,
signing, and installation

• Pointers to further resources, both bibliographic and online.

NOTE This white paper is not intended as a single source of information on

CDSA. Readers intending to make full use of the libraries are
encouraged to consult the resources and websites listed at the end of this
paper.

Chapter 1 3

Common Data Security Architecture (CDSA) White Paper

Glossary of CDSA Terms and Acronyms

Glossary of CDSA Terms and Acronyms

API

Application program interface.

Abstract Syntax Notation One (ASN.1)

A standard means of describing a message that can be sent over a network.
Two ISO standards define ASN.1syntax (ISO 8824/ITU X.208) and encoding
rules (ISO 8825/ITU X.209) for applications using the Open Systems
Interconnection (OSI) framework.

Add-in modules

Shared libraries that when attached to the Common Security Services
Manager provide cryptography services (these are called CSPs), certificate
library services (CLs), data storage libraries (DLs), and trust policy libraries
(TPs).

Certificate Authority (CA)

A trusted party that creates and issues certificates (electronic identities) to
users and “signs” certificates with their private key. A Certificate Authority
attests to the legitimacy of the user by the certificate signing action.
Typically, a CA will require additional proof of identity before signing a
user’s certificate, such as a birth certificate or driver’s license.

Certificate Library Services (CL)

A module that performs operations on digital certificates. Each certificate
library has knowledge of one or more specific certificate formats. Certificate
libraries perform the following operations: signing and signature
verification of certificates; management of certificate fields; export and
import of multiple certificate formats. The HP-UX implementation of CDSA
supports X.509v3 certificates and X.509v2 certificate revocation lists
(CRLs).

Common Data Security Architecture (CDSA)

An open cross-platform, interoperable and extensible software framework
consisting of APIs designed to make computers more secure for applications
such as electronic commerce, communications, and digital content. CDSA
provides an infrastructure for managing the various security-related
services embodied in existing security standards.

4 Chapter1

Common Data Security Architecture (CDSA) White Paper

Common Security Services Manager (CSSM)

A central, extensible infrastructure that defines APIs for access to
cryptography, certificate, trust, or storage services.

Cryptography Service Provider (CSP)

A CSP (whether software and/or hardware-based) provides data
encryption/decryption, digital signatures, cryptographic hashing, key
generation, random-number generation services.

Diffie-Hellman key exchange

A protocol developed by Whitfield Diffie and Martin Hellman in 1976 that
allows participants to agree on a symmetric-cipher key over an insecure
channel.

Data Encryption Standard (DES)

A widely used encryption algorithm that applies a 56-bit key to each 64-bit
block of data. DES is specified in ANSI X3.92 and X3.106 standards and in
the FIPS 46 and 81 standards.

Data Storage Library (DL)

Glossary of CDSA Terms and Acronyms

Provides persistent storage for security-related CDSA objects, such as
certificates, CRLs, public keys, or trust information. A DL can use a
commercial database package, custom hardware, or a file system as the
underlying storage repository. The DL provides the following services:
management of data stores, including creation, deletion, import, export of
data stores; storage and management of security objects; management of
attributes associated with stored security objects.

Globally Unique ID (GUID)

A set of descriptive attributes that provides the means to attach add-in
modules to the CSSM Applications.

International Organization for Standardization (ISO)

A non-governmental, worldwide federation of national standards bodies
representing 130 nations, based in Geneva, Switzerland. ISO’s mission is to
foster increased cooperation in the spheres of scientific, technological, and
economic activity through standardization of criteria and components..

Message Authentication Code (MAC)

A function that produces fixed length output from variable-length input and
a key. Might be hash-based, cipher-based, or stream-cipher based.

Chapter 1 5

Common Data Security Architecture (CDSA) White Paper

Glossary of CDSA Terms and Acronyms

OID/value pair

An abstract identifer representing a data type and the corresponding value
of that data type.

Optimal Asymmetric Encryption Padding (OAEP)

A method of encoding a message with a masked random number, then
encrypting it.

Open Group

A software standards organization sponsored by major software vendors to
develop and foster industry standards for software interfaces. Open Group
standards include UNIX program interfaces and SQL, a data base query
language.

Pretty Good Privacy (PGP)(TM)

A program used to encrypt and decrypt data using a public key system.

Public Key Cryptography Standards (PKCS)

A set of protocols enabling secure informaiton exchange on the Internet.
PKCS was developed by RSA Labs.

Public Key Infrastructure (PKI)

Protocols, services, and standards used for managing public keys, often
through use of a Certificate Authority.

RC2

A variable key-size block cipher, with a block size of 64 bits and said to be
2-3 times faster than DES. (Export use of RC2 limits the RC2 key size.) RC2
was developed by RSA Labs.

RC4

A variable key-size stream cipher with byte-oriented operations, whose
algorithm is based on use of a random permutation. RC4 was developed by
RSA Labs.

RSA Public Key Cryptosystem

A popular form of public key cryptography, whose inventors’ surnames
(Rivest, Shamir, and Adleman) form the acronym for a body of algorithms.

SHA-1

A hash function specified in FIPS 180-1 and typically used with the DSA
signature algorithm.

6 Chapter1

Common Data Security Architecture (CDSA) White Paper

Glossary of CDSA Terms and Acronyms

Secure Electronic Transactions (SET)

A standard to enable online credit card transactions, using public-key
encryption and digital signature validation.

Secure Multipurpose Internet Mail Extensions (S/MIME)

A secure protocol for sending e-mail using RSA encryption and following the
syntax provided in the PKCS format #7.

Secure Sockets Layer (SSL)

A protocol created by Netscape Communications, Inc. for managing the
security of message transmissions in a network, using RSA’s public and
private key encryption.

Transmission Control Protocol/Internet Protocol (TCP/IP)

The basic communications language (protocol) of the Internet, including
intranets and extranets. The TCP portion assembles a message or file into
smaller packets for transmission and reassembles at reception; the IP layer
handles the address portion of the packet to ensure that it reaches its
destination. TCP/IP is used by other Internet protocols, such as HTTP, FTP,
telnet, and SMTP.

Trust Policy Library (TP)

A set of rules used to determine if a requester is trusted or authorized to
perform an action on a data object. Typical actions requiring trust
verification include signing or verifying of certificates and CRLs, revoking
certificates, and other application-specific actions or operations.

X.509 certificate

A certificate is a digital document containing a public key and a name and
allowing authentication of the source of the data accompanying the
certificate. X.509 is the most accepted format for certificates and is defined
by the ITU-T X.509 international standard.

authentication

The assurance that persons “are who they say they are” in a communication
or transaction.

bilateral authentication

Checks performed between software modules to ensure that software
modules using services from each other are valid and uncompromised. The
CSSM checks the integrity of add-in modules to ensure that no malicious or
corrupted module is added to the system.

Chapter 1 7

Common Data Security Architecture (CDSA) White Paper

Glossary of CDSA Terms and Acronyms

bulk encryption

Technique used to disguise a large amount of data using symmetric key
algorithms that are relatively “inexpensive” computationally.

bundled modules

HP’s implementation of CDSA includes CSSM, CSP, and CL bundled
modules. No DL or TP module is included in the first release of CDSA.

certificate revocation list (CRL)

A list of certificates that have been revoked or suspended.

cipher block chaining

Cipher block chaining is a technique wherein the output of a previous
encrypted block is exclusive-ORed with an unencrypted block. The result is
then encrypted.

computer security

Computer security consists of four elements: privacy, integrity, authenticity,
and non-repudiation. Privacy is typically implemented by encrypting
information so that only the intended reader may understand it. Data
integrity requires that data is transmitted or stored in a tamperproof
manner and that if data is modified or forged, alterations are readily
detected. Authenticity means that the identity of the user responsible for
the data creation can be verified. Non-repudiation ensures that users who
created or sent data cannot falsely deny their responsibility for having done
so.

cryptographic hash

A hash is a transformation of arbitrary data input into a shorter, fixed-size
series of bits. Cryptographic hashing is in digital signatures. Among the
message-digest hash functions used in cryptography are MD2, MD4, MD5,
and the Secure Hash Algorithm (SHA-1).

cryptography

The science of mathematical algorithms that disguise data.

digital signature

A logical hash of information encoded using an asymmetric key unique to
the signer, used to help authenticate the identify of the sender of a message.

encryption/decryption

Encryption is the scrambling of data into an unrecognizable form.

8 Chapter1

Decryption is the conversion of encrypted data into its original,
comprehensible form.

data integrity

The assurance that information has not been altered since it was originally
generated.

key

A piece of data that is used with an algorithm to encrypt and decrypt
information.

key wrapping/unwrapping

Encryption/decryption of a key. The key can be a symmetric key or private
key of a public/private key pair.

key-pair generation

The creation of two keys, one public, one private, for signing and verifying
digital signatures.

manifest

A thorough description of an add-in module. A manifest’s specification must
be written in terms defined by the CSSM_MODULE_INFO structure.

Common Data Security Architecture (CDSA) White Paper

Glossary of CDSA Terms and Acronyms

message digest

The results of a hash operation on an arbitrary series of bits.

pass-through functionality

The paradigm by which a CDSA add-in shared library provides extra
functionality beyond what is specified by the CDSA API.

protocols, higher-level security

PKCS, SSL, S/MIME, IPSec, and SET are among the higher-level security
protocols that provide the basis for secure Internet interoperability.

public-key cryptography

Cryptography based on techniques that use public and private keys. A
public key is made available to all and is typically used for encryption or for
verifying signatures. By contrast, a private key is kept secret and is used to
generate digital signatures or for decryption operations.

public/private key pair

See key-pair generation.

Chapter 1 9

Common Data Security Architecture (CDSA) White Paper

Glossary of CDSA Terms and Acronyms

root of trust

The concept that a single authority may propagate trust by signing an
entity’s identity certificate.

salt

Random bytes that are usually mixed with other bytes to form a key or
password.

secure hash algorithms (SHA-1 and its predecessor SHA)

Algorithms specified in the Secure Hash Standard (SHS, FIBS PUB 180)
and developed by the National Institute of Standards and Technology
(NIST).

seed

Random bytes used to help generate other random bytes.

session key

Typically, a symmetric cipher key spontaneously generated to bulk-encrypt
data.

signature

See digital signature.

10 Chapter1

Common Data Security Architecture (CDSA) White Paper

What Is CDSA?

What Is CDSA?

The Common Security Architecture (CDSA) is a set of application program interfaces (APIs)
to perform cryptography and other public key infrastructure operations. Additional shared
libraries implement the API functionality. The Cryptographic Service Provider (CSP) module
implements most popular cryptographic algorithms. The Certificate Library (CL) module
implements X.509v3 certificate operations. The Trust Policy (TP) and Data Storage Library
(DL) are not implemented in this release. CDSA consists of the most popular cryptographic
algorithms needed for security applications; the code may be used by C or C++ applications.

HP’s Implementation of CDSA

HP’s initial release of CDSA consists of shared libraries, header and module information files,
and manpages for CDSA APIs covering a Common System Security Manager (CSSM),
Cryptographic Service Provider (CSP), and Certificate Library (CL). Each manpage describes
an API function. HP’s implementation also includes CDSA’s standard service provider
interfaces for Data Library (DL) and Trust Policy (TP), although HP is not providing DL or TP
add-in modules.

Figure 1-1 HP-UX CDSA Product Overview

CSSM (v1.2) Framework

Shared Library

CSP CL DL TP

shared library shared library

Header and Module

Manpages

Information files

Not included in first release

CDSA Files on HP-UX

As of June 1999, CDSA is available on the HP-UX 11.0 Application CD. In the future, it will

Chapter 1 11

Common Data Security Architecture (CDSA) White Paper

What Is CDSA?

be available as part of the HP-UX core. The CDSA product contains all CDSA components,
which can be found in the following directories and files (remember that as of June 1999, you
will have to install the HP-UX 11.0 Application CD for these directories and files to be on your
system):

/usr/lib/libcssm.1 & libcssm.sl CSSM framework library
/usr/lib/cdsa/libx509v3.1 CL library
/usr/lib/cdsa/meta-inf/libcssm.dsa CSSM credential file
/usr/include/cdsa/*.h CDSA header files
/usr/share/doc/CDSA.ps HP-UX CDSA white paper (postscript)
/usr/share/doc/CDSA.pdf HP-UX CDSA white paper (Adobe

Acrobat format)
/var/cdsa/cssm/* CSSM module information files
/usr/share/man/man*.Z/* CDSA manpages

The HP-UX distribution of CDSA does not include a CSP. You must select the CSP you desire
from the Hewlett Packard Software Depot web site (www.software.hp.com). The CDSA
CSPs are listed under the Internet and Security Solutions category. Three CSP's are
available:

HP Praesidium World Wide Importable CDSA CSP
HP Praesidium World Wide Exportable CDSA CSP
HP Praesidium Strong Encryption CDSA CSP
To install the CSP package you download; refer to the directions on the web site.

12 Chapter1

Common Data Security Architecture (CDSA) White Paper

Figure 1-2 CDSA Components on HP-UX

Common Security Services Manager (CSSM) APIs

What Is CDSA?

Crypotgraphy

Services
Manager

and

Interface

Cryptography

Services
Provider

(CSP)

Certificate

Library

Manager

and

Interface

Certificate

Library

(CL)

Data Storage

Library

Manager

and

Interface

Data

Storage

Library

(DL)

Trust Policy

Manager

and

Interface

Trust

Policy

Library

(TP)

CDSA Components in HP-UX

Each component of the HP-UX CDSA infrastructure provides a key element necessary for a
unified security architecture.

The Common Security Service Manager (CSSM) provides access to the general security
services, such as encryption/decryption, signatures, and so forth. The CSSM’s Core Service
APIs:

• Provides capability for encryption, decryption, and authentication

• Integrate and manage all modular security services,

• Provide support for additional add-in security modules.

• Provide CSP integrity services.
A Cryptographic Service Provider (CSP) implements the functionality implied by the API

functions and services, including:

• Bulk encryption and decryption

• Digital signing and verification

• Cryptographic hash

• Key exchange

• Key and key-pair generation

• Random number generation

• Encrypted storage of private keys

Chapter 1 13

Common Data Security Architecture (CDSA) White Paper

What Is CDSA?

• Pass-through capabilities to import/export RSA and DSA keys
The Certificate Library (CL) API performs memory-based, syntactic manipulations on

X.509v3 certificates and certificate revocation lists. These actions include:

• Creating, signing, and verifying certificates and revocation lists

• Extracting values (such as public keys) from certificates

• Revoking and reinstating certificates

• Searching certificate revocation lists

• Providing pass-through functionality to manipulate certificate and revocation-list data
formats

In addition to the APIs, HP’s implementation of CDSA provides service provider interfaces for
use in the development of Trust Policy (TP) and Data Library (DL) modules.

NOTE You may notice seemingly duplicated APIs, some whose names begin

CSSM_ followed by a type of service provider (CSP, CL, and so forth),
others whose names begin directly with the service provider designation.
The CSSM_* APIs are intended for application development; that is, to
enable applications to request services of the shared library via the
CSSM. The interfaces whose names begin with the service provider
designation (CSP_, CL_, and so forth) are called SPIs and are used for
developing add-in modules. They are “invisible” to applications.

14 Chapter1

Common Data Security Architecture (CDSA) White Paper

What Is CDSA?

Figure 1-3 Example of CDSA APIs Used for Applications vs. Shared

Libraries

Applications

Use CSSM_CL* APIs for developing applications using the
CL shared library

Common Security Services Manager (CSSM) APIs

Use CL_* APIs for developing CL add-in modules

Certificate

Library (CL)

Shared Library

CDSA in the Context of Other Security Applications

Growth of Internet traffic and the proliferation of e-commerce opportunities have prompted
HP to offer the CDSA functionality freely for use by customers who develop and deploy
security applications. The increased need for Internet security features creates an
opportunity that CDSA functionality can serve well.

While CDSA provides the raw building-blocks for doing cryptography, for an application to be
secure may require use of other, higher-level set of protocols (among them, SSL, S/MIME,
PGP, or SET). These protocols not only provide a higher level structuring for the results of
primitive cryptographic operations, but also ensure cryptographic interoperability between
differing platforms. Thus, when Internet applications developers field their products, they
might employ the SSL or S/MIME protocols to ensure interoperability between different
applications. Broadly speaking, these high-level security protocols safeguard the
transmission of e-commerce information and serve as defacto standards of secure
communication.

The following figure shows CDSA with higher-level protocols and user applications.

Chapter 1 15

Common Data Security Architecture (CDSA) White Paper

What Is CDSA?

Figure 1-4 CDSA, shown relative to higher-level protocols and user

applications

End User Applications

Higher-Level Security Protocols (PKCS, SSL, S/MIME, IPSEC, SET, et al.)

Common Security Services Manager (CSSM) APIs

Crypotgraphy

Services
Manager

and

Interface

Cryptography

Services
Provider

(CSP)

The first protocol to have developed widespread use is called Secure Sockets Layer (SSL),
which runs on top of TCP/IP and provides security for web browsers and servers.

Another protocol, called Secure Multipurpose Internet Mail Extensions (S/MIME), is used to
safeguard email over the Internet. MIME extended the email specification, so that other data
types, such as graphics and files created using word-processing programs, can be included in
email messages. S/MIME provides privacy, authentication, and integrity services for Internet
email messaging.

Pretty Good Privacy (PGP) is another protocol that uses cryptographic techniques for doing
security messaging.

Secure Electronic Transactions (SET) is a protocol designed to protect transfer of credit-card
information over the Internet. It is a standard being promoted by VISA and MasterCard.

Certificate

Library

Manager

and

Interface

Certificate

Library

(CL)

Data Storage

Library

Manager

and

Interface

Data

Storage

Library

(DL)

Trust Policy

Manager

and

Interface

Trust

Policy

Library

(TP)

The above protocols make use of some subset of the thirteen Public-Key Cryptography
Standards (PKCS). These standards address RSA encryption, password-based encryption,
and extended certificate syntax. One of the key benefits of PKCS is that the standards

16 Chapter1

Common Data Security Architecture (CDSA) White Paper

What Is CDSA?

promote interoperability. The syntax for expressing PKCS definitions are based on the
Abstract Syntax Notation One (ASN.1), which is defined in two ISO standards that describe
data syntax and encoding.

While these higher-level protocols provide the basis for secure Internet application
interoperability, the APIs of the cryptographic libraries give the application developer access
to the cryptographic algorithms necessary to ensure data privacy, authentication, and
integrity. CDSA provides a comprehensive set of the cryptographic building-block libraries,
much like other cryptographics libraries already available to application developers.

HP’s Paradigm Shift

By offering CDSA, HP changes the way software developers can approach writing and
disseminating commercial security applications.

HP’s license agreement allows developers to write applications that make free use of CDSA
and to market the application as a product without paying royalties. The code is available on
HP platforms on a right-to-use (not right-to-distribute) basis. HP places no limitations on
how the cryptographic libraries can be used, in that any application can link to it or use it,
royalty-free.

Large and small developers alike benefit from the likelihood that the CDSA crypto APIs will
become pervasive through their adoption by the Open Group. Application developers will
benefit from the portability of code written using CDSA APIs. An application written with
CDSA APIs and linked against a CDSA library on a particular platform could be moved to any
other platform as long as the other platform had the appropriate CDSA library. No code
would have to be modified to make use of the same cryptographic capabilities or functionality.
As long as the other system has CDSA, you would simply have to recompile.

U.S. application developers implementing CDSA may need to seek U.S. government approval
for the export or reexport of their products due to the export control nature of certain
cryptography technologies and implementations. In addition, the import and use of certain
products with cryptography in some countries may require local country authorization. You
should consult with proper government authorities or your legal counsel before distributing
your products with cryptography.

Chapter 1 17

Common Data Security Architecture (CDSA) White Paper

Common Security Services Manager (CSSM) API

Common Security Services Manager (CSSM)
API

The Common Security Services Manager (CSSM) provides the general-purpose core services
of the CDSA and operates on behalf of its libraries and add-in modules, such as the
cryptographic service provider (CSP) or certificate library (CL). The CSSM APIs support
modules with functions to install and uninstall modules, dynamically select and load modules,
and query modules about features and status.

System administration utilities use CSSM install and uninstall functions to maintain add-in
modules on a local system. A module might implement a range of services across the CSSM
APIs or restrict its purpose to a single CSSM category of service (for example, certificate
library services only).

The CSSM is designed for add-in modules to be attached by means of an assigned, Globally
Unique ID (GUID) with a set of descriptive attributes. Applications attach the module by
specifying the module’s GUID. The attach function returns a handle representing a unique
pairing between the caller and the attached module. This handle is then used as an input
parameter when requesting services from the attached module; that is, CSSM uses the handle
to match the caller with the appropriate service module. The calling application uses the
handle to obtain services implemented by the attached module. Each call to attach is an
independent request with its own handle and an independent execution state.

Before attaching a service module, an application can query the CSSM module information
files about the system’s installed modules, their capabilities and functions, and the module’s
GUID. Applications use this information to select a module. Applications can also query
about CSSM itself.

The CSSM memory management functions are a class of routines for reclaiming memory
allocated by CSSM on behalf of an application from the CSSM memory heap. When CSSM
allocates objects from its own heap and returns them to an application, the application must
inform CSSM when it no longer requires the use of that object. Applications use specific APIs
to free CSSM-allocated memory. When an application invokes a free function, CSSM can
choose to retain or free the indicated object, depending on other conditions known only to
CSSM. In this way CSSM and applications work together to manage these objects in the
CSSM memory heap.

As a security framework in which applications run, CSSM safeguards the environmental
integrity against threat of viruses and other forms of impersonation. CSSM reduces the risk
of these threats by requiring digitally signed modules and by checking dynamically the
identity and integrity of CSP modules at attach time. This verification ensures that any
modification, whether accidental or malicious, may be detected prior to performing trusted

18 Chapter1

Common Data Security Architecture (CDSA) White Paper

Common Security Services Manager (CSSM) API

operations.
Module verification has three aspects:

• verification of the module’s identity, based on a digitally-signed certificate

• verification of object code, whose integrity is itself based on a signed hash of the object

• tightly binding the verified module identity with the verified set of object code.

CSSM Module Information Files

Each CSSM module (including CSSM itself and add-ins) must be installed on the system
before applications can use it. CSSM_ModuleInstall() is the API used to install modules.
CSSM_ModuleInstall() creates information files under the directory /var/cdsa/cssm. The
information file for each module installed is named for its module GUID, in the form
“module-guid”.info.

For example, the CSSM core has a module GUID of

{4405ee7c-eeac-11d1-b73d-0060b0b6e655}

Its module-guid.info file, named

/var/cdsa/cssm/{4405ee7c-eeac-11d1-b73d-0060b0b6e655}.info

contains the following information:

String*Location: /usr/lib/libcssm.1
String*Name: Helwett-Packard Common Security Service Managers Module
String*Version: 1.20
String*Vendor: Hewlett-Packard Company
String*Description: CSSM Module
Binary*ThreadSafe: 00000000
Binary*NumberOfServices: 00000000
String*GUID: {4405ee7c-eeac-11d1-b73d-0060b0b6e655}
Binary*ServiceMasks: 00000001

If the NumberOfServices is not 0, the directory guid contains information for each service.
CSSM_ModuleUnInstall() is the API to uninstall a module. CSSM_ModuleUnInstall()

removes the module information file from /var/cdsa/cssm. After a module is uninstalled, it
becomes unavailable to applications.

ForHP-UX, CSSM core, the bundled CSP and the x509v3 CL are preinstalled into the system

Chapter 1 19

Common Data Security Architecture (CDSA) White Paper

Common Security Services Manager (CSSM) API

and are available to applications without further operations required. They should remain on
the system and not be removed.

NOTE CDSA requires the /var file system to support long file names (greater

than 14 characters). CSSM and the bundled add-ins will not be
pre-installed if its /var supports only short file names. In this case,
CSSM_ModuleInstall() will return the error code
CSSM_NOT_LONG_FILE_NAME_SYS.

20 Chapter1

Common Data Security Architecture (CDSA) White Paper

Cryptography Service Provider (CSP) API

Cryptography Service Provider (CSP) API

The algorithms of the cryptography service provider (CSP) APIs provide the means to :

• Disguise data, so that it is unreadable in encrypted form.

• Ensure data integrity, to make sure it has not changed in transport.

• Uniquely identify the sender of received data.
The CSP is an add-in module to the CSSM. The CSP supplies the cryptographic capabilities

to applications that call into it through the CSSM API.

Public/Private Key Algorithms

In the simplest terms, the user creates a public/private key pair. If a public key (which can be
distributed freely) is used to encrypt, only the private key can be used to decrypt. Conversely,
if the private key is used to encrypt, the public key is used to decrypt.

The following three examples show how public and private keys are used for secure
messaging.

Dual Asymmetric Key Algorithm

[1] A requests B’s public key and uses it to encrypt data, which A sends to B.
[2] B uses B’s private key to decrypt A’sencrypted data. (This is the only key that can decrypt

this message.)

Chapter 1 21

Common Data Security Architecture (CDSA) White Paper

Cryptography Service Provider (CSP) API

Figure 1-5 Dual Asymmetric Key Algorithm

[1]

.

A:

[2]

B

A’s encrypted dataA’s data B’s public key

B

B:

B

A’s dataA’s encrypted dataB’s private key

Symmetric Key Algorithm

Because asymmetric key algorithms are very expensive computationally, symmetric key
algorithms (which use the same one key to encrypt and decrypt) are used to bulk-encrypt the
data. In this example, an asymmetric key algorithm is used to encrypt only the symmetric
key.

[1] A chooses a symmetric key algorithm (such as RC2 or RC4) and uses it to generate a
symmetric key to bulk-encrypt A’s data.

[2] A then use B’s public key to encrypt the symmetric key. A sends both symmetric key and
bulk-encrypted data to B.

[3] B uses B’s private key to decrypt the symmetric key.
[4] B uses the symmetric key to decrypt A’s encrypted data.

22 Chapter1

Common Data Security Architecture (CDSA) White Paper

Figure 1-6 Symmetric Key Algorithm

[1]

Cryptography Service Provider (CSP) API

A:

[2]

A:

[3]

B:

B’s private key

[4]

B:

RC2 or RC4

symmetric key algorithm

A’s data A’s encrypted data

symmetric key

B

symmetric key

symmetric key

encrypted symmetric keyB’s public key

B

encrypted symmetric key

symmetric key

B

symmetric key

Authenticating a Digital Signature

When B receives the data, B can be certain only of having received it from someone who used
B’s public key to encrypt it. If B wanted to authenticate the message (that is, make sure that
it was A who sent it), B would have to authenticate a digital signature that A would send with
A’s data. This is shown in Figure 1-7, “Authenticating a Digital Signature.”

[1] Before encrypting data with a symmetric key algorithm, A hashes the data. This creates a

Chapter 1 23

A’s encrypted data

A’s data

Common Data Security Architecture (CDSA) White Paper

Cryptography Service Provider (CSP) API

unique set of bits corresponding to the data. Typically generated hashes are very small (e.g.
20 bytes).

[2] A encrypts the hash using A’s private key to create A’s “digital signature.”
[3] A passes the digital signature, encrypted symmetric key, and bulk-encrypted data to B.
[4] B uses B’s private key to decrypt the encrypted symmetric key.
[5] B uses the symmetric key to decrypt A’s bulk-encrypted data.
[6] With knowledge of what hash function A used to generate A’s digital signature, B

calculates the hash over A’s data.
[7] B uses A’s public key to decrypt A’s hash of A’s data.
[8] B compares A’s hash of A’s data to B’s hash of A’s data.
Since only A’s public key can decrypt data that A encrypted using A’s private key, B knows

that the data came from A, and further, that it has not been tampered with, since A’s hash of
A’s data and B’s hash of A’s data are identical.

All basic cryptographic operations discussed above (symmetric key encryption, dual
assymetric key cryptography, hashing, and digital signatures) can be found in the HP CDSA
library’s capabilities. The APIs for using CDSA are discussed in the sections that follow.

24 Chapter1

Common Data Security Architecture (CDSA) White Paper

Cryptography Service Provider (CSP) API

Figure 1-7 Authenticating a Digital Signature

[1]

A:

A’s data

hash

A’s hash of A’s data

[2]

A:

A’s hash of A’s data A’s digital signature

A

A’s private key

[3]

A:

A’s digital signature,

encrypted symmetric key,

A’s encrypted data

[4]

B:

B

B’s private key

encrypted symmetric key

[5]

B:

A’s encrypted data

symmetric key

[6]

B

symmetric key

A’s data

B:

hash

B’s hash of A’s dataA’s data

[7]

B:

A’s digital signature

A

A’s public key

A’s hash of A’s data

[8]

B:

A’s hash of A’s data B’s hash of A’s data

Chapter 1 25

Identical?

Common Data Security Architecture (CDSA) White Paper

Cryptography Service Provider (CSP) API

Interaction between CSP and Applications

The application selects a CSP and requests CSSM to attach to it. The CSSM returns a CSP
handle to the application that uniquely identifies the pairing of the application thread to the
CSP module instance. This handle is used by the application to identify the CSP in the future.

The application establishes a “session,” a framework in which the CSP will perform
cryptographic operations.

The application creates an operation “context,” which must exist prior to starting CSP
operations and is deleted as soon as possible upon completion of the operation.

Depending on the class of cryptographic operations, individualized attributes are available for
the cryptographic context.

When creating the context, the application specifies an algorithm and may also initialize a
session key, pass an initialization vector and/or pass padding information to complete the
description of the session.

A successful return value from the create function to the application indicates the desired
CSP is available. Functions are also provided to manage the created context.

All cryptographic services requested by applications are channeled to the CSP via the CSSM.
The CSP uses the CSSM module information files and query mechanism for disclosing
detailed information about its cryptographic services to the application. For example, a CSP
may register with the CSSM:

Encryption is supported. The algorithms present are RC2 with cipher block chaining for

key sizes 40 and 56 bits.

During the session, the CSP may perform cryptographic operations such as encryption,
decryption, digital signaturing, key and key-pair generation, random number generation,
message digest, key wrapping, key unwrapping, and key exchange. Cryptographic services
can be implemented by an add-in module of hardware and software or by software alone.

Cryptographic operations might take place:

• as a single call to perform an operation and obtain a result.

• as a sequence of calls, starting with an initialization call, followed by one or more update
calls, and ending with a completion (final) call. Usually, the result is available after the
final function completes its execution. Staged encryption/decryption are an exception, in
that each update call generates a portion of the result.

The CSP is responsible for the secure storage of private keys created during a CSP session.
Context information is not persistent; it is not saved permanently in a file or database.

When a context is no longer required, the application calls CSSM_DeleteContext to delete the
session’s context information. Resources that were allocated for that context can be reclaimed

26 Chapter1

Common Data Security Architecture (CDSA) White Paper

Cryptography Service Provider (CSP) API

by the operating system.

CSP Operations

CSP_SignData ()
CSP_SignDataInit ()
CSP_SignDataUpdate ()
CSP_SignDataFinal ()
Each operation accepts as input a handle to a cryptographic context describing the sign

operation and the data on which to operate. The result of the completed sign operation is
returned in a CSSM_DATA structure.

CSP_VerifyData ()
CSP_VerifyDataInit ()
CSP_VerifyDataUpdate ()
CSP_VerifyDataFinal ()
Each operation accepts as input a handle to a cryptographic context describing the verify

operation and the data on which to operate. The result of the completed verify operation is
either true or false.

CSP_DigestData ()
CSP_DigestDataInit ()
CSP_DigestDataUpdate ()
CSP_DigestDataFinal ()
Each operation accepts as input a handle to a cryptographic context describing the digest

operation and the data on which to operate. The result of the completed digest operation is
returned in a CSSM_DATA structure.

CSP_DigestDataClone ()
Accepts as input a handle to a cryptographic context describing the digest operation. A

handle to another cryptographic context is created with similar information and intermediate
result as described by the first context.

CSP_GenerateMac ()
CSP_GenerateMacInit ()
CSP_GenerateMacUpdate ()

Chapter 1 27

Common Data Security Architecture (CDSA) White Paper

Cryptography Service Provider (CSP) API

CSP_GenerateMacFinal ()
Each operation accepts as input a handle to a cryptographic context describing the MAC

operation and the data on which to operate. The result of the completed MAC operation is
returned in a CSSM_DATA structure.

CSP_VerifyMac ()
CSP_VerifyMacInit ()
CSP_VerifyMacUpdate ()
CSP_VerifyMacFinal ()
Each operation accepts as input a handle to a cryptographic context describing the MAC

operation and the data on which to operate. The result of the completed verify operation is a
CSSM_RETURN value.

CSP_QuerySize ()
Accepts as input a handle to a cryptographic context describing the encryption or decryption

operation, and an array of input block sizes. This function returns the output block sizes
corresponding to the input sizes for the specified algorithm.

CSP_EncryptData ()
CSP_EncryptDataInit ()
CSP_EncryptDataUpdate ()
CSP_EncryptDataFinal ()
Each operation accepts as input a handle to a cryptographic context describing the encryption

operation and the data to operate on. The encrypted data is returned in CSSM_DATA
structures.

CSP_DecryptData ()
CSP_DecryptDataInit ()
CSP_DecryptDataUpdate ()
CSP_DecryptDataFinal ()
Each operation accepts as input a handle to a cryptographic context describing the decryption

operation and the data on which to operate. The decrypted data is returned in CSSM_DATA
structures.

CSP_GenerateKey ()
Accepts as input a handle to a cryptographic context describing the generate key operation

and attributes of the new key. The key is returned in a CSSM_KEY structure.

28 Chapter1

Common Data Security Architecture (CDSA) White Paper

Cryptography Service Provider (CSP) API

CSP_GenerateKeyPair ()
Accepts as input a handle to a cryptographic context describing the generate key operation

and attributes of each key in the new key pair. The keys are returned in CSSM_KEY
structures.

CSP_GenerateRandom ()
Accepts as input a handle to a cryptographic context describing the generate random

operation. The random data is returned in a CSSM_DATA structure.
CSP_WrapKey ()
Accepts as input a handle to a symmetric/asymmetric cryptographic context describing the

wrap key operation and the wrapping key to be used in the operation, the key to be wrapped,
and a passphrase (if required by the CSP) that permits access to the private key to be
wrapped.

CSP_UnwrapKey ()
Accepts as input a handle to a cryptographic context describing the key unwrap operation, the

wrapped key to be unwrapped, and a passphrase (if required by the CSP) that will be used to
control access to the private key for the unwrapping operation.

CSP_DeriveKey ()
Accepts as input a handle to a cryptographic context describing the derive key operation and

the base key that will be used to derive new keys.
CSP_GenerateAlgorithmParams ()
Accepts as input a handle to a cryptographic context describing an algorithm and returns a

set of algorithm parameters appropriate for that algorithm.
CSP_QueryKeySizeInBits ()
Accepts as input a handle to a cryptographic context and the context containing the key. This

function returns a pointer to a data structure containing the keysize and effective keysize in
bits.

CSP_AssociatePublicKeyWithPrivateKey ()
Accepts as input a handle to a cryptographic context and a public and private key pair and

associates the public key with the private key.
CSP_ObtainPrivateKeyFromPublicKey ()
Accepts as input a CSP handle and a public key. This function returns a pointer to the private

key that is associated with the public key.
CSP_Login ()

Chapter 1 29

Common Data Security Architecture (CDSA) White Paper

Cryptography Service Provider (CSP) API

Accepts as input a login password and logs the user into the CSP. CSPs are not required to
support a login model. If a login model is supported, the CSP may request additional
passwords at any time during the period of service. The HP-UX bundled CSP supports logins.

CSP_Logout ()
The caller is logged out of the current login session with the designated CSP.
CSP_ChangeLoginPassword ()
Accepts as input a handle to a CSP, the callers old login password for that CSP, and the callers

new login password. The old password is replaced with the new password. The callers
current login is terminated and another login session is created using the new password.

Extensibility Functions

CSP_PassThrough ()
Performs the CSP module-specific function indicated by the operation ID. The operation ID

specifies an operation which the CSP has exported for use by an application or module. Such
operations are specific to the CSP module. The operation IDs supported by the HP-UX
bundled CSP and the examples of how to use them are found in Appendix C, “Code Examples.”

Supported Functions and Algorithms

The HP Praesidium Worldwide Importable CSP supports the following functions and
algorithms:

• Random Number Generation
Algorithm ID:

— CSSM_ALGID_SHARandom

• Message Digest
Algorithm IDs:

— CSSM_ALGID_MD5
— CSSM_ALGID_SHA1

• Message Authentication Code
Algorithm IDs:

— CSSM_ALGID_MD5
— CSSM_ALGID_SHA1

• Symmetric Key Generation

30 Chapter1

Common Data Security Architecture (CDSA) White Paper

Cryptography Service Provider (CSP) API

Algorithm IDs, shown with keysize specification in bits:
— CSSM_ALGID_CDMF; 64

The effective key size of a 64-bit CDMF key is 40 bits.
— CSSM_ALGID_RC2; <=40, in any multiple of 8, between 8 and 40
— CSSM_ALGID_RC4; <=40, in any multiple of 8, between 8 and 40
— CSSM_ALGID_MD5, unlimited*
— CSSM_ALGID_SHA1 unlimited*

* When these keys are used to generate a symmetric context, they are subject to the

same length restriction as the algorithm (CSSM_ALGID_CDMF, CSSM_ALGID_RC2,

or CSSM_ALGID_RC4) specified for the context.

• Asymmetric Key Generation
Algorithm ID, shown with keysize specification:

— CSSM_ALGID_RSA; 512, 768, 1024

When these keys are used to generate an asymmetric context, only keys with 512 bits
length are allowed for encryption/decryption or for key wrapping/unwrapping

operations.
— CSSM_ALGID_DSA; 512, 768, 1024
— CSSM_ALGID_DH; 512, 768, 1024

Only keys with 512 bits length are allowed for key derivation.

Algorithm ID Keysize Modes Padding (specified in bits)
CSSM_ALGID_CDMF 64 CSSM_ALGMODE_ECB CSSM_PADDING_NONE

CSSM_ALGMODE_CBC CSSM_PADDING_NONE
CSSM_ALGMODE_CBC_IV8 CSSM_PADDING_NONE
CSSM_ALGMODE_CBCPadIV8 CSSM_PADDING_PKCS5

CSSM_ALGID_RC2 <=40 CSSM_ALGMODE_ECB CSSM_PADDING_NONE

CSSM_ALGMODE_CBC CSSM_PADDING_NONE
CSSM_ALGMODE_CBC_IV8 CSSM_PADDING_NONE
CSSM_ALGMODE_CBCPadIV8 CSSM_PADDING_PKCS5

CSSM_ALGID_RC4 <=40 CSSM_ALGMODE_NONE CSSM_PADDING_NONE

Chapter 1 31

Common Data Security Architecture (CDSA) White Paper

Cryptography Service Provider (CSP) API

• Digital Signature and Validation
Algorithm ID:

— CSSM_ALGID_MD5WithRSA
— CSSM_ALGID_SHA1WithRSA
— CSSM_ALGID_SHA1WithDSA

• Parameter Generation
Algorithm ID:

— CSSM_ALGID_DSA
— CSSM_ALGID_DH

• Key Wrapping and Unwrapping
Algorithm ID, shown with keysize specification in bits:

— CSSM_ALGID_RSA; 512
— CSSM_ALGID_CDMF; 64
— CSSM_ALGID_RC2; <=40
— CSSM_ALGID_RC4; <=40

• Key Derivation
Algorithm ID, shown with supported derived key type:

— CSSM_ALGID_DH; CDMF, RC2, RC4
— CSSM_ALGID_MD5_PBE; CDMF
— CSSM_ALGID_SHA1_PBE; CDMF

Purpose Pass-Through ID

Provide OAEP message formatting and parsing.
Support SHA1 or MD5 hash functions or
user-specified mask generation function.

BER-encode CSSM RSA and DSA keys ISC_CSP_ENCODE_DSA_PUBKEY

32 Chapter1

ISC_CSP_OAEP_ENCODE
ISC_CSP_OAEP_DECODE

ISC_CSP_ENCODE_DSA_PRIKEY
ISC_CSP_ENCODE_RSA_PUBKEY
ISC_CSP_ENCODE_RSA_PRIKEY

Common Data Security Architecture (CDSA) White Paper

Cryptography Service Provider (CSP) API

Purpose Pass-Through ID

Decode BER-encoded CSSM RSA and DSA keys ISC_CSP_DECODE_DSA_PUBKEY

ISC_CSP_DECODE_DSA_PRIKEY
ISC_CSP_DECODE_RSA_PUBKEY

ISC_CSP_DECODE_RSA_PRIKEY
Delete a private key ISC_CSP_DELETE_PRVKEY
Reverse the order of octets in a symmetric CSSM key ISC_CSP_REVERSE_KEY
Create a DSA or RSA CSSM private key using raw

application-supplied data
BER-encode DSA parameters ISC_CSP_ENCODE_DSA_PARAMS
BER-encode Diffie-Hellman (DH) parameters ISC_CSP_ENCODE_DH_PARAMS
BER-decode DSA parameters ISC_CSP_DECODE_DSA_PARAMS
BER-decode Diffie-Hellman (DH) parameters ISC_CSP_DECODE_DH_PARAMS

ISC_CSP_IMPORT_KEY

The HP Praesidium worldwide exportable and HP Praesidium Strong Encryption CSPs
support all functions and algorithms described in this section (only with larger available key
sizes). In addition, both CSPs support the DES algorithm. See the CSP manpage for specific
details.

Chapter 1 33

Common Data Security Architecture (CDSA) White Paper

Certificate Library Services (CL) API

Certificate Library Services (CL) API

What is a Certificate?

A certificate is a mechanism for establishing identity. Think of an X.509 certificate as a
packet that can be given safely to others. X.509 derives from a data storage concept for
directory services, called X.500, a mechanism that allows individuals to access others’ data.

The most important characteristic about a certificate is that it can be digitally signed by a
Certificate Authority (CA). An Internet infrastructure is emerging to handle that
responsibility.

When a certificate is “signed”, the contents of the certificate (such as public key,start validity
date, and so forth) are hashed. Then, the hash is signed with the CA’s private key.

The encrypted hash is then also placed in the certificate as the “signature” of the certificate.
When someone verifies the authenticity of a certificate, he or she may need to establish a

certificate chain to verify, then decrypt the signature with the public key at the end of the
certificate chain, rehash the certificate, and compare the hash to the decrypted hash. He or
she may also check the certificate’s start and end validity dates to verify the certificate is still
valid.

Outline of a Generic Certificate

All certificates have the following basic fields:

• Version ID (Version 1, 2, or 3)

• Serial Number (arbitrary, but should be unique for each Certificate Authority)

• Signature Algorithm ID (for example, RSA with MD5)

• Issuer Distinguished Name (that is, the Certificate Authority (CA) who issues the
certificate)

• Start Validity Date

• End Validity Date

• Subject Distinguished Name (that is, the owner or recipient of the certificate)

• Public Key Algorithm ID (for example, RSA encryption)

• Signature

• Extensions (optional)

34 Chapter1

Common Data Security Architecture (CDSA) White Paper

Certificate Library Services (CL) API

Certificates may have various classifications, and increasingly, developers are wanting to
include more information in a certificate. The CL module bundled as part of CDSA allows you
to create extensions, which can contain additional data.

Each field of a certificate format consists of a tag/value pair. The tag is is an object identifier
(OID) that references specific data types or data structures within the certificate or CRL and
indicates what kind of information the field contains. The value is the actual data
corresponding to the field. The OIDs are defined in the header files oidscert.h and oidscrl.h,
located in the /usr/include/cdsa/ directory. The OID structure is then passed to
CSSM_CL_CertCreateTemplate(), to create the certificate.

Field management operations allow an application to retrieve fields from a certificate without
knowledge of the certificate’s content or format. For example,
CSSM_CL_CertGetFirstFieldValue() returns the value of a designated certificate field.

In order for a certificate to be valid, it must be signed. To sign a certificate, pass the template
(output of CSSM_CL_CertCreateTemplate()) to CSSM_CL_CertSign(). Once a certificate is
signed, its fields cannot be modified. However, they can be queried for their values using the
CSSM certificate interface (for example, CSSM_CL_CertGetFirstFieldValue).

The CL bundled with HP-UX as part of CDSA allows for self-signing; that is, the CA and
recipient can be the same. The CL can also receive someone else’s certificate and verify it.

Before using a certificate, you must verify that it is still valid. (For example, is the signature
valid? Are the dates still valid? Certificates expire.) To do so, use the API
CSSM_CL_CertVerify().

Certificate Revocation List (CRL) and Operations

Certificates can be withdrawn from use or rendered invalid by placing them on a certificate
revocation list (CRL). An application generates a CRL by using the API
CSSM_CL_CrlCreateTemplate(). An X.509v2 CRL has the following structure:

• version

• signature algorithm

• Distinguished name field of issuer

• Issue date of CRL

• Date next CRL will be issued

• list of revoked certificates

• numbers and sequences of extensions, if present
The revoked certificates are linked as a list with each node having the following fields:

Chapter 1 35

Common Data Security Architecture (CDSA) White Paper

Certificate Library Services (CL) API

• Serial number of the revoked certificate

• Date on which the revocation occurred

• Number of extensions

• Pointers to extensions, if present

The certificate library manages the translation from the certificate to be revoked to its
representation in the CRL.

The contents of the CRL can be queried for its revocation records, certificates, or individual
CRL fields.Field management APIs allow you to set or get CRL fields, or to add or remove
certificates from the certificate revocation list.

The entire CRL can be signed or verified, to ensure the integrity of its contents as it is passed
between systems. Certificates can be revoked or unrevoked by adding or removing them from
the CRL at any time before the CRL is signed.

Each time a CRL is changed, it must be signed to maintain its validity.

Interaction between Certificate Library and Application

Making the CL available to an application requires coordination of CSSM, CL module, and
application.

An application determines the availability and capabilities (for example, certificate types and
fields) of the CL module by querying the CSSM module information files.

The application then requests that CSSM attach the CL.
The CSSM returns a CL handle to the application that uniquely identifies the pairing of the

application thread to the CL module instance. This handle is used by the application to
identify the CL in future function calls that the CSSM passes from an application to the CL.

The application must allocate and deallocate all memory passed into or out of the CL module.
It does so when the CSSM passes the handle identifying the application and module pairing
to the CL.

CL APIs manipulate memory-based objects only. The CL is not responsible for ensuring the
persistence of those objects (certificates, CRLs, and others); that responsibility lies with an
application and/or a data library.

At attach time, the CSSM receives the certificate library’s function table, making the CL
functions accessible to the CSSM. Any unsupported function has a NULL function pointer in
the function table.

A pass-through function of the CLI allows access to services beyond those defined in the
CSSM API, based on the data format of the certificates and CRLs manipulated by the library.
The CSSM passes an operation identifier and input parameters from the application to the

36 Chapter1

Common Data Security Architecture (CDSA) White Paper

Certificate Library Services (CL) API

CL_PassThrough function in the CL. The CL interprets the input parameters to enable the
appropriate operation to be performed.

NOTE Certificate and CRL operations initiated by an application are performed

with APIs whose names have the form CSSM_CL_*().
Other interfaces, whose names have the form CL_*() are intended for use

by add-on module developers only, for operations between the CSSM and
the CL module.

Interaction between CSSM and Certificate Library Interface

CSSM provides the general-security APIs that safeguard the CL manipulations of certificates
and certificate revocation lists.

The CSSM module information files (located in /var/cdsa/cssm) contain specifications of
CL-supported functions for use by the application.

The Certificate Library Interface (CLI) works with the CSSM APIs to make CL functions
available to applications. CL functions perform syntactic operations (including creation, field
management, signing, and verification, as well as extensibility operations and module
management) on certificates and CRLs, so that applications may focus on the use of
certificates rather than the mechanics of format manipulation.

Operations on Certificates

CSSM provides the general-security APIs that safeguard the CL manipulations of certificates
and certificate revocation lists. The CL module provides functionality that includes:

• Certificate operations

• Certificate revocation list (CRL) operations

• Extensibility functions.
The CSSM module information files contain specifications of CL supported functions. The

application can obtain and use this information.

Certificate Library Interface

The Certificate Library Interface (CLI) specifies the CL functions available to applications via
CSSM to support certificate and certificate revocation list (CRL) formats. These functions
work with the CSSM APIs to perform certificate operations, certificate revocation list
operations, extensibility functions, and module management functions.

Chapter 1 37

Common Data Security Architecture (CDSA) White Paper

Certificate Library Services (CL) API

The CL functions are accessible to the CSSM at attach time, when the CSSM receives the
certificate library’s function table. In the function table, any unsupported function has a
NULL function pointer.

Certificate operations fall into three general areas:
Cryptographic Operations, wherein a certificate is signed and its signature verified. The

certificate library determines the certificate fields to be signed or verified and manages the
interaction with a cryptographic service provider to perform the signing or verification.

Certificate Field Management, which involves adding fields to a certificate when it is created.
Once the certificate is signed, the fields cannot be modified. However, they can be queried for
their values using the CSSM certificate interface.

The fields of a certificate format consist of tag/value pairs. The tag is an object identifier
(OID) that references specific data types or data structures within the certificate or CRL.

Cryptographic operations and field management operations affect the entire CRL and
individual revocation records. The entire CRL can be signed or verified, to ensure the
integrity of its contents as the CRL is passed between systems. Individual revocation records
can be signed when they are revoked and verified when they are queried. Certificates can be
revoked or unrevoked by adding or removing them from the CRL at any time before the CRL
is signed. The contents of the CRL can be queried for its revocation records, certificates, or
individual CRL fields.

Certificate Operations This section summarizes the functions that comprise the certificate
operations in the CLI, as to operation and parameter definitions.

CL_CertSign ( )
Creates a digital signature for the subject certificate using the signer’s certificate. The

cryptographic context handle indicates the algorithm and parameters to be used for signing.
CL_CertVerify ( )
Verifies the signer certificate’s signature on the subject certificate. The cryptographic context

handle indicates the algorithm and parameters to be used for verification.
CL_CertCreateTemplate ( )
Creates a certificate template in the CL’s own certificate template format from the OID/value

pairs provided by the application. The CL module makes its supported OIDs available to the
application via the CertTemplate registered with CSSM and via the CL_CertDescribeFormat
function. The CL indicates which fields are required to create a certificate. A returned
certificate template is not valid until it has been signed.

CL_CertGetFirstFieldValue ( )

38 Chapter1

Common Data Security Architecture (CDSA) White Paper

Certificate Library Services (CL) API

Returns the first field in the certificate matching the input OID. If the certificate contains
more than one instance of the requested OID, the CL returns a handle used for obtaining and
tallying the additional instances of the OID in the certificate. The application obtains the
additional matching instances by repeated calls to CL_CertGetNextFieldValue.

CL_CertGetNextFieldValue ( )
Returns the next field that matched the OID given in the CL_CertGetFirstFieldValue

function.
CL_CertAbortQuery ( )
Releases the handle assigned by the CL_CertGetFirstFieldValue function to identify the

results of a certificate query. It is only supported by certificate library modules that allow
multiple instances of an OID in a single certificate.

CL_CertGetKeyInfo ( )
Retrieves the public key information stored in the certificate, based on which portions of the

CSSM_KEY data structure the CL has specified for the CSSM to reveal.
CL_CertGetAllFields ( )
Returns a list of all the fields in the input certificate, as described by their OID/value pairs.
CL_CertDescribeFormat ( )
Returns a list of the kinds of data objects comprising the CL module’s own certificate format.

Certificate Revocation List Operations This section summarizes the functions that
comprise the CRL operations in the certificate library interface, as to operation and
parameter definitions.

CL_CrlCreateTemplate ( )
Creates a CRL in the default CRL format based on the OID/value pairs provided by the

application. The CL makes its supported OIDs available to the application by two means: via
the CrlTemplate registered with CSSM and the CL_CrlDescribeFormat function. The CL
defines which fields are required to create a CRL, or conversely, which fields cannot be set
using this function. The returned CRL template is not valid until it has been signed.

CL_CrlSetFields ( )
Sets the fields of an existing CRL to new values, based on the OID/value pairs provided by the

application. The CL defines the fields that must or cannot be set using this function, and for
specifying module-specific behavior, such as overwriting existing fields, adding new fields, or
modifying CRL records. This operation is valid only if the CRL has not been signed. Once the
CRL has been signed, fields cannot be changed.

CL_CrlAddCert ( )

Chapter 1 39

Common Data Security Architecture (CDSA) White Paper

Certificate Library Services (CL) API

Revokes the input certificate by adding a record of the certificate to the CRL. The CRL entry
consists of OID/values provided by the application. The new record is signed using the
revoker’s certificate and the updated CRL is returned to the calling application. The CL
defines which fields 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 certificate by removing the record representing the certificate 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 certificate. The

cryptographic context handle indicates the algorithm and parameters to be used for signing.
CL_CrlVerify ( )
Verifies the signer certificate’s signature on the subject CRL. The cryptographic context

handle indicates the algorithm and parameters to be used for verification.
CL_IsCertInCrl ( )
Searches the CRL for a record corresponding to the input certificate.
CL_CrlGetFirstFieldValue ( )
Returns the first field 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 first 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 field 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 fields in the CRL format supported by the CL module.

40 Chapter1

Common Data Security Architecture (CDSA) White Paper

Certificate Library Services (CL) API

Extensibility Functions

CL_PassThrough ( )
Performs a function indicated by an operation ID, which identifies an operation exported by

CL for use by an application or other module. These operations are specific to the data format
of the certificates and CRLs manipulated by the CL module.

The HPUX bundled CL supports the following pass-through functions. Each pass-through ID
defined in cdsa/x509defs.h represents a pass-through function available to applications. To
perform the function, applications invoke the CL API CSSM_CL_PassThrough(), which has
the following syntax:

output = CSSM_CL_PassThrough(CLHandle, PassThroughID, Input);

• CLHandle is the handle returned by CSSM_ModuleAttach() when attaching the CL.

• PassThroughID is a pass-through number to indicate the function to be performed.

• Input is the input parameter required to perform the specific function. Each pass-through
ID has a specific input requirement.

• Output is the result returned by the function.

The information that follows specifies the function performed, input requirement and output
for each pass-through ID. For further details about the data structures, see the CSSM(4)
manpage:

INTEL_X509V3_PASSTHROUGH_ENCODE_CERTIFICATE

Function Encode a certificate
Input Pointer to a certificate in the format of X509_SIGNED_CERTIFICATE
Output Pointer to a DER-encoded certificate in the format of CSSM_DATA

INTEL_X509V3_PASSTHROUGH_DECODE_CERTIFICATE

Function Decode a certificate
Input Pointer to a DER-encoded certificate in the format of CSSM_DATA
Output Pointer to a certificate in the format of X509_SIGNED_CERTIFICATE

INTEL_X509V3_PASSTHROUGH_FREE_CERTIFICATE

Function Free a certificate structure and all of the pointers inside
Input Pointer to a certificate in the format of X509_SIGNED_CERTIFICATE
Output A CSSM_BOOL to indicate success/failure

INTEL_X509V3_PASSTHROUGH_CREATE_ENCODED_NAME

Chapter 1 41

Common Data Security Architecture (CDSA) White Paper

Certificate Library Services (CL) API

Function Create a DER-encoded X.509 distinguished name structure
Input Pointer to an array; the first element points to multiple entres of

X509_TYPE_VALUE comprising the name

Output Pointer to the name in the format of CSSM_DATA

INTEL_X509V3_PASSTHROUGH_ENCODE_NAME

Function Encode an issuer/subject name
Input Pointer to an issuer/subject name in the format of X509_NAME
Output Pointer to DER-encoded name in the format of CSSM_DATA

INTEL_X509V3_PASSTHROUGH_DECODE_NAME

Function Decode an issuer/subject name
Input Pointer to DER-encoded name in the format of CSSM_DATA
Output Pointer to an issuer/subject name in the format of X509_NAME

INTEL_X509V3_PASSTHROUGH_FREE_NAME

Function Free the X509_NAME structure
Input Pointer to an ssuer/subject name in the format of X509_NAME
Output A CSSM_BOOL to indicate success/failure

INTEL_X509V3_PASSTHROUGH_TRANSLATE_DERNAME_TO_STRING

Function Concatenate the leaves of the encoded name in the order they are presented

in the DER-encoded blob.
Input Pointer to an encoded name in the format of CSSM_DATA
Output Pointer to the name in the format of CSSM_DATA

INTEL_X509V3_PASSTHROUGH_ENCODE_EXTENSION

Function Encode the certificate extension
Input Pointer to the extension in the format of X509_EXTENSION
Output Pointer to the DER-encoded extension in the format of CSSM_DATA

INTEL_X509V3_PASSTHROUGH_DECODE_EXTENSION

Function Decode the certificate extension
Input Pointer to the DER-encoded extension in the format of CSSM_DATA
Output Pointer to the extension in the format of X509_EXTENSION

42 Chapter1

Common Data Security Architecture (CDSA) White Paper

Certificate Library Services (CL) API

INTEL_X509V3_PASSTHROUGH_ENCODE_EXTENSIONS

Function Encode an array of certificate extensions
Input Pointer to an array. The first element points to another array containing

extensions in the format of X509_EXTENSION. The second element is the
total number of extensions.

Output Pointer to the DER-encoded extensions in the format of CSSM_DATA

INTEL_X509V3_PASSTHROUGH_DECODE_EXTENSIONS

Function Decode an array of certificate extension
Input Pointer to an array. The first elements points to another array of

DER-encoded extensions in the format of CSSM_DATA as input parameter.
The second element points to DER-decoded extension in the format of
X509_EXTENSION as output parameter. The third elements contains the
number of extensions as output parameter.

Output Pointer to CSSM_BOOL for success/failure

INTEL_X509V3_PASSTHROUGH_FREE_EXTENSIONS

Function Free the array of extensions and the pointers inside
Input Pointer to an array. The first element points to another array containing

extensions in the format of X509_EXTENSION. The second element is the
total number of extensions.

Output Pointer to CSSM_BOOL for success/failure

INTEL_X509V3_PASSTHROUGH_ALGID_TO_ALGOID

Function Convert an alogirithm identifier to the OID/value pair format
Input Pointer to an integer representing an alogirithm identifier defined in

cdsa/cssmtype.h

Output Pointer to the algorithm identifier in the format of CSSM_OID

INTEL_X509V3_PASSTHROUGH_ALGOID_TO_ALGID

Function Convert an OID/value pair algorithm identifier to the value defined in

cdsa/cssmtype.h
Input Pointer to the alogrithm identifier in the format of CSSM_OID
Output Pointer to an integer representing an algorithm identifier defined in

cdsa/cssmtype.h

INTEL_X509V3_PASSTHROUGH_ENCODE_ALGID

Chapter 1 43

Common Data Security Architecture (CDSA) White Paper

Certificate Library Services (CL) API

Function Encode algorithm identifier
Input Pointer to an algorithm identifier in the format of

X509_ALGORITHM_IDENTIFIER

Output Pointer to encoded algorithm identifier in the format of CSSM_DATA

INTEL_X509V3_PASSTHROUGH_DECODE_ALGID

Function Decode algorithm identifier
Input Pointer to encoded algorithm identifier in the format of CSSM_DATA
Output Pointer to an algorithm identifier in the format of

X509_ALGORITHM_IDENTIFIER

INTEL_X509V3_PASSTHROUGH_FREE_ALGID

Function Free the algorithm identifier structure
Input Pointer to an algorithm identifier in the format of

X509_ALGORITHM_IDENTIFIER

Output Pointer to CSSM_BOOL for success/failure

INTEL_X509V3_PASSTHROUGH_OPEN_FILE

Function Open a file
Input Pointer to an array, the first element contains the file name the second

element contains the type (r, w, rw,...etc)

Output File pointer returned by fopen()

INTEL_X509V3_PASSTHROUGH_CLOSE_FILE

Function Close a file
Input File pointer
Output Pointer to CSSM_RETURN to indicate success/failure

INTEL_X509V3_PASSTHROUGH_WRITE_CERT_TO_FILE

Function Write certificate to a file
Input Pointer to an array. The first elements contains file pointer. The second

element contains a pointer to encoded certificate in the format of
CSSM_DATA.

Output Pointer to CSSM_RETURN to indicate success/failure

INTEL_X509V3_PASSTHROUGH_READ_CERT_FROM_FILE

44 Chapter1

Common Data Security Architecture (CDSA) White Paper

Certificate Library Services (CL) API

Function Read certificate from a file
Input File pointer
Output Pointer to encoded certificate in the format of CSSM_DATA

INTEL_X509V3_PASSTHROUGH_ENCODE_SIGNED_CRL

Function Encode a signed CRL
Input Pointer to the signed CRL in the format of X509_SIGNED_CRL
Output Pointer to an encoded, signed CRL in the format of CSSM_DATA

INTEL_X509V3_PASSTHROUGH_DECODE_SIGNED_CRL

Function Decode a signed CRL
Input Pointer to an encoded, signed CRL in the format of CSSM_DATA
Output Pointer to the signed CRL in the format of X509_SIGNED_CRL

INTEL_X509V3_PASSTHROUGH_FREE_SIGNED_CRL

Function Free the signed CRL structure
Input Pointer to a signed CRL in the format of X509_SIGNED_CRL
Output Pointer to CSSM_BOOL for success/failure

INTEL_X509V3_PASSTHROUGH_ENCODE_TBS_CERTLIST

Function Encode an unsigned CRL
Input Pointer to an unsigned CRL in the format of X509_TBS_CERTLIST
Output Pointer to encoded, unsigned CRL in the format of CSSM_DATA

INTEL_X509V3_PASSTHROUGH_DECODE_TBS_CERTLIST

Function Decode the unsigned CRL
Input Pointer to an encoded unsigned CRL in the format of CSSM_DATA
Output Pointer to the unsigned CRL in the format of X509_TBS_CERTLIST

INTEL_X509V3_PASSTHROUGH_FREE_TBS_CERTLIST_DATA

Function Free the pointers inside the unsigned CRL
Input Pointer to an unsigned revoked certificate list in the format of

X509_TBS_CERTLIST
Output Pointer to CSSM_BOOL for success/failure

INTEL_X509V3_PASSTHROUGH_ENCODE_REVOKED_CERTLIST

Chapter 1 45

Common Data Security Architecture (CDSA) White Paper

Certificate Library Services (CL) API

Function Encode the certificate list
Input Pointer to the certificate list in the format of X509_REVOKED_CERT_LIST
Output Pointer to the encoded certificate list in the format of CSSM_DATA

INTEL_X509V3_PASSTHROUGH_DECODE_REVOKED_CERTLIST

Function Decode the certificate list
Input Pointer to the encoded certificate list in the format of CSSM_DATA
Output Pointer to the certificate list in the format of X509_REVOKED_CERT_LIST

INTEL_X509V3_PASSTHROUGH_FREE_REVOKED_CERTLIST

Function Free all memory from a CRL
Input Pointer to the revoked certificate list in the format of

X509_REVOKED_CERT_LIST

Output Pointer to CSM_BOOL for success/failure

INTEL_X509V3_PASSTHROUGH_ENCODE_REVOKED_CERT_ENTRY

Function Encode the revoked certificate list entry
Input Pointer to the revoked certificate list entry in the format of

X509_REVOKED_CERT_ENTRY

Output Pointer to the encoded revoked certificate list entry in the format of

CSSM_DATA

INTEL_X509V3_PASSTHROUGH_DECODE_REVOKED_CERT_ENTRY

Function Decode the revoked certificate list entry
Input Pointer to the encoded revoked certificate list entry in the format of

CSSM_DATA

Output Pointer to the revoked certificate list entry in the format of

X509_REVOKED_CERT_ENTRY

INTEL_X509V3_PASSTHROUGH_FREE_REVOKED_CERT_ENTRY

Function Free all memory from a revoked certificate list entry
Input Pointer to the revoked certificate list entry in the format of

X509_REVOKED_CERT_ENTRY

Output Pointer to CSSM_BOOL to indicate success/failure

INTEL_X509V3_PASSTHROUGH_FIND_SUPPORTING_CSP

46 Chapter1

Common Data Security Architecture (CDSA) White Paper

Certificate Library Services (CL) API

Function Find which CSP supports an input cryptographic algorithm
Input Pointer to an algorithm ID defined in cdsa/cssm.h
Output Pointer to the structure of CSSM_SUBSERVICE_UID for the CSP that

supports the algorithm

INTEL_X509V3_PASSTHROUGH_CSSMKEY_TO_SPKI

Function Translate CSSM key format to subject public key
Input Pointer to the key in the format of CSSM_KEY
Output Pointer to subject public key in the format of

X509_SUBJECT_PUBLIC_KEY_INFO

INTEL_X509V3_PASSTHROUGH_SPKI_TO_CSSMKEY

Function Translate subject public key to CSSM key format
Input Pointer to subject public key in the format of

X509_SUBJECT_PUBLIC_KEY_INFO
Output Pointer to the key in the format of CSSM_KEY

Chapter 1 47

Common Data Security Architecture (CDSA) White Paper

Introduction to Add-in Modules

Introduction to Add-in Modules

NOTE This section provides a conceptual overview of CDSA add-in modules.

For a summary of how to create an add-in module, see “How to Create a
CDSA Add-In Module for HP-UX” on page 53.

For information on credentials required for any CSP add-in module, see
“Validating the CSP Credentials” on page 65 and “HP Signing Policy for
CSP Add-In Vendors for CDSA Version 1.2” on page 84.

The Role of Add-In Modules in the CDSA Framework

In HP-UX, a CDSA add-in module is a shared library that can be dynamically loaded into the
system by CSSM and uses CSSM to provide services to applications.

By convention, the add-in module is named libxxx.1 for the first version of the library, where
xxx is the library’s chosen name.

The CSSM acts as a “broker” between applications and add-in modules, by receiving and
handling all requests from applications for access and use of add-in modules.

An application derives information about add-in modules from CSSM module information
files, which contain data about a module and its services. Using that information, applications
request that CSSM attach to an add-in module. Applications can query the CSSM module
information files using the CSSM_GetModuleInfo function.

The first time the module is attached, CSSM calls the module’s Initialize function to allow the
module to perform initialization operations.

When CSSM attaches to a module service, it returns a module handle to the application that
uniquely identifies the pairing of the application thread to the module service instance. The
application uses this handle to identify the module service in future function calls. The
module service uses the handle to identify the calling application.

During the initialization process, if the module is a CSP, it undergoes a series of integrity
checks, including a bilateral authentication protocol to ensure the integrity of the CSSM, as
part of CSSM_ModuleAttach. This verification must succeed for a CSP module to attach to
CSSM.

Once the integrity of a CSP module is verified, the add-in module uses
CSSM_RegisterServices to register a function table with CSSM for each sub-service that it

48 Chapter1

Common Data Security Architecture (CDSA) White Paper

Introduction to Add-in Modules

supports. The function tables consist of pointers to the service functions supported by the
module and are created dynamically when the module is registered. Whenever the
application makes function calls, CSSM uses these function pointers to call the appropriate
module service.

When a module is detached, CSSM calls the Terminate function which allows the module to
perform any necessary cleanup actions. CSSM calls the module’s EventNotify function to
notify the add-in module as part of every attach and detach operation.

Interaction with add-in modules is not limited to CSSM and applications. Modules can use
one another to implement their functionality.

For example, a CL module can use the capabilities of a CSP module to perform the
cryptographic operations of sign and verify. In that case, the CL could package the certificate
or CRL fields to be signed or verified, attach to the appropriate CSP module, and call
CSSM_SignData or CSSM_VerifyData to perform the operation. Similarly, other CSSM
add-in modules may use the CL module to implement their functionality.

The integrity services of CSSM can be used by CSP add-in modules to verify their own
integrity and that of the CSSM. This aids in CSSM’s detection and protection against
malicious attacks.

Design Criteria for Add-In Modules

Because a CDSA add-in module must work within the CDSA framework, it must comply with
CDSA design criteria.

• If the add-in module is a CSP, it must have a set of digital credentials that are verified by

CSSM when the module is attached.

• The add-in module installation program must create module information files using

CSSM_ModuleInstall. The module information files are used for informing CSSM and
applications of the module’s identity and capabilities.

• The sequence of module initialization and verification steps must occur prior to dynamic

binding of the CSP module with CSSM.

Global Unique Identifier (GUID)

Each add-in module is identified by a global unique identifier (GUID). The GUID is needed
when the module is created, installed and used by the CSSM, applications, and any module.
For example, the GUID is used by:

* the CSSM module information files to expose add-in module availability and capabilities to
applications.

Chapter 1 49

Common Data Security Architecture (CDSA) White Paper

Introduction to Add-in Modules

* a module to identify itself when it sets an error.
* an application, to identify the requested module when attaching an add-in module.
For each bundled module, HP provides a GUID in /var/cdsa/cssm. Existing GUIDs and their

associated shared libraries are also specified in cdsa/hpguids.h.
Here is a sample GUID:

String*Location: /usr/lib/libcsp.1
String*Name: CDSA Adaptation Layer CSP for the CSP Toolkit from Co. A
String*Version: 1.2
String*CompatibleCSSMVersion: 1.20
String*Description: CDSA Adaptation Layer CSP for the CSP Toolkit from Co. A
String*Vendor: Hewlett Packard
Binary*Flags: 0
Binary*ServiceMasks: 2
Binary*NumberOfServices: 1

Users can run the HP-UX uuidgen command to generate a GUID for new modules. For an
example showing the creation of a GUID and how to alias it, see “How to Create a CDSA
Add-In Module for HP-UX” on page 53.

Initializer

For each add-in library, an initialization routine is required to be invoked by the system
loader right after the library loads successfully. If the library is a CSP, the initializer performs
integrity checks and prepares for registration with the CSSM.

The initialization routine is also invoked right before the library is unloaded, during which
time it unregisters with CSSM.

The initializer performs two tasks:

• initialization

• termination
The main purpose of initialization is to perform the add-in self-check.
If the add-in module is a CSP, a sequence of self-checking is required. For other types of

add-ins (CL, TP, and DL), the routine can be simpler.

• If self-checking is not required, the initialization functions become null functions.

50 Chapter1

Common Data Security Architecture (CDSA) White Paper

Introduction to Add-in Modules

• If self-checking is required, the initialization function calls the ISL_SelfCheck function.
Fora sample initialization routine, see “How to Create a CDSA Add-In Module for HP-UX” on

page 53.
For detailed information about CSP self-checks,see “Programming Self-Check Functions into

the Initializer” on page 56.

Code to Register Services with CSSM

In order to notify CSSM what capabilities the add-in module can perform, the add-in module
needs to register its services to CSSM. The registration takes place via a routine,
AddInAuthenticate(), which is invoked by CSSM.

Each add-in must implement AddInAuthenticate() to do the following tasks:

• If the add-in module is a CSP, perform integrity verification on CSSM. (This is

unnecessary if the add-in module is a CL, DL or TP.)

• Build and register the function table, which contains function pointers that CSSM can

invoke.

Fordetailed information on what takes place during AddInAuthenticate(), see “Programming
AddInAuthenticate() to Perform Bilateral Authentication” on page 60.

Add-In Module Install Program

An add-in module is not visible to applications until it is installed into the system. The add-in
module install program performs two tasks:

• Move the add-in library into place, in /usr/lib/cdsa.

• Create add-in module information files, by invoking CSSM_ModuleInstall with module

information. The files are stored in /var/cdsa/cssm.

An add-in module becomes unavailable after it is uninstalled from the system. The uninstall
program peforms two tasks:

• Remove the add-in library from /usr/lib/cdsa.

• Remove add-in module information files from /var/cdsa/cssm, by invoking

CSSM_ModuleUninstall.

NOTE You must be a superuser to run the install/uninstall program.

Chapter 1 51

Common Data Security Architecture (CDSA) White Paper

Introduction to Add-in Modules

To Install an Add-In Library

The install operation expects the add-in library to be installed in the same directory.

• Copy your library into the same directory, then execute the program, or

• Modify the code to read it from a different directory.
To uninstall an add-in library, pass in the -u option.
Link the install program source code with /usr/lib/libcssm.1

NOTE Sample source code for an install program may be found in Appendix A,

“Sample Install Program.”

52 Chapter1

Common Data Security Architecture (CDSA) White Paper

How to Create a CDSA Add-In Module for HP-UX

How to Create a CDSA Add-In Module for
HP-UX

This section summarizes the steps involved in creating a CDSA add-in module.
By convention, the CDSA add-in module is named libxxx.1 for the first version of the library,

where xxx is the library’s chosen name. If /usr/lib file system supports only short file names,
limit the library name to 14 characters. The add-in libraries must reside in /usr/lib/cdsa.

1. Create a global unique identifier (GUID) for the add-in module on the system.

On HP-UX, you can use /usr/bin/uuidgen to generate a GUID.

Example:

Issue the following from the command line:
#/usr/bin/uuidgen -s
Output will resemble the following:

= { /* 714ed4ea-15d8-11d2-9be7-0060b0b6e655 */
0x714ed4ea, 0x15d8, 0x11d2, 0x9b, 0xe7,
{ 0x00, 0x60, 0xb0, 0xb6, 0xe6, 0x55 }
}

The “714ed4ea-15d8-11d2-9be7-0060b0b6e655” might be the literal name of the GUID, but
in your source file, you can define it as follows:

CSSM_GUID my_addin_guid =
{ /* 714ed4ea-15d8-11d2-9be7-0060b0b6e655 */
0x714ed4ea, 0x15d8, 0x11d2, {0x9b, 0xe7, 0x00, 0x60, 0xb0, 0xb6, 0xe6,

0x55}
};

Then my_addin_guid can be used whenever a GUID is needed; for example:

• when you register the module to CSSM, pass &my_addin_guid to
CSSM_RegisterServices().

• when you install the module, pass &my_addin_guid to CSSM_ModuleInstall().

• when you attach the module, pass &my_addin_guid to CSSM_ModuleAttach().

Chapter 1 53

Common Data Security Architecture (CDSA) White Paper

How to Create a CDSA Add-In Module for HP-UX

For further conceptual information about GUIDs, see “Global Unique Identifier (GUID)”
on page 49.

2. Define an initializer for each add-in module. The initialization routine is invoked by the
system loader immediately after the shared library loads successfully. It is also invoked
right before the library is unloaded.

NOTE To ensure that initialization routines are named uniquely, HP

recommends the following naming convention:

YourCompanyName_RoutineName_Init()

The initialization routine is specified by the linker option +I when the library is created.
For example:

ld -b -o libmylib.1 +I _MyAddIn_Init ....

In this example, _MyAddIn_Init() becomes your add-in library’s initializer and your add-in
source must contain the _MyAddIn_Init routine.

The following is a skeletal example of an add-in initializer:

void _MyAddIn_Init (shl_t hInstance, int loading)
{
if (loading) { /* perform initialization */
#ifdef ISL_SELF_CHECK
/* self-check code here */
#endif
} else { /* perform termination */
/* un-register services by invoking CSSM_DeregisterServices. */
}
}

As this example shows, _MyAddIn_Init() is invoked with loading == 1, when the library is
loaded (usually when applications invoke CSSM_ModuleAttach).

To perform termination, _MyAddIn_Init() is invoked again with loading == 0, when
applications invoke CSSM_ModuleDetach().

The main purpose of initialization is to perform the add-in self-check. If the add-in module
is a CSP, extensive self-checking is required. For CL, TP, and DL add-ins, the routine is

54 Chapter1

Common Data Security Architecture (CDSA) White Paper

How to Create a CDSA Add-In Module for HP-UX

simpler.
For detailed information on coding the initialization program to perform self-checks, see

“Programming Self-Check Functions into the Initializer” on page 56.
For more conceptual information about initialization, see “Initializer” on page 50.

3. Register services to CSSM by calling AddInAuthenticate().
Every add-in module must implement AddInAuthenticate() to do the following tasks:

• If the add-in is a CSP, perform integrity verification on CSSM. This is not needed if

your add-in is a CL, DL or TP.

• Build the function table, which contains function pointers that CSSM can invoke. Set

unsupported functions to NULL.

• Register the function table to CSSM by invoking a CSSM API

CSSM_RegisterServices().

For detailed information about CSP code requirements, see “Validating the CSP
Credentials” on page 65 and “HP Signing Policy for CSP Add-In Vendors for CDSA
Version 1.2” on page 297.

4. Create an install (or uninstall) program to install (uninstall) the add-in module, to make it
visible to applications.

The install program performs two tasks:

• Move the add-in library to the add-in module directory /usr/lib/cdsa and set the mode to

555.

• Invoke CSSM_ModuleInstall() to create add-in information files for your add-in. The

information files will be in /var/cdsa/cssm and may be queried by applications using the
CSSM_GetModuleInfo function.

An add-in module becomes unavailable after being uninstalled from the system. The
uninstall program performs two tasks:

• Remove the add-in library from /usr/lib/cdsa.

• Invoke CSSM_ModuleUninstall() to remove information files from /var/cdsa/cssm.

Implementing Integrity Checking in Add-In Modules

If you are developing a CSP add-in module, its initialization program must implement
integrity checking, both self-check and bilateral. The following reference will guide you in
this task.

Chapter 1 55

Common Data Security Architecture (CDSA) White Paper

How to Create a CDSA Add-In Module for HP-UX

Programming Self-Check Functions into the Initializer

As soon as a CSP shared library is loaded into computer memory, it should cause one of its
own functions to execute to perform self-checks. The initialization function should call the
ISL_SelfCheck function. (When self checking is not desired, these initialization functions
become null functions.)

Here is the previous example of an initialization function with ISL_SelfCheck invoked:

void _MyAddIn_init( shl_t hInstance, int loading)
{
ISL_VERIFIED_MODULE_PTR VerifiedCLModulePtr = NULL;
if (loading)
{
VerifiedCLModulePtr = ISL_SelfCheck(hInstance);
ISL_RecycleVerifiedModuleCredentials(VerifiedCLModulePtr);
} else { /* perform termination */
/* un-register services by invoking CSSM_DeregisterServices. */
}
}

Observe, the initialization function cannot return a status, since nothing really calls it. It is
simply run by the HP-UX shl_load function after the function loads the shared library.

ISL_SelfCheck ISL_SelfCheck does the following:

• Retrieves self-check credentials from /usr/lib/cdsa/meta-inf.

• Retrieves self-check public key (public key of the entity that signed the credential for the
add-in).

• Verifies the add-in module.

The ISL_SelfCheck function is included in the CSSM shared library. To access it, include the
header file cdsa/eislapi.h in your program.

In addition, other functions must be present in the add-in module. ISL_SelfCheck assumes
the existence of the following functions (whose use will be detailed shortly):

• ISL_RetrieveSelfCheckCredentials

• ISL_RetrieveSelfCheckSectionName

• ISL_RetrieveSelfCheckKey

56 Chapter1

Common Data Security Architecture (CDSA) White Paper

How to Create a CDSA Add-In Module for HP-UX

These functions use another function, GetModulePath (whose source is also shown for
convenience).

All these functions (except ISL_RetrieveSelfCheckKey) are typically put in a file named
callouts.c. After callouts.c is compiled, the objects should be placed in the add-in shared
library.

The ISL_RetrieveSelfCheckKey function is typically placed in a file called public.c. It too
should be compiled, and its object placed in the add-in shared library.

ISL_RetrieveSelfCheckCredentials This function returns the full path name to the
add-in credential file name, located in /usr/lib/cdsa/meta-inf.

void ISL_RetrieveSelfCheckCredentials(struct data *Name)
{
uint32 i;

if ((Name == NULL) || (Name->value == NULL))
return;
i = GetModulePath((char *)Name->value, Name->length);
for (; (Name->value[i] != ‘\\’) && (Name->value[i] != ‘/’); i--)
{
if (i == 0)
return;
}
/* addInManifestFileName might be libsomecsp.dsa */
if (Name->length < (strlen(“meta-inf/”)+strlen(addInManifestFileName)+1))
return;
memcpy(&Name->value[i+1], “meta-inf/”, 9);
memcpy( &Name->value[i+1+9],
addInManifestFileName,
strlen(addInManifestFileName));
Name->value[i+1+9+strlen(addInManifestFileName)+1] = ‘\0’
return;
}

Chapter 1 57

Common Data Security Architecture (CDSA) White Paper

How to Create a CDSA Add-In Module for HP-UX

GetModulePath Returns the path to the add-in shared library. Since all add-ins are placed
in /usr/lib/cdsa; szPath has the form /usr/lib/cdsa/libadd_in_name.1

uint32 GetModulePath(char *szPath, uint32 len)
{
strcpy(szPath,”/usr/lib/cdsa/libadd_in_name.1”);
len = strlen(szPath);
return len;
}

ISL_RetrieveSelfCheckSectionName The credential name has the form
/usr/lib/cdsa/meta-inf/some-add-in.dsa

The section name will be of the form /usr/lib/cdsa/some-add-in.1; that is, the section name is
the name of the shared library we wish to load.

void ISL_RetrieveSelfCheckSectionName(struct data *Name)
{
int i, j, k;

i = Name->length;
while (Name->value[i] != ‘.’ && i >= 0)
i--;
/* i Now points to . before extension */

j = i - 1;
while (Name->value[j] != ‘/’ && i >= 0)
j--;

/* j points to last directory ‘/’ after meta-inf */

k = j - 1;
while (Name->value[k] != ‘/’ && k >= 0)
k--;

58 Chapter1

Common Data Security Architecture (CDSA) White Paper

How to Create a CDSA Add-In Module for HP-UX

/* k points to behind the meta-inf, the 2nd to last ‘/’ */

/* Now change the extension to .1 */

Name->value[i+1] = ‘1’;
Name->value[i+2] = ‘\0’;

/* And move the lib name over the meta-inf which isn’t needed anymore */

k++;
j++;
while ( Name->value[j] != ‘\0’ )
{
Name->value[k] = Name->value[j];
j++;k++;
}
Name->value[k] = ‘\0’;
Name->length = strlen((char *)&Name->value[0]);
return;
}

ISL_RetrieveSelfCheckKey This function returns the public key of the entity that signed
the add-in credential.

To make this function, the add-in provider needs to ask HP to:

• create a DSA public/private key pair for the add-in provider

• 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 file.

void ISL_RetrieveSelfCheckKey(struct data *Name)
{

const unsigned char Key[] = { 0x,......,0x };

Chapter 1 59

Common Data Security Architecture (CDSA) White Paper

How to Create a CDSA Add-In Module for HP-UX

long len = <number of bytes in Key>;

if (!Name || (len > Name->length))
return;
Name->length = len;
memcpy(Name->value, Key, Name->length);
return;
}

Programming AddInAuthenticate() to Perform Bilateral
Authentication

If the Self check is successful, control is returned to the CSSM manager, which will call the
add-in’s AddInAutheticate function. Ironically, the name implies that authentication is going
on. This is not true unless specific code is added to perform bilateral authentication.

If the add-in module does not have to be authenticated, AddInAuthenticate() simply sets up
pointers to functions the add-in module will need to access.

When authentication is desired, AddInAuthenticate() function must do the following:

1. Get the public key of the root CA authority that signed the CSSM module credential.

2. Get the distinguished name of the root CA authority that signed the CSSM module
credential.

3. Call ISL_VerifyLoadedModuleAndCredentials using the public key and distinguished
name retrieved in steps 1 and 2. This step checks the integrity of the CSSM shared
library.

4. Verify that the function that called AddInAuthenticate() comes from the same code verified
in step 3 (that is, that AddInAuthenticate() is being called from the CSSM module).

The ISL_VerifyLoadedModuleCredentials function is included in the CSSM library. To access
it, include the header file cdsa/eislapi.h in your program.

The following functions must also be present in the add-in shared library for
AddInAuthenticate() to perform bilateral authentication:

• ISL_RetrieveRootIssuerKey

• ISL_RetrieveRootIssuerName

Source code for these functions may be obtained directly from HP. Place these functions in the

60 Chapter1

Common Data Security Architecture (CDSA) White Paper

How to Create a CDSA Add-In Module for HP-UX

add-in module’s public.c file. Compile and place the objects in the add-in shared library.
Please contact HP when you have need for these functions.

Sample Code Showing Bilateral Authentication in AddInAuthenticate()

Here is an example of typical code that might be added to an AddInAuthenticate function to
accomplish bilateral authentication:

.
.
.

ISL_VERIFIED_MODULE_PTR VerifiedCLModulePtr = NULL;
ISL_STATUS islret;
void* retAddress;
ISL_CONST_DATA key = {0, NULL};
ISL_CONST_DATA signer = {0, NULL};
CSSM_PROC_ADDR tmp;
int i;
shl_t pImage = NULL;
uint8 work[2][1024];

key.Data = (uint8 *)&work[0];
key.Length = 1024;
signer.Data = (uint8 *)&work[1];
signer.Length = 1024;

pImage = (shl_t)pVerifiedModule->hModule;
pVerifiedModule->Path.Length = 50;
tmp = NULL;

if ((i = shl_findsym( (shl_t *)&pImage,
“ISL_RetrieveRootIssuerKey”,
TYPE_PROCEDURE,
(void *)&tmp ) ) != 0 )

Chapter 1 61

Common Data Security Architecture (CDSA) White Paper

How to Create a CDSA Add-In Module for HP-UX

return CSSM_FAIL;

/* Call function */
((RETRV)tmp)((ISL_CALLOUT_DATA *)&key);

tmp = NULL;
if ((i = shl_findsym( (shl_t *)&pImage,
“ISL_RetrieveRootIssuerName”,
TYPE_PROCEDURE,
(void *)&tmp ) ) != 0 )
return CSSM_FAIL;

/* Call function */
((RETRV)tmp)((ISL_CALLOUT_DATA *)&signer);

VerifiedCSSMModulePtr = ISL_VerifyLoadedModuleAndCredentials(
ConstPathData,
ConstSectionData,
signer,
key);
if(VerifiedCSSMModulePtr == NULL)
return CSSM_FAIL;

/* Make sure CSSM manager really called AddInAuthenticate */

retAddress = (void *)ISL_GetReturnAddress();
islret = ISL_CheckAddressWithinModule( VerifiedCSSMModulePtr, retAddress);
if(islret == ISL_FAIL)
{
ISL_RecycleVerifiedModuleCredentials(VerifiedCSSMModulePtr);

62 Chapter1

Common Data Security Architecture (CDSA) White Paper

How to Create a CDSA Add-In Module for HP-UX

VerifiedCSSMModulePtr = NULL;
return CSSM_FAIL;
}
.

.
.

Completing the Development of a CSP that Performs Integrity
Checking

1. Test your add-in module, using a CSSM manager running in non-authentication mode.
(Such a CSSM manager can be obtained from Hewlett-Packard with a special license
agreement.)

2. Once you are confident the add-in module is functioning properly in non-authentication
mode, re-compile the add-in module with both self-checking and bilateral authentication
enabled. In your link directive to generate the add-in, specify either the following for CSP
add-ins:

+e AddInAuthenticate +e ISL_RetrieveSelfCheckCredentials \
+e ISL_RetrieveSelfCheckSectionName +e ISL_RetrieveSelfCheckKey \
+e ISL_RetrieveRootIssuerKey +e ISL_RetrieveRootIssuerName

or specify the following for CL/TP/DL add-ins:

+e AddInAuthenticate

That is, you want all symbols hidden belonging to the add-in, except for the

AddInAuthenticate function for all types of add-ins, and the
ISL_RetrieveSelfCheckCredentials, ISL_RetrieveSelfCheckSectionName,
ISL_RetrieveSelfCheckKey, ISL_RetrieveRootIssuerKey, and
ISL_RetrieveRootIssuerName functions for CSP add-ins.

3. Produce a credential file for this shared library. To do this, you must use the HP signing
tool, signdll.

Currently HP is unable to release this code to add-in module developers. Instead, HP will
generate the credential file for the add-in developer upon request, using the private key
described in “ISL_RetrieveSelfCheckKey” on page 59.

HP requires that the shared library add-in module be compiled with self-check and
bilateral authentication enabled, and be named as follows:

lib<some_csp_name>.1

4. Once you have the credential for the new add-in module, you are ready to test the module

Chapter 1 63

Common Data Security Architecture (CDSA) White Paper

How to Create a CDSA Add-In Module for HP-UX

with a CSSM capable of integrity checking.

64 Chapter1

Common Data Security Architecture (CDSA) White Paper

Validating the CSP Credentials

Validating the CSP Credentials

Before a CSP add-in module can be loaded by CSSM, CDSA must ensure that the module has
not been tampered with. This is done by performing a series of verifications on the shared
library.

Every CSP add-in module has a corresponding credential file that contains a digitally signed
hash of the CSP shared library. Every time an application uses the CSP, a new SHA-1 hash of
the CSP shared library is calculated and compared with the pre-calculated hash in the shared
library’s corresponding credential file.

CDSA operations proceed only when the pre-calculated hash and the dynamically calculated
hash match exactly and the signature authenticating the pre-calculated hash is verified.

The signature algorithm utilized is DSA, the hash algorithm SHA-1.

The Credential File

The credential file is a ZIP-formatted file containing three uncompressed files:

• .MF file, containing the hash of the shared library and the library name. Also called
manifest file.

• .SF file, containing the hash of data in the .MF file This hash serves to validate the
contents of the .MF file. Also called signature file.

• .DSA file, containing the signer’s DSA signature on the .SF file. The .DSA file also
contains X.509v3 certificates.

.DSA file contents are in a PKCS7 format [4].

For specifications of ZIP format, see “ZIP format” on page 333.

X.509 Certificate Chain

The embedded certificates provide a validation path from the root to the signer’s certificate.
The HP CDSA software has one root public key embedded in its framework. If the X.509

certificate chain cannot be constructed using the embedded key, the credential file cannot be
validated.

The certificate chaining concept is illustrated in Figure 1-8 on page 66. Certificate 1 is signed
with the root private key. Certificate 1 can be verified using the public key in Certificate 0.
Certificate 2 is signed with Certificate 1’s private key and can be verified using Certificate 1’s
public key. Certificate 3 is signed with Certificate 2’s private key and can be verified using

Chapter 1 65

Common Data Security Architecture (CDSA) White Paper

Validating the CSP Credentials

Certificate 2’s public key, and so on.

Figure 1-8 Verifying a Certificate Chain

Certificate 0

Issuer: Root Issuer

Subject: Root Issuer

Root Public Key

Certificate 1

Issuer: Root Issuer

Subject: Issuer A

DSA Signature

Public Key

Certificate 2

Issuer: Issuer A

Subject: Issuer B

DSA Signature

Public Key

Certificate 3

Issuer: Issuer B

Subject: Signer

DSA Signature

The Validation Sequence

The validation process is comprised of three phases:

• Integrity check by the CSSM of the CSP shared library prior to loading

• Self-check of the CSP by itself

Public Key

• Bilateral authentication check of the CSSM by the CSP

NOTE The CSP add-in module is not used in the validation sequence. Instead,

duplicate cryptographic functions for validating DSA signatures and
calculating SHA-1 hashes are embedded in the integrity checking library
of the HP CDSA Framework.

CSP shared libraries are validated in the order they are loaded by the CDSA application user.

66 Chapter1

Common Data Security Architecture (CDSA) White Paper

Validating the CSP Credentials

Integrity Check prior to Loading

The integrity check performed on the CSP prior to loading ensures that the add-in shared
library has not been tampered with before it is loaded. The CSSM performs this check before
loading any CSP add-in module.

1. First, the signature on the signed .SF file is validated. To accomplish this, the CSSM uses
the certificate chain of X.509 certificates embedded in the credential file.

2. If the chain can be validated, the public key of the validated signer’s certificate is used to
verify the signature of the .SF file, as shown in Figure 1-9 on page 67.

Figure 1-9 Verifying the signature on the .SF file

.DSA file,

containing

signer's DSA

signature

DSA

Signer's

Verify

public key

.SF file,

containing hash

of data in .MF file

3. After the signature of the .SF file is validated, a SHA-1 hash of the section in the .MF file
referring to the shared library to be loaded is calculated and compared with the hash in
the .SF file. This is shown in Figure 1-10.

Did the

Signature

verify?

Yes

.SF file was

created by Signer

No

.SF file was created

by unknown entity.

STOP!

Chapter 1 67

Common Data Security Architecture (CDSA) White Paper

Validating the CSP Credentials

Figure 1-10 Verifying the authenticity of data in the .MF file

.SF file, containing hash

of data in .MF file

.MF file,

containing

hash of

shared library

and library

name

SHA-1

HASH

function

Are
SHA-1
hashes

equal?

Yes

No

.MF or .SF file

has been

tampered with.

STOP!

Proceed to verify hash

of shared library

4. If these hashes match, a hash of the shared library to be loaded is calculated. The hash is
then compared to the pre-calculated value in the .MF file, as shown in Figure 1-11 on page

69.

68 Chapter1

Common Data Security Architecture (CDSA) White Paper

Validating the CSP Credentials

Figure 1-11 Verifying the validity of the CSP library

.MF file, containing hash of

shared library and library name

.CSP shared

library has been

tampered with.

STOP!

CSP file

SHA-1

HASH

function

Are

SHA-1

hashes

equal?

No

Yes

CSP shared library is valid

5. If the values match, the shared library is loaded. If the hashes do not match, CDSA
execution will terminate.

The Self Check

Once an HP-UX shared library is loaded, it is initialized. Then control is returned to the
function that initiated loading of the shared library.

In the self check, the CSP add-in module that has just been loaded checks itself, to make sure
it has not been tampered with.

1. The signer’s public key is extracted from the CSP shared library and used to directly verify
the signature on .SF file. No chaining validation is necessary.

2. After the signature is validated, the SHA-1 hash of the section in the .MF file referring to
the shared library just loaded is calculated and compared with the hash in the .SF file.

3. If these hashes match, a hash of the CSP shared library is calculated and compared to the
hash in the .MF file.

4. If the hash matches (indicating the .MF file has not been tampered with), control is
returned back to the function which initiated loading of the shared library.

Chapter 1 69

Common Data Security Architecture (CDSA) White Paper

Validating the CSP Credentials

Bilateral Authentication

In the final set of integrity checks, known as bilateral authentication, the CSP add-in module
checks the integrity of the CSSM manager that requested the CSP’s loading to ensure the
CSSM has not been tampered with.

1. The CSP reconstructs the certificate chain from the root public key embedded in the CSP
shared library to the CSSM signer’s certificate, using the certificates embedded in the
credential file.

2. Once the certificate chain is verified, the signature in the .DSA file is verified, using the
public key of the last certificate in the chain (that is, the CSSM signer’s certificate).

3. An SHA-1 hash is calculated of the CSSM section in the .MF file and compared to the hash
in the .SF file.

4. If the hashes match, an SHA-1 hash of the CSSM shared lbrary is calculated and
compared to the hash n the .MF file.

5. If the hash matches, the CSP looks for the function that called the bilateral authentication
function (AddInAuthenticate()) and verifies that the function was called by the CSSM
shared library.

After this is done, the integrity checks for the loaded shared library are complete. At this
point, another add-in can be loaded and verified, if necessary.

In-Memory vs. Static Checking

A difference exists in the way NT and HP-UX ensures the integrity of processes in memory.
In the original Intel CDSA Framework, which operates on the Windows NT operating system,

hash evaluations are made of loaded shared libraries (called DLLs in NT) that are in
computer memory. These in-memory checks are necessary because the NT operating system
does not protect running processes from tampering. By contrast, once an HP-UX process is
running, it can be accessed only by the user who owns that process or the superuser. Thus,
in-memory checks are not performed in the HP CDSA Framework.

70 Chapter1

Common Data Security Architecture (CDSA) White Paper

Concluding Remarks

Concluding Remarks

CDSA is a powerful, flexible modular infrastructre for safeguarding information. However,as
with all things powerful, CDSA requires extensive knowledge to take full advantage of its
capabilities. Currently, application developers may need expertise in both cryptography and
the details of Internet security protocols (SSL, S/MIME, etc). CDSA, in conjunction with
higher-level protocols, provides a solid, interoperable framework on which to develop secure
applications.

Further References

Intel Corporation, “Common Data Security Architecture Specification, Version 1.2,” March
1997, http://www.intel.com/ial/security/specs_1_2.htm.

Intel Corporation, “Common Security Services Manager, Version 1.2,” March 1997,
http://www.intel.com/ial/security/specs_1_2.htm.

RSA DAta Security Inc., PKCS #7, Cryptographic Message Syntax Standard, November 1,
1993, ftp://www.rsa.com/pub/pkcs/ascii/pkcs-7.asc

Menezes, A.J.; van Oorschot, P.C; Vanstone, S.A. Handbook of Applied Cryptography, CRC
Press LLC, 1997. ISBN 0-8493-8523-7.

Schneier, Bruce. Applied Cryptography: Protocols, Algorithms, and Source Code in C, second
edition, New York: John Wiley and Sons, Inc., 1996. 0-471-12845-7.

Chapter 1 71

Common Data Security Architecture (CDSA) White Paper

Concluding Remarks

72 Chapter1

Sample Install Program

A Sample Install Program

Copyright (C) 1998 The Hewlett Packard Corporation. All rights reserved.
This file is used as an example of how to write an application program that installs or

uninstalls a CDSA add-in module.
Hewlett Packard Company (“HP”) grants you a non-exclusive, royalty-free license to use, copy,

modify and distribute this source file solely for the purpose of developing application
programs that utilize HP CDSA.

This source file is licensed “as is.” No warranty, express or implied, statutory or otherwise, as
to the condition, quality, durability, performance, non-infringement, merchantability, or
fitness for a particular purpose or use of this source file is given or assumed by HP or its
agents and all such warranties are hereby excluded. HP and its agents shall in no event be
liable for any damages (including, without limitation, any direct, indirect, incidental, or
consequential damages, lost profits, lost savings or, to the extent allowed by applicable law,
damages resulting from death or injury of licensee or anyone else) arising out of or in
connection with the use, improper use, or inability to use this source file, even if HP has been
advised of the possibility of such damages.

/*************************************************************************
* To install an add-in: the install operation expects the add-in library to
* be installed is in the same directory. You have to copy your library
* into the same directory, then execute the program, or you modify
* the code to read it from a different directory.
*
* To un-install an add-in: pass in the option “-u”.
* Note: you need to link this source code with /usr/lib/libcssm.1.
*************************************************************************/

/* CSSM includes */
#include <cdsa/cssm.h>

Appendix A 73

Sample Install Program

/* OS-specific includes */

#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <unistd.h>
#include <sys/stat.h>

#define PATH_LEN 256
#define DL_LIB “libdummydl.1”
#define DEST_PATH “/usr/lib/cdsa”
#define TARGET_NAME “/usr/lib/cdsa/libdummydl.1”
#define DUMMY_DL_MAJOR_VER 1
#define DUMMY_DL_MINOR_VER 2

static CSSM_GUID my_addin_guid =
{ /* 714ed4ea-15d8-11d2-9be7-0060b0b6e655 */
0x714ed4ea, 0x15d8, 0x11d2, {0x9b, 0xe7, 0x00, 0x60, 0xb0, 0xb6, 0xe6, 0x55}
};

/* Memory Funcs */
#if defined(__STDC__ ) || defined(__cplusplus)
void* ex_malloc(uint32 size,void *ref) {
return malloc(size);
}

void ex_free(void *block,void *ref) {
free(block);
}

74 AppendixA

void* ex_realloc(void *block,uint32 size,void *ref) {
return realloc(block,size);
}

void* ex_calloc(uint32 count,uint32 size,void *ref) {
return calloc(count,size);
}

CSSM_RETURN uninstall_addin(int cleanup);
#else
void* ex_malloc(size, ref)
uint32 size; void *ref;
{
return malloc(size);
}

Sample Install Program

void ex_free(block, ref)
void *block; void *ref;
{
free(block);
}

void* ex_realloc(block, size, ref)
void *block;uint32 size;void *ref;
{
return realloc(block,size);
}

void* ex_calloc(count,size, ref)
uint32 count;uint32 size;void *ref;

Appendix A 75

Sample Install Program

{
return calloc(count,size);
}

CSSM_RETURN uninstall_addin();
#endif

CSSM_API_MEMORY_FUNCS
DBMemoryFunctions = { ex_malloc, ex_free, ex_realloc, ex_calloc };

void main(argc, argv)
int argc; char* argv[];

{
CSSM_VERSION cssm_version;
CSSM_VERSION dl_version;
CSSM_VERSION ex_version;
CSSM_VERSION access_version;
CSSM_DL_WRAPPEDPRODUCT_INFO access_desc;
CSSM_DLSUBSERVICE sub_service;
CSSM_SERVICE_INFO service_info;
CSSM_MODULE_INFO module_info;
CSSM_ERROR_PTR error_ptr = NULL;
char cpcmd[PATH_LEN];
CSSM_RETURN result;

/* check super-user capability */
if (getuid() != 0) {

printf(“Super-user capability is required to install/uninstall a CDSA add-in

module.\n”);

76 AppendixA

Sample Install Program

exit (1);
}

/* variable initialization */
cssm_version.Major = CSSM_MAJOR;
cssm_version.Minor = CSSM_MINOR;
dl_version.Major = DUMMY_DL_MAJOR_VER;
dl_version.Minor = DUMMY_DL_MINOR_VER;
ex_version.Major = 1;
ex_version.Minor = 2;
access_version.Major = 2;
access_version.Minor = 0;

/* initialize CSSM */
if( CSSM_Init(&cssm_version, &DBMemoryFunctions, NULL) != CSSM_OK )
{
error_ptr = CSSM_GetError();
printf(“Failed at CSSM_Init, error = %d\n”, error_ptr->error);
exit (1);
}

if (argc == 2) {
if (strcmp(argv[1], “-u”) == 0) {
result = uninstall_addin(0);
exit (result);
} else {
printf(“Usage: dummy_install [-u]\n”);
printf(“ -u: uninstall the add-in\n”);
exit (1);
}

Appendix A 77

Sample Install Program

} else if (argc != 1) {
printf(“Usage: dummy_install [-u]\n”);
printf(“ -u: uninstall the add-in\n”);
exit (1);
}

/* Fill the Access product info */
access_desc.StandardVersion = dl_version;
strcpy(access_desc.StandardDescription, “DUMMY”);
access_desc.ProductVersion = access_version;
strcpy(access_desc.ProductDescription, “Dummy”);
strcpy(access_desc.ProductVendor, “HP”);
access_desc.ProductFlags = 0;

/* fill sub-service information */
sub_service.SubServiceId = 0;
strcpy(sub_service.Description, “Dummy DLM”);
sub_service.Type = CSSM_DL_CUSTOM;
sub_service.Attributes.OdbcAttributes = NULL;
sub_service.WrappedProduct = access_desc;
sub_service.AuthenticationMechanism = CSSM_AUTHENTICATION_NONE;
sub_service.NumberOfRelOperatorTypes = 1;
sub_service.RelOperatorTypes = 0;
sub_service.NumberOfConjOperatorTypes = 1;
sub_service.ConjOperatorTypes = 0;
sub_service.QueryLimitsSupported = CSSM_FALSE;
sub_service.NumberOfDataStores = 0;
sub_service.DataStoreNames = NULL;
sub_service.DataStoreInfo = NULL;
sub_service.Reserved = NULL;

78 AppendixA

/* fill service information */
strcpy(service_info.Description, “Dummy DL Module”);
service_info.Type = CSSM_SERVICE_DL;
service_info.Flags = 0;
service_info.NumberOfSubServices = 1;
service_info.SUBSVR.DlSubServiceList = &sub_service;
service_info.Reserved = NULL;

/* fill module information */
module_info.Version = dl_version;
module_info.CompatibleCSSMVersion = cssm_version;
strcpy(module_info.Description, “HP Dummy DL Module”);
strcpy(module_info.Vendor, “HP example”);
module_info.Flags = CSSM_MODULE_EXPORTABLE;

Sample Install Program

module_info.ServiceMask = CSSM_SERVICE_DL;
module_info.NumberOfServices = 1;
module_info.ServiceList = &service_info;
module_info.Reserved = NULL;

/* Install the module */
if ( CSSM_ModuleInstall( “HP Dummy Data Storage Module”,
DL_LIB,
DEST_PATH,
&my_addin_guid,
&module_info,
NULL,
NULL) )
{
error_ptr = CSSM_GetError();

Appendix A 79

Sample Install Program

if (error_ptr->error == CSSM_GUID_BEEN_INSTALLED)
printf(“The add-in/GUID has been installed arleady.\n”);
else {
printf(“Failed at CSSM_ModuleInstall, error = %d\n”, error_ptr->error);
printf(“Check <cdsa/cssmerr.h> for the error.\n”);
}
exit(1);
}

/* copy library to /usr/lib/cdsa */
memset(cpcmd, 0, PATH_LEN);
(void) sprintf(&cpcmd[0], “cp %s %s”, DL_LIB, TARGET_NAME);
if (system(cpcmd) != 0) {
printf(“Failed to copy library image to /usr/lib/cdsa\n”);
uninstall_addin(1);
exit (1);
}

if (chmod (TARGET_NAME, S_IRUSR|S_IXUSR|S_IRGRP|S_IXGRP|S_IROTH|S_IXOTH) != 0)

{
printf(“Failed to change library mode.\n”);
uninstall_addin(1);
exit (1);
}

printf(“The add-in module has been installed successfully.\n”);

exit( 0 );
}

CSSM_RETURN uninstall_addin(cleanup)

80 AppendixA

Sample Install Program

int cleanup;
{
CSSM_ERROR_PTR error_ptr;

if (CSSM_ModuleUninstall(&my_addin_guid) != CSSM_OK) {
if (!cleanup) {
error_ptr = CSSM_GetError();
if (error_ptr->error == CSSM_GUID_NOT_INSTALLED)
printf(“This add-in/GUID has not been installed yet.\n”);
else {
printf(“Failed to uninstall the add-in library, error = %d\n”,

error_ptr->error);
printf(“Check <cdsa/cssmerr.h> for the error.\n”);
}
}
return(CSSM_FAIL);
}

if (!cleanup) {
remove(TARGET_NAME);
printf(“The add-in has been uninstalled successfully.\n”);
}
return (CSSM_OK);
}

Appendix A 81

Sample Install Program

82 AppendixA

Generating the Credential File

B Generating the Credential File

Every CSP module requires a credential file that which must be generated using a secure
software program, called signdll, before the CSP can be accessed by applications using the
CDSA framework. signdll is not distributed to customers, but is retained by HP “in-house.”

However, if an HP customer wishes to produce and market an add-in CSP module for the HP
CDSA product, HP will allow that customer to use the signing tool at an HP facility to
generate an appropriate credential file, provided they meet the criteria stipulated in “HP
Signing Policy for CSP Add-In Vendors for CDSA Version 1.2.”

Appendix B 83

Generating the Credential File

HP Signing Policy for CSP Add-In Vendors for CDSA Version 1.2

HP Signing Policy for CSP Add-In Vendors for
CDSA Version 1.2

1. The vendor,whether a company incorporated in the United States or not, is responsible for
obtaining a license from the Intel Corporation to gain access to the CDSA Software.

2. If the vendor is a company incorporated in the United States and will sign legally binding
documents indicating the CSP add-in will be for North America (Canada and the United
States) use only, HP will sign the company’s X.509 identity certificate and allow the vendor
to use the signdll signing tool at a designated HP facility, to actually sign the CSP.

3. If the vendor is a company incorporated in the United States and indicates the CSP add-in
module will be for world export, the vendor must first submit evidence of U.S. State
Department approval for export of its CSP. Upon review and acceptance of the evidence,
HP will sign the company’s X.509 identity certificate and allow the vendor to use the
signdll signing tool at a designated HP facility, to actually sign the CSP.

HP may require other general legally binding documents to be signed for vendors in 2 and
3 above, including:

a. Declarations the vendor will follow United States law in any export of the CSP.
b. The vendor represents that it is responsible for its CSP. That is, that the vendor is

responsible for all shipments out of North America and for complying with all United
States regulations. The vendor is responsible for acquiring any required licenses.

4. Appropriate protocol will have to be determined for non-United States corporations in
relation to their CSP products for North America and the rest of the world.

84 AppendixB

Sample Add-in Module Code

C Sample Add-in Module Code

Copyright (C) 1998 The Hewlett Packard Corporation. All rights reserved.
This file is used as an example of how to write an add-in service module for the Hewlett

Packard Common Data Security Architecture (HP CDSA). This file just shows you the
framework of creating a Data Storage Library (DL) and doesn’t perform any real operations.
This framework can also be used to create a Certificate Library (CL) or Trust Policy Library
(TP).

Hewlett PackardCompany (“HP”) grants you a non-exclusive, royalty free license to use, copy,
modify and distribute this source file solely for the purpose of developing application
programs that utilize HP CDSA. THIS SOURCE FILE IS LICENSED “AS IS.” NO
WARRANTY, EXPRESS OR IMPLIED, STATUTORY OR OTHERWISE, AS TO THE
CONDITION, QUALITY, DURABILITY, PERFORMANCE, NON-INFRINGEMENT,
MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE OR USE OF THIS
SOURCE FILE IS GIVEN OR ASSUMED BY HP OR ITS AGENTS AND ALL SUCH
WARRANTIES ARE HEREBY EXCLUDED. HP AND ITS AGENTS SHALL IN NO EVENT
BE LIABLE FOR ANY DAMAGES (INCLUDING, WITHOUT LIMITATION, ANY DIRECT,
INDIRECT, INCIDENTAL, OR CONSEQUENTIAL DAMAGES, LOST PROFITS, LOST
SAVINGS OR, TO THE EXTENT ALLOWED BY APPLICABLE LAW, DAMAGES
RESULTING FROM DEATH OR INJURY OF LICENSEE OR ANYONE ELSE) ARISING
OUT OF OR IN CONNECTION WITH THE USE, IMPROPER USE, OR INABILITY TO USE
THIS SOURCE FILE, EVEN IF HP HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH
DAMAGES.

/* CSSM includes */
#include <dl.h>
#include <cdsa/cssm.h>
#include <cdsa/cssmspi.h>
#include <stdio.h>

/* define prototype for add-in functions */

#ifdef __cplusplus
extern “C” {

Appendix C 85

Sample Add-in Module Code

#endif

#if defined(__STDC__) || defined(__cplusplus)

CSSM_DB_HANDLE DL_DbOpen (
CSSM_DL_HANDLE DLHandle,
const char *DbName,
const CSSM_DB_ACCESS_TYPE_PTR AccessRequest,
const CSSM_USER_AUTHENTICATION_PTR UserAuthentication,
const void *OpenParameters);

CSSM_RETURN DL_DbClose (CSSM_DL_DB_HANDLE DLDBHandle);

CSSM_DB_HANDLE DL_DbCreate (
CSSM_DL_HANDLE DLHandle,
const char *DbName,
const CSSM_DBINFO_PTR DbInfo,
const CSSM_DB_ACCESS_TYPE_PTR AccessRequest,
const CSSM_USER_AUTHENTICATION_PTR UserAuthentication,
const void *OpenParameters);

CSSM_RETURN DL_DbDelete (
CSSM_DL_HANDLE DLHandle,
const char *DbName,
const CSSM_USER_AUTHENTICATION_PTR UserAuthentication);

char * DL_GetDbNameFromHandle (CSSM_DL_DB_HANDLE DLDBHandle);

CSSM_DB_UNIQUE_RECORD_PTR DL_DataInsert (

86 AppendixC

Sample Add-in Module Code

CSSM_DL_DB_HANDLE DLDBHandle,
const CSSM_DB_RECORDTYPE RecordType,
const CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,
const CSSM_DATA_PTR Data);

CSSM_RETURN DL_DataDelete (
CSSM_DL_DB_HANDLE DLDBHandle,
CSSM_DB_RECORDTYPE RecordType,
const CSSM_DB_UNIQUE_RECORD_PTR UniqueRecordIdentifier);

CSSM_DB_UNIQUE_RECORD_PTR DL_DataGetFirst (
CSSM_DL_DB_HANDLE DLDBHandle,
const CSSM_QUERY_PTR Query,
CSSM_HANDLE_PTR ResultsHandle,
CSSM_BOOL *EndOfDataStore,
CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,
CSSM_DATA_PTR Data);

CSSM_DB_UNIQUE_RECORD_PTR DL_DataGetNext (
CSSM_DL_DB_HANDLE DLDBHandle,
CSSM_HANDLE ResultsHandle,
CSSM_BOOL *EndOfDataStore,
CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes,
CSSM_DATA_PTR Data);

CSSM_RETURN DL_FreeUniqueRecord (
CSSM_DL_DB_HANDLE DLDBHandle,
CSSM_DB_UNIQUE_RECORD_PTR UniqueRecord);

CSSM_RETURN DL_DataAbortQuery (

Appendix C 87

Sample Add-in Module Code

CSSM_DL_DB_HANDLE DLDBHandle,
CSSM_HANDLE ResultsHandle);

CSSM_RETURN DL_Initialize (
CSSM_MODULE_HANDLE AppHandle,
uint32 VerMajor,
uint32 VerMinor);

CSSM_RETURN DL_Uninitialize (
CSSM_MODULE_HANDLE AppHandle);

CSSM_RETURN DL_Authenticate (CSSM_DL_DB_HANDLE DLDBHandle,
const CSSM_DB_ACCESS_TYPE_PTR AccessRequest,
const CSSM_USER_AUTHENTICATION_PTR UserAuthentication);

CSSM_RETURN DL_DbImport (CSSM_DL_HANDLE DLDBHandle,
const char *DbDestinationName,
const char *DbSourceName,
const CSSM_DBINFO_PTR DBInfo,
CSSM_BOOL InfoOnly,
const CSSM_USER_AUTHENTICATION_PTR UserAuthentication);

CSSM_RETURN DL_DbExport (CSSM_DL_HANDLE DLDBHandle,
const char *DbDestinationName,
const char *DbSourceName,
CSSM_BOOL InfoOnly,
const CSSM_USER_AUTHENTICATION_PTR UserAuthentication);

CSSM_RETURN DL_DbSetRecordParsingFunctions (CSSM_DL_HANDLE DLHandle,
const char* DbName,

88 AppendixC

Sample Add-in Module Code

CSSM_DB_RECORDTYPE RecordType,
const CSSM_DB_RECORD_PARSING_FNTABLE_PTR FunctionTable);

CSSM_DB_RECORD_PARSING_FNTABLE_PTR DL_DbGetRecordParsingFunctions
(CSSM_DL_HANDLE DLHandle,

const char* DbName,
CSSM_DB_RECORDTYPE RecordType);

void * DL_PassThrough (CSSM_DL_DB_HANDLE DLHandle,
uint32 PassThroughId,
const void * InputParams);
/* CSSM Wrapper functions */
CSSM_RETURN dl_RegisterServices ();
CSSM_RETURN dl_DeregisterServices ();

CSSM_RETURN dl_SetError (uint32 error);

void _MyAddIn_Init (shl_t hInstance, int loading);
CSSM_RETURN AddInAuthenticate(char* cssmCredentialPath, char* cssmSection);
CSSM_RETURN dl_GetCSSMFunctionPointer (char *FunctionName,
void **FunctionPtr);
#else
#define const
CSSM_DB_HANDLE DL_DbOpen ();
CSSM_RETURN DL_DbClose ();
CSSM_DB_HANDLE DL_DbCreate ();
CSSM_RETURN DL_DbDelete ();
char * DL_GetDbNameFromHandle ();
CSSM_DB_UNIQUE_RECORD_PTR DL_DataInsert ();
CSSM_RETURN DL_DataDelete ();

Appendix C 89

Sample Add-in Module Code

CSSM_DB_UNIQUE_RECORD_PTR DL_DataGetFirst ();
CSSM_DB_UNIQUE_RECORD_PTR DL_DataGetNext ();
CSSM_RETURN DL_FreeUniqueRecord ();
CSSM_RETURN DL_DataAbortQuery ();
CSSM_RETURN DL_Initialize ();
CSSM_RETURN DL_Uninitialize ();
CSSM_RETURN DL_Authenticate ();
CSSM_RETURN DL_DbImport ();
CSSM_RETURN DL_DbExport ();
CSSM_RETURN DL_DbSetRecordParsingFunctions ();
CSSM_DB_RECORD_PARSING_FNTABLE_PTR DL_DbGetRecordParsingFunctions ();
void * DL_PassThrough ();
/* CSSM Wrapper functions */
CSSM_RETURN dl_RegisterServices ();
CSSM_RETURN dl_DeregisterServices ();
CSSM_RETURN dl_SetError ();
void _MyAddIn_Init ();
CSSM_RETURN AddInAuthenticate();
CSSM_RETURN dl_GetCSSMFunctionPointer ();
#endif
#ifdef __cplusplus
}
#endif

#define MY_ADDIN_MAJOR_VER 1
#define MY_ADDIN_MINOR_VER 2

shl_t g_cssmHandle;

CSSM_SPI_MEMORY_FUNCS DLMemoryFunctions;

90 AppendixC

Sample Add-in Module Code

typedef void * FUNC_PTR;

#if defined(__STDC__) || defined(__cplusplus)
typedef CSSM_RETURN (*REGISTER_FUNC_PTR) (
const CSSM_GUID_PTR GUID,
const CSSM_REGISTRATION_INFO_PTR FunctionTable,
CSSM_SPI_MEMORY_FUNCS_PTR UpcallTable,
void *Reserved);
typedef CSSM_RETURN (*DE_REGISTER_FUNC_PTR) (const CSSM_GUID_PTR GUID);
typedef CSSM_RETURN (*SET_ERROR_FUNC_PTR) (CSSM_GUID_PTR guid, uint32 error);
#else
typedef CSSM_RETURN (*REGISTER_FUNC_PTR) ();
typedef CSSM_RETURN (*DE_REGISTER_FUNC_PTR) ();
typedef CSSM_RETURN (*SET_ERROR_FUNC_PTR) ();
#endif

static void * cssmRegister = NULL;
static void * cssmDeregister = NULL;
static void * cssmSetError = NULL;

static CSSM_GUID my_addin_guid =
{ /* 714ed4ea-15d8-11d2-9be7-0060b0b6e655 */
0x714ed4ea, 0x15d8, 0x11d2, {0x9b, 0xe7, 0x00, 0x60, 0xb0, 0xb6, 0xe6, 0x55}
};

/*---------------------------------------------------------------------------­ * Name: _MyAddIn_Init
* This is the add-in initializer. When the library is loaded, “loading” is 1,
* when the library is unloaded, “loading” is 0.

Appendix C 91

Sample Add-in Module Code

*
*---------------------------------------------------------------------------*/

void _MyAddIn_Init(hInstance, loading)
shl_t hInstance;
int loading;
{

if (loading) {
}
else {
dl_DeregisterServices();
}
}

/*-------------------------------------------------------------------------­ * Name: dl_GetCSSMFunctionPointer

-------------------------------------------------------------------------- */

CSSM_RETURN dl_GetCSSMFunctionPointer (FunctionName,
FunctionPtr)
char *FunctionName;
void **FunctionPtr;
{
void *tmp;

shl_findsym(&g_cssmHandle, FunctionName, TYPE_PROCEDURE, (void *) &tmp);
*FunctionPtr = tmp;
if (*FunctionPtr)
return CSSM_OK;

92 AppendixC

Sample Add-in Module Code

else
return CSSM_FAIL;
}

/*----------------------------------------------------------------------------­ * Name: AddInAuthenticate
*---------------------------------------------------------------------------*/
CSSM_RETURN AddInAuthenticate(cssmCredentialPath, cssmSection)
char* cssmCredentialPath;
char* cssmSection;
{

/* if your add-in is CSP, the code needs to perform integrity checking here.

*/

g_cssmHandle = shl_load(cssmSection, BIND_DEFERRED, 0L);

/* Load any required CSSM functions */
if (dl_GetCSSMFunctionPointer(“CSSM_RegisterServices”, (void **)

&cssmRegister) == CSSM_FAIL ||

dl_GetCSSMFunctionPointer(“CSSM_SetError”, (void **) &cssmSetError) ==

CSSM_FAIL ||
dl_GetCSSMFunctionPointer(“CSSM_DeregisterServices”,(void **)

&cssmDeregister) == CSSM_FAIL
)
{
return CSSM_FAIL;
}

/* Register the DL function table with the authenticated CSSM */

Appendix C 93

Sample Add-in Module Code

return dl_RegisterServices();
}

/*----------------------------------------------------------------------------­ * Name: dl_RegisterServices
*---------------------------------------------------------------------------*/
CSSM_RETURN dl_RegisterServices ()
{
CSSM_REGISTRATION_INFO DLRegInfo;
CSSM_MODULE_FUNCS Services;
CSSM_SPI_DL_FUNCS DLFunctionTable;

/* Fill in Registration information */
DLRegInfo.Initialize = DL_Initialize;
DLRegInfo.Terminate = DL_Uninitialize;
DLRegInfo.EventNotify = NULL;
DLRegInfo.GetModuleInfo = NULL;
DLRegInfo.FreeModuleInfo = NULL;
DLRegInfo.ThreadSafe = CSSM_TRUE;
DLRegInfo.ServiceSummary = CSSM_SERVICE_DL;
DLRegInfo.NumberOfServiceTables = 1;
DLRegInfo.Services = &Services;

/* Fill in Services */
Services.ServiceType = CSSM_SERVICE_DL;
Services.FUNCS.DlFuncs = &DLFunctionTable;

/* Fill in Function Table */

94 AppendixC

Sample Add-in Module Code

DLFunctionTable.Authenticate = DL_Authenticate;
DLFunctionTable.DbOpen = DL_DbOpen;
DLFunctionTable.DbClose = DL_DbClose;
DLFunctionTable.DbCreate = DL_DbCreate;
DLFunctionTable.DbDelete = DL_DbDelete;
DLFunctionTable.DbImport = DL_DbImport;
DLFunctionTable.DbExport = DL_DbExport;
DLFunctionTable.DbSetRecordParsingFunctions =

DL_DbSetRecordParsingFunctions;
DLFunctionTable.DbGetRecordParsingFunctions =

DL_DbGetRecordParsingFunctions;
DLFunctionTable.GetDbNameFromHandle = DL_GetDbNameFromHandle;
DLFunctionTable.DataInsert = DL_DataInsert;
DLFunctionTable.DataDelete = DL_DataDelete;
DLFunctionTable.DataGetFirst = DL_DataGetFirst;
DLFunctionTable.DataGetNext = DL_DataGetNext;
DLFunctionTable.DataAbortQuery = DL_DataAbortQuery;
DLFunctionTable.FreeUniqueRecord = DL_FreeUniqueRecord;
DLFunctionTable.PassThrough = DL_PassThrough;

/* Register with CSSM and retrieve memory management function pointers */
return ((REGISTER_FUNC_PTR)cssmRegister)(&my_addin_guid, &DLRegInfo,

&DLMemoryFunctions, NULL);
}

CSSM_RETURN dl_DeregisterServices ()
{ return ((DE_REGISTER_FUNC_PTR)cssmDeregister)(&my_addin_guid); }

/*----------------------------------------------------------------------------­ * Name: DL_Initialize

Appendix C 95

Sample Add-in Module Code

*---------------------------------------------------------------------------*/
CSSM_RETURN DL_Initialize(AppHandle, VerMajor, VerMinor)
CSSM_MODULE_HANDLE AppHandle;
uint32 VerMajor;
uint32 VerMinor;
{
CSSM_API_MEMORY_FUNCS_PTR AppMemFuncs = NULL;

/* Verify that this module is compatible with the requested version */
if( VerMajor != MY_ADDIN_MAJOR_VER || VerMinor != MY_ADDIN_MINOR_VER )
{
dl_SetError(CSSM_DL_INCOMPATIBLE_VERSION);
return CSSM_FAIL;
}

return CSSM_OK;
}

/*----------------------------------------------------------------------------­ * Name: DL_Uninitialize
*---------------------------------------------------------------------------*/
CSSM_RETURN DL_Uninitialize(AppHandle)
CSSM_MODULE_HANDLE AppHandle;
{

return CSSM_OK;

}

/*---------------------------------------------------------------------------*/

96 AppendixC

Sample Add-in Module Code

CSSM_RETURN dl_SetError (error)
uint32 error;
{ return ((SET_ERROR_FUNC_PTR)cssmSetError)(&my_addin_guid, error); }

/*---------------------------------------------------------------------------*/
CSSM_DB_HANDLE DL_DbOpen (
DLHandle, DbName, AccessRequest, UserAuthentication,
OpenParameters)

CSSM_DL_HANDLE DLHandle;
const char *DbName;
const CSSM_DB_ACCESS_TYPE_PTR AccessRequest;
const CSSM_USER_AUTHENTICATION_PTR UserAuthentication;
const void *OpenParameters;
{
printf(“in DL_DbOpen\n”);
return (NULL);
}
/*---------------------------------------------------------------------------*/

CSSM_RETURN DL_DbClose (DLDBHandle)
CSSM_DL_DB_HANDLE DLDBHandle;
{
printf(“in DL_DbClose\n”);
return CSSM_OK;

} /* End of DL_DbClose */

/*---------------------------------------------------------------------------*/

Appendix C 97

Sample Add-in Module Code

CSSM_DB_HANDLE DL_DbCreate (DLHandle, DbName, DbInfo, AccessRequest,
UserAuthentication, OpenParameters)
CSSM_DL_HANDLE DLHandle;
const char *DbName;
const CSSM_DBINFO_PTR DbInfo;
const CSSM_DB_ACCESS_TYPE_PTR AccessRequest;
const CSSM_USER_AUTHENTICATION_PTR UserAuthentication;
const void *OpenParameters;
{
printf(“in DL_DbCreate\n”);
return( NULL );
}

/*---------------------------------------------------------------------------*/
CSSM_RETURN DL_DbDelete (DLHandle, DbName, UserAuthentication)
CSSM_DL_HANDLE DLHandle;
const char *DbName;
const CSSM_USER_AUTHENTICATION_PTR UserAuthentication;
{
printf(“in DL_DbDelete\n”);
return CSSM_OK;
}

/*---------------------------------------------------------------------------*/
char * DL_GetDbNameFromHandle (DLDBHandle)
CSSM_DL_DB_HANDLE DLDBHandle;
{
printf(“in DL_GetDbNameFromHandle\n”);
return NULL;

98 AppendixC

Sample Add-in Module Code

}

/*---------------------------------------------------------------------------*/
CSSM_DB_UNIQUE_RECORD_PTR DL_DataInsert (DLDBHandle, RecordType, Attributes,
Data)
CSSM_DL_DB_HANDLE DLDBHandle;
const CSSM_DB_RECORDTYPE RecordType;
const CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes;
const CSSM_DATA_PTR Data;
{
printf(“in DL_DataInsert\n”);
return NULL;
}

/*---------------------------------------------------------------------------*/
CSSM_RETURN DL_DataDelete (DLDBHandle, RecordType, UniqueRecordIdentifier)
CSSM_DL_DB_HANDLE DLDBHandle;
CSSM_DB_RECORDTYPE RecordType;
const CSSM_DB_UNIQUE_RECORD_PTR UniqueRecordIdentifier;
{
printf(“in DL_DataDelete\n”);
return CSSM_OK;
}

/*---------------------------------------------------------------------------*/
CSSM_DB_UNIQUE_RECORD_PTR DL_DataGetFirst (DLDBHandle, Query, ResultsHandle,
EndOfDataStore, Attributes, Data)
CSSM_DL_DB_HANDLE DLDBHandle;
const CSSM_QUERY_PTR Query;
CSSM_HANDLE_PTR ResultsHandle;

Appendix C 99

Sample Add-in Module Code

CSSM_BOOL *EndOfDataStore;
CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes;
CSSM_DATA_PTR Data;
{
printf(“in DL_DataGetFirst\n”);
return NULL;
}

/*---------------------------------------------------------------------------*/
CSSM_DB_UNIQUE_RECORD_PTR DL_DataGetNext (DLDBHandle, ResultsHandle,
EndOfDataStore, Attributes, Data)
CSSM_DL_DB_HANDLE DLDBHandle;
CSSM_HANDLE ResultsHandle;
CSSM_BOOL *EndOfDataStore;
CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes;
CSSM_DATA_PTR Data;
{
printf(“in DL_DataGetNext\n”);
return NULL;
}

/*---------------------------------------------------------------------------*/
CSSM_RETURN DL_FreeUniqueRecord (DLDBHandle, UniqueRecord)
CSSM_DL_DB_HANDLE DLDBHandle;
CSSM_DB_UNIQUE_RECORD_PTR UniqueRecord;
{
printf(“in DL_FreeUniqueRecord\n”);
return CSSM_OK;
}

100 AppendixC