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.
For example, the AlgorithmId field in the CSSM_KEYHEADER structure is referenced as:
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.
Format
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. |
Every key type has a default format that is used in the cases where the
caller does not specify a specific format type.
AlgorithmId
CSSM_ALGID_* | Format
CSSM_KEYBLOB_RAW_FORMAT_* |
---|---|
RSA | PKCS1 |
DSA | FIPS186 |
DH | PKCS3 |
All symmetric key algorithms | OCTET_STRING |
Format
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
|
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. |
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
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
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.
Format
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. |
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.
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
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 |
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
Format types allowed for wrapped keys are those that begin with
CSSM_KEYBLOB_WRAPPED_FORMAT_*. Note that the
Cryptographic Context Attribute
| Valid for APIs |
---|---|
PUBLIC_KEY_FORMAT | |
PRIVATE_KEY_FORMAT | |
SYMMETRIC_KEY_FORMAT | |
WRAPPED_KEY_FORMAT |
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".
Abbreviation | Algorithm Operation | CSSM API(s) |
---|---|---|
H | Message digest (hashing) | |
M | Message Authentication Code (MAC) | |
E | Symmetric key encryption | |
P | Public key encryption/private key decryption | |
R | Signature with message recovery (private key encryption/public key decryption) | |
S | Signature w/Appendix | |
W | Key wrapping | |
D | Key derivation | CSSM_DeriveKey |
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.
-
-
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.
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.
Context Typei
| Algorithm Mode
| 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 |
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
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.
Context Typei
| Algorithm Mode
| 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 |
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.
Contents | Next section | Index |