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

Certiﬁcate Library Services (CL) API . . . . . . . . . . . . . . . . . . . . . . . . . . .34

What is a Certiﬁcate?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .34

Operations on Certiﬁcates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .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 Identiﬁer (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

Contents

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

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

X.509 Certiﬁcate 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

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 Certiﬁcate 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

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 deﬁne 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), certiﬁcate library services (CLs), data storage libraries (DLs), and trust policy libraries (TPs).

Certiﬁcate Authority (CA)

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

Certiﬁcate Library Services (CL)

A module that performs operations on digital certiﬁcates. Each certiﬁcate library has knowledge of one or more speciﬁc certiﬁcate formats. Certiﬁcate libraries perform the following operations: signing and signature veriﬁcation of certiﬁcates; management of certiﬁcate ﬁelds; export and import of multiple certiﬁcate formats. The HP-UX implementation of CDSA supports X.509v3 certiﬁcates and X.509v2 certiﬁcate 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 deﬁnes APIs for access to cryptography, certiﬁcate, 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.

Difﬁe-Hellman key exchange

A protocol developed by Whitﬁeld Difﬁe 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 speciﬁed 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 certiﬁcates, CRLs, public keys, or trust information. A DL can use a commercial database package, custom hardware, or a ﬁle 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 scientiﬁc, technological, and economic activity through standardization of criteria and components..

Message Authentication Code (MAC)

A function that produces ﬁxed 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 Certiﬁcate 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 speciﬁed 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 ﬁle 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 veriﬁcation include signing or verifying of certiﬁcates and CRLs, revoking certiﬁcates, and other application-speciﬁc actions or operations.

X.509 certiﬁcate

A certiﬁcate is a digital document containing a public key and a name and allowing authentication of the source of the data accompanying the certiﬁcate. X.509 is the most accepted format for certiﬁcates and is deﬁned 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 ﬁrst release of CDSA.

certiﬁcate revocation list (CRL)

A list of certiﬁcates 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 modiﬁed or forged, alterations are readily detected. Authenticity means that the identity of the user responsible for the data creation can be veriﬁed. 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, ﬁxed-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 speciﬁcation must be written in terms deﬁned 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 speciﬁed 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 certiﬁcate.

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 speciﬁed 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?

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 Certiﬁcate Library (CL) module implements X.509v3 certiﬁcate 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 ﬁles, and manpages for CDSA APIs covering a Common System Security Manager (CSSM), Cryptographic Service Provider (CSP), and Certiﬁcate 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 ﬁles (remember that as of June 1999, you will have to install the HP-UX 11.0 Application CD for these directories and ﬁles 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 ﬁle /usr/include/cdsa/*.h CDSA header ﬁles /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 ﬁles /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 uniﬁed 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 veriﬁcation

• 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 Certiﬁcate Library (CL) API performs memory-based, syntactic manipulations on

X.509v3 certiﬁcates and certiﬁcate revocation lists. These actions include:

• Creating, signing, and verifying certiﬁcates and revocation lists

• Extracting values (such as public keys) from certiﬁcates

• Revoking and reinstating certiﬁcates

• Searching certiﬁcate revocation lists

• Providing pass-through functionality to manipulate certiﬁcate 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 trafﬁc 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 ﬁeld 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 ﬁgure 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 ﬁrst 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 speciﬁcation, so that other data types, such as graphics and ﬁles 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 certiﬁcate syntax. One of the key beneﬁts 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 deﬁnitions are based on the Abstract Syntax Notation One (ASN.1), which is deﬁned 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 beneﬁt from the likelihood that the CDSA crypto APIs will become pervasive through their adoption by the Open Group. Application developers will beneﬁt 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 modiﬁed 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

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 certiﬁcate 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, certiﬁcate 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 ﬁles 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 speciﬁc 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 veriﬁcation ensures that any modiﬁcation, 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 veriﬁcation has three aspects:

• veriﬁcation of the module’s identity, based on a digitally-signed certiﬁcate

• veriﬁcation of object code, whose integrity is itself based on a signed hash of the object

• tightly binding the veriﬁed module identity with the veriﬁed 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 ﬁles under the directory /var/cdsa/cssm. The information ﬁle 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 ﬁle, 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 ﬁle 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 ﬁle system to support long ﬁle names (greater

than 14 characters). CSSM and the bundled add-ins will not be pre-installed if its /var supports only short ﬁle 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

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]

[2]

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

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

[2]

[3]

B’s private key

[4]

RC2 or RC4

symmetric key algorithm

A’s data A’s encrypted data

symmetric key

encrypted symmetric keyB’s public key

encrypted symmetric key

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’s data

hash

A’s hash of A’s data

[2]

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

A’s private key

[3]

A’s digital signature,

encrypted symmetric key,

A’s encrypted data

[4]

B’s private key

encrypted symmetric key

[5]

A’s encrypted data

symmetric key

[6]

symmetric key

A’s data

hash

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

[7]

A’s digital signature

A’s public key

A’s hash of A’s data

[8]

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 identiﬁes 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 speciﬁes 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 ﬁles 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 (ﬁnal) call. Usually, the result is available after the ﬁnal 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 ﬁle 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 ﬁrst 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 speciﬁed 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-speciﬁc function indicated by the operation ID. The operation ID

speciﬁes an operation which the CSP has exported for use by an application or module. Such operations are speciﬁc 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

+ 100 hidden pages