Cryptographic Service Provider Behavior

Introduction

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

STRUCTURE_TYPE::FieldName.

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

CSSM_KEYHEADER::AlgorithmId

Formats

Key Formats

• plaintext blobs

• indirect references

• wrapped blobs

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

• CSSM_KEYHEADER::BlobType is equal to CSSM_BLOBTYPE_RAW

• CSSM_KEYHEADER::WrapAlgorithmId is equal to CSSM_ALGID_NONE

• CSSM_KEYHEADER::WrapMode is equal to CSSM_ALGMODE_NONE

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.

Key References

• CSSM_KEYHEADER::BlobType is equal to CSSM_KEYBLOB_REFERENCE

• CSSM_KEYHEADER::WrapAlgorithmId is equal to CSSM_ALGID_NONE

• CSSM_KEYHEADER::WrapMode is equal to CSSM_ALGMODE_NONE

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

• CSSM_KEYHEADER::BlobType is equal to CSSM_KEYBLOB_WRAPPED,

• CSSM_KEYHEADER::WrapAlgorithmId is not equal to CSSM_ALGID_NONE, and

• CSSM_KEYHEADER::WrapMode is equal to the appropriate mode, possibly CSSM_ALGMODE_NONE.

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

Diffie-Hellman Private Keys

DSA Private Keys

Requesting Format Types

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.

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.

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

Basic Algorithm Usage

Digital Signatures

• Compute the message digest of a piece of data

• Perform 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. 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

 

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

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