Previous section.

Common Security: CDSA and CSSM, Version 2
Copyright © 1999 The Open Group

Cryptographic Service Provider Behavior

Introduction

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 provides a set of behavior guidelines for CDSA Cryptographic Service Provider (CSP) modules. The scope is limited to the interface for cryptographic algorithms.

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

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

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 a big-endian octet string.
PKCS3 Diffie-Hellman private key T{ 
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.    
T}    
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 in 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

below describes the values of the CSSM_KEYHEADER fields and the corresponding key reference formats that they represent. A key reference format requires that:

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

Algorithm Use Abbreviations

The following table contains a list of algorithm actions, and the associated abbreviation used in the rest of this chapter.

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)
CSSM_SignData() (Private key)
CSSM_DecryptData() (Public key)
S Signature w/Appendix CSSM_SignData() (Private key)
CSSM_VerifyData() (Public key)
W Key wrapping CSSM_WrapKey() (Public key)
CSSM_WrapKey() (Symmetric key),
CSSM_UnwrapKey() (Private key)
CSSM_UnwrapKey() (Symmetric key)
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:

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. For the remainder of 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 has 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.

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

The extent of the message digest transformations performed by the CSP is governed by the CSSM_ATTRIBUTE_MODE and CSSM_ATTRIBUTE_DIGEST_ALG attributes. 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 CSSM_ATTRIBUTE_DIGEST_ALG attribute is present in the CC, the CSP must check the digest length to make sure that it is appropriate for the specified digest algorithm and then apply the digest tagging. If the attribute is not present in the CC, the CSP assumes that the client has performed the appropriate digest tagging and performs all other transformation operations, including padding. The CSP may optionally confirm that the information submitted for a signature is properly tagged before performing the private key operation. If the check is made and fails, the CSP returns the error CSSM_CSP_INVALID_DIGEST. Encrypt-only signatures can only be performed using single-stage APIs.

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

Context Typei
CSSM_ALGCLASS_*
Algorithm Mode
CSSM_ALGMODE_*
Valid
Operations
Applicable Standard
ASYMMETRIC PKCS1_EME_V15 P/R/W PKCS #1 v2.0, EME-PKCS1-v1_5
ASYMMETRIC PKCS1_EME_OAEP P/W PKCS #1 v2.0, EME-OAEP
SIGNATURE PKCS1_EMSA_V15 S/R PKCS #1 v2.0, EMSA-PKCS1-v1_5
SIGNATURE X9_31 S 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

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. If a specific public exponent value is required, the client can specify the value using the Param parameter of the CSSM_CSP_CreateKeyGenContext() API. The value of the parameter must be an exponent represented as an octet string with the most significant byte first. 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.

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


Click here to return to the publication details.

Contents Next section Index