Previous section.

Common Security: CDSA and CSSM, Version 2 (with corrigenda)
Copyright © 2000 The Open Group

Cryptographic Service Provider Behavior

Introduction

Guidelines for Each Service Provider type

As a growing number of services become available for the CDSA infrastructure, it is important that providers of the same type behave in a common and predictable manner. A set of guidelines for each service provider type must be established to ensure common behavior. Without them, using CDSA provides little or no inherent advantage to application and middleware developers.

This Appendix is designed to serve as a set of behavior guidelines for CDSA Cryptographic Service Provider (CSP) modules. It is written as an "edge specification" relative to the Cryptographic Service Provider SPI, in that it specifies the apparent behavior of the CSP through the SPI interface, but does not specify how the underlying implementation must be done. In this case, the edge is the boundary between the CSSM and the Service Provider, although it also makes references to the boundary between the application and the CSSM, so in this respect it is also an interface specification.

No examples of interface usage are provided in this Appendix, since it is not a "how-to" guide.

Typographic Conventions

When referring to a field inside of a complex structure, the following notation is used:

STRUCTURE_TYPE::FieldName

For example, the AlgorithmId field in the CSSM_KEYHEADER structure is referenced as:


CSSM_KEYHEADER::AlgorithmId

Formats

Key Formats

CDSA Cryptographic Service Providers (CSP) represent keys in three ways:

Plaintext blobs include PKCS #1 RSA public keys, key references include string names, and wrapped key blobs include PKCS #8 encrypted private key blobs.

The following sections list the CSSM_KEYHEADER field values, and the corresponding CSSM_KEY::KeyData contents that they describe.

Plaintext Keys
Plaintext Key Format Descriptor Values for CSSM_KEYHEADER describes the values of the CSSM_KEYHEADER fields and the corresponding plaintext key formats that they represent. A plaintext key format requires that CSSM_KEYHEADER::BlobType is equal to CSSM_KEYBLOB_RAW. When CSSM_KEYHEADER::BlobType is equal to CSSM_KEYBLOB_RAW, CSSM_KEYHEADER::WrapAlgorithmId and CSSM_KEYHEADER::WrapMode should be ignored.

Format
CSSM_KEYBLOB_
RAW_FORMAT_* 		Valid key types CSSM_KEY::KeyData
PKCS1 RSA An RSA public or private key formatted according to the PKCS #1 v2.0 specification.
PKCS3 Diffie-Hellman public key A Diffie-Hellman public key calculated according to PKCS #3 v1.4. The public key format is the public value as an octet string with the most significant byte first (big-endian).
PKCS3 Diffie-Hellman private key A Diffie-Hellman private key calculated according to PKCS #3 v1.4. The private key format is the BER encoded sequence of the p, g, and x values.
MSCAPI All Microsoft CAPI supported A key formatted according to the Microsoft CAPI 2.0 keyblob specification.
PGP All PGP supported A key formatted according to the PGP keyring specification.
FIPS186 DSA A DSA key formatted as a DER sequence of p, q, g, and either y or x for public or private keys respectively.
BSAFE All A key formatted in the RSA BSafe key format.
CCA All A key formatted according to the IBM CCA specification.
PKCS8 All private keys A private key formatted according to PKCS #8 v1.2, without encryption.
SPKI All asymmetric keys A public or private key formatted according to the SPKI specification.
OCTET_STRING All symmetric keys A symmetric key represented as an octet string, with the most significant byte first (big-endian).
OTHER Vendor specific A key formatted according to individual vendor requirements. See individual documentation for format details. This format is not recommended for most CSPs.

Table: Plaintext Key Format Descriptor Values for CSSM_KEYHEADER

Every key type has a default format that is used in the cases where the caller does not specify a specific format type. Default Plaintext Key Formats below lists the defined CSSM algorithms and their default plaintext key formats.

AlgorithmId
CSSM_ALGID_* 		Format
CSSM_KEYBLOB_RAW_FORMAT_*
RSA PKCS1
DSA FIPS186
DH PKCS3
All symmetric key algorithms OCTET_STRING

Table: Default Plaintext Key Formats
Key References
Key Reference Format Descriptor Values for CSSM_KEYHEADER below describes the values of the CSSM_KEYHEADER fields and the corresponding key reference formats that they represent. A key reference format requires that CSSM_KEYHEADER::BlobType is equal to CSSM_KEYBLOB_REFERENCE. When CSSM_KEYHEADER::BlobType is equal to CSSM_KEYBLOB_REFERENCE, CSSM_KEYHEADER::WrapAlgorithmId and CSSM_KEYHEADER::WrapMode should be ignored.

Format
CSSM_KEYBLOB_
REF_FORMAT_* 		Valid key types CSSM_KEY::KeyData
INTEGER All An integer value of any length, and any byte-sex.
STRING All A valid RFC2279 (UTF8) string that corresponds to the "Label" attribute of a key in a DL schema, and the Label parameter to the CSSM_GenerateKey() or CSSM_GenerateKeyPair() API. UTF8 degrades to ASCII for english text.
SPKI All asymmetric keys A key reference as defined in the SPKI specification. It has the form
(public-key (hash)) or (private-key (hash))
OTHER Vendor specific A key reference formatted according to individual vendor requirements. See individual documentation for format details.

Table: Key Reference Format Descriptor Values for CSSM_KEYHEADER

Integer references, CSSM_KEYBLOB_REF_FORMAT_INTEGER, are domain specific to a specific service provider, and must not be interpreted by a client. A client must consider a reference of this type to become invalid as soon as the CSP handle used to instantiate the reference is invalidated using the CSSM_ModuleDetach() API. Even though the reference becomes invalid, the memory for the reference must still be released using the CSSM_FreeKey() API.

String references, CSSM_KEYBLOB_REF_FORMAT_STRING, are valid for the lifetime of the key that they reference. For instance, if the key is instantiated with the CSSM_KEYATTR_PERMANENT flag, then the reference is valid until CSSM_FreeKey() is called with the Delete parameter set to CSSM_TRUE. If the key is instantiated without the CSSM_KEYATTR_PERMANENT flag, then the key will be destroyed and the reference invalidated by the CSP when the CSP handle used to instantiate the key is detached. As with integer references, the memory for the reference must be released using the CSSM_FreeKey() API, regardless of whether or not the reference is valid.

SPKI references, CSSM_KEYBLOB_REF_FORMAT_SPKI, have the same lifetimes and deletion requirements as string references.

Vendor specific references, CSSM_KEYBLOB_REF_FORMAT_OTHER, have lifetime behavior that is specific to a certain CSP. They have the same deletion requirements as all other reference types.

The default reference type is CSP specific. The application can safely treat a reference of an unknown type as if it is an integer reference since it has the most restrictive lifetime semantics.

Wrapped Keys
Wrapped Key Format Descriptor Values for CSSM_KEYHEADER below describes the values of the CSSM_KEYHEADER fields and the corresponding wrapped key formats that they represent. A wrapped key format requires that:

Format
CSSM_KEYBLOB_
WRAPPED_FORMAT_* 		Valid key types CSSM_KEY::KeyData
PKCS8 All private keys A private key in formatted and encrypted according to PKCS #8 v1.2. This format is used to wrap asymmetric keys using a symmetric algorithm
PKCS7 All symmetric keys A symmetric key encrypted as required by PKCS #7 v1.5. This format is used to wrap symmetric keys using either symmetric or asymmetric algorithms.
MSCAPI All Microsoft CAPI supported A key formatted and encrypted according to the Microsoft CAPI 2.0 keyblob specification.
OTHER Vendor specific A key formatted and encrypted according to individual vendor requirements. See individual documentation for format details. This format is not recommended for most CSPs.

Table: Wrapped Key Format Descriptor Values for CSSM_KEYHEADER

PKCS #7 wrapping, CSSM_KEYBLOB_WRAPPED_FORMAT_PKCS7, wraps only the raw key value of the symmetric key. None of the information in the CSSM_KEYHEADER structure is encryted with the key. All information in the key header of the key to be wrapped is copied to the wrapped key structure, and updated as necessary by the wrapping operation.

PKCS #8 wrapping, CSSM_KEYBLOB_WRAPPED_FORMAT_PKCS8, wraps only the information specified in the PKCS #8 specification. None of the information in the CSSM_KEYHEADER structure is encryted with the key. All information in the key header of the key to be wrapped is copied to the wrapped key structure, and updated as necessary by the wrapping operation.

ASN.1 Structures for PKCS #8 Wrapping
Unlike RSA, some commonly used algorithms do not have an ASN.1 structure defined for use with PKCS #8. PKCS #1 defines the RSAPrivateKey structure for wrapping RSA private keys with PKCS #8. The following text defines the ASN.1 structure used to wrap keys for other algorithms.

Diffie-Hellman Private Keys

Wrapping a Diffie-Hellman private key uses the DHParameter structure defined in PKCS #3 to embed the p and g values into the privateKeyAlgorithmIdentifier field of the PrivateKeyInfo structure. The private value, x, is placed in the privateKey field BER encoded as BER type INTEGER.

DSA Private Keys

Wrapping a DSA private key uses the Dss-parms structure defined in PKCS #11 v2.01 to embed the p, q, and g values into the privateKeyAlgorithmIdentifier field of the PrivateKeyInfo structure. The private value, x, is placed in the privateKey field BER encoded as BER type INTEGER.

Requesting Key Format Types

The CSSM API provides a method for requesting a key format that allows varying degrees of control. The method involves specifying two levels of detail that build on each other.

The first level of detail is the easiest to use, and implement in a CSP, but provides only limited amounts of control over the key format. All CSP APIs that instantiate a key object have a parameter KeyAttr ( PublicKeyAttrandPrivateKeyAttr for CSSM_GenerateKeyPair()). A series of flags is defined to allow the application to define the class of key format to return. The application may choose to receive a CSSM_KEY structure containing a plaintext key, a key reference, or "no data". The CSP may choose to return the key in any format within the specified class.

Key Attribute Format Flags and Corresponding Format Class below lists the defined format flags and the corresponding format class. If more than one of the flags is set, the CSP will return the error CSSM_CSP_INVALID_KEYATTR. If the CSP can not support the requested class of key format, it will return CSSM_CSP_KEY_FORMAT_UNSUPPORTED.

Key Attribute Format Flag CSP to return format class
CSSM_KEYATTR_RETURN_DATA Plaintext key
CSSM_KEYATTR_RETURN_REF Key reference
CSSM_KEYATTR_RETURN_NONE No data

Table: Key Attribute Format Flags and Corresponding Format Class

The second level of detail for specifying the key format provides fine control over the value returned. Fine control requires that one of the attribute types listed in APIs and the Appropriate Key Format Attributes below is located in the Cryptographic Context (CC) used by the CSP to instantiate the key object. The attribute used depends on the type of key being instantiated. The format types allowed for all unwrapped keys are those that begin with CSSM_KEYBLOB_RAW_FORMAT_* and CSSM_KEYBLOB_REF_FORMAT_* for plaintext keys and key references respectively. The format specifier in the CC attribute must be valid for the format class specified in the KeyAttr mask.

Format types allowed for wrapped keys are those that begin with CSSM_KEYBLOB_WRAPPED_FORMAT_*. Note that the CSSM_WrapKey() API only uses the CC attribute without a key format class flag because the class is implied by the operation.

Cryptographic Context Attribute
CSSM_ATTRIBUTE_* 		Valid for APIs
PUBLIC_KEY_FORMAT CSSM_GenerateKeyPair()  
PRIVATE_KEY_FORMAT CSSM_GenerateKeyPair()
CSSM_UnwrapKey()  
SYMMETRIC_KEY_FORMAT CSSM_GenerateKey()
CSSM_UnwrapKey()
CSSM_DeriveKey()  
WRAPPED_KEY_FORMAT CSSM_WrapKey()  

Table: APIs and the Appropriate Key Format Attributes

If the application chooses "no data", the CSP instantiates the key in its persistent storage but returns no reference. The CSP will return the error CSSM_CSP_INVALID_KEYATTR if "no data" is requested without setting the CSSM_KEYATTR_PERMANENT flag. All key format attributes in a CC are ignored if "no data" is returned. A key wrapping operation may not specify "no data".

Events

One of the ways that a service provider and the CSSM communicate is by using events. All service providers send events to the CSSM, but CSPs also have the ability to receive events from the CSSM.

Receiving Context Events

The CSSM sends an event to the CSP whenever the client manipulates a cryptographic context (CC). The events indicate that a context is being created, deleted, or updated. The CSSM uses the CSP_EventNotify() SPI function to send context events to the CSP. For this reason, the CSP_EventNotify() SPI must be implemented by all CSPs. The reactions to all but the delete event are CSP specific, but suggestions are given here.

The create event, CSSM_CONTEXT_EVENT_INSERT, is sent to the CSP whenever the client calls one of the CSSM_CSP_Create*Context APIs. The CSSM passes a copy of the new CC and the new CC handle along with the event. At this point, the CSP has the ability to check the CC and reject its contents by returning an error. If the CC is rejected, then the CSSM will fail the context creation call. The CSP is not required to check the CC at this point. If the check is not made when the CC is created, then the check must be performed the first time it is used.

The update event, CSSM_CONTEXT_EVENT_UPDATE, is sent to the CSP whenever the client calls the CSSM_UpdateContextAttributes() or CSSM_SetContext() APIs. The CSSM sends a copy of the modified CC to the CSP along with the event. At this point, the CSP has the ability to check the modified CC and reject the contents by returning an error. If the CC is rejected, the updates are not applied by the CSSM. The CSP is not required to check the CC at this point. If the check is not made when the context is created, then the check must be performed the first time it is used with the updated attributes. The CSP is not required to accept changes to a CC that is currently being used to perform a staged operation. It can return the error CSSM_CSP_CONTEXT_BUSY to indicate that the changes can not be accepted. If it accepts the changes while the CC is being used, then the changes are not used by the CSP until the current operation completes and the client starts another operation using the context.

The delete event, CSSM_CONTEXT_EVENT_DELETE, is sent to the CSP whenever the client calls the CSSM_DeleteContext() API. The CSSM sends a copy of the current CC to the CSP along with the event. Deleting a CC has the effect of canceling any operations that use it. The CSP must insure that all state information associated with the CC in the CSP is destroyed. The CSP does not have the ability to reject this operation. Deleting a CC always succeeds. An error can be returned to the CSSM, but the operation will always complete.

Sending Insert and Remove Events

A service provider sends insert and remove events to indicate that a subservice is available or unavailable for use by a client respectively. Clients cannot attach to a subservice until an insert event for that subservice has been sent to the CSSM. Once a remove event has been sent for a subservice, all module handles to that subservice are invalidated by the CSSM and the client can no longer attach to the subservice until another insert event is sent.

A service provider module is required to send an insert event, CSSM_NOTIFY_INSERT, to the CSSM for each subservice that it provides regardless of whether or not that subservice can be removed. This allows the CSSM to implement a common interaction model for all service provider modules. If the module implements multiple module types for the same subservice ID, they should both be included in the same insert event. If two module types are implemented for the same subservice ID, the services should be related. For instance, a smartcard module will probably provide both CSP and DL services for the same subservice ID. This is a valid re-use of a subservice ID. A module that interfaces to a database and a totally independent cryptographic library should place those services on different subservice IDs. The CSSM will fail events that break this rule.

The following example shows both correct and incorrect use of the events and subservice IDs. In the examples, CssmNotifyCallback() is a function with type CSSM_API_ModuleEventHandler() and ADDIN_GUID is the GUID of the service provider module. 



 

/* Typical usage. A single service type with a single subservice ID. */ 
CssmNotifyCallback( &ADDIN_GUID,
                    CssmNotifyCallbackCtx, 
                    0, 
                    CSSM_SERVICE_CSP,
                    CSSM_NOTIFY_INSERT ); /* Correct */

/* Usage by a module that exports multiple service types using the */
/* SAME subservice ID.                                             */ 

/* Correct usage, services are related and allowed to share an SSID  */ 
CssmNotifyCallback( &ADDIN_GUID,
                    CssmNotifyCallbackCtx, 
                    1, 
                    CSSM_SERVICE_CSP | CSSM_SERVICE_DL, 
                    CSSM_NOTIFY_INSERT );

/* Incorrect usage, the second event fails, services are not related */
CssmNotifyCallback( &ADDIN_GUID,
                    CssmNotifyCallbackCtx, 
                    2, 
                    CSSM_SERVICE_CSP,
                    CSSM_NOTIFY_INSERT );
CssmNotifyCallback( &ADDIN_GUID,
                    CssmNotifyCallbackCtx, 
                    2, 
                    CSSM_SERVICE_DL,
                    CSSM_NOTIFY_INSERT );

If a service provider implements subservices that are always available (like most software-only service providers), then the insert events must be sent to the CSSM when the service provider is handling the CSSM_SPI_ModuleLoad() interface. The events should be sent every time the CSSM_SPI_ModuleLoad() interface is called. It may cause duplicate events to be sent to some event handling functions in the client, but it allows modules loading the service provider for the first time to obtain a complete picture of the available subservices.

Remove events, CSSM_NOTIFY_REMOVE, are used much more sparingly than the corresponding insert events. They are used to indicate that a removable device is no longer available. The definition of "remove" is service provider specific but the result is always the same, the subservice is no longer available to the client. Remove events should not be sent to the CSSM when the CSSM_SPI_ModuleUnload() interface is called. Even though reversing all module loads will cause a subservice (actually, the whole service provider) to become unavailable to the client, it is not a service provider initiated action. Client initiated actions will never trigger a remove event.

Sending Fault Events

A fault event, CSSM_NOTIFY_FAULT, indicates that a dangerous situation, usually an integrity error, has been detected by the service provider and that the CSSM must immediately sever all connections and cause the operating system to remove the binary from the process space. This has the effect of canceling all attach and load operations performed on the service provider. The client must attempt to reestablish all connections to the service provider if it requires those services.

The CSSM will most likely avoid calling any interfaces in the service provider after receiving a fault event to avoid executing any unstable, or altered code. Therefore, the service provider should insure that it has cleaned up all internal resources before sending the fault event to the CSSM.

Memory Management

CSP service providers have the most complex memory management tasks compared to the other standard CDSA service provider types. Most service providers will allocate the memory for all of the return data, and provide appropriate APIs to release that memory. CSPs have situations where either the client or the service provider can do the memory allocation. The follow subsections describe the methods that should be used by CSPs to handle memory.

Types of Memory Allocation

The CDSA architecture defines two ways for service providers to manage memory. The first is through the use of a local memory heap. The functions that manipulate the local heap are called the local memory functions. The second method is to use a set of memory allocation functions in the CSSM that will allocate memory suitable for being returned to the client. These functions are called the applicationmemoryfunctions", and are given to the service provider by the CSSM using the CSSM_SPI_ModuleAttach() interface.

Service providers should use the local heap for all internal memory requirements. Internal memory requirements include any memory required to perform an operation that will not be returned to the client. This provides higher performance, and reduces exposure of internal data outside of the service provider.

Any memory that will be returned to the client must be allocated using the application memory functions given to the service provider by the CSSM. The memory obtained this way is guaranteed to be allocated in a way that will allow the client to release them when they are no longer needed.

Allocation of Key Information

All functions that return a key allocate a memory buffer for the CSSM_KEY::KeyData field, unless the return type is CSSM_KEYATTR_RETURN_NONE. The CSP will always allocate this buffer, regardless of the state of the CSSM_KEY::KeyData.Data pointer. The client does not have the option to allocate this buffer. The memory must be allocated using the application memory functions.

The CSSM_FreeKey() API releases the resources in a CSSM_KEY structure, and optionally deletes the key material from the CSPs internal storage. The CSP will always release the buffer referenced by the CSSM_KEY::KeyData.Data pointer, and set the pointer to NULL. The memory must be released using the application memory functions.

Allocation of Single Output Buffers

In cases where the output from a function is a single buffer, the application has the option of allocating its own memory. The CSP determines whether or not to allocate memory using the application memory functions according to Actions Taken when Returning Values in a Single Buffer below. The value of CSSM_DATA::Data is shown on the left, and the value of CSSM_DATA::Length is shown across the top.

Length 0 >
_    
Data    
NULL Allocate required memory Error
= CSSM_CSP_INVALID_INPUT_POINTER
!NULL Error
= CSSM_CSP_INVALID_INPUT_POINTER 		Use supplied memory
Error
= CSSM_CSP_INVALID_INPUT_LENGTH
if not suitable size

Table: Actions Taken when Returning Values in a Single Buffer

Allocation of Vector-of-Buffers

A vector-of-buffers is an array of CSSM_DATA structures. They are used for both input and output in multiple CSP APIs. The CSP must treat the individual memory buffers in the vector as if they make up a single continuous memory buffer.

When filling an output vector, each component buffer is completely filled before placing any data in the next buffer of the array. None of the length values for the component buffers can be modified by the CSP. The output length parameter that accompanies each output vector must be used to indicate the total number of bytes placed in the output vector.

The CSP should only allocate memory if all of the entries in the vector have a NULL data pointer and a zero length. If memory is allocated, a single output buffer with enough space for the output should be allocated and assigned to the first array element's data pointer. The memory must be allocated using the application memory functions.

CSP Query Mechanisms

CSPs provide three interfaces for querying the current state of the service provider, or one of the operations being performed.

Querying Key Sizes

The CSP_QueryKeySizeInBits() SPI (.Fn CSSM_QueryKeySizeInBits API) is used to get the logical and effective size of a key. The logical size of the key is the number of bits in the key data for a symmetric key, or the size of the key component commonly used to reference the size of an asymmetric key. The effective size of a key is the number of bits in a key that are actually used in the cryptographic operation. For instance, the logical size of a DES key is 64, and the effective size of the same key is 56. Differences in logical and effective sizes will be notes in Algorithm Reference.

The key can be supplied to the function directly or in a cryptographic context. The size of the key must be calculated by looking at the key data itself. The key header information should not be used to calculate the values.

Querying Output Sizes

The CSP_QuerySize() SPI (.Fn CSSM_QuerySize API) is used to query the size of the output buffer required to hold the result of a cryptographic operation. The CSP must take into account any applicable information including the block size, number of bytes required to complete a block, padding data, the amount of the data being input to the function, and any other algorithm specific information. If the algorithm has a block size, then the size reported may be up to one block size larger than the actual result.

Behavior of CSP_QuerySize for all supported Operation Types below describes the behavior for each supported cryptographic operation type. The CSP returns the error CSSM_CSP_INVALID_CONTEXT if a query is made for an unsupported operation.

Operation Type Encrypt Parameter Result
Encrypt CSSM_TRUE Returns the output size of the next operation.
_ _  
Decrypt CSSM_FALSE If the cryptographic context (CC) used to perform the operation is currently being used to perform a staged operation, then the output is based on the current state of the algorithm. If the CC is not being used to perform a staged operation, then the result is based on a single stage operation.
Digest No effect Always returns the length of the digest output regardless of the algorithm state. This value is also available by fetching the CSSM_ATTRIBUTE_OUTPUT_SIZE attribute for the corresponding capability information in the MDS.
Generate MAC CSSM_TRUE Always returns the length of the signature output regardless of the algorithm state. For MAC algorithms that always generate the same size signature, this value is also available by fetching the CSSM_ATTRIBUTE_OUTPUT_SIZE attribute for the corresponding capability information in the MDS.
Verify MAC CSSM_FALSE Always returns zero.
Sign CSSM_TRUE Always returns the length of the signature output regardless of the algorithm state. For signature algorithms that always generate the same size signature (i.e. DSA), this value is also available by fetching the CSSM_ATTRIBUTE_OUTPUT_SIZE attribute for the corresponding capability information in the MDS.
Verify CSSM_FALSE Always returns zero.

Table: Behavior of CSP_QuerySize for all supported Operation Types

Querying State of the CSP Subservice

The current state of the CSP subservice can be determined using the CSP_GetOperationalStatistics() SPI (.Fn CSSM_CSP_GetOperationalStatistics API). CSSM_CSP_OPERATIONAL_STATISTICS Structure describes the meaning of each field in the CSSM_CSP_OPERATIONAL_STATISTICS structure.

Field Name Description
UserAuthenticated This field will be set to CSSM_TRUE if the client has authenticated to the subservice using the CSP_Login() SPI (.Fn CSSM_CSP_Login API).
DeviceFlags This field is described in detail in CSSM_CSP_OPERATIONAL_STATISTICS::DeviceFlags Field.
TokenMaxSessionCount Indicates the maximum number of simultaneous attach handles that can be issued for the subservice.
TokenOpenedSessionCount Indicates the number of attach handles that have already been issued for the subservice.
TokenMaxRWSessionCount Indicates the maximum number of simultaneous read/write attach handles that can be issued for the subservice. By default, attach handles are created in read/write mode.
TokenOpenedRWSessionCount Indicates the number of read/write attach handles that have already been issued for the subservice.
TokenTotalPublicMem Indicates the amount of storage space that can be used to store objects that are usable without the client authenticating to the subservice using the CSP_Login() SPI.
TokenFreePublicMem Indicates the amount of storage space that has been used to store objects that are usable without the client authenticating to the subservice using the CSP_Login() SPI.
TokenTotalPrivateMem Indicates the amount of storage space that can be used to store objects that are not usable without the client authenticating to the subservice using the CSP_Login() SPI.
TokenFreePrivateMem Indicates the amount of storage space that has been used to store objects that are not usable without the client authenticating to the subservice using the CSP_Login() SPI.

Table: CSSM_CSP_OPERATIONAL_STATISTICS Structure

Any of the Token* fields can have the value CSSM_VALUE_NOT_AVAILABLE to indicate that the CSP does not use these values, or that it will not reveal the values. The values are primarily applicable to hardware cryptographic devices.

The DeviceFlags field can be a mask of the values listed in CSSM_CSP_OPERATIONAL_STATISTICS::DeviceFlags Field below.

Field Name Description
CSSM_CSP_TOK_WRITE_PROTECTED The meaning of this flag varies by service provider. In some service providers, no objects may be created, deleted, or modified. In others, permanent objects may not be manipulated but transient objects may be freely created.
CSSM_CSP_TOK_LOGIN_REQUIRED The CSP requires the client to authenticate to the subservice before cryptographic operations other than random number generation and message digest calculation.
CSSM_CSP_TOK_USER_PIN_INITIALIZED If the subservice requires authentication before cryptographic operations can be performed, it indicates that the authentication data for the client has been initialized.
CSSM_CSP_TOK_PROT_AUTHENTICATION The subservice provides a protected mechanism for collecting authentication information.
CSSM_CSP_TOK_USER_PIN_EXPIRED If the subservice requires authentication before cryptographic operations can be performed, it indicates that the authentication data for the client has expired and must be changed before it can be used.
CSSM_CSP_TOK_SESSION_KEY_PASSWORD Indicates that the subservice supports separate authentication data for individual symmetric keys.
CSSM_CSP_TOK_PRIVATE_KEY_PASSWORD Indicates that the subservice supports separate authentication data for individual private keys.
CSSM_CSP_STORES_PRIVATE_KEYS Indicates that private keys can be stored permanently by the subservice.
CSSM_CSP_STORES_PUBLIC_KEYS Indicates that public keys can be stored permanently by the subservice.
CSSM_CSP_STORES_SESSION_KEYS Indicates that session keys can be stored permanently by the subservice.
CSSM_CSP_STORES_CERTIFICATES Indicates that certificates can be stored permanently by the subservice. This flag can only be set by a multi-service module that also implements a DL interface.
CSSM_CSP_STORES_GENERIC Indicates that generic data objects can be stored permanently by the subservice. This flag can only be set by a multi-service module that also implements a DL interface.

Table: CSSM_CSP_OPERATIONAL_STATISTICS::DeviceFlags Field

Client Authentication and Authorization

Client authentication and authorization in Cryptographic Service Providers (CSPs) has two forms:

Many CSPs will implement one form or the other, but they are not mutually exclusive. Each authentication mechanism has its own functional properties that make it useful.

Client Login ACLs

Client login ACLs protect resources in the CSP that affect the subservice as a whole. All authorizations granted to a subservice using the CSP_Login() SPI (.Fn CSSM_CSP_Login API) can be utilized using any CSP handle issued to the same process1. Authorizations granted using client login ACLs are cancelled in the following situations:

  1. The CSP_Logout() SPI (.Fn CSSM_CSP_Login API) is called the same number of times as the CSP_Login() SPI

  2. All CSP handles to the subservice in the process have been invalidated using the CSSM_SPI_ModuleDetach() SPI (.Fn CSSM_ModuleDetach API).

If the CSP supports client login ACLs, then it must set the CSSM_CSP_TOK_LOGIN_REQUIRED flag in the CSSM_CSP_OPERATIONAL_STATISTICS::DeviceFlags field.

Client login ACLs control the visibility of some keys stored in the CSP. Keys with the CSSM_KEYATTR_PRIVATE flag set in their CSSM_KEY::KeyHeader.KeyAttr field are not visible to the client until it has authenticated to the subservice. As a result, functions such as CSP_ObtainPrivateKeyFromPublicKey() will not succeed in finding private keys with the CSSM_KEYATTR_PRIVATE flag set until the client has authenticated using CSP_Login().

Client login ACLs also control the ability to use the subservice for cryptographic operations. If the CSSM_CSP_TOK_LOGIN_REQUIRED flag is set, then the client must authenticate to the subservice before operations other than random number generation and message digesting can be performed.

Managing Client Login ACLs
ACL Contents
The contents of a client login ACL can be fetched using the CSP_GetLoginAcl() SPI (.Fn CSSM_CSP_GetLoginAcl API). The CSP must filter the set of returned ACL entries based on the SelectionTag parameter. The CSP must allocate all memory for the ACL information structures using the application memory functions, and fill in the NumberOfAclInfos with the number of allocated structures. If either the AclInfos or NumberOfAclInfos parameters are NULL, then the CSP will return the error CSSM_CSP_INVALID_OUTPUT_POINTER. If there are no matching ACL information structures, then the CSP sets the NumberOfAclInfos parameter to zero and leaves the AclInfos value untouched. If the CSP does not support client login ACLs, then it returrns the error CSSM_CSP_OBJECT_ACL_NOT_SUPPORTED.

The contents of a client login ACL can be modified by the ACL owner using the CSP_ChangeLoginAcl() SPI (.Fn CSSM_CSP_ChangeLoginAcl API). If the requested edit mode is not supported by the CSP, then it returns CSSM_CSP_INVALID_ACL_EDIT_MODE.

ACL Owner
The subject of the ACL owner is the entity that has the right to change the contents of the client login ACL. The value of the ACL owner subject is initialized in a CSP specific manner outside the scope of the CSP SPI.

The contents of a client login owner ACL can be fetched using the CSP_GetLoginOwner() SPI (.Fn CSSM_CSP_GetLoginOwner API). The CSP must allocate all memory for the ACL owner information structure using the application memory functions. If the Owner parameter is NULL, then the CSP returns the error CSSM_CSP_INVALID_OUTPUT_POINTER. If the CSP does not support client login ACLs, then it returns the error CSSM_CSP_OBJECT_ACL_NOT_SUPPORTED.

The contents of a client login ACL owner can be modified by the subject of the ACL owner using the CSP_ChangeLoginOwner() SPI (.Fn CSSM_CSP_ChangeLoginOwner API). If the requested edit mode is not supported by the CSP, then it returns CSSM_CSP_INVALID_ACL_EDIT_MODE.

Individual Key ACLs

Individual key ACLs protect and control the usage of individual symmetric or private keys. All authorizations granted to a client for a key are only valid until a single operation using the key has completed. Authorizations granted using individual key ACLs are cancelled in the following situations:

  1. The operation using the key completes

  2. The cryptographic context that uses the key is deleted

If the CSP supports individual key ACLs, then it must set at least one of the CSSM_CSP_TOK_SESSION_KEY_PASSWORD and CSSM_CSP_TOK_PRIVATE_KEY_PASSWORD flags in the CSSM_CSP_OPERATIONAL_STATISTICS::DeviceFlags field to indicate what key types can be protected using individual key ACLs. Public keys never require ACLs.

Individual key ACLs control the ability of clients to use the key for a specific purpose. Since individual key ACLs control the use of the key they protect, the operations listing in the ACL must match the list of operations found in the CSSM_KEY::KeyHeader.KeyUsage field (or specified to a key creation API).

ACL Contents
The contents of an individual key ACL can be fetched using the CSP_GetKeyAcl() SPI (.Fn CSSM_CSP_GetKeyAcl API). The CSP must filter the set of returned ACL entries based on the SelectionTag parameter. The CSP must allocate all memory for the ACL information structures using the application memory functions, and fill in the NumberOfAclInfos with the number of allocated structures. If either the AclInfos or NumberOfAclInfos parameters are NULL, then the CSP returns the error CSSM_CSP_INVALID_OUTPUT_POINTER. If there are no matching ACL information structures, then the CSP sets the NumberOfAclInfos parameter to zero and leaves the AclInfos value untouched. If the CSP does not support individual key ACLs, then it returns the error CSSM_CSP_OBJECT_ACL_NOT_SUPPORTED.

The contents of an individual key ACL can be modified by the ACL owner using the CSP_ChangeKeyAcl() SPI (.Fn CSSM_CSP_ChangeKeyAcl API). If the requested edit mode is not supported by the CSP, then it returns CSSM_CSP_INVALID_ACL_EDIT_MODE.

ACL Owner
The subject of the ACL owner is the entity that has the right to change the contents of the client login ACL. The value of the ACL owner subject is initialized to the ACL subject specified in the initial ACL for the key.

The contents of a client login owner ACL can be fetched using the CSP_GetKeyOwner() SPI (.Fn CSSM_CSP_GetKeyOwner API). The CSP must allocate all memory for the ACL owner information structure using the application memory functions. If the Owner parameter is NULL, then the CSP returns the error CSSM_CSP_INVALID_OUTPUT_POINTER. If the CSP does not support client login ACLs, then it returns the error CSSM_CSP_OBJECT_ACL_NOT_SUPPORTED.

The contents of an individual key ACL owner can be modified by the subject of the ACL owner using the CSP_ChangeKeyOwner() SPI (.Fn CSSM_CSP_ChangeKeyOwner API). If the requested edit mode is not supported by the CSP, then it returns CSSM_CSP_INVALID_ACL_EDIT_MODE.

Protected Authentication Paths

Some CSPs have the ability to collect authentication information using a method that does not reveal the information to the host system. These methods are usually only found in CSPs that are implemented in hardware or as hybrid hardware/software modules. When an ACL indicates that the subject of an authorization group is a protected value, such as a protected password, the client must supply a CSSM_ACCESS_CREDENTIALS structure listing the subject type but no value, or a CSSM_ACCESS_CREDENTIALS structure that only specifies a challenge callback. A CSP never calls a challenge callback to obtain a protected value.

Module Directory Service Information

The Module Directory Service (MDS) contains information about each service provider. The information is used by the CSSM and its clients to locate a service provider and determine its capabilities. This section lists each MDS relation related to a CSP and describes how the record or records for the service provider must be populated. If the service provider implements dynamic subservices, there is also a description of how each relation must be updated when handling module events.

Common Relation

Every service provider, regardless of type, must register a single record in this relation. When a client calls CSSM_ModuleLoad() the CSSM searches this relation for a record with a matching ModuleId GUID value. When it finds the record it uses the ModuleName, ModulePath, and Manifest fields to verify and load the module.

Field Name Contents
ModuleId GUID (in string format) uniquely identifying the service provider.
Manifest Signed manifest describing the service provider binary. If the service provider implements the Module Services and Administration (MSA) interfaces (i.e. CSSM_SPI_Load(), CSSM_SPI_Attach() ) and the module interface functions (i.e. CSP_SignData()) in different binaries, then this manifest describes the binary that implements the MSA functions.
ModuleName File name of the service provider binary without the system path information.
Path List of system paths where the module might be found. The format of the list is system dependent. The paths will be searched in order until the module is found. This path is used to find all binaries required for the service provider.
Version CSSM interface version implemented by the service provider. This must be a text representation of the CSSM_MAJOR and CSSM_MINOR constants in the form "X.Y".
Desc Human readable text string describing the service provider.
DynamicFlag Boolean flag indicating whether or not the service provider implements dynamic services. Zero indicates static services and a non-zero value indicates dynamic services. See Sending Insert and Remove Events (Sending Insert and Remove Events) for more information on dynamic services.
MultiThreadFlag Boolean flag indicating whether or not the CSSM should allow multiple threads to call the service provider at the same time. Zero indicates that the CSSM should synchronize all threads making requests to the service provider, non-zero indicates that any number of threads are allowed to execute at the same time.

Note:
This functionality is deprecated and may be removed in future implementations of the CSSM. All service providers should insure thread-safe operation on their own and set this value to a non-zero value. In the situation where multiple CSSM modules are present in the same process, there is no way for the modules to synchronize their operation and guarantee that only a single thread is executing in the service provider. The result is that the flag limits the number of threads to one per loaded CSSM.

ServiceMask Service Mask of all service types supported by the service provider. The value of the mask is the bitwise logical OR of constants defined for the CSSM_SERVICE_MASK type.

Table: Contents of CDSA Common MDS Relation

This record should remain static once the service provider is installed.

CSP Primary Relation

Service provider modules that export a CSP interface must register a single record in this relation for each CSP subservice that they export. When a client calls CSSM_ModuleAttach() for a CSP, the CSSM searches this relation for a record with a matching ModuleId GUID and SSID subservice ID value. When it finds the record it uses the ModuleName and Manifest fields along with the ModulePath field from the CDSA Common Relation to verify and load the subservice binary for the module. If the service provider is implemented using a single binary, then the CSSM simply uses the library that is already loaded instead of attempting to reload the binary a second time.

Software CSPs that implement a single static subservice should use a i SSID value of zero. CSPs that implement dynamic subservices can use any SSID including zero. A CSP should typically allocate a new SSID value for each logical service. For instance, a smartcard CSP should allocate an SSID value for each card reader slot present on the system.

Field Name Description
ModuleID GUID (in string format) uniquely identifying the service provider. This value must be the same as the ModuleId field in the CDSA Common Relation record.
SSID Subservice ID. This value can be any unsigned 32-bit value. If the CSP implements a single static subservice, this value should be zero. If the CSP implements one or more dynamic subservices, then this value can be any value including zero.
Manifest Signed manifest describing the service provider binary that implements the subservice. If the service provider implements the Module Services and Administration (MSA) interfaces (i.e. CSSM_SPI_Load(), CSSM_SPI_Attach()) and the module interface functions (i.e. CSP_SignData()) in different binaries, then this manifest describes the binary that implements the CSP functions for the subservice. If the entire service provider is implemented as a single binary, the most common case, then this value should be a copy of the value in the CDSA Common Relation record.
ModuleName File name of the service provider binary without the system path information. The ModulePath value in the CDSA Common relation record will be used as the search path to find the binary.
Version CSSM interface version implemented by the service provider. This must be a text representation of the CSSM_MAJOR and CSSM_MINOR constants in the form "X.Y".
Vendor Service provider vendor name in ASCII text.
CspType CSP implementation type, such as software, hardware, or hybrid. The value corresponds to constants of type CSSM_SERVICE_MASK.
CspFlags CSP descriptions flags (32-bits). The flags are a bitwise logical OR of the constants defined for CSSM_CSP_FLAGS.
CspCustomFlags CSP specific flags (32-bits).
UseeTags Array of 32-bit integers containing the privilege values supported by the CSP. The integers correspond to symbols of type CSSM_PRIVILEGE.
SampleTypes An array of 32-bit integers representing the sample types accepted by the CSP. The integers correspond to symbols of type CSSM_SAMPLE_TYPE
AclSubjectTypes An array of 32-bit integers representing the ACL subject types accepted by the CSP. The integers correspond to symbols of type CSSM_ACL_SUBJECT_TYPE
AuthTags An array of 32-bit integers representing the authorization tag values defined by the CSP. The integers correspond to symbols of type CSSM_ACL_AUTHORIZATION_TAG

Table: Contents of the CSP Primary MDS Relation

This record should remain static once the service provider is installed. An exception to this rule might be when a user installs a new reader slot supported by a smartcard CSP.

CSP Encapsulated Product Relation

Service provider modules that export a CSP interface must register a single record in this relation for each CSP subservice that they export. It contains information about the underlying functionality provided by the specific CSP subservice. Service providers that are not wrappers around other products should create these records to insure that a complete set of information is available to clients. It is not used by the CSSM. Some of the information includes the product version, standard and standard version implemented by the service provider, and token reader device information (if applicable).

Field Name Description
ModuleID GUID (in string format) uniquely identifying the service provider. This value must be the same as the ModuleId field in the corresponding CSP Primary Relation record.
SSID Subservice ID. This must match the SSID value of the corresponding CSP Primary Relation record.
ProductDesc ASCII text description of the product encapsulated by the CSP implementation.
ProductVendor ASCII text description of the vendor that produces the product encapsulated by the CSP implementation.
ProductVersion Version string in dotted high/low format (i.e. 2.0) indicating the version of the product encapsulated by the CSP implementation.
ProductFlags Product flags (32-bits). The definition of the flag values is product specific.
CustomFlags Custom flags (32-bits). The definition of the flag value is product specific.
StandardDesc String describing the standard that the implementation encapsulates (i.e. PKCS #11)
StandardVersion Version string in dotted high/low format (i.e. 2.0) indicating the version of the standard implemented by the encapsulated product.
ReaderDesc If the product encapsulates a hardware device that includes a reader device, this is an ASCII text description of the reader. This field should be empty (" ") if there is no hardware reader.
ReaderVendor If the product encapsulates a hardware device that includes a reader device, this is an ASCII text description of the reader vendor. This field should be empty ("") if there is no hardware reader device.
ReaderVersion Version string in dotted high/low format (i.e. 2.0) indicating the version of the hardware reader device. This field should be empty (" ") if there is no hardware reader device.
ReaderFirmwareVersion Version string in dotted high/low format (i.e. 2.0) indicating the firmware version of the hardware reader device. This field should be empty (" ") if there is no hardware reader device.
ReaderFlags Reader flags (32-bits). The flags are a bitwise logical OR of the constants defined for CSSM_CSP_READER_FLAGS.
ReaderCustomFlags Reader custom flags (32-bits). The definition of the flag value is product specific.
ReaderSerialNumber ASCII representation of the reader device serial number. This field should be empty (" ") if there is no hardware reader device.

Table: Contents of CSP Encapsulated Product MDS Relation

This record should updated to reflect correct information whenever the corresponding CSP Primary Relation record is updated.

CSP Smartcard Relation

Service providers that export a CSP interface to a hardware device must register a record in the CSP Smartcard relation for each applicable subservice. All hardware devices, regardless of form-factor or dynamic properties must create these records. CSPs that are implemented in software are not required to create records in this relation.

Field Name Comment
ModuleID GUID (in string format) uniquely identifying the service provider. This value must be the same as the ModuleId field in the corresponding CSP Primary relation record.
SSID Subservice ID. This must match the SSID value of the corresponding CSP Primary relation record.
ScDesc ASCII text description of the subservice device.
ScVendor ASCII text description of the subservice device vendor.
ScVersion Version string in dotted high/low format (i.e. 2.0) indicating the product version of the subservice device. This field should be empty (" ") if there is no version information available.
ScFirmwareVersion Version string in dotted high/low format (i.e. 2.0) indicating the firmware version of the subservice device. This field should be empty (" ") if there is no version information available.
ScFlags Subservice device flags (32-bits). Indicates the set of built-in features of the subservice device. The features should be implemented in hardware.
ScCustomFlags Custom subservice flags (32-bits). The definition of the flag value is product specific.
ScSerialNumber ASCII text representation of the subservice device serial number.

Table: Contents of CSP Smartcard MDS Relation

The contents of the CSP Smartcard relation record for a subservice can be updated at any time by the CSP. It must be updated to reflect current information before the insert event is sent to the CSSM, and it must remain valid until the remove event is sent or the module is unloaded from all processes. See Sending Insert and Remove Events (Sending Insert and Remove Events) for more information on insert events.

CSP Capabilities Relation

A CSP service provider will enter multiple record in the CSP Capabilities relation for each cryptographic operation supported by a subservice. Contents of CSP Capabilities MDS Relation describes the fields for each attribute. The interpretation of the AttributeValue field varies based on the AttributeType field. Later subsections will describe the list of attributes that are required for each type of cryptographic operation, as well as other optional attributes. The UseeTag field allows a CSP to reflect additional capabilities based on a client's privileges granted in its signed manifest. The proper method for reflecting the changes in available capabilities is described in later sections.

Field Name Comment
ModuleID GUID (in string format) uniquely identifying the service provider. This value must be the same as the ModuleId field in the corresponding CSP Primary relation record.
SSID Subservice ID. This must match the SSID value of the corresponding CSP Primary relation record.
UseeTag 32-bit privilege tag associated with the attribute values. The values correspond to constants of type CSSM_USEE_TAG.
ContextType Class of cryptographic operation described by the attribute (32-bit). The value corresponds to constants of type CSSM_CONTEXT_TYPE.
AlgType Cryptographic algorithm supported by the CSP (32-bit). The value corresponds to constants of type CSSM_ALGORITHMS.
GroupId 32-bit identifier grouping all of the attributes associated with a single cryptographic capability.
AttributeType CSP attribute tag to identify the attribute value (32-bit). The value corresponds to constants of type CSSM_ATTRIBUTE_TYPE.
AttributeValue Array of 32-bit values. Some attribute types can have multiple values.
Description ASCII text, human readable description of the algorithm (.I AlgType ). All attributes with the same GroupId value should have the same Description value.

Table: Contents of CSP Capabilities MDS Relation

The contents of the CSP Capabilities relation records for a subservice can be updated at any time by the CSP. It must be updated to reflect current information before the insert event is sent to the CSSM, and it must remain valid until the remove event is sent or the module is unloaded from all processes. See Sending Insert and Remove Events (Sending Insert and Remove Events) for more information on insert events.

Assigning GroupId Values
Attributes that describe the same cryptographic capability are bound together using a group identifier, the GroupId field. The group identifier is an arbitrary unsigned integer that has no meaning other than to bind related attributes.

For simplicity, and to allow easier searches for all attributes of a single capability, all capabilities must have a unique GroupId value. The values should range from zero to N-1 without gaps in the sequence, where N is the number of capabilities supported by the CSP.

Privileged Capabilities
Some CSP service providers may elect to restrict some of their capabilities so that they can only be used by clients with the appropriate privileges granted in their signed manifests. The UseeTag field is used to indicate that the attribute only applies when the client's privilege is equal to a specific privilege value. The value CSSM_USEE_NONE indicates that the capability is available using any privilege value. This means that any client, including those that have not been granted special privileges in their signed manifest, can use the capability.

To indicate privilege restrictions on capabilities, the attributes are entered into the MDS in two "phases". The first phase is the attributes for capabilities supported without special privileges from the client (CSSM_USEE_NONE), otherwise known as the base attributes. The second phase is the deltas to those capabilities available to clients that have been granted special privilege (i.e. CSSM_USEE_FINANCIAL). The two phases build on each other, so that a CSP can reflect upgrades in a capability due to client privilege.

Example Representation of Capabilities Set for CSP in MDS illustrates a set of attributes for a CSP that implements RSA key generation, SHA-1 message digests and RSA key exchange. By looking at the attributes with a CSSM_USEE_NONE UseeTag value, you can tell that SHA-1 message digests can always be calculated regardless of the privilege used by a client attached to the CSP. You can also tell that the CSP implements 512-bit RSA key generation and 512-bit key exchange at any time. By looking at the attributes with a CSSM_USEE_KEYEXCH UseeTag value, you can tell that the CSP allows 1024-bit RSA key generation and 1024-bit key exchange when the client has been granted that privilege. Notice that the deltas in capabilities, the additional key size, use the same GroupId value as the base set of attributes.

UseeTag GroupId ContextType AlgType AttributeType AttributeValue
NONE 0 KEYGEN RSA KEYSIZE 512
KEYEXCH 0 KEYGEN RSA KEYSIZE 1024
NONE 1 DIGEST SHA1 OUTPUT_SIZE 20
NONE 2 ASYMMETRIC RSA KEYSIZE 512
KEYEXCH 2 ASYMMETRIC RSA KEYSIZE 1024

Table: Example Representation of Capabilities Set for CSP in MDS

Required Capability Attributes
Each type of cryptographic capability has a set of required attribute types, and an additional set of optional values depending on the specific algorithm. The following subsections describe the required and optional attributes for each capability type.

If a capability does not have any required attributes and no optional attributes are present, a single attribute must be inserted with the following fixed values.

Field Name Value
AttributeType CSSM_ATTRIBUTE_NONE
AttributeValue 0

Table: Fixed Attribute Values for No Required Attributes

Random Number Generation Capabilities

Optional Attributes
CSSM_ATTRIBUTE_* 		Description
BLOCK_SIZE If the RNG algorithm uses a block generation method, this value can be used to indicate the size of each block.
ROUNDS_RANGE If the RNG can be configured to use a variable number of rounds to generate random data, this attribute indicates the valid range of round values that are supported by the CSP.
ROUNDS This attribute must be specified if the ROUNDS_RANGE attribute is present. It indicates the default rounds value used by the CSP if this attribute is not found in the cryptographic context.

Table: Capability Attributes for Random Number Generation
Message Digest Capabilities

Optional Attributes
CSSM_ATTRIBUTE_* 		Description
OUTPUT_SIZE This is the output length of the message digest algorithm in bytes.

Table: Capability Attributes for Message Digest Capabilities
Symmetric Key Generation Capabilities

Optional Attributes
CSSM_ATTRIBUTE_* 		Description
KEY_LENGTH_RANGE If the algorithm supports multiple key sizes, this is the range of key sizes supported in bits.
KEY_LENGTH If the algorithm uses a fixed key size, this is the logical key size in bits.
Optional Attributes
KEYUSAGE Indicates the key usage mask values that can be specified for the new key.

Table: Capability Attributes for Symmetric Key Generation
Symmetric Block Cipher Capabilities

Optional Attributes
CSSM_ATTRIBUTE_* 		Description
MODE Indicates the algorithm mode described by this set of attributes. Each algorithm mode should be described by its own capability differentiated using the GroupId field.
KEY_LENGTH_RANGE If the algorithm supports multiple key sizes, this is the range of key sizes supported in bits.
KEY_LENGTH If the algorithm uses a fixed key size, this is the logical key size in bits.
BLOCK_SIZE Block size of the cipher. If the cipher is used without a padding method, the length of the input must be a multiple of this value. If a padding method is used, the total output length from the cipher will be a multiple of this value.
Optional Attributes
PADDING List of padding methods supported for this cipher and mode.
ROUNDS_RANGE If the cipher can be configured to use a variable number of rounds to transform data, this attribute indicates the valid range of round values that are supported by the CSP.
ROUNDS This attribute must be specified if the ROUNDS_RANGE attribute is present. It indicates the default rounds value used by the CSP if this attribute is not found in the cryptographic context.
IV_SIZET If the algorithm and mode requires and initialization vector, this value indicates the required length of the value that must be supplied by the client.

Table: Capability Attributes for Symmetric Block Cipher
Symmetric Stream Cipher Capabilities

Optional Attributes
CSSM_ATTRIBUTE_* 		Description
KEY_LENGTH_RANGE If the algorithm supports multiple key sizes, this is the range of key sizes supported in bits.
KEY_LENGTH If the algorithm uses a fixed key size, this is the logical key size in bits.
Optional Attributes
MODE Indicates the algorithm mode described by this set of attributes. Each algorithm mode should be described by its own capability differentiated using the GroupId field.
ROUNDS_RANGE If the cipher can be configured to use a variable number of rounds to transform data, this attribute indicates the valid range of round values that are supported by the CSP.
ROUNDS This attribute must be specified if the ROUNDS_RANGE attribute is present. It indicates the default rounds value used by the CSP if this attribute is not found in the cryptographic context.
KEYUSAGE Indicates the key usage mask values that can be specified for the new key.

Table: Capability Attributes for Symmetric Stream Cipher
Message Authentication Code Capabilities

Optional Attributes
CSSM_ATTRIBUTE_* 		Description
MODE Indicates the algorithm mode described by this set of attributes. Each algorithm mode should be described by its own capability differentiated using the GroupId field.
KEY_LENGTH_RANGE If the algorithm supports multiple key sizes, this is the range of key sizes supported in bits.
KEY_LENGTH If the algorithm uses a fixed key size, this is the logical key size in bits.
BLOCK_SIZE Block size of the cipher used to generate the MAC. Optional Attributes
Optional attributes
ROUNDS_RANGE If the cipher can be configured to use a variable number of rounds to transform data, this attribute indicates the valid range of round values that are supported by the CSP.
ROUNDS This attribute must be specified if the ROUNDS_RANGE attribute is present. It indicates the default rounds value used by the CSP if this attribute is not found in the cryptographic context.
OUTPUT_SIZE Length of the MAC value generated by the algorithm.
IV_SIZE If the algorithm and mode requires an initialization vector, this value indicates the required length of the value that must be supplied by the client.

Table: Capability Attributes for Message Authentication Code
Asymmetric Key Generation Capabilities

Optional Attributes
CSSM_ATTRIBUTE_* 		Description
KEY_LENGTH_RANGE If the algorithm supports multiple key sizes, this is the range of key sizes supported in bits.
KEY_LENGTH If the algorithm uses a fixed key size, this is the logical key size in bits
Optional Attributes
KEYUSAGE Indicates the key usage mask values that can be specified for the new keys. The mask is a combination of the values that are valid for the public and private keys.

Table: Capability Attributes for Asymmetric Key Generation
Asymmetric Encryption Capabilities

Optional Attributes
CSSM_ATTRIBUTE_* 		Description
KEY_LENGTH_RANGE If the algorithm supports multiple key sizes, this is the range of key sizes supported in bits.
KEY_LENGTH If the algorithm uses a fixed key size, this is the logical key size in bits.
Optional Attributes
MODE Indicates the algorithm mode described by this set of attributes. Each algorithm mode should be described by its own capability differentiated using the GroupId field.

Table: Capability Attributes for Asymmetric Encryption
Asymmetric Signature Capabilities

Optional Attributes
CSSM_ATTRIBUTE_* 		Description
KEY_LENGTH_RANGE If the algorithm supports multiple key sizes, this is the range of key sizes supported in bits.
KEY_LENGTH If the algorithm uses a fixed key size, this is the logical key size in bits
Optional Attributes
MODE Indicates the algorithm mode described by this set of attributes. Each algorithm mode should be described by its own capability differentiated using the GroupId field.

Table: Capability Attributes for Asymmetric Signature
Key Derivation Capabilities

Optional Attributes
CSSM_ATTRIBUTE_* 		Description
KEY_LENGTH_RANGE If the algorithm supports multiple key sizes, this is the range of key sizes supported in bits.
KEY_LENGTH If the algorithm uses a fixed key size, this is the logical key size in bits. lb s l l. Optional Attributes ROUNDS_RANGE!T{ If the key derivation algorithm can be configured to use a variable number of rounds to transform data, this attribute indicates the valid range of round values that are supported by the CSP.
ROUNDS This attribute must be specified if the ROUNDS_RANGE attribute is present. It indicates the default rounds value used by the CSP if this attribute is not found in the cryptographic context.
KEY_TYPE List of algorithm identifiers (CSSM_ALGORITHMS) indicating the types of keys that can be created by the derivation mechanism.

Table: Capability Attributes for Key Derivation

CSP Multi-Service Modules with DL Interface

CSPs are unique among CDSA service providers in that they take on extra capabilities when combined with service providers of other types. Examples of service provider type combinations that produce extra capabilities are CSPs with Key Recovery (KR), and CSPs with a Data Storage Library (DL).

The capability changes for a CSP combined with a KR service provider are described in the CDSA KR specification and will not be covered here. The most common service provider type is CSP with a DL interface. This combination is covered here in detail.

Purpose of CSP Multi-Service Modules

The purpose of CSP multi-service modules with a DL interface (CSP/DL) is to give the CSP the ability to manage multiple key storage repositories, and provide more robust key management APIs. CSP/DLs are not intended to provide a fully capable DL module and an independent CSP in the same binary. As a result, CSP/DLs will usually provide a limited DL interface as required to implement key management. The DL interfaces in CSP/DL service providers are not required to support all database management functions. Specific functions that are not required include database creation, deletion, and schema modification.

Identifying Multi-Service Modules

CSP/DLs are identified using the MDS. The client must search the CDSA Common relation in the MDS for modules that have a ServiceMask field that has the CSSM_SERVICE_CSP and CSSM_SERVICE_DL flags set.

Assigning Subservice Identifiers

Subservice identifiers in CSP/DL service providers are assigned based on "cooperating service". Cooperating services are those that provide different interfaces to the same logical entity. For hardware CSPs, the logical entity may be a smartcard, PCMCIA card, or other general-purpose cryptographic device. For software only CSPs, the meaning of "logical entity" is left up to the service provider designer. The rule for cooperating services is that if a service provider supports a CSP and a DL subservice with the same subservice identifier, then they are cooperative and reference the same logical entity. If the service provider supports two different service provider types that do not cooperate, the subservice identifiers used by each type must not overlap.

Client Authentication and Authorization

The authentication and authorization for a CSP/DL is combined into a shared state for both service provider interfaces to a subservice. As a result, if the client has called the CSP_Login() SPI (.Fn CSSM_CSP_Login API), it achieves the same effect as calling the DL_Authenticate() SPI (.Fn CSSM_DL_Authenticate API) and vice-versa.

Managing Multiple Key Storage Databases

A client that uses a CSP/DL service provider has the ability to specify a specific database (DB) handle to a CSP interface that is to be used for storage of the new key. The client may only specify DB handles that were issued by the CSP's own DL interface. This allows the client to have control over where keys are stored, but allows the CSP to insure that the data is stored in a secure manner.

To specify a specific DB for key storage, the client must place the CSSM_DL_DB_HANDLE structure into the cryptographic context (CC) that will create the new key as a CSSM_ATTRIBUTE_DL_DB_HANDLE attribute using the CSSM_UpdateContextAttributes() API. A CSP/DL service provider must always check for the CSSM_ATTRIBUTE_DL_DB_HANDLE attribute before storing a key. If it is not present in the CC, the CSP must use a default storage DB. The CSP/DL must always make sure that the DB handle is valid, and that it was issued by its own DL interface. CSP-only service providers do not check for the CSSM_ATTRIBUTE_DL_DB_HANDLE attribute, and will never return an error based on its value if it is present in the CC.

A CSP/DL must always have a default DB that is used for key storage in case the client does not specify a specific DB in the CC. The default DB is the first one in the list returned by the DL_GetDbNames() SPI (.Fn CSSM_DL_GetDbNames API).

Algorithm Reference

Conventions

Abbreviations for Algorithm Uses contains a list of algorithm actions, and the associated abbreviation used in this Appendix.

Abbreviation Algorithm Operation CSSM API(s)
H Message digest (hashing) CSSM_DigestData
M Message Authentication Code (MAC) CSSM_GenerateMac
CSSM_VerifyMac
E Symmetric key encryption CSSM_EncryptData
CSSM_DecryptData
P Public key encryption/
private key decryption 		CSSM_EncryptData(Public key)
CSSM_DecryptData(Private key)
R Signature with message recovery (private key encryption / public key decryption) CSSM_EncryptData(Private key)
or CSSM_SignData(Private key),
CSSM_DecryptData(Public key)
S Signature w/Appendix CSSM_SignData(Private key)
CSSM_VerifyData(Public key)
X Key exchange CSSM_WrapKey(Public key) or
CSSM_WrapKey(Symmetric key),
CSSM_UnwrapKey(Private key) or
CSSM_UnwrapKey(Symmetric key)
K Key generation CSSM_GenerateKey (symmetric)
CSSM_GenerateKeyPair (asymmetric)
D Key derivation CSSM_DeriveKey

Table: Abbreviations for Algorithm Uses

Basic Algorithm Usage

Algorithms are specified to CSPs using a Cryptographic Context (CC). CCs contain information such as the algorithm class, algorithm ID, and a collection of attributes required by the algorithm or in addition to the required attributes to modify the default behaviors of the algorithm. In some cases, not all of the possible attributes for an operation can be specified using one of the CC creation APIs. In these cases, the additional attributes are added to the context using the CSSM_UpdateContextAttributes() API.
Digital Signatures
Digital signatures are typically generated using a two step process: computing the message digest of a piece of data, and performing a private key operation to obtain the final result. In the most common situation, both steps are performed with a single signature operation. In some applications, such as PKCS #7 packages with multiple signers, it is more efficient to perform both steps separately. In this Appendix, signature algorithms that perform both steps are called combination signatures, and algorithms that perform only the private key operation are called encrypt-only signatures.

Some signature algorithms are capable of being used in a variety of modes. The mode determines how the message digest is tagged and how the digest is transformed before performing the private key operation. Transformation of the message digest includes padding, masking, etc. Each algorithm that supports multiple modes will have a default mode that is assumed by the CSP if one is not explicitly specified as a CC attribute of type CSSM_ATTRIBUTE_MODE.

Combination Signatures
Combination signature algorithms have algorithm ID names of the form: 


 

CSSM_ALGID_<DigestAlg>With<PrivateKeyAlg>

DigestAlg identifies the name of the message digest algorithm, such as SHA-1 or MD5. PrivateKeyAlg identifies the algorithm used to perform the private key operation. For instance CSSM_ALGID_MD5WithRSA and CSSM_ALGID_SHA1WithDSA indicate combination signature algorithms.

For a combination algorithm, the CSP performs all necessary message digest transformations according to the CSSM_ATTRIBUTE_MODE attribute in the signature CC. In addition, the DigestAlgorithm parameter to either CSSM_SignData() or CSSM_VerifyData() must be set to CSSM_ALGID_NONE.

Encrypt-only Signatures
Encrypt-only signatures are generated by transforming a message digest value and then performing the private key operation in separate steps. The signature algorithm does not compute the message digest value.

The CSSM_ATTRIBUTE_MODE attribute and the DigestAlgorithm parameter (to either CSSM_SignData() or CSSM_VerifyData()) govern the extent of the message digest transformations performed by the CSP. The mode determines how the input digest is transformed. The digest algorithm indicates whether the CSP has to perform the entire transformation or should assume that the client has done the work of tagging the message digest. Tagging a message digest in most signature modes means that an indicator of the digest algorithm is appended or prepended to the digest value. If the digest algorithm is specified to be CSSM_ALGID_NONE, then the CSP assumes that the client has already tagged the digest value. If the digest tagging is performed by the CSP, then it must always check that the digest length is appropriate for the specified digest algorithm.

Encrypt-only signatures can only be performed using single-stage APIs (.Fn CSSM_SignData and CSSM_VerifyData()).

Algorithm Parameters

Many algorithms require a set of parameters to operate. For instance, the PKCS #3 Diffie-Hellman algorithm requires both parties to use a common prime (P) and base (G) value pair. In situations like this, the parameters are represented using a data block held in the CSSM_ATTRIBUTE_ALG_PARAMS attribute of the cryptographic context (CC).

When a client needs to generate the algorithm parameters, it uses the CSP_GenerateAlgorithmParams() SPI (.Fn CSSM_GenerateAlgorithmParams API) to make the CSP generate a suitable set of parameters and place them in the CC. The CSP must generate the appropriate parameter values based on the context type, algorithm, etc. and add or update the CSSM_ATTRIBUTE_ALG_PARAMS attribute by returning an array of CSSM_CONTEXT_ATTRIBUTE structures to the CSSM. The CSP must allocate the memory for the array of attributes to be updated. The structures must be allocated using the application memory functions so that they can be deallocated by the CSSM. See for more information about application memory functions.

The formats for the algorithm parameters, if any, will be given along with the algorithm description in Algorithm List, below.

Algorithm List

RSA
The RSA algorithm, CSSM_ALGID_RSA, is an asymmetric algorithm used for single-stage encryption and decryption, encrypt-only digital signature generation and verification (with and without message recovery), and key wrapping. RSA can be used in a number of modes, as listed in Applicable Modes for CSSM_ALGID_RSA Context Type below.

Context Type
CSSM_ALGCLASS_* 		Algorithm Mode
CSSM_ALGMODE_* 		Valid
Operations 		Applicable Standard
ASYMMETRIC NONE P/R PKCS #1 v2.0, RSAEP/RSADP
ASYMMETRIC PKCS1_EME_V15 P/R/X PKCS #1 v2.0, EME-PKCS1-v1_5
ASYMMETRIC PKCS1_EME_OAEP P/X PKCS #1 v2.0, EME-OAEP
SIGNATURE PKCS1_EMSA_V15 S/R PKCS #1 v2.0, EMSA-PKCS1-v1_5
SIGNATURE X9_31 S ASNI X9.31-1998
ASYMMETRIC ISO_9796 P/R ISO 9796-1
SIGNATURE ISO_9796 S/R ISO 9796-1

Table: Applicable Modes for CSSM_ALGID_RSA Context Type

The default algorithm mode if the CSSM_ATTRIBUTE_MODE attribute is not in the CC is CSSM_ALGMODE_PKCS1_EME_V15 for asymmetric contexts and CSSM_ALGMODE_PKCS1_EMSA_V15 for signature contexts.

Refer to the appropriate standards for the input length restrictions and output sizes for each mode.

When generating RSA keypairs, the length of the public-modulus may be specified in 8-bit increments. The resulting public and private keys have CSSM_KEYHEADER::AlgorithmId equal to CSSM_ALGID_RSA.

Signature generation and key unwrapping require a private key with CSSM_KEYHEADER::AlgorithmId equal to CSSM_ALGID_RSA. Signature verification and key wrapping require a public key of the same type. Encryption and decryption accept either a public or private key.

Algorithm Parameters
RSA key generation has an optional algorithm parameter, the CSSM_ATTRIBUTE_ALG_PARAM attribute, specified using the Param parameter of the CSSM_CSP_CreateKeyGenContext() API. The value of the parameter is the public exponent for the new key pair. The exponent must be represented as an integer with the most significant byte first. The CSSM_GenerateAlgorithmParams() API can be used to make the CSP pre-generate the public exponent for the key generation.

When using the PKCS #1 OAEP algorithm mode, CSSM_ALGMODE_PKCS1_EME_OAEP, the client must specify the algorithm parameters as an attribute of type CSSM_ATTRIBUTE_ALG_PARAMS. The CSSM_DATA::Data value must point to the start address of a CSSM_PKCS1_OAEP_PARAMS structure, and the CSSM_DATA::Length value must be the size of the parameter structure. The CSSM_GenerateAlgorithmParams() API can not be used to generate these parameters.

Combination Signatures with RSA
The RSA combination signature algorithms are used for single-stage and multi-staged digital signature generation and verification (without message recovery). The RSA combination signature algorithms can be used in a number of modes, as listed in Applicable Modes for Combination Signatures with RSA below.

Context Type
CSSM_ALGCLASS_* 		Algorithm Mode
CSSM_ALGMODE_* 		Valid
Operations 		Applicable Standard
SIGNATURE PKCS1_EMSA_V15 S PKCS #1 v2.0, EMSA-PKCS1-v1_5
SIGNATURE X9_31 S ANSI X9.31-1998
SIGNATURE ISO_9796 S ISO 9796-1

Table: Applicable Modes for Combination Signatures with RSA

The default algorithm mode if the CSSM_ATTRIBUTE_MODE attribute is not in the CC is CSSM_ALGMODE_PKCS1_EMSA_V15.

Refer to the appropriate standards for the input length restrictions and output sizes for each mode.

Signature generation requires a private key with CSSM_KEYHEADER::AlgorithmId equal to CSSM_ALGID_RSA. Signature verification requires a public key of the same type.

DSA
The DSA algorithm, CSSM_ALGID_DSA, is an asymmetric algorithm used for single-stage encrypt-only digital signature generation and verification. RSA can be used in the modes listed in Applicable Modes for CSSM_ALGID_DSA.

Context Type
CSSM_ALGCLASS_* 		Algorithm Mode
CSSM_ALGMODE_* 		Valid
Operations 		Applicable Standard
SIGNATURE NONE S NIST FIPS 186-2; ANSI X9.30:1-1993

Table: Applicable Modes for CSSM_ALGID_DSA

When generating DSA keypairs, the length of the prime may be specified in 64-bit increments, starting at 512. The resulting public and private keys have CSSM_KEYHEADER::AlgorithmId equal to CSSM_ALGID_DSA.

Signature generation requires a private key with CSSM_KEYHEADER::AlgorithmId equal to CSSM_ALGID_DSA. Signature verification requires a public key of the same type. The DigestAlgorithm parameter to the CSSM_SignData() and CSSM_VerifyData() APIs must be CSSM_ALGID_SHA1, and the length of the input must total exactly 160 bits.

Algorithm Parameters
DSA key generation has an optional algorithm parameter, the CSSM_ATTRIBUTE_ALG_PARAM attribute, specified using the Param parameter of the CSSM_CSP_CreateKeyGenContext() API. The parameter is a BER encoded Dss-params structure, described above, containing the prime, sub-prime, and base (p, q, and g) values. If the CSSM_ATTRIBUTE_ALG_PARAMS attribute is not present in the context, the parameters will be generated along with the public and private values. The CSSM_GenerateAlgorithmParams() API can be used to make the CSP pre-generate the key parameters for subsequent key pair generation.

Generating DSA parameters requires a 160-bit seed value. The CSP obtains this value using the CSSM_ATTRIBUTE_SEED attribute in the cryptographic context. If the supplied seed value is not 160 bits long, then the seed value is processed using SHA-1 and the resulting 160-bit value is used. If the CSSM_ATTRIBUTE_SEED attribute is not present in the context, then an internally generated 160-bit random value is used.

Combination Signatures with DSA
The DSA combination signature algorithms are used for single-stage and multi-staged digital signature generation and verification. The DSA combination signature algorithms do not have a choice of operating modes. They are listed in Applicable Modes for combination Signatures with DSA.

Context Type
CSSM_ALGCLASS_* 		Algorithm Mode
CSSM_ALGMODE_* 		Valid
Operations 		Applicable Standard
SIGNATURE NONE S NIST FIPS 186-2; ANSI X9.30:1-1993

Table: Applicable Modes for combination Signatures with DSA

Signature generation requires a private key with CSSM_KEYHEADER::AlgorithmId equal to CSSM_ALGID_DSA. Signature verification requires a public key of the same type.

Diffie-Hellman (PKCS #3)
The PKCS #3 Diffie-Hellman algorithm, CSSM_ALGID_DH, is an algorithm used for asymmetric key pair generation and symmetric key derivation. The combination of the two functions completes a key agreement between two parties. The resulting symmetric key can range in length from 8 bits to the length of the prime value, p, in increments of 8 bits.

Context Types and Modes for PKCS #3 Diffie-Hellman lists the context types and applicable standards for PKCS #3 Diffie-Hellman key agreement.

Context Type
CSSM_ALGCLASS_* 		Algorithm Mode
CSSM_ALGMODE_* 		Valid
Operations 		Applicable Standard
KEYGEN NONE K PKCS #3 v1.5
DERIVEKEY NONE D PKCS #3 v1.5

Table: Context Types and Modes for PKCS #3 Diffie-Hellman

When generating Diffie-Hellman keypairs, the length of the prime value may be specified in 8-bit increments. The resulting public and private keys have CSSM_KEYHEADER::AlgorithmId equal to CSSM_ALGID_DH. The public key value, CSSM_KEY::KeyData, must be sent to the other party taking part in the key agreement process.

When deriving the symmetric key, the public value received from the other party is specified using the Params parameter to the CSSM_DeriveKey() API. Key derivation requires a private key with CSSM_KEYHEADER::AlgorithmId equal to CSSM_ALGID_DH.

Algorithm Parameters
PKCS #3 Diffie-Hellman key pair generation has an optional algorithm parameter, the CSSM_ATTRIBUTE_ALG_PARAM attribute, specified using the Param parameter of the CSSM_CSP_CreateKeyGenContext() API. The parameter is a BER encoded DHParameter structure, described in PKCS #3, containing the prime and base (p and g) values. If the CSSM_ATTRIBUTE_ALG_PARAMS attribute is not present in the context, the parameters will be generated along with the public and private values.

The CSSM_GenerateAlgorithmParams() API can be used to have the CSP pre-generate the key parameters for subsequent key pair generation. These parameters must also be sent to the other party taking place in the key agreement process. They can be fetched from the context using the CSSM_GetContext() and CSSM_GetContextAttribute() APIs.

Password Based Key Derivation (PKCS #5)
PKCS #5 Password Based Key Derivation (PBD) is a collection of algorithms for deriving a symmetric encryption key, and sometimes an initialization vector from a password and random salt value. PKCS #5 v2.0 defines two methods for deriving key material from a password: PBKDF1 and PBKDF2. PBKDF1 is compatible with the PKCS #5 v1.5 key derivation algorithm, and generates a key with a maximum length of 64-bits, and an 8-byte initialization vector (IV). PBKDF2 allows derivation of keys with an arbitrary length, but does not generate an IV.

,cX table34 "" 1 lists the PBD functions defined in PKCS #5 v2.0.

Context Type
CSSM_ALGCLASS_* 		Algorithm
CSSM_ALGID_* 		PBD Function Parameter Structure
CSSM_PKCS5_*
DERIVEKEY PKCS5_PBKDF1_MD2 PBKDF1 PBKDF1_PARAMS
DERIVEKEY PKCS5_PBKDF1_MD5 PBKDF1 PBKDF1_PARAMS
DERIVEKEY PKCS5_PBKDF1_SHA1 PBKDF1 PBKDF1_PARAMS
DERIVEKEY PKCS5_PBKDF2 PBKDF2 PBKDF2_PARAMS

Table: Algorithm IDs and Parameter Structures for PKCS-5 PBD

All of the PKCS #5 PBD algorithms require salt and iteration count values. They are obtained from the CSSM_ATTRIBUTE_SALT and CSSM_ATTRIBUTE_ITERATION_COUNT attributes and specified by the application using the Salt and Iterations parameters to the CSSM_CreateDeriveKeyContext() API respectively.

For PBKDF1 based algorithms, the salt value must be exactly 8 bytes long. For PBKDF2, the salt value may have any non-zero length. The CSP returns CSSMERR_CSP_MISSING_ATTR_SALT if the salt attribute is not present in the context, and CSSMERR_CSP_INVALID_ATTR_SALT if the value does not meet the requirements of the algorithm.

The CSP returns CSSMERR_CSP_MISSING_ATTR_ITERATION_COUNT if the iteration count attribute is not present in the context, and CSSMERR_CSP_INVALID_ATTR_ITERATION_COUNT if the value is zero.

The type of the output key is determined by the CSSM_ATTRIBUTE_KEY_TYPE attribute in the context. The CSP returns CSSMERR_CSP_MISSING_ATTR_KEY_TYPE if the key type attribute is not present in the context, and CSSMERR_CSP_INVALID_ATTR_KEY_TYPE if the type is not supported by the CSP.

Data Structures
When using a PKCS #5 PBD algorithm, the caller must supply an appropriate parameter structure. The structure is supplied through the Params parameter to the CSSM_DeriveKey() API. Params.Data must point to the structure, and Params.Length must be equal to the size of the structure.

CSSM_PKCS5_PBKDF1_PARAMS 


 

typedef struct CSSM_PKCS5_PBKDF1_PARAMS {
    CSSM_DATA Passphrase;       /* Input  */ 
    CSSM_DATA InitVector;       /* Output */ 
} CSSM_PKCS5_PBKDF1_PARAMS;

Definitions

Passphrase (input)

Buffer containing the passphrase used as the basis for the PBD operation. CSP returns CSSMERR_CSP_INVALID_INPUT_POINTER if the data pointer is NULL, and CSSMERR_CSP_INVALID_DATA if the length is zero.

InitVector (output)

The CSP will return an 8-byte IV in this buffer. If the caller does not supply a buffer, it is allocated as described above.

CSSM_PKCS5_PBKDF2_PARAMS 



 

typedef uint32 CSSM_PKCS5_PBKDF2_PRF; 
#define CSSM_PKCS5_PBKDF2_PRF_HMAC_SHA1 ( 0 )

typedef struct CSSM_PKCS5_PBKDF2_PARAMS {
    CSSM_DATA Passphrase; 
    CSSM_PKCS5_PBKDF2_PRF PseudoRandomFunction; 
} CSSM_PKCS5_PBKDF2_PARAMS;

Definitions

Passphrase (input)

Buffer containing the passphrase used as the basis for the PBD operation. CSP returns CSSMERR_CSP_INVALID_INPUT_POINTER if the data pointer is NULL, and CSSMERR_CSP_INVALID_DATA if the length is zero.

PseudoRandomFunction (input)

Pseudo random function (PRF) used by the PBKDF2 algorithm.

Generic Message Digests
Message digests implement a one-way compression function on a stream of data. The result is a message representative that is usually shorter that the input value. Message digests can be calculated using single-stage or multi-stage APIs.

Generic Message Digest Algorithm Identifiers and Standards lists the generic message digest algorithm identifiers defined by the current version of the CDSA standard.

Algorithm Name
CSSM_ALGID_* 		Valid
Operations 		Applicable Standard
MD2 H IETF RFC1319, April 1992
MD4 H IETF RFC1320, April 1992
MD5 H IETF RFC1321, April 1992
SHA1 H NIST FIPS 180-1; ASNI X9.30:2-1993
RIPEMD160 H ISO/IEC 10118-3:1998

Table: Generic Message Digest Algorithm Identifiers and Standards

Generic message digest algorithms do not have different modes of operation.

Refer to the appropriate standards for the input length restrictions and output sizes for each algorithm.

Generic Block Ciphers
Generic block ciphers are used for symmetric key generation, bulk encryption and decryption, computing Message Authentication Codes, and key wrapping and unwrapping. Block ciphers operate on fixed length block of data, are capable of being used in multiple feedback modes, and can be used with a number of padding modes in case the input data is not a multiple of the block length.

Commonly used block ciphers are listed in Generic Message Digest Algorithm Identifiers and Standards.

Algorithm
CSSM_ALGID_* 		Valid
Operations 		Applicable
Standards 		Comments
DES,
3DES_3KEY_EEE,
3DES_3KEY_EDE,
3DES_2KEY_EEE,
3DES_2KEY_EDE,
3DES_1KEY_EEE 		E, X, M NIST FIPS 46-3;
ANSI X9.52- 1998 		The 3KEY identifiers indicate a triple-length DES key. The 2KEY identifiers indicate a double-length DES key. The EEE identifiers indicate an encrypt, encrypt, encrypt sequence is performed using consecutive DES keys within the single, double, or triple length keys. Double length operations use the first key for the first and third operation. Single length operations use the same key for all operations. EDE identifiers indicate an encrypt, decrypt, encrypt sequence using the keys as described for EEE operations.
RC2 E, X, M IETF RFC2268,
January 1998 		 
RC5 E, X, M IETF RFC2040,
October 1996 		 

Generic block ciphers can be used in a number of different modes, with multiple padding methods. The most common methods are described in Algorithm IDs and Standards for Block Ciphers. The additional required cryptographic context attributes are also listed for each mode.

Algorithm Mode
CSSM_ALGMODE_* 		Applicable
Standards 		Additional
CC Attributes
CSSM_ATTRIBUTE_* 		Description
ECB NIST FIPS 46-3;
NIST FIPS 81;
ANSI X9.52-1998 		None Electronic Codebook (ECB) mode. Raw block encryption with no feedback between data blocks. Equivalent blocks will encrypt to the same value. The input data length must be a multiple of the cipher block size.
_   _ _
ECBPad   PADDING ECB mode with data padding. The final block of the input data is padded until a multiple of the block length is obtained. Some padding modes may add an additional block to the output data.
_   _ _
CBC_IV8
CFB_IV8
OFB_IV8 		  INIT_VECTOR Cipher Block Chaining (CBC), Cipher Feedback (CFB), and Output Feedback (OFB) modes. Block encryption with feedback between blocks. Equivalent blocks will encrypt to different values. The input data length must be a multiple of the cipher block size.
_   _ _
CBCPadIV8
CFBPadIV8
OFBPadIV8 		  INIT_VECTOR,
PADDING 		Cipher Block Chaining (CBC), Cipher Feedback (CFB), and Output Feedback (OFB) modes with data padding. The final block of the input data is padded until a multiple of the block length is obtained. Some padding modes may add an additional block to the output data.

Table: Algorithm IDs and Standards for Block Ciphers

If the algorithm mode indicates IV8, then the application must supply an 8-byte initialization vector using the CSSM_ATTRIBUTE_INIT_VECTOR attribute, and specified by the application using the InitVector parameter to the CSSM_CSP_CreateSymmetricContext() API. The CSP returns CSSMERR_CSP_MISSING_ATTR_INIT_VECTOR if the attribute is not present in the context and CSSMERR_CSP_INVALID_ATTR_INIT_VECTOR if it does not meet length requirements.

If the algorithm mode indicates Pad, then the application must supply a padding method using the CSSM_ATTRIBUTE_PADDING attribute, and specified by the application using the Padding parameter to the CSSM_CSP_CreateSymmetricContext() API. The CSP returns CSSMERR_CSP_MISSING_ATTR_PADDING if the attribute is not present in the context, and CSSMERR_CSP_INVALID_ATTR_PADDING if the requested method is not supported by the CSP. If the cipher mode selected applies data padding, it can use the padding methods in . Note that some methods are not always desirable due to the inability to accurately remove the padding during decryption.

Padding Method
CSSM_PADDING_* 		Applicable
Standard 		Description
ZERO   The final block is padded with zeros until the proper length is reached. The method cannot be accurately stripped during decryption if the data contains trailing zero bytes.
ONE   The final block is padded with one bits until the proper length is reached. The method cannot be accurately stripped during decryption if the data contains trailing bytes containing all one bits.
PKCS5 PKCS #5 v2.0 Popular padding method that can be accurately stripped in all cases. Limited to an 8-byte block length. If the input data length is a multiple of the block length, an extra block of data will be added to the output.
PKCS7 PKCS #7 v1.5 Generalized version of PKCS #5 padding that can be applied to any block length.
RANDOM   Random bytes are used to extend the input data to the proper length. This padding cannot be stripped by the CSP.

Table: Padding Modes for Block Ciphers
Additional RC2 Requirements
RC2 allows a variable number of bits in the key schedule to be used for encryption and decryption. The number of effective bits can be configured using the CSSM_ATTRIBUTE_EFFECTIVE_BITS attribute in the cryptographic context. The value of the attribute can range from 1 to 1024. If the attribute is missing from the context, the default value 1024 is used. If the value of the attribute is outside the value range, the error CSSMERR_CSP_INVALID_ATTR_EFFECTIVE_BITS is returned. The CSSM_ATTRIBUTE_EFFECTIVE_BITS attribute must be added to the context using the CSSM_UpdateContextAttributes API.
Additional RC5 Requirements
RC5 allows a variable block size and number of rounds.

The block size can be configured using the CSSM_ATTRIBUTE_BLOCK_SIZE attribute in the cryptographic context. The value of the attribute can be 32, 64, or 128. If the attribute is missing from the context, the default value 64 is used. If the value of the attribute is outside the value range, the error CSSMERR_CSP_INVALID_ATTR_BLOCK_SIZE is returned.

The number of rounds can be configured using the CSSM_ATTRIBUTE_ROUNDS attribute in the cryptographic context. If the attribute is missing from the context, the default value 16 is used. The CSSM_ATTRIBUTE_BLOCK_SIZE and CSSM_ATTRIBUTE_ROUNDS attributes must be added to the context using the CSSM_UpdateContextAttributes() API.

Generic Stream Ciphers
Generic stream ciphers are used for symmetric key generation, bulk encryption and decryption, and key wrapping and unwrapping. Stream ciphers operate on data one bit or byte at a time, and have no block length or mode restrictions.

Commonly used stream ciphers are listed in Algorithm IDs and Standards for Stream Ciphers.

Algorithm
CSSM_ALGID_* 		Valid
Operations 		Applicable
Standard 		Comments
RC4 E, X    

Table: Algorithm IDs and Standards for Stream Ciphers

SSL 3.0 Algorithms

The CDSA Technical Standard defines a set of algorithm identifiers that represent steps in the SSL 3.0 handshake protocol. The protocol steps include pre-master key generation, master key derivation, cipher and MAC key derivation, and the SSL defined MD5-MAC and SHA-1-MAC variants.

SSL 3.0 Algorithm IDs, Context Types and Parameter lists the SSL 3.0 handshake protocol step identifiers, the context types, and the parameter structures used with the CSSM_DeriveKey() API. A detailed description of each identifier follows after SSL 3.0 Algorithm IDs, Context Types and Parameter. When a parameter structure is required, the Params parameter to the CSSM_DeriveKey() API has the Data field pointing to the parameter structure, and the Length field is the size of the parameter structure.

Context Type
CSSM_ALGCLASS_* 		Algorithm ID
CSSM_ALGID_* 		Parameter Structure
CSSM_SSL3_*
KEYGEN SSL3PreMasterGen None.
DERIVEKEY SSL3MasterDerive MASTER_KEY_DERIVE_PARAMS
DERIVEKEY SSL3KeyAndMacDerive KEY_AND_MAC_DERIVE_PARAMS
MAC SSL3MD5_MAC N/A
MAC"SSL3SHA1_MAC N/A  

Table: SSL 3.0 Algorithm IDs, Context Types and Parameter
 The Data Structures are defined below.
Data Structures
CSSM_SSL3_MASTER_KEY_DERIVE_PARAMS 


 

typedef struct CSSM_SSL3_MASTER_KEY_DERIVE_PARAMS {
    CSSM_DATA ClientRandom; /* Input  */ 
    CSSM_DATA ServerRandom; /* Input  */ 
    CSSM_VERSION Version;   /* Output */ 
} CSSM_SSL3_MASTER_KEY_DERIVE_PARAMS;

Definitions

ClientRandom (input)

Buffer containing the client random data. The CSP returns CSSMERR_CSP_INVALID_INPUT_POINTER if the data pointer is NULL, and CSSMERR_CSP_INVALID_DATA if the length is zero.

ServerRandom

Buffer containing the server random data. The CSP returns CSSMERR_CSP_INVALID_INPUT_POINTER if the data pointer is NULL, and CSSMERR_CSP_INVALID_DATA if the length is zero.

Version (output)

SSL protocol version number extracted from the pre-master secret during the derivation process. Modified by the key derivation process.


CSSM_SSL3_KEY_AND_MAC_DERIVE_PARAMS 


 

typedef struct CSSM_SSL3_KEY_AND_MAC_DERIVE_PARAMS {
    uint32 MACKeyLogicalSizeInBits;    /* Input */ 
    uint32 SecretKeyLogicalSizeInBits; /* Input */ 
    uint32 IVLengthInBits;             /* Input */ 
    CSSM_BOOL IsExport;                /* Input */ 
    CSSM_DATA ClientRandom;            /* Input */ 
    CSSM_DATA ServerRandom;            /* Input */ 
    CSSM_KEY ClientMACKey;             /* Output */ 
    CSSM_KEY ServerMACKey;             /* Output */ 
    CSSM_KEY ClientWriteKey;           /* Output */ 
    CSSM_KEY ServerWriteKey;           /* Output */
    CSSM_DATA ClientIV;                /* Output */ 
    CSSM_DATA ServerIV;                /* Output */ 
} CSSM_SSL3_KEY_AND_MAC_DERIVE_PARAMS;

Definitions

MACKeyLogicalSizeInBits (input)

The size of the MACing keys created during the derivation process.

SecretKeyLogicalSizeInBits (input)

The size of the encryption keys created during the derivation process.

IVLengthInBits (input)

If initialization vectors are required, then this must be set to the length of the IV in bits. If IVs are not required, then this field must be set to zero.

IsExport (input)

CSSM_TRUE if the keys are being derived for an export cipher, CSSM_FALSE otherwise.

ClientRandom (input)

Buffer containing the client random data. The CSP returns CSSMERR_CSP_INVALID_INPUT_POINTER if the data pointer is NULL, and CSSMERR_CSP_INVALID_DATA if the length is zero.

ServerRandom (input)

Buffer containing the server random data. The CSP returns CSSMERR_CSP_INVALID_INPUT_POINTER if the data pointer is NULL, and CSSMERR_CSP_INVALID_DATA if the length is zero.

ClientMACKey (output)

MACing key of type CSSM_ALGID_GenericSecret used for data written by the client.

ServerMACKey (output)

MACing key of type CSSM_ALGID_GenericSecret used for data written by the server.

ClientWriteKey (output)

Encryption key used for data written by the client.

ServerWriteKey (output)

Encryption key used for data written by the server.

ClientIV (output)

Initialization vector used for data written by the client.

ServerIV (output)

Initialization vector used for data written by the server.

Pre-Master Key Generation
SSL 3.0 Pre-Master Key Generation, CSSM_ALGID_SSL3PreMasterGen, is used to generate a 48-byte pre-master key. The client wraps the pre-master key and sends it to the server when the chosen key exchange mechanism is RSA or Fortezza.

The result of the key generation is a symmetric key of type CSSM_ALGID_GenericSecret. The length of the key is always 48 bytes (384 bits). The CSP returns CSSMERR_CSP_INVALID_ATTR_KEY_TYPE or CSSMERR_CSP_INVALID_ATTR_KEY_LENGTH if the requested key algorithm, or the requested length does not match those values respectively.

The pre-master secret includes a protocol version number to prevent version rollback attacks. The client can specify the protocol version by adding a CSSM_ATTRIBUTE_VERSION attribute to the key generation context. If the protocol version is not found in the context, then it defaults to 3.0.

Refer to the SSL 3.0 specification for a detailed description of pre-master key generation.

Master Key Derivation
SSL 3.0 Master Key Derivation, CSSM_ALGID_SSL3MasterDerive, is used to derive a 48-byte master secret from a pre-master secret key and random data supplied by both the client and the server. This step in the handshake protocol is performed regardless of the key exchange algorithm.

The result of the key derivation is a symmetric key of type CSSM_ALGID_GenericSecret. The length of the key is always 48 bytes (384 bits). The CSP returns CSSMERR_CSP_INVALID_ATTR_KEY_TYPE or CSSMERR_CSP_INVALID_ATTR_KEY_LENGTH if the requested key algorithm, or the requested length does not match those values respectively. The version number embedded in the pre-master secret is also returned in the CSSM_SSL_MASTER_KEY_DERIVE_PARAMS::Version field of the parameters structure.

The following rules are applied to the CSSM_KEYATTR_ALWAYS_SENSITIVE and CSSM_KEYATTR_NEVER_EXTRACTABLE attributes based on the attributes of the pre-master secret key and the attributes specified for the resulting key:

Encryption and MACing Secret Key Derivation
SSL 3.0 encryption and MACing key derivation, CSSM_ALGID_SSL3KeyAndMacDerive, is used to derive client and server encryption and integrity keys from the master secret key. This is the final step in the SSL 3.0 handshake protocol. The algorithm returns two encryption keys, two integrity keys, and two initialization vectors.

The two MACing keys are always type CSSM_ALGID_GenericSecret. The CSSM_KEYHEADER::KeyUse fields have the CSSM_KEYUSE_SIGN (generate MAC), CSSM_KEYUSE_VERIFY (verify MAC), and CSSM_KEYUSE_DERIVE flags set.

The two encryption keys are determined by the value of the CSSM_ATTRIBUTE_KEY_TYPE attribute in the context. The CSP will return CSSMERR_CSP_MISSING_ATTR_KEY_TYPE if the key type attribute is not present in the context, and CSSMERR_CSP_INVALID_ATTR_KEY_TYPE if the type is not supported by the CSP. The CSSM_KEYHEADER::KeyUse fields have the CSSM_KEYUSE_ENCRYPT, CSSM_KEYUSE_DECRYPT, and CSSM_KEYUSE_DERIVE flags set.

All four keys always inherit the values of the CSSM_KEYATTR_SENSITIVE, CSSM_KEYATTR_ALWAYS_SENSITIVE, CSSM_KEYATTR_EXTRACTABLE, and CSSM_KEYATTR_NEVER_EXTRACTABLE flags from the base key.

When using this algorithm, the DerivedKey parameter is not used and must be NULL.

MD5 and SHA-1 MACing
SSL 3.0 MD5 and SHA-1 MACing, CSSM_ALGID_SSL3MD5_MAC and CSSM_ALGID_SSL3SHA1_MAC, algorithms are used to generate message authentication codes according to the SSL 3.0 specification.

Algorithm Name
CSSM_ALGID_* 		Valid
Operations 		Applicable
Standard
SSL3MD5_MAC M Netscape SSL 3.0
SSL3SHA1_MAC M Netscape SSL 3.0

Table: MD5 and SHA-1 MAC Algorithms for MACs

The length of the MAC output is variable, from 4 to 8 bytes. The length is determined by specifying the CSSM_ATTRIBUTE_OUTPUT_SIZE parameter in the context. If the attribute is not present, then the output size defaults to 8. If the attribute is presentebut outside the valid range, the CSP returns CSSMERR_CSP_INVALID_ATTR_OUTPUT_SIZE. The CSSM_ATTRIBUTE_OUTPUT_SIZE attribute must be added to the context using the CSSM_UpdateContextAttributes() API.

Both MAC algorithms require a symmetric key with type CSSM_ALGID_GenericSecret.

Footnotes

1.
A process is defined as all threads of execution sharing the same addressable memory space.

Contents Next section Index