The key header
contains meta-data about a key. It contains information used by a
CSP or application when using the associated key data. The service
provider module is responsible for setting the appropriate values.
typedef struct cssm_keyheader {
CSSM_HEADERVERSION HeaderVersion;
CSSM_GUID CspId;
uint32 BlobType;
uint32 Format;
uint32 AlgorithmId;
uint32 KeyClass;
uint32 KeySizeInBits;
uint32 KeyAttr;
uint32 KeyUsage;
CSSM_DATE StartDate;
CSSM_DATE EndDate;
uint32 WrapAlgorithmId;
uint32 WrapMode;
uint32 Reserved;
} CSSM_KEYHEADER, *CSSM_KEYHEADER_PTR;
Definitions:
- HeaderVersion
- This is the version of the key header structure.
- CspId
- If known, the GUID of the CSP that generated the key. This value
will not be known if a key is received from a third party, or extracted
from a certificate.
- BlobType
- Describes the basic format of the key data. It can be any one
of the values in Table 1.
Table 1. Keyblob
Type Identifiers| Identifier |
Description |
|---|
| CSSM_KEYBLOB_RAW |
The blob is a clear, raw key. |
|---|
| CSSM_KEYBLOB_RAW_BERDER |
The blob is a clear key, DER-encoded. |
|---|
| CSSM_KEYBLOB_REFERENCE |
The blob is a reference to a key. |
|---|
| CSSM_KEYBLOB_WRAPPED |
The blob is a wrapped RAW key. |
|---|
| CSSM_KEYBLOB_WRAPPED_BERDER |
The blob is a wrapped DER-encoded key. |
|---|
| CSSM_KEYBLOB_OTHER |
Other keyblob type. |
|---|
- Format
- Describes the detailed format of the key data based on the value
of the BlobType field. If the blob type has a non-reference
basic type, then a CSSM_KEYBLOB_RAW_FORMAT identifier must be used,
otherwise a CSSM_KEYBLOB_REF_FORMAT identifier is used. Any of the
values are valid as format identifiers in Table 2.
Table 2. Keyblob Format Identifiers| Keyblob Format Identifier |
Description |
|---|
| CSSM_KEYBLOB_RAW_FORMAT_NONE |
No further conversion needs to be done. |
|---|
| CSSM_KEYBLOB_RAW_FORMAT_PKCS1 |
RSA PKCS1 V1.5 |
|---|
| CSSM_KEYBLOB_RAW_FORMAT_PKCS3 |
RSA PKCS3 V1.5 |
|---|
| CSSM_KEYBLOB_RAW_FORMAT_MSCAPI |
Microsoft CAPI V2.0 |
|---|
| CSSM_KEYBLOB_RAW_FORMAT_PGP |
PGP |
|---|
| CSSM_KEYBLOB_RAW_FORMAT_FIPS186 |
U.S. Gov. FIPS 186 - DSS V |
|---|
| CSSM_KEYBLOB_RAW_FORMAT_BSAFE |
RSA BSAFE V3.0 |
|---|
| CSSM_KEYBLOB_RAW_FORMAT_PKCS11 |
RSA PKCS11 V2.0 |
|---|
| CSSM_KEYBLOB_RAW_FORMAT_CDSA |
Intel CDSA |
|---|
| CSSM_KEYBLOB_RAW_FORMAT_OTHER |
Other, CSP defined. |
|---|
| CSSM_KEYBLOB_REF_FORMAT_INTEGER |
Reference is a number or handle. |
|---|
| CSSM_KEYBLOB_REF_FORMAT_STRING |
Reference is a string or name. |
|---|
| CSSM_KEYBLOB_REF_FORMAT_OTHER |
Other, CSP defined. |
|---|
- AlgorithmId
- The algorithm for which the key was generated. This value does
not change when the key is wrapped. Any of the defined OCSF algorithm
IDs may be used.
- KeyClass
- Class of key contained in the keyblob. Valid key classes are
as follows in Table 3.
Table 3. Key
Class Identifiers| Key Class Identifiers |
Description |
|---|
| CSSM_KEYCLASS_PUBLIC_KEY |
Key is a public key. |
|---|
| CSSM_KEYCLASS_PRIVATE_KEY |
Key is a private key. |
|---|
| CSSM_KEYCLASS_SESSION_KEY |
Key is a session or symmetric key. |
|---|
| CSSM_KEYCLASS_SECRET_PART |
Key is part of secret key. |
|---|
| CSSM_KEYCLASS_OTHER |
Other |
|---|
- KeySizeInBits
- This is the logical size of the key in bits. The logical size
is the value referred to when describing the length of the key. For
instance, an RSA key would be described by the size of its modulus
and a DSA key would be represented by the size of its prime. Symmetric
key sizes describe the actual number of bits in the key. For example,
DES keys would be 64 bits and an RC4 key could range from 1 to 128
bits.
- KeyAttr
- Attributes of the key represented by the data. These attributes
are used by CSPs to convey information about stored or referenced
keys. The attributes are represented as a bit-mask (see Table 4).
- KeyUsage
- A bit-mask representing the valid uses of the key. Any of the
values are valid in Table 5.
Table 4. Key
Attribute Flags| Attribute |
Description |
|---|
| CSSM_KEYATTR_PERMANENT |
Key is stored persistently in the CSP, e.g., PKCS#11
token object. |
|---|
| CSSM_KEYATTR_PRIVATE |
Key is a private object and protected by either
a user login, a password, or both. |
|---|
| CSSM_KEYATTR_MODIFIABLE |
The key or its attributes can be modified. |
|---|
| CSSM_KEYATTR_SENSITIVE |
Key is sensitive. It may only be extracted from
the CSP in a wrapped state. It will always be false for raw keys. |
|---|
| CSSM_KEYATTR_ALWAYS_SENSITIVE |
Key has always been sensitive. It will always
be false for raw keys. |
|---|
| CSSM_KEYATTR_EXTRACTABLE |
Key is extractable from the CSP. If this bit is
not set, the key is either not stored in the CSP or cannot be extracted
from the CSP under any circumstances. It will always be false for
raw keys. |
|---|
| CSSM_KEYATTR_NEVER_EXTRACTABLE |
Key has never been extractable. It will always
be false for raw keys. |
|---|
Table 5. Key Usage Flags| Usage Mask |
Description |
|---|
| CSSM_KEYUSE_ANY |
Key may be used for any purpose supported by the
algorithm. |
|---|
| CSSM_KEYUSE_ENCRYPT |
Key may be used for encryption. |
|---|
| CSSM_KEYUSE_DECRYPT |
Key may be used for decryption. |
|---|
| CSSM_KEYUSE_SIGN |
Key can be used to generate signatures. For symmetric
keys this represents the ability to generate MACs. |
|---|
| CSSM_KEYUSE_VERIFY |
Key can be used to verify signatures. For symmetric
keys this represents the ability to verify MACs. |
|---|
| CSSM_KEYUSE_SIGN_RECOVER |
Key can be used to perform signatures with message
recovery. This form of a signature is generated using the CSSM_EncryptData
API with the algorithm mode set to CSSM_ALGMODE_PRIVATE_KEY. This
attribute is only valid for asymmetric algorithms. |
|---|
| CSSM_KEYUSE_VERIFY_RECOVER |
Key can be used to verify signatures with message
recovery. This form of a signature is verified using the CSSM_DecryptData
API with the algorithm mode set to CSSM_ALGMODE_PRIVATE_KEY. This
attribute is only valid for asymmetric algorithms. |
|---|
| CSSM_KEYUSE_WRAP |
Key can be used to wrap another key. |
|---|
| CSSM_KEYUSE_UNWRAP |
Key can be used to unwrap a key. |
|---|
| CSSM_KEYUSE_DERIVE |
Key can be used as the source for deriving other
keys. |
|---|
- StartDate
- Date from which the corresponding key is valid. All fields of
the CSSM_DATA structure will be set to zero if the date is unspecified
or unknown. This date is not enforced by the CSP.
- EndDate
- Data that the key expires and can no longer be used. All fields
of the CSSM_DATA structure will be set to zero is the date if unspecified
or unknown. This date is not enforced by the CSP.
- WrapAlgorithmId
- If the key data contains a wrapped key, this field contains the
algorithm used to create the wrapped blob. This field will be set
to CSSM_ALGID_NONE if the key is not wrapped.
- WrapMode
- If the wrapping algorithm supports multiple wrapping modes, this
field contains the mode used to wrap the key. This field is ignored
if the WrapAlgorithmId is CSSM_ALGID_NONE.
- Reserved
- This field is reserved for future use. It should always be set
to zero.