Previous section.

Common Security: CDSA and CSSM
Copyright © 1997 The Open Group

Cryptographic Services API

Overview

Cryptographic Service Providers (CSPs) are add-in modules which perform cryptographic operations including 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 a hardware-software combination or by software only. Besides the traditional cryptographic functions, CSPs may provide other vendor-specific services. The set of services provided can be dynamic even after the CSP has been attached for service by a caller. This means the capabilities registered when the CSP was installed can change during execution based on changes internal or external to the system.

The CSP is always responsible for the secure storage of private keys. Optionally the CSP may assume responsibility for the secure storage of other object types, such as symmetric keys and certificates. The implementation of secured persistent storage for keys can use the services of a Data Storage Library module within the CSSM framework (if that module provides secured storage) or some approach internal to the CSP. Accessing persistent objects managed by the CSP, other than keys, is performed using CSSM's Data Storage Library APIs.

CSPs optionally support a password-based login sequence. When login is supported, the caller is allowed to change passwords as deemed necessary. This is part of a standard user-initiated maintenance procedure. Some CSPs support operations for privileged, CSP administrators. The model for CSP administration varies widely among CSP implementations. For this reason, CSSM does not define APIs for vendor-specific CSP administration operations. CSP vendors can make these services available to CSP administration tools using the CSSM_Passthrough function.

The range and types of cryptographic services a CSP supports is at the discretion of the vendor. A registry and query mechanism is available through the CSSM for CSPs to disclose the services and details about the services. As an example, a CSP may register with the CSSM: Encryption is supported, the algorithms present are DES with cipher block chaining for key sizes 40 and 56 bits, triple DES with 3 keys for key size 168 bits.

All cryptographic services requested by applications will be channeled to one of the CSPs via the CSSM. CSP vendors only need target their modules to CSSM for all security-conscious applications to have access to their product.

Calls made to a Cryptographic Service Provider (CSP) to perform cryptographic operations occur within a framework called a session, which is established and terminated by the application. The session context (simply referred to as the context) is created prior to starting CSP operations and is deleted as soon as possible upon completion of the operation. Context information is not persistent; it is not saved permanently in a file or database.

Before an application calls a CSP to perform a cryptographic operation, the application uses the query services function to determine what CSPs are installed, and what services they provide. Based on this information, the application then can determine which CSP to use for subsequent operations; the application creates a session with this CSP and performs the operation.

Depending on the class of cryptographic operations, individualized attributes are available for the cryptographic context. Besides specifying an algorithm when creating the context, the application 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 indicates the desired CSP is available. Functions are also provided to manage the created context.

When a context is no longer required, the application calls CSSMDeleteContext. Resources that were allocated for that context can be reclaimed by the operating system.

Cryptographic operations come in two types-a single call to perform an operation and a staged method of performing the operation. For the single call method, only one call is needed to obtain the result. For the staged method, there is an initialization call followed by one or more update calls, and ending with a completion (final) call. The result is available after the final function completes its execution for most cryptographic operations-staged encryption/decryption are an exception in that each update call generates a portion of the result.

Key Formats for Public Key-Based Algorithms

To ensure interoperability among cryptographic service providers and portability for application developers, CSSM must mandate standard key formats for public key based cryptographic algorithms. Standard key formats have not been defined for many of the algorithms identified by CSSM because these algorithms are not yet in wide spread use. For those algorithms in wide spread use, CDSA adopts existing standard formats or defines a format when no standard exists.

The two PKI-based algorithms with wide spread usage are:

For RSA-based algorithms, CDSA adopts the PKCS#1 standard for key representation.

For DSA-based algorithms, no organization has published a standard and no de facto standard seems to exists. CDSA defines a standard representation for DSA key based on the DSA algorithm definitions in the FIPS 186 and FIPS 186a standards. Complete documentation on these standards can be found at http://csrc.ncsl.nist.gov/fips/fips186.txt and at http://csrc.ncsl.nist.gov/fips/fips186a.txt respectively.

A DSA public key is represented as a BER-encoded, ordered sequence containing the prime modulus, the prime divisor, the order modulo the prime modulus, and the public key value. A DSA private key is represented as a BER-encoded, ordered sequence containing the prime modulus, the prime divisor, the order modulo the prime modulus, and the private key value. Additional information is provided in the specification titled CSSM Cryptographic Service Providers Interface.

Data Structures

CSSM_CC_HANDLE

typedef uint32 CSSM_CC_HANDLE /* Cryptographic Context Handle */

CSSM_CSP_HANDLE

typedef uint32 CSSM_CSP_HANDLE /* Cryptographic Service Provider 
                                        Handle */

CSSM_DATE

typedef struct cssm_date {
    uint8 Year[4];
    uint8 Month[2];
    uint8 Day[2];
} CSSM_DATE, *CSSM_DATE_PTR;

Definition

Year

Four-digit ASCII representation of the year.

Month

Two-digit ASCII representation of the month.

Day

Two-digit ASCII representation of the day.

CSSM_RANGE

typedef struct cssm_range {
    uint32 Min; /* inclusive minimum value */
    uint32 Max; /* inclusive maximum value */
} CSSM_RANGE, *CSSM_RANGE_PTR;

Definition

Min

Minimum value in the range.

Max

Maximum value in the range.

CSSM_QUERY_SIZE_DATA

typedef struct cssm_query_size_data {
    uint32 SizeInputBlock; /* size of input data block */
    uint32 SizeOutputBlock; /* size of resulting output 
                                        data block */
} CSSM_QUERY_SIZE_DATA, *CSSM_QUERY_SIZE_DATA_PTR;

Definition

SizeInputBlock

Size of the data block to be input for processing.

SizeOutputBlock

Size of the output data block that results from processing.

CSSM_HEADERVERSION

typedef uint32 CSSM_HEADERVERSION;

#define CSSM_KEYHEADER_VERSION (2)

Definition
Represents the version number of a key header structure. This version number is an integer that increments with each format revision. The current revision number is represented by the defined constant CSSM_KEYHEADER_VERSION.

CSSM_KEY_SIZE

This structure holds the key size and the effective key size for a given key. The metric used is bits. The number of effective bits is the number of key bits that can be used in a cryptographic operation compared with the number of bits that may be present in the key. When the number of effective bits is less than the number of actual bits, this is known as "dumbing down".
typedef struct cssm_key_size {
   uint32 KeySizeInBits; /* Key size in bits */
   uint32 EffectiveKeySizeInBits; /* Effective key size in bits */
} CSSM_KEYSIZE, *CSSM_KEYSIZE_PTR;

Definition

KeySizeInBits

The actual number of bits in a key.

EffectiveKeySizeInBits

The number of key bits that can be used for cryptographic operations.

CSSM_KEYHEADER

The key header contains meta-data about a key. It contains the GUID of the CSP that owns the data. Attributes of the key are defined by the CSP and the application when the key is created. Most of these attributes describe both the CSP-stored copy of the key and the application's local copy of the key or the key reference. A subset of the attributes describe only the application-resident copy of the key or the key reference. A table at the end of this section summarizes the scope of each key header attribute.
typedef struct cssm_keyheader {
    CSSM_HEADERVERSION HeaderVersion; /* Key header version */
    CSSM_GUID CspId; /* GUID of CSP generating the key */
    uint32 BlobType; /* See BlobType #define's */
    uint32 Format; /* Raw or Reference format */
    uint32 AlgorithmId; /* Algorithm ID of key */
    uint32 KeyClass; /* Public/Private/Secret, etc. */
    uint32 EffectiveKeySizeInBits; /* Size of logical 
                                      key/modulus/prime in bits */
    uint32 KeySizeInBits; /* Size of actual key/modulus/prime 
                                        in bits */
    uint32 KeyAttr; /* Attribute flags */
    uint32 KeyUsage; /* Key use flags */
    CSSM_DATE StartDate; /* Effective date of key */
    CSSM_DATE EndDate; /* Expiration date of key */
    uint32 WrapAlgorithmId; /* == CSSM_ALGID_NONE if clear key */
    uint32 WrapMode; /* if alg supports multiple wrapping modes */
    uint32 Reserved;
} CSSM_KEYHEADER, *CSSM_KEYHEADER_PTR;

Definition

HeaderVersion

This is the version of the keyheader structure. The current version is represented by the defined constant CSSM_KEYHEADER_VERSION.

CspId

If known, the GUID of the CSP that generated the key. This value will not be known if a key is received from a third party, or extracted from a certificate.

BlobType

Describes the basic format of the key data. It can be any one of the following values:

Keyblob Type Identifier Description
CSSM_KEYBLOB_RAW The blob is a clear, raw key
CSSM_KEYBLOB_RAW_BERDER The blob is a clear key, DER encoded
CSSM_KEYBLOB_REFERENCE The blob is a reference to a key
CSSM_KEYBLOB_WRAPPED The blob is a wrapped RAW key
CSSM_KEYBLOB_WRAPPED_BERDER The blob is a wrapped DER encoded key
CSSM_KEYBLOB_OTHER The blob is a wrapped DER encoded key

Format

Describes the detailed format of the key data based on the value of the BlobType field. If the blob type has a non-reference basic type, then a CSSM_KEYBLOB_RAW_FORMAT identifier must be used, otherwise a CSSM_KEYBLOB_REF_FORMAT identifier is used. Any of the following values are valid as format identifiers.

Keyblob Format Identifier Description
CSSM_KEYBLOB_RAW_FORMAT_NONE Raw format is unknown
CSSM_KEYBLOB_RAW_FORMAT_PKCS1 RSA PKCS1 V1.5 See "RSA Encryption Standard", an RSA Laboratories publication http://www.rsa.com/rsalabs/pubs/PKCS/
CSSM_KEYBLOB_RAW_FORMAT_PKCS3 RSA PKCS3 V1.5 See"Diffie-Hellman Key-Agreement Standard", an RSA Laboratories publication http://www.rsa.com/rsalabs/pubs/PKCS/
CSSM_KEYBLOB_RAW_FORMAT_MSCAPI Microsoft CAPI V2.0
CSSM_KEYBLOB_RAW_FORMAT_PGP PGP See "PGP Cryptographic Software Development Kit (PGP sdk)", a PGP Publication
CSSM_KEYBLOB_RAW_FORMAT_FIPS186 US Gov. FIPS 186: DSS V
CSSM_KEYBLOB_RAW_FORMAT_BSAFE RSA Bsafe V3.0 See "BSAFE, A Cryptographic Toolkit, Library Reference Manual", an RSA Data Security Inc. publication
CSSM_KEYBLOB_RAW_FORMAT_PKCS8 RSA PKCS8 V1.2 See "Private-Key Information Syntax Standard", an RSA Laboratories publication http://www.rsa.com/rsalabs/pubs/PKCS/"
CSSM_KEYBLOB_RAW_FORMAT_PKCS11 RSA PKCS11 V2.0 See "Cryptographic Token Interface Standard", an RSA Laboratories publication http://www.rsa.com/rsalabs/pubs/PKCS/
CSSM_KEYBLOB_RAW_FORMAT_CDSA CDSA format See this specifications and CSSM Cryptographic Service Provider Interface Specification
CSSM_KEYBLOB_RAW_FORMAT_OTHER Other, CSP defined
CSSM_KEYBLOB_REF_FORMAT_INTEGER Reference is a number or handle
CSSM_KEYBLOB_REF_FORMAT_STRING Reference is a string or name
CSSM_KEYBLOB_REF_FORMAT_OTHER Reference is a CSP-defined format

AlgorithmId

The algorithm for which the key was generated. This value does not change when the key is wrapped. Any of the defined CSSM algorithm IDs may be used.

KeyClass

Class of key contained in the key blob. Valid key classes are as follows:

Key Class Identifier Description
CSSM_KEYCLASS_PUBLIC_KEY Key is a public key
CSSM_KEYCLASS_PRIVATE_KEY Key is a private key
CSSM_KEYCLASS_SESSION_KEY Key is a session or symmetric key
CSSM_KEYCLASS_SECRET_PART Key is part of secret key
CSSM_KEYCLASS_OTHER Other

EffectiveKeySizeInBits

This is the logical size of the key in bits. The logical size is the value referred to when describing the length of the key. For instance, an RSA key would be described by the size of its modulus and a DSA key would be represented by the size of its prime. Symmetric key sizes describe the actual number of bits in the key. For example, DES keys would be 64 bits and an RC4 key could range from 1 to 128 bits.

KeyAttr

Attributes of the key represented by the data. These attributes are used by CSPs and applications to convey information about stored or referenced keys. Some of the attribute values are used only as input or output values for CSP functions, can appear in a keyheader, and some can be used only by the CSP. The attributes are represented by a bitmask. The attribute name, its description, and its usage constraints are summarized in the following:

Attribute values valid only as inputs to functions and will never appear in a key header:
Attribute Description
CSSM_KEYATTR_RETURN_DEFAULT Key is returned in CSP's default form.
CSSM_KEYATTR_RETURN_DATA Key is returned with key bits present. The format of the returned key can be raw or wrapped.
CSSM_KEYATTR_RETURN_REF Key is returned as a reference.
CSSM_KEYATTR_RETURN_NONE Key is not returned.
Attribute values valid as inputs to functions and retained values in a key header:
Attribute Description
CSSM_KEYATTR_PERMANENT Key is stored persistently in the CSP, such asa PKCS11 token object.
CSSM_KEYATTR_PRIVATE Key is a private object and protected by either a user login, a password, or both.
CSSM_KEYATTR_MODIFIABLE The key or its attributes can be modified.
CSSM_KEYATTR_SENSITIVE Key is sensitive. It may only be extracted from the CSP in a wrapped state.
CSSM_KEYATTR_EXTRACTABLE Key is extractable from the CSP. If this bit is not set, either the key is not stored in the CSP, or it cannot be extracted under any circumstances.
  
  
Attribute values valid in a key header when set by a CSP:
Attribute Description
CSSM_KEYATTR_ALWAYS_SENSITIVE Key has always been sensitive.
CSSM_KEYATTR_NEVER_EXTRACTABLE Key has never been extractable.

Key Usage

A bitmask representing the valid uses of the key. Any of the following values are valid:

Usage Mask Description
CSSM_KEYUSE_ANY Key may be used for any purpose supported by the algorithm.
CSSM_KEYUSE_ENCRYPT Key may be used for encryption.
CSSM_KEYUSE_DECRYPT Key may be used for decryption.
CSSM_KEYUSE_SIGN Key can be used to generate signatures. For symmetric keys this represents the ability to generate MACs.
CSSM_KEYUSE_VERIFY Key can be used to verify signatures. For symmetric keys this represents the ability to verify MACs.
CSSM_KEYUSE_SIGN_RECOVER Key can be used to perform signatures with message recovery. This form of a signature is generated using the CSSM_EncryptData API with the algorithm mode set to
CSSM_ALGMODE_PUBLIC_KEY This attribute is only valid for asymmetric algorithms.
CSSM_KEYUSE_VERIFY_RECOVER Key can be used to verify signatures with message recovery. This form of a signature verified using the CSSM_DecryptData API with the algorithm mode set to
CSSM_ALGMODE_PUBLIC_KEY This attribute is only valid for asymmetric algorithms.
CSSM_KEYUSE_WRAP Key can be used to wrap another key.
CSSM_KEYUSE_UNWRAP Key can be used to unwrap a key.
CSSM_KEYUSE_DERIVE Key can be used as the source for deriving other keys.

StartDate

Date from which the corresponding key is valid. All fields of the CSSM_DATA structure will be set to zero if the date is unspecified or unknown.

EndDate

Data that the key expires and can no longer be used. All fields of the CSSM_DATA structure will be set to zero is the date is unspecified or unknown.

WrapAlgorithmId

If the key data contains a wrapped key, this field contains the algorithm used to create the wrapped blob. This field will be set to CSSM_ALGID_NONE if the key is not wrapped.

WrapMode

If the wrapping algorithm supports multiple wrapping modes, this field contains the mode used to wrap the key. This field is ignored if the WrapAlgorithmId is CSSM_ALGID_NONE.

Reserved

This field is reserved for future use. It should always be set to zero.

The scope of the key header attributes is summarized as follows:

Attribute Name
Pertains to
the Application's
local copy of the key
Pertains to
the CSP-stored
copy of the key
BlobType X  
Format X  
AlgorithmId X X
KeyClass X X
EffectiveKeySizeInBits X X
KeyAttr Only the flag bits RETURN_XXX All the flag bits except RETURN_XXX
KeyUsage X X
StartDate X X
EndDate X X
WrapAlgorithmId X  
WrapMode X  

CSSM_KEY

This structure is used to represent keys in CSSM.
typedef struct cssm_key {
    CSSM_KEYHEADER KeyHeader; /* Fixed length key header */
    CSSM_DATA KeyData; /* Variable length key data */
} CSSM_KEY, *CSSM_KEY_PTR;

Definition

KeyHeader

Header describing the key.

KeyData

Data representation of the key.

CSSM_WRAP_KEY

This type is used to reference keys that are known to be in wrapped form.
typedef CSSM_KEY CSSM_WRAP_KEY, *CSSM_WRAP_KEY_PTR;

CSSM_CSP_TYPE

typedef enum cssm_csptype {
    CSSM_CSP_SOFTWARE = 1,
    CSSM_CSP_HARDWARE = CSSM_CSP_SOFTWARE+1,
    CSSM_CSP_HYBRID = CSSM_CSP_SOFTWARE+2,
}CSSM_CSPTYPE;

CSSM_CSP_SESSION_TYPE

A session type flags is used as an input parameter to the CSSM_ModuleAttach function to declare the type of session requested by the caller.
#define CSSM_CSP_SESSION_EXCLUSIVE 0x0001
       /* single user CSP */
#define CSSM_CSP_SESSION_READWRITE 0x0002
       /* caller can read and write objects such as keys in 
                                    the CSP */
#define CSSM_CSP_SESSION_SERIAL 0x0004
       /* multi-user, re-entrant CSP that requires serial 
                                    access */

CSSM_PADDING

Enumerates the padding options that can be provided by a CSP.
typedef enum cssm_padding {
    CSSM_PADDING_NONE = 0,
    CSSM_PADDING_CUSTOM = CSSM_PADDING_NONE+1,
    CSSM_PADDING_ZERO = CSSM_PADDING_NONE+2,
    CSSM_PADDING_ONE = CSSM_PADDING_NONE+3,
    CSSM_PADDING_ALTERNATE = CSSM_PADDING_NONE+4,
    CSSM_PADDING_FF = CSSM_PADDING_NONE+5,
    CSSM_PADDING_PKCS5 = CSSM_PADDING_NONE+6,
    CSSM_PADDING_PKCS7 = CSSM_PADDING_NONE+7,
    CSSM_PADDING_CipherStealing = CSSM_PADDING_NONE+8,
    CSSM_PADDING_RANDOM = CSSM_PADDING_NONE+9,
} CSSM_PADDING.

CSSM_CONTEXT_ATTRIBUTE

typedef struct cssm_context_attribute{
    uint32 AttributeType;
    uint32 AttributeLength;
    union cssm_context_attribute_value{
        char *String;
        uint32 Uint32;
        CSSM_CRYPTO_DATA_PTR Crypto;
        CSSM_KEY_PTR Key;
        CSSM_DATA_PTR Data;
        CSSM_DATE_PTR Date;
        CSSM_RANGE_PTR Range;
        CSSM_VERSION_PTR Version;
    } Attribute;
} CSSM_CONTEXT_ATTRIBUTE, *CSSM_CONTEXT_ATTRIBUTE_PTR;

Definition

AttributeType

An identifier describing the type of attribute. Valid attribute types are as follows:

Value Description Data Type
CSSM_ATTRIBUTE_NONE No attribute None
CSSM_ATTRIBUTE_CUSTOM Custom data Opaque pointer
CSSM_ATTRIBUTE_DESCRIPTION Description of attribute String
CSSM_ATTRIBUTE_KEY Key Data CSSM_KEY
CSSM_ATTRIBUTE_INIT_VECTOR Initialization vector CSSM_DATA
CSSM_ATTRIBUTE_SALT Salt CSSM_DATA
CSSM_ATTRIBUTE_PADDING Padding information CSSM_PADDING
CSSM_ATTRIBUTE_RANDOM Random data CSSM_DATA
CSSM_ATTRIBUTE_SEED Seed CSSM_CRYPTO_DATA
CSSM_ATTRIBUTE_PASSPHRASE Pass phrase CSSM_CRYPTO_DATA
CSSM_ATTRIBUTE_KEY_LENGTH Key length specified in bits uint32
CSSM_ATTRIBUTE_KEY_LENGTH_RANGE Key length range specified in bits CSSM_RANGE
CSSM_ATTRIBUTE_BLOCK_SIZE Block size uint32
CSSM_ATTRIBUTE_OUTPUT_SIZE Output size uint32
CSSM_ATTRIBUTE_ROUNDS Number of runs or rounds uint32
CSSM_ATTRIBUTE_IV_SIZE Size of initialization vector uint32
CSSM_ATTRIBUTE_ALG_PARAMS Algorithm parameters CSSM_DATA
CSSM_ATTRIBUTE_LABEL Label placed on an object when it is created CSSM_DATA
CSSM_ATTRIBUTE_KEY_TYPE Type of key to generate or derive uint32
CSSM_ATTRIBUTE_MODE Algorithm mode to use for encryption uint32
CSSM_ATTRIBUTE_EFFECTIVE_BITS Number of effective bits used in the RC2 cipher uint32
CSSM_ATTRIBUTE_START_DATE Starting date for an object's validity CSSM_DATE
CSSM_ATTRIBUTE_END_DATE Ending date for an object's validity CSSM_DATE
CSSM_ATTRIBUTE_KEYUSAGE Usage restriction on the key uint32
CSSM_ATTRIBUTE_KEYATTR Key attribute uint32
CSSM_ATTRIBUTE_VERSION Version number CSSM_VERSION
CSSM_ATTRIBUTE_PRIME Prime value CSSM_DATA
CSSM_ATTRIBUTE_BASE Base Value CSSM_DATA
CSSM_ATTRIBUTE_SUBPRIME Subprime Value CSSM_DATA
CSSM_ATTRIBUTE_ALG_ID Algorithm identifier uint32
CSSM_ATTRIBUTE_ITERATION_COUNT Algorithm iterations uint32
CSSM_ATTRIBUTE_ROUNDS_RANGE Range of number of rounds possible CSSM_RANGE

The data referenced by a CSSM_ATTRIBUTE_CUSTOM attribute must be a single continuous memory block. This allows the CSSM to appropriately release all dynamically allocated memory resources.

AttributeLength

Length of the attribute data.

Attribute

Union representing the attribute data. The union member used is named after the type of data contained in the attribute. See the attribute types table for the data types associated with each attribute type

CSSM_CONTEXT

typedef uint32 CSSM_CC_HANDLE /* Cryptographic Context Handle */

typedef struct cssm_context {
    uint32 ContextType; /* context type */
    uint32 AlgorithmType; /* algorithm type of context */
    uint32 Reserve; /* reserved for future use */
    uint32 NumberOfAttributes; /* number of attributes associated 
                                        with context */
    CSSM_CONTEXT_ATTRIBUTE_PTR ContextAttributes; /* pointer to 
                                        attributes */
} CSSM_CONTEXT, *CSSM_CONTEXT_PTR

Definition

ContextType

An identifier describing the type of services for this context.

Value Description
CSSM_ALGCLASS_NONE Null Context type
CSSM_ALGCLASS_CUSTOM Custom Algorithms
CSSM_ALGCLASS_KEYXCH Key Exchange Algorithms
CSSM_ALGCLASS_SIGNATURE Signature Algorithms
CSSM_ALGCLASS_SYMMETRIC Symmetric Encryption Algorithms
CSSM_ALGCLASS_DIGEST Message Digest Algorithms
CSSM_ALGCLASS_RANDOMGEN Random Number Generation Algorithms
CSSM_ALGCLASS_UNIQUEGEN Unique ID Generation Algorithms
CSSM_ALGCLASS_MAC Message Authentication Code Algorithms
CSSM_ALGCLASS_ASYMMETRIC Asymmetric Encryption Algorithms
CSSM_ALGCLASS_KEYGEN Key Generation Algorithms
CSSM_ALGCLASS_DERIVEKEY Key Derivation Algorithms

AlgorithmType

An ID number describing the algorithm to be used.

Value Description
CSSM_ALGID_NONE Null algorithm
CSSM_ALGID_CUSTOM Custom algorithm
CSSM_ALGID_DH Diffie Hellman key exchange algorithm
CSSM_ALGID_PH Pohlig Hellman key exchange algorithm
CSSM_ALGID_KEA Key Exchange Algorithm
CSSM_ALGID_MD2 MD2 hash algorithm
CSSM_ALGID_MD4 MD4 hash algorithm
CSSM_ALGID_MD5 MD5 hash algorithm
CSSM_ALGID_SHA1 Secure Hash Algorithm
CSSM_ALGID_NHASH N-Hash algorithm
CSSM_ALGID_HAVAL HAVAL hash algorithm (MD5 variant)
CSSM_ALGID_RIPEMD RIPE-MD hash algorithm (MD4 variant developed for the European Community's RIPE project)
CSSM_ALGID_IBCHASH IBC-Hash (keyed hash algorithm or MAC)
CSSM_ALGID_RIPEMAC RIPE-MAC
CSSM_ALGID_HASHwithHitachi Hitachi hash algorithm
CSSM_ALGID_DES Data Encryption Standard block cipher
CSSM_ALGID_DESX DESX block cipher (DES variant from RSA)
CSSM_ALGID_RDES RDES block cipher (DES variant)
CSSM_ALGID_3DES_3KEY Triple-DES block cipher (with 3 keys)
CSSM_ALGID_3DES_2KEY Triple-DES block cipher (with 2 keys)
CSSM_ALGID_3DES_1KEY Triple-DES block cipher (with 1 key)
CSSM_ALGID_IDEA IDEA block cipher
CSSM_ALGID_RC2 RC2 block cipher
CSSM_ALGID_RC5 RC5 block cipher
CSSM_ALGID_RC4 RC4 stream cipher
CSSM_ALGID_SEAL SEAL stream cipher
CSSM_ALGID_CAST CAST block cipher
CSSM_ALGID_BLOWFISH BLOWFISH block cipher
CSSM_ALGID_SKIPJACK Skipjack block cipher
CSSM_ALGID_LUCIFER Lucifer block cipher
CSSM_ALGID_MADRYGA Madryga block cipher
CSSM_ALGID_FEAL FEAL block cipher
CSSM_ALGID_REDOC REDOC 2 block cipher
CSSM_ALGID_REDOC3 REDOC 3 block cipher
CSSM_ALGID_LOKI LOKI block cipher
CSSM_ALGID_KHUFU KHUFU block cipher
CSSM_ALGID_KHAFRE KHAFRE block cipher
CSSM_ALGID_MMB MMB block cipher (IDEA variant)
CSSM_ALGID_GOST GOST block cipher
CSSM_ALGID_SAFER SAFER K-40, K-64, K-128 block cipher
CSSM_ALGID_CRAB CRAB block cipher
CSSM_ALGID_MULTI2 MULTI2 block cipher algorithm(MULTI variant from Hitachi)
CSSM_ALGID_RSA RSA public key cipher
CSSM_ALGID_CIPHERwithHitachiECCS Hitachi's public key cipher algorithm with Elliptic Curve Cryptosystems
CSSM_ALGID_DSA Digital Signature Algorithm
CSSM_ALGID_MD5WithRSA MD5/RSA signature algorithm
CSSM_ALGID_MD2WithRSA MD2/RSA signature algorithm
CSSM_ALGID_SIGwithHitachiECCS Hitachi's signature algorithm with Elliptic Curve Cryptosystems
CSSM_ALGID_ElGamal ElGamal signature algorithm
CSSM_ALGID_MD2Random MD2-based random numbers
CSSM_ALGID_MD5Random MD5-based random numbers
CSSM_ALGID_SHARandom SHA-based random numbers
CSSM_ALGID_DESRandom DES-based random numbers
CSSM_ALGID_MULTI2Random MULTI2-based random numbers
CSSM_ALGID_SHA1WithRSA SHA-1/RSA signature algorithm
CSSM_ALGID_RSA_PKCS RSA as specified in PKCS #1
CSSM_ALGID_RSA_ISO9796 RSA as specified in ISO 9796
CSSM_ALGID_RSA_RAW Raw RSA as assumed in X.509
CSSM_ALGID_CDMF CDMF block cipher
CSSM_ALGID_CAST3 Entrust's CAST3 block cipher
CSSM_ALGID_CAST5 Entrust's CAST5 block cipher
CSSM_ALGID_GenericSecret Generic secret operations
CSSM_ALGID_ConcatBaseAndKey Concatenate two keys, base key first
CSSM_ALGID_ConcatKeyAndBase Concatenate two keys, base key last
CSSM_ALGID_ConcatBaseAndData Concatenate base key and random data, key first
CSSM_ALGID_ConcatDataAndBase Concatenate base key and data, data first
CSSM_ALGID_XORBaseAndData XOR a byte string with the base key
CSSM_ALGID_ExtractFromKey Extract a key from base key, starting at arbitrary bit position
CSSM_ALGID_SSL3PreMasterGen Generate a 48 byte SSL 3 pre-master key
CSSM_ALGID_SSL3MasterDerive Derive an SSL 3 key from a pre-master key
CSSM_ALGID_SSL3KeyAndMacDerive Derive the keys and MACing keys for the SSL cipher suite
CSSM_ALGID_SSL3MD5_MAC Performs SSL 3 MD5 MACing
CSSM_ALGID_SSL3SHA1_MAC Performs SSL 3 SHA-1 MACing
CSSM_ALGID_MD5_PBE Generate key by MD5 hashing a base key
CSSM_ALGID_MD2_PBE Generate key by MD2 hashing a base key
CSSM_ALGID_SHA1_PBE Generate key by SHA-1 hashing a base key
CSSM_ALGID_WrapLynks Spyrus LYNKS DES based wrapping scheme w/checksum
CSSM_ALGID_WrapSET_OAEP SET key wrapping
CSSM_ALGID_BATON Fortezza BATON cipher
CSSM_ALGID_ECDSA Elliptic Curve DSA
CSSM_ALGID_MAYFLY Fortezza MAYFLY cipher
CSSM_ALGID_JUNIPER Fortezza JUNIPER cipher
CSSM_ALGID_FASTHASH Fortezza FASTHASH
CSSM_ALGID_3DES Generix 3DES
CSSM_ALGID_SSL3MD5 SSL3 with MD5
CSSM_ALGID_SSL3SHA1 SSL3 with SHA1
CSSM_ALGID_FortezzaTimestamp Fortezza with Timestamp
CSSM_ALGID_SHA1WithDSA SHA1 with DSA
CSSM_ALGID_SHA1WithECDSA SHA1 with Elliptic Curve DSA
CSSM_ALGID_DSA_BSAFE DSA with BSAFE Key format
CSSM_ALGID_Bcrypt BSI algorithm
CSSM_ALGID_LUCpkcds LUC Public key crypto and Dig Sig Alg
CSSM_ALGID_BARAS  
CSSM_ALGID_SxalMbal Substitution Xor Alg / Multi Block Alg
CSSM_ALGID_MISTY1 Block Cipher
CSSM_ALGID_ENCRIP  

Some of the above algorithms operate in a variety of modes. The desired mode is specified using an attribute of type CSSM_ATTRIBUTE_MODE. The valid values for the mode attribute are as follows:

Value Description
CSSM_ALGMODE_NONE Null Algorithm mode
CSSM_ALGMODE_CUSTOM Custom mode
CSSM_ALGMODE_ECB Electronic Code Book
CSSM_ALGMODE_ECBPad ECB with padding
CSSM_ALGMODE_CBC Cipher Block Chaining
CSSM_ALGMODE_CBC_IV8 CBC with Initialization Vector of 8 bytes
CSSM_ALGMODE_CBCPadIV8 CBC with padding and Initialization Vector of 8 bytes
CSSM_ALGMODE_CFB Cipher FeedBack
CSSM_ALGMODE_CFB_IV8 CFB with Initialization Vector of 8 bytes
CSSM_ALGMODE_CFBPadIV8 CFB with Initialization Vector of 8 bytes and padding
CSSM_ALGMODE_OFB Output FeedBack
CSSM_ALGMODE_OFB_IV8 OFB with Initialization Vector of 8 bytes
CSSM_ALGMODE_OFBPadIV8 OFB with Initialization Vector of 8 bytes and padding
CSSM_ALGMODE_COUNTER Counter
CSSM_ALGMODE_BC Block Chaining
CSSM_ALGMODE_PCBC Propagating CBC
CSSM_ALGMODE_CBCC CBC with Checksum
CSSM_ALGMODE_OFBNLF OFB with NonLinear Function
CSSM_ALGMODE_PBC Plaintext Block Chaining
CSSM_ALGMODE_PFB Plaintext FeedBack
CSSM_ALGMODE_CBCPD CBC of Plaintext Difference
CSSM_ALGMODE_PUBLIC_KEY Use the public key
CSSM_ALGMODE_PRIVATE_KEY Use the private key
CSSM_ALGMODE_SHUFFLE Fortezza shuffle mode
CSSM_ALGMODE_ECB64 Electronic Code Book 64 bytes
CSSM_ALGMODE_CBC64 Cipher Block Chaining 64 bytes
CSSM_ALGMODE_OFB64 Output Feedback 64 bytes
CSSM_ALGMODE_CFB64 Cipher Feedback 64 bytes
CSSM_ALGMODE_CFB32 Cipher Feedback 32 bytes
CSSM_ALGMODE_CFB16 Cipher Feedback 16 bytes
CSSM_ALGMODE_CFB8 Cipher Feedback 8 bytes
CSSM_ALGMODE_WRAP  
CSSM_ALGMODE_PRIVATE_WRAP  
CSSM_ALGMODE_RELAYX  
CSSM_ALGMODE_ECB128 Electronic Code Book 128 bytes
CSSM_ALGMODE_ECB96 Electronic Code Book 96 bytes
CSSM_ALGMODE_CBC128 Cipher Block Chaining 128 bytes
CSSM_ALGMODE_OAEP_HASH Algorithm mode for SET key wrapping

NumberOfAttributes

Number of attributes associated with this service.

ContextAttributes

Pointer to data that describes the attributes. To retrieve the next attribute, advance the attribute pointer.

CSSM_CSP_CAPABILITY

typedef CSSM_CONTEXT CSSM_CSP_CAPABILITY, *CSSM_CSP_CAPABILITY_PTR;

CSSM_SOFTWARE_CSPSUBSERVICE_INFO

typedef struct cssm_software_cspsubservice_info {
    uint32 NumberOfCapabilities;
    CSSM_CSP_CAPABILITY_PTR CapabilityList;
    VOID* Reserved;
} CSSM_SOFTWARE_CSPSUBSERVICE_INFO, *CSSM_SOFTWARE_CSPSUBSERVICE_INFO_PTR;

Definition

NumberOfCapabilities

Number of capabilities available from the CSP.

CapabilityList

Pointer to an array of CSSM_CSP_CAPABILITY structures that represent the capabilities available from the CSP.

Reserved

This field is reserved for future use and must always be set to zero.

CSSM_HARDWARE_CSPSUBSERVICE_INFO

typedef struct cssm_hardware_cspsubservice_info {
    uint32 NumberOfCapabilities;
    CSSM_CSP_CAPABILITY_PTR CapabilityList;
    void* Reserved;

    /* Reader/Slot Info */
    char *ReaderDescription;
    char *ReaderVendor;
    char *ReaderSerialNumber;
    CSSM_VERSION ReaderHardwareVersion;
    CSSM_VERSION ReaderFirmwareVersion;
    uint32 ReaderFlags;
    uint32 ReaderCustomFlags;

    char *TokenDescription;
    char *TokenVendor;
    char *TokenSerialNumber;
    CSSM_VERSION TokenHardwareVersion;
    CSSM_VERSION TokenFirmwareVersion;

    uint32 TokenFlags;
    uint32 TokenCustomFlags;
    uint32 TokenMaxSessionCount;
    uint32 TokenOpenedSessionCount;
    uint32 TokenMaxRWSessionCount;
    uint32 TokenOpenedRWSessionCount;
    uint32 TokenTotalPublicMem;
    uint32 TokenFreePublicMem;
    uint32 TokenTotalPrivateMem;
    uint32 TokenFreePrivateMem;
    uint32 TokenMaxPinLen;
    uint32 TokenMinPinLen;
    char TokenUTCTime[16];

    CSSM_STRING UserLabel;
    CSSM_DATA UserCACertificate;
} CSSM_HARDWARE_CSPSUBSERVICE_INFO, *CSSM_HARDWARE_CSPSUBSERVICE_INFO_PTR;

Definition

NumberOfCapabilities

Number of capabilities available from the CSP.

CapabilityList

A context list that specifies the capabilities of the CSP.

Reserved

This field is reserved for future use and must always be set to zero.

ReaderDescription

A NULL-terminated character string that contains a text description of the device reader.

ReaderVendor

A NULL-terminated string that contains the name of the reader vendor.

ReaderSerialNumber

A NULL-terminated string that contains the serial number of the reader.

ReaderHardwareVersion

Hardware version of the reader.

ReaderFirmwareVersion

Firmware version of the reader.

ReaderFlags

Bit mask containing information about the reader. The flags specified in the mask are as follows:

Reader Flag Description
CSSM_CSP_RDR_TOKENPRESENT Token is present in the reader
CSSM_CSP_RDR_TOKENREMOVABLE Reader supports removable tokens
CSSM_CSP_RDR_HW Reader is a hardware device

ReaderCustomFlags

Flags defined by the vendor. Consult the individual CSP user's guide for the list of valid flags.

The following fields may not be valid if the CSSM_CSP_RDR_TOKENPRESENT flag is not set in the ReaderFlags field. Unknown string and CSSM_DATA fields will be set to NULL, integer and date fields will be set to zero and flag fields will have all flags set to false.

TokenDescription

A NULL-terminated character string that contains a text description of the token. This value may be NULL or equal to ReaderDescription if the token is not removable.

TokenVendor

A NULL-terminated string that contains the name of the token vendor. This value may be NULL or equal to ReaderVendor if the token is not removable.

TokenSerialNumber

A NULL-terminated string that contains the serial number of the token. This value may be NULL or equal to ReaderSerialNumber if the token is not removable.

TokenHardwareVersion

Hardware version of the token.

TokenFirmwareVersion

Firmware version of the token.

TokenFlags

Bit mask containing information about the token. The flags specified in the mask are as follows:

Token Flags Description
CSSM_CSP_TOK_RNG Token has random number generator
CSSM_CSP_TOK_WRITE_PROTECTED Token is write protected
CSSM_CSP_TOK_LOGIN_REQUIRED User must login to access private objects
CSSM_CSP_TOK_USER_PIN_INITIALIZED User's PIN has been initialized
CSSM_CSP_TOK_EXCLUSIVE_SESSION An exclusive session currently exists
CSSM_CSP_TOK_CLOCK_EXISTS Token has built in clock
CSSM_CSP_TOK_ASYNC_SESSION Token supports asynchronous operations
CSSM_CSP_TOK_PROT_AUTHENTICATION Token has protected authentication path
CSSM_CSP_TOK_DUAL_CRYPTO_OPS Token supports dual cryptographic operations

TokenCustomFlags

Flags defined by the vendor. Consult the individual CSP user's guide for the list of valid flags.

TokenMaxSessionCount

Maximum number of CSP handles referencing the token that may exist simultaneously.

TokenOpenedSessionCount

Number of existing CSP handles referencing the token.

TokenTotalPublicMem

Amount of public storage space in the CSP. This value will be set to CSSM_VALUE_NOT_AVAILABLE if the CSP does not wish to expose this information.

TokenFreePublicMem

Amount of public storage space available for use in the CSP. This value will be set to CSSM_VALUE_NOT_AVAILABLE if the CSP does not wish to expose this information.

TokenTotalPrivateMem

Amount of private storage space in the CSP. This value will be set to CSSM_VALUE_NOT_AVAILABLE if the CSP does not wish to expose this information.

TokenFreePrivateMem

Amount of private storage space available for use in the CSP. This value will be set to CSSM_VALUE_NOT_AVAILABLE if the CSP does not wish to expose this information.

TokenMaxPinLen

Maximum length of passwords that can be used for authentication to the CSP.

TokenMinPinLen

Minimum length of passwords that can be used for authentication to the CSP.

TokenUTCTime

Character array containing the current UTC time value in the CSP. The value is valid if the CSSM_CSP_TOK_CLOCK_EXISTS flag is true. The time is represented in the format YYYYMMDDhhmmssxx (4 characters for the year; 2 characters each for the month, the day, the hour, the minute, and the second; and 2 additional reserved '0' characters).

UserLabel

A NULL-terminated string containing the label of the token.

UserCACertificate

Certificate of the CA.

CSSM_HYBRID_CSPSUBSERVICE_INFO

typedef CSSM_HYBRID_CSPSUBSERVICE_INFO 
                    CSSM_HARDWARE_CSPSUBSERVICE_INFO

CSSM_CSP_WRAPPEDPRODUCTINFO

typedef struct cssm_csp_wrappedproductinfo {
    CSSM_VERSION StandardVersion;
    CSSM_STRING StandardDescription;
    CSSM_VERSION ProductVersion;
    CSSM_STRING ProductDescription;
    CSSM_STRING ProductVendor;
    uint32 ProductFlags;
    uint32 ProductCustomFlags;
} CSSM_CSP_WRAPPEDPRODUCTINFO, *CSSM_CSP_WRAPPEDPRODUCTINFO_PTR;

Definition

StandardVersion

Version of the standard to which the wrapped product complies.

StandardDescription

A CSSM character string containing a text description of the standard to which the wrapped product complies.

ProductVersion

Version of the product wrapped by the CSP.

ProductDescription

A CSSM character string containing a text description of the product wrapped by the CSP.

ProductVendor

A CSSM character string containing the name of the wrapped product's vendor.

ProductFlags

This version of CSSM has no flags defined. This field must be set to zero.

ProductCustomFlags

Flags defined by the vendor. Consult the individual CSP user's guide for the list of valid flags.

CSSM_CSP_FLAGS

A bit mask containing information about the CSP. The mask may be a combination of any of the following:
typedef uint32 CSSM_CSP_FLAGS;

#define CSSM_CSP_STORES_PRIVATE_KEYS
#define CSSM_CSP_STORES_PUBLIC_KEYS
#define CSSM_CSP_STORES_SESSION_KEYS

CSSM_CSPSUBSERVICE

typedef struct cssm_cspsubservice {
    uint32 SubServiceId;
    CSSM_STRING Description;
    CSSM_CSP_FLAGS CspFlags;
    uint32 CspCustomFlags;
    uint32 AccessFlags;
    CSSM_CSPTYPE CspType;
    union cssm_subservice_info{
        CSSM_SOFTWARE_CSPSUBSERVICE_INFO SoftwareCspSubService;
        CSSM_HARDWARE_CSPSUBSERVICE_INFO HardwareCspSubService;
        CSSM_HYBRID_CSPSUBSERVICE_INFO HybridCspSubService;
    } SubServiceInfo;
    CSSM_CSP_WRAPPEDPRODUCTINFO WrappedProduct;
} CSSM_CSPSUBSERVICE, *CSSM_CSPSUBSERVICE_PTR;

Definition

SubServiceId

The sub-service ID required for an attach call to connect a CSP to an individual sub-service within a CSP.

Description

A CSSM character string containing a text description of the sub-service.

CspFlags

CSSM-defined flags indicating the key storage services provided by the CSP.

CspCustomFlags

Flags defined by the vendor. Consult the individual CSP user's guide for the list of valid flags.

AccessFlags

Flags that are required to be provided by the application during an attach call when specifying the sub-service ID given in SubServiceId.

CspType

Identifier that determines the type of CSP information structure referenced by CspInfo. The following values and their corresponding CSP information structures are currently defined.

CSP Information Structure Identifier Structure Type
CSSM_CSP_SOFTWARE CSSM_SOFTWARE_CSPSUBSERVICE_INFO
CSSM_CSP_HARDWARE CSSM_HARDWARE_CSPSUBSERVICE_INFO

SubServiceInfo

A CSP sub-service information structure of the type specified by CspType.

WrappedProduct

A CSSM_CSP_WRAPPEDPRODUCTINFO structure describing a product that is wrapped by the CSP.

Cryptographic Context Operations

The manpages for Cryptographic Context Operations can be found at the end of this chapter.

Cryptographic Sessions and Logon

The manpages for Cryptographic Sessions and Logon can be found at the end of this chapter.

Cryptographic Operations

The manpages for Cryptographic Operations can be found at the end of this chapter.

Miscellaneous Functions

The manpages for Miscellaneous Functions can be found at the end of this chapter.

Extensibility Functions

The CSSM_CSP_PassThrough function is provided to allow CSP developers to extend the crypto functionality of the CSSM API. Because it is only exposed to CSSM as a function pointer, its name, internal to the CSP, can be assigned at the discretion of the CSP module developer. However, its parameter list and return value must match what is shown below. The error codes given in this chapter constitute the generic error codes which may be used by all CSPs to describe common error conditions.

The manpages for Extensibility Functions can be found at the end of this chapter.


Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.
You should also read the legal notice explaining the terms and conditions relating to the CDSA documentation.

Contents Next section Index