Previous section.

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

Service Provider Interface

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 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 makes 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 CSSM_DeleteContext. 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 crypto operations-staged encryption/decryption are an exception in that each update call generates a portion of the result.

Cryptographic Operations

CSSM_RETURN CSP_SignData

CSSM_RETURN CSP_SignDataInit

CSSM_RETURN CSP_SignDataUpdate

CSSM_RETURN CSP_SignDataFinal

Accepts as input a handle to a cryptographic context describing the sign operation and the data to operate on. The result of the completed sign operation is returned in a CSSM_DATA structure.

CSSM_BOOL CSP_VerifyData

CSSM_RETURN CSP_VerifyDataInit

CSSM_RETURN CSP_VerifyDataUpdate

CSSM_BOOL CSP_VerifyDataFinal

Accepts as input a handle to a cryptographic context describing the verify operation and the data to operate on. The result of the completed verify operation is a CSSM_TRUE or CSSM_FALSE.

CSSM_RETURN CSP_DigestData

CSSM_RETURN CSP_DigestDataInit

CSSM_RETURN CSP_DigestDataUpdate

CSSM_RETURN CSP_DigestDataFinal

Accepts as input a handle to a cryptographic context describing the digest operation and the data to operate on. The result of the completed digest operation is returned in a CSSM_DATA structure.

CSSM_CC_HANDLE 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.

CSSM_RETURN CSP_GenerateMac

CSSM_RETURN CSP_GenerateMacInit

CSSM_RETURN CSP_GenerateMacUpdate

CSSM_RETURN CSP_GenerateMacFinal

Accepts as input a handle to a cryptographic context describing the MAC operation and the data to operate on. The result of the completed MAC operation is returned in a CSSM_DATA structure.

CSSM_RETURN CSP_VerifyMac

CSSM_RETURN CSP_VerifyMacInit

CSSM_RETURN CSP_VerifyMacUpdate

CSSM_RETURN CSP_VerifyMacFinal

Accepts as input a handle to a cryptographic context describing the MAC operation and the data to operate on. The result of the completed verify operation is a CSSM_RETURN value.

CSSM_RETURN 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 the output block sizes corresponding to the input sizes for the specified algorithm.

CSSM_RETURN CSP_EncryptData

CSSM_RETURN CSP_EncryptDataInit

CSSM_RETURN CSP_EncryptDataUpdate

CSSM_RETURN CSP_EncryptDataFinal

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.

CSSM_RETURN CSP_DecryptData

CSSM_RETURN CSP_DecryptDataInit

CSSM_RETURN CSP_DecryptDataUpdate

CSSM_RETURN CSP_DecryptDataFinal

Accepts as input a handle to a cryptographic context describing the decryption operation and the data to operate on. The decrypted data is returned in CSSM_DATA structures.

CSSM_RETURN 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.

CSSM_RETURN CSP_GenerateKeyPair

Accepts as input a handle to a cryptographic context describing the generate key operation and attributes of each key in the new keypair. The keys are returned in CSSM_KEY structures.

CSSM_RETURN 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.

CSSM_RETURN 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.

CSSM_RETURN 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 that will be unwrapped.

CSSM_RETURN 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.

CSSM_RETURN 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.

CSSM_RETURN CSP_QueryKeySizeInBits

Accepts as input a handle to a cryptographic context and the key. This function returns a pointer to a data structure containing the keysize and effective keysize in bits.

Cryptographic Sessions and Logon

CSSM_RETURN CSP_Login

Accepts as input a login password and a flag indicating the persistent or non-persistent status of keys and other objects created during the login session. 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.

CSSM_RETURN CSP_Logout

The caller is logged out of the current login session with the designated CSP.

CSSM_RETURN CSP_ChangeLoginPassword

Accepts as input a handle to a CSP, the caller's old login password for that CSP, and the caller's new login password. The old password is replaced with the new password. The caller's current login is terminated and another login session is created using the new password.

Extensibility Functions

CSSM_RETURN CSP_PassThrough

This 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 should be specific to the key format of the private keys stored in the CSP module.

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 http://csrc.ncsl.nist.gov/fips/fips186a.txt respectively.

A DSA public key is represented as a BER-encoding of a sequence list containing:

PrimeModulus;    /* p */
PrimeDivisor;    /* q */
OrderQ;          /* g */
PublicKey;       /* y */

A DSA private key is represented as a BER-encoded sequence list containing:

PrimeModulus;    /* p */
PrimeDivisor;    /* q */
OrderQ;          /* g */
PrivateKey;      /* x */

Data Structures

This section describes the data structures which may be passed to or returned from a CSP function. They will be used by applications to prepare data to be passed as input parameters into CSSM API function calls, that will be passed without modification to the appropriate CSP. The CSP is then responsible for interpreting them and returning the appropriate data structure to the calling application via CSSM. These data structures are defined in the header file <cssmtype.h> distributed with CSSM.

CSSM_CSP_HANDLE

The CSSM_CSP_HANDLE is used to identify the association between an application thread and an instance of a CSP module. It is assigned when an application causes CSSM to attach to a CSP. It is freed when an application causes CSSM to detach from a CSP. The application uses the CSSM_CSP_HANDLE with every CSP function call to identify the targeted CSP. The CSP uses the CSSM_CSP_HANDLE to identify the appropriate application's memory management routines when allocating memory on the application's behalf.
typedef uint32 CSSM_CSP_HANDLE
                    /* Cryptographic Service Provider Handle */

CSSM_DATA

The CSSM_DATA structure is used to associate a length, in bytes, with an arbitrary block of contiguous memory. This memory must be allocated and freed using the memory management routines provided by the calling application via CSSM.
typedef struct cssm_data{
    uint32 Length;  /* in bytes */
    uint8 *Data;
} CSSM_DATA, *CSSM_DATA_PTR

Definition

Length

Length of the data buffer in bytes.

Data

Points to the start of an arbitrary length data buffer.

CSSM_CRYPTO_DATA

typedef struct cssm_crypto_data {
    CSSM_DATA_PTR Param;
    CSSM_CALLBACK Callback;
    uint32 CallbackID;
}CSSM_CRYPTO_DATA, *CSSM_CRYPTO_DATA_PTR

Definition

Param

A pointer to the parameter data and its size in bytes.

Callback

An optional callback routine for the add-in modules to obtain the parameter.

CallbackID

A tag that identifies the callback.

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;  /* Input data block size */
    uint32 SizeOutputBlock; /* Output data block size */
} 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 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 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 Other, CSP defined

Table: Keyblob Type Identifiers

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 specification 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

Table: Keyblob Format Identifiers

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

Table: Key Class Identifiers

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.

KeyUsage

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_PRIVATE_KEY
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.
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.

Table: Key Usage Flags

StartDate

Date from which the corresponding key is valid. All fields of the CSSM_DATA structure are 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 are 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_CALLBACK

typedef CSSM_DATA_PTR (CSSMAPI *CSSM_CALLBACK)
                                    (void *allocRef, uint32 ID);

Definition

allocRef

Memory heap reference specifying which heap to use for memory allocation.

ID

Input data to identify the callback.

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 flag is a valid 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_NOTIFY_CALLBACK

An application uses this data type to request that an add-in module call back into the application to notify it of certain events.
typedef CSSM_RETURN (CSSMAPI *CSSM_NOTIFY_CALLBACK)
    (CSSM_CSP_HANDLE ModuleHandle,
      uint32 Application,
      uint32 Reason,
      void* Param)

Definition

ModuleHandle

Handle of the add-in to which the notification applies.

Application

Application specific context indicator. This value is specified when an add-in module is attached.

Reason

One of the values specified below.
#define CSSM_NOTIFY_SURRENDER  0
#define CSSM_NOTIFY_COMPLETE   1
#define CSSM_NOTIFY_DEVICE_REMOVED  2
#define CSSM_NOTIFY_DEVICE_INSERTED  3

Param

Used by the add-in that triggers the notification to pass relevant information about the notification to the application. This parameter will contain the cryptographic context handle for the CSSM_NOTIFY_SURRENDER/COMPLETE types and zero for the CSSM_NOTIFY_DEVICE_REMOVED/INSERTED types.

CSSM_HANDLEINFO

typedef struct cssm_handleinfo {
    uint32 SlotID;
    uint32 SessionFlags;
    CSSM_NOTIFY_CALLBACK Callback;
    uint32 ApplicationContext;
} CSSM_HANDLEINFO, *CSSM_HANDLEINFO_PTR;

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

Table: Attribute Types

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_KEYEXCH 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

Table: Context Types

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  

Table: Algorithms for a Session Context

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 bits
CSSM_ALGMODE_CBC64 Cipher BlockChaining 64 bits
CSSM_ALGMODE_OFB64 Output Feedback 64 bits
CSSM_ALGMODE_CBC64 Cipher Feedback 64 bits
CSSM_ALGMODE_CBC32 Cipher Feedback 32 bits
CSSM_ALGMODE_CBC16 Cipher Feedback 16 bits
CSSM_ALGMODE_CBC8 Cipher Feedback 8 bits
CSSM_ALGMODE_WRAP  
CSSM_ALGMODE_PRIVATE_WRAP  
CSSM_ALGMODE_RELAYX  
CSSM_ALGMODE_ECB128 Electronic Code Book 128 bits
CSSM_ALGMODE_ECB96 Electronic Code Book 96 bits
CSSM_ALGMODE_CBC128 Cipher Block Chaining 128 bits
CSSM_ALGMODE_OAEP_HASH Algorithm mode for SET key wrapping

Table: PKCS #11 CSP Reader Flags

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;
    uint32 Reserved;
} CSSM_SOFTWARE_CSPSUBSERVICE_INFO,
                          *CSSM_SOFTWARE_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.

CSSM_HARDWARE_CSPSUBSERVICE_INFO

typedef struct cssm_hardware_cspsubservice_info {
    uint32 NubmerOfCapabilities;
    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 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

Table: PKCS #11 CSP Reader Flags

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 t 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

Table: PKCS #11 CSP Token Flags

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

CSSM_HARDWARE_CSPSUBSERVICE_INFO, *CSSM_HARDWARE_CSPSUBSERVICE_INFO_PTR;

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_CSP_TYPE 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 contained in the union. The following values and their corresponding CSP information structures are currently defined.

CSP Information Structure Identifier Structure Type
CSSM_CSP_TYPE_SOFTWARE CSSM_SOFTWARE_CSPSUBSERVICE_INFO
CSSM_CSP_TYPE_HARDWARE CSSM_HARDWARE_CSPSUBSERVICE_INFO

Table: CSP Information Type Identifiers and Associated Structure Types

SoftwareCspSubService or HardwareCspSubService

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

WrappedProduct

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

CSSM_SERVICE_INFO

This structure holds a description of a module service. The service described is of the CSSM service type specified by the module usage type. This structure is defined by CSSM core services and pertains to add-in service providers of all service types. See the CSSM Add-in Module Structure and Administration Specification. for additional descriptions of these CSSM core structure and the definitions of flag values to be specified as values in these structures.
typedef struct cssm_serviceinfo {
    CSSM_STRING Description;    /* Service description */
    CSSM_SERVICE_TYPE Type;     /* Service type */
    CSSM_SERVICE_FLAGS Flags;   /* Service flags */
    uint32 NumberOfSubServices; /* Number of sub services in
                                        SubService List */
    union cssm_subservice_list {
        void *SubServiceList;
        CSSM_CSPSUBSERVICE_PTR CspSubServiceList;
        CSSM_DLSUBSERVICE_PTR  DlSubServiceList;
        CSSM_CLSUBSERVICE_PTR  ClSubServiceList;
        CSSM_TPSUBSERVICE_PTR  TpSubServiceList;
    } SubServiceList;
    void *Reserved;
} CSSM_SERVICE_INFO, *CSSM_SERVICE_INFO_PTR;

Definition

Description

A text description of the service.

Type

Specifies exactly one type of service structure, such as CSSM_SERVICE_CSP, CSSM_SERVICE_CL, and so on.

Flags

Characteristics of this service, such as whether it contains any embedded products.

NumberOfSubServices

The number of elements in the module SubServiceList.

SubServiceList

A list of descriptions of the encapsulated SubServices which are not of the basic service types.

CspSubServiceList

A list of descriptions of the encapsulated CSP SubServices.

DlSubServiceList

A list of descriptions of the encapsulated DL SubServices.

ClSubServiceList

A list of descriptions of the encapsulated CL SubServices.

TpSubServiceList

A list of descriptions of the encapsulated TP SubServices.

Reserved

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

CSSM_MODULE_INFO

This structure aggregates all service descriptions about all service types of a module implementation. The structure is defined by CSSM core services and pertains to add-in service modules of all module types. See the CSSM Add-in Module Structure and Administration Specification for additional descriptions of these CSSM core structure and the definitions of flag values to be specified as values in these structures.
typedef struct cssm_moduleinfo {
    CSSM_VERSION Version;               /* Module version */
    CSSM_VERSION CompatibleCSSMVersion; /* CSSM version the
                                        module is written for*/
    CSSM_GUID_PTR InterfaceGUID; /* opt GUID defining supported
                                        interface */
    CSSM_STRING Description;            /* Module description */
    CSSM_STRING Vendor;                 /* Vendor name */
    CSSM_MODULE_FLAGS Flags;            /* Flags to describe and
                                        control module use */
    CSSM_KEY_PTR AppAuthenRootKeys;     /* Module-specific keys
                                        to authenticate apps */
    uint32 NumberOfAppAuthenRootKeys;   /* Number of module-specific
                                        root keys */
    CSSM_SERVICE_MASK ServiceMask;      /* Bit mask of supported
                                        services */
    uint32 NumberOfServices;            /* Number of services in
                                        ServiceList */
    CSSM_SERVICE_INFO_PTR ServiceList;  /* A list of service info
                                        structures */
    void *Reserved;
} CSSM_MODULE_INFO, *CSSM_MODULE_INFO_PTR;

Definition

Version

The major and minor version numbers of this add-in module.

CompatibleCSSMVersion

The version of CSSM that this module was written to.

InterfaceGUID

GUID describing the interface supported by the version of CSSM that this module was written to.

Description

A text description of this module and its functionality.

Vendor

The name and description of the module vendor.

Flags

Characteristics of this module, such as whether or not it is threadsafe.

AppAuthenRootKeys

Public root keys used by CSSM to verify an application's credentials when the service module has requested authentication based on module-specified root keys by setting the CSSM_MODULE_CALLER_AUTHENTOMODULE bit to true in its CSSM_MODULE_FLAGS mask. These keys should successfully authenticate only those applications that the service module wishes to recognize to receive the services the module has registered with CSSM during module installation.

NumberOfAppAuthenRootKeys

The number of public root keys in the AppAuthenRoot Keys list.

ServiceMask

A bit mask identifying the types of services available in this module.

NumberOfServices

The number of services for which information is provided. Multiple descriptions (as sub-services) can be provided for a single service category.

ServiceList

An array of pointers to the service information structures. This array contains NumberOfServices entries.

Reserved

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

Cryptographic Operations

The manpages for Cryptographic 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.

Extensibility Functions

The KRSP_PassThrough function is provided to allow KRSP developers to extend the key recovery 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 section constitute the generic error codes which may be used by all CSPs to describe common error conditions.

CSP developers may also define their own module-specific error codes, as described in CSSM Add-in Module Structure and Administration Specification.

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


Module Management Functions

The CSP_GetCapabilities and CSP_EventNotify functions are used by the CSSM Core to interact with the CSP module. Because these functions are only exposed to CSSM as function pointers, their names internal to the CSP library can be assigned at the discretion of the CSP module developer. However, their parameter lists and return values must match what is shown below. The error codes given in this section constitute the generic error codes, which may be used by all CSP libraries to describe common error conditions. CSP module developers may also define their own module-specific error codes, as described in the CSSM Add-in Module Structure and Administration Specification.

The manpages for Module Management 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