The CSP is always responsible for the secure storage of private keys. Optionally the CSP may assume responsibility for the secure storage of other object types, such as symmetric keys and certificates. The implementation of secured persistent storage for keys can use the services of a Data Storage Library module within the CSSM framework (if that module provides secured storage) or some approach internal to the CSP. Accessing persistent objects managed by the CSP, other than keys, is performed using CSSM's Data Storage Library APIs.
CSPs optionally support a password-based login sequence. When login is
supported, the caller is allowed to change passwords as deemed
necessary. This is part of a standard user-initiated maintenance
procedure. Some CSPs support operations for privileged, CSP
administrators. The model for CSP administration varies widely among
CSP implementations. For this reason, CSSM does not define APIs for
vendor-specific CSP administration operations. CSP vendors can make
these services available to CSP administration tools using the
All cryptographic services requested by applications will be channeled to one of the CSPs via the CSSM. CSP vendors only need target their modules to CSSM for all security-conscious applications to have access to their product.
Before an application calls a CSP to perform a cryptographic operation,
the application uses the
Module Directory Service (MDS) to determine what CSPs are available on
the system, and what services they provide.
Based on this
information, the application then can determine which CSP to use for
subsequent
operations. An application establishes an attach session using
Depending on the class of cryptographic operations, individualized attributes are available for the cryptographic context. Besides specifying an algorithm when creating the context, the application may also initialize a session key, pass an initialization vector and/or pass padding information to complete the description of the session. A successful return value from the create function indicates the desired CSP is available. Functions are also provided to manage the created context. The cryptographic context contains most if not all of the input parameters required for an operation. Some of the cryptographic service functions accept input parameters in addition to the CSP Handle and the context handle. These input parameters always take precedence over any duplicate or conflicting parameters in the cryptographic context.
When a context is no longer required, the application calls CSSMDeleteContext. Resources that were allocated for that context can be reclaimed by the operating system.
Cryptographic operations come in two types-a single call to perform an operation and a staged method of performing the operation. For the single call method, only one call is needed to obtain the result. For the staged method, there is an initialization call followed by one or more update calls, and ending with a completion (final) call. The result is available after the final function completes its execution for most cryptographic operations-staged encryption/decryption are an exception in that each update call generates a portion of the result.
The two PKI-based algorithms with wide spread usage are:
For RSA-based algorithms, CDSA adopts the PKCS#1 standard for key representation.
For DSA-based algorithms, no organization has published a standard and no de facto standard seems to exists. CDSA defines a standard representation for DSA key based on the DSA algorithm definitions in the FIPS 186 and FIPS 186a standards. Complete documentation on these standards can be found at http://csrc.ncsl.nist.gov/fips/fips186.txt and at http://csrc.ncsl.nist.gov/fips/fips186a.txt respectively.
A DSA public key is represented as a BER-encoded, ordered sequence containing the prime modulus, the prime divisor, the order modulo the prime modulus, and the public key value. A DSA private key is represented as a BER-encoded, ordered sequence containing the prime modulus, the prime divisor, the order modulo the prime modulus, and the private key value. Additional information is provided in the specification titled CSSM Cryptographic Service Providers Interface.
A DSA wrapped, private key is represented as defined by the PKCS#8 specification. The PKCS#8 standard specifies the wrapped key format resulting from encoding an algorithm OID with an encoded private key.
typedef CSSM_LONG_HANDLE CSSM_CC_HANDLE; /* Cryptographic Context
Handle */
typedef CSSM_MODULE_HANDLE CSSM_CSP_HANDLE /* Cryptographic Service
Provider Handle */
typedef struct cssm_date {
uint8 Year[4];
uint8 Month[2];
uint8 Day[2];
} CSSM_DATE, *CSSM_DATE_PTR;
typedef struct cssm_range {
uint32 Min; /* inclusive minimum value */
uint32 Max; /* inclusive maximum value */
} CSSM_RANGE, *CSSM_RANGE_PTR;
typedef struct cssm_query_size_data {
uint32 SizeInputBlock; /* size of input data block */
uint32 SizeOutputBlock; /* size of resulting output
data block */
} CSSM_QUERY_SIZE_DATA, *CSSM_QUERY_SIZE_DATA_PTR;
typedef uint32 CSSM_HEADERVERSION;
#define CSSM_KEYHEADER_VERSION (2)
typedef struct cssm_key_size {
uint32 LogicalKeySizeInBits; /* Logical key size in bits */
uint32 EffectiveKeySizeInBits; /* Effective key size in bits */
} CSSM_KEY_SIZE, *CSSM_KEY_SIZE_PTR;
typedef uint32 CSSM_KEYBLOB_TYPE;
#define CSSM_KEYBLOB_RAW (0) /* The blob is a clear, raw key */
#define CSSM_KEYBLOB_REFERENCE (1) /* The blob is a reference to a key */
#define CSSM_KEYBLOB_WRAPPED (2) /* The blob is a wrapped RAW key */
#define CSSM_KEYBLOB_OTHER (0xFFFFFFFF)
typedef uint32 CSSM_KEYBLOB_FORMAT;
/* Raw Format */
#define CSSM_KEYBLOB_RAW_FORMAT_NONE (0)
/* No further conversion need to be done */
#define CSSM_KEYBLOB_RAW_FORMAT_PKCS1 (1) /* RSA PKCS1 V1.5 */
#define CSSM_KEYBLOB_RAW_FORMAT_PKCS3 (2) /* RSA PKCS3 V1.5 */
#define CSSM_KEYBLOB_RAW_FORMAT_MSCAPI (3) /* Microsoft CAPI V2.0 */
#define CSSM_KEYBLOB_RAW_FORMAT_PGP (4) /* PGP V */
#define CSSM_KEYBLOB_RAW_FORMAT_FIPS186 (5) /* US Gov. FIPS 186 - DSS V */
#define CSSM_KEYBLOB_RAW_FORMAT_BSAFE (6) /* RSA Bsafe V3.0 */
#define CSSM_KEYBLOB_RAW_FORMAT_CCA (9) /* CCA clear public key blob */
#define CSSM_KEYBLOB_RAW_FORMAT_PKCS8 (10) /* RSA PKCS8 V1.2 */
#define CSSM_KEYBLOB_RAW_FORMAT_SPKI (11) /* SPKI Specification */
#define CSSM_KEYBLOB_RAW_FORMAT_OCTET_STRING (12)
#define CSSM_KEYBLOB_RAW_FORMAT_OTHER (0xFFFFFFFF) /* Other, CSP defined */
/* Wrapped Format */
#define CSSM_KEYBLOB_WRAPPED_FORMAT_NONE 90)
/* No further conversion need to be done */
#define CSSM_KEYBLOB_WRAPPED_FORMAT_PKCS8 (1) /* RSA PKCS8 V1.2 */
#define CSSM_KEYBLOB_WRAPPED_FORMAT_PKCS7 (2)
> #define CSSM_KEYBLOB_WRAPPED_FORMAT_MSCAPI (3)
#define CSSM_KEYBLOB_WRAPPED_FORMAT_OTHER (0xFFFFFFFF) /* Other, CSP defined */
/* Reference Format */
#define CSSM_KEYBLOB_REF_FORMAT_INTEGER (0) /*Reference is a number or handle*/
#define CSSM_KEYBLOB_REF_FORMAT_STRING (1) /* Reference is a string or label */
#define CSSM_KEYBLOB_REF_FORMAT_SPKI (2) /* Reference is an SPKI S-expression*/
/* to be evaluated to locate the key */
#define CSSM_KEYBLOB_REF_FORMAT_UNIQUE_ID (3) /* A unique ID for the key */
/*relative to the data base in which it is created */
#define CSSM_KEYBLOB_REF_FORMAT_OTHER (0xFFFFFFFF) /* Other, CSP defined */
typedef uint32 CSSM_KEYCLASS;
#define CSSM_KEYCLASS_PUBLIC_KEY (0) /* Key is public key */
#define CSSM_KEYCLASS_PRIVATE_KEY (1) /* Key is private key */
#define CSSM_KEYCLASS_SESSION_KEY (2) /* Key is session or symmetric key */
#define CSSM_KEYCLASS_SECRET_PART (3) /* Key is part of secret key */
#define CSSM_KEYCLASS_OTHER (0xFFFFFFFF) /* Other */
typedef uint32 CSSM_KEYATTR_FLAGS;
/* Valid only during call to an API. Will never be valid when set
in a key header */
#define CSSM_KEYATTR_RETURN_DEFAULT (0x00000000)
#define CSSM_KEYATTR_RETURN_DATA (0x10000000)
#define CSSM_KEYATTR_RETURN_REF (0x20000000)
#define CSSM_KEYATTR_RETURN_NONE (0x40000000)
/* Valid during an API call and in a key header */
#define CSSM_KEYATTR_PERMANENT (0x00000001)
#define CSSM_KEYATTR_PRIVATE (0x00000002)
#define CSSM_KEYATTR_MODIFIABLE (0x00000004)
#define CSSM_KEYATTR_SENSITIVE (0x00000008)
#define CSSM_KEYATTR_EXTRACTABLE (0x00000020)
/* Valid only in a key header generated by a CSP, not valid during
an API call */
#define CSSM_KEYATTR_ALWAYS_SENSITIVE (0x00000010)
#define CSSM_KEYATTR_NEVER_EXTRACTABLE (0x00000040)
typedef uint32 CSSM_KEYUSE;
#define CSSM_KEYUSE_ANY (0x80000000)
#define CSSM_KEYUSE_ENCRYPT (0x00000001)
#define CSSM_KEYUSE_DECRYPT (0x00000002)
#define CSSM_KEYUSE_SIGN (0x00000004)
#define CSSM_KEYUSE_VERIFY (0x00000008)
#define CSSM_KEYUSE_SIGN_RECOVER (0x00000010)
#define CSSM_KEYUSE_VERIFY_RECOVER (0x00000020)
#define CSSM_KEYUSE_WRAP (0x00000040)
#define CSSM_KEYUSE_UNWRAP (0x00000080)
#define CSSM_KEYUSE_DERIVE (0x00000100)
The key header attributes describe both the CSP-stored copy of the key
and the application's local ...
Most of these
attributes describe both the CSP-stored copy of the key and the
application's local copy of the key or the key reference. A subset of
the attributes describe only the application-resident copy of the key
or the key reference. A table at the end of this section summarizes the
scope of each key header attribute.
typedef struct cssm_keyheader {
CSSM_HEADERVERSION HeaderVersion; /* Key header version */
CSSM_GUID CspId; /* GUID of CSP generating the key */
CSSM_KEYBLOB_TYPE BlobType; /* See BlobType #define's */
CSSM_KEYBLOB_FORMAT Format; /* Raw or Reference format */
CSSM_ALGORITHMS AlgorithmId; /* Algorithm ID of key */
CSSM_KEYCLASS KeyClass; /* Public/Private/Secret, etc. */
uint32 LogicalKeySizeInBits; /* Logical key size in bits */
CSSM_KEYATTR_FLAGS KeyAttr; /* Attribute flags */
CSSM_KEYUSE KeyUsage; /* Key use flags */
CSSM_DATE StartDate; /* Effective date of key */
CSSM_DATE EndDate; /* Expiration date of key */
CSSM_ALGORITHMS WrapAlgorithmId; /* == CSSM_ALGID_NONE if clear key */
CSSM_ENCRYPT_MODE WrapMode; /* if alg supports multiple wrapping modes */
uint32 Reserved;
} CSSM_KEYHEADER, *CSSM_KEYHEADER_PTR;
Keyblob Type 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 key |
CSSM_KEYBLOB_OTHER | The blob is CSP specific |
Keyblob Format Identifier | Description |
---|---|
CSSM_KEYBLOB_RAW_FORMAT_NONE | Raw format is none |
CSSM_KEYBLOB_RAW_FORMAT_PKCS1 | RSA PKCS1 V1.5 See "RSA Encryption Standard", an RSA Laboratories publication http://www.rsa.com/rsalabs/pubs/PKCS/ |
CSSM_KEYBLOB_RAW_FORMAT_PKCS3 | RSA PKCS3 V1.5 See"Diffie-Hellman Key-Agreement Standard", an RSA Laboratories publication http://www.rsa.com/rsalabs/pubs/PKCS/ |
CSSM_KEYBLOB_RAW_FORMAT_MSCAPI | Microsoft CAPI V2.0 |
CSSM_KEYBLOB_RAW_FORMAT_PGP | PGP See "PGP Cryptographic Software Development Kit (PGP sdk)", a PGP Publication |
CSSM_KEYBLOB_RAW_FORMAT_FIPS186 | US Gov. FIPS 186: DSS V |
CSSM_KEYBLOB_RAW_FORMAT_BSAFE | RSA Bsafe V3.0 See "BSAFE, A Cryptographic Toolkit, Library Reference Manual", an RSA Data Security Inc. publication |
CSSM_KEYBLOB_RAW_FORMAT_CCA | CCA clear public key blob |
CSSM_KEYBLOB_RAW_FORMAT_PKCS8 | RSA PKCS8 V1.2 See "Private-Key Information Syntax Standard", an RSA Laboratories publication http://www.rsa.com/rsalabs/pubs/PKCS/" |
CSSM_KEYBLOB_RAW_FORMAT_SPKI | SPKI Specification |
CSSM_KEYBLOB_RAW_FORMAT_OTHER | Other, CSP defined |
CSSM_KEYBLOB_WRAPPED_FORMAT_NONE | No further conversion needs to be performed |
CSSM_KEYBLOB_WRAPPED_FORMAT_PKCS8 | PKCS8 V1.2: See "Private-Key Information Syntax Standard", an RSA Laboratories publication http://www.rsa.com/rsalabs/pubs/PKCS/ |
CSSM_KEYBLOB_WRAPPED_FORMAT_PKCS5 | PKCS5 V1.5 PBE scheme |
CSSM_KEYBLOB_WRAPPED_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 label |
CSSM_KEYBLOB_REF_FORMAT_SPKI | Reference is an SPKI S-expression to be evaluated to locate the key |
CSSM_KEYBLOB_REF_FORMAT_OTHER | Reference is a CSP-defined format |
Key Class Identifier | 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 |
Attribute values valid only as inputs to functions and will never appear in a key header: | |
---|---|
Attribute | Description |
CSSM_KEYATTR_RETURN_DEFAULT | Key is returned in CSP's default form. |
CSSM_KEYATTR_RETURN_DATA | Key is returned with key bits present. The format of the returned key can be raw or wrapped. |
CSSM_KEYATTR_RETURN_REF | Key is returned as a reference. |
CSSM_KEYATTR_RETURN_NONE | Key is not returned. |
Attribute values valid as inputs to functions and retained values in a key header: | |
Attribute | Description |
CSSM_KEYATTR_PERMANENT | Key is stored persistently in the CSP, such asa PKCS11 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. |
CSSM_KEYATTR_EXTRACTABLE | Key is extractable from the CSP. If this bit is not set, either the key is not stored in the CSP, or it cannot be extracted under any circumstances. |
Attribute values valid in a key header when set by a CSP: | |
Attribute | Description |
CSSM_KEYATTR_ALWAYS_SENSITIVE | Key has always been sensitive. |
CSSM_KEYATTR_NEVER_EXTRACTABLE | Key has never been extractable. |
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_KEYUSE_VERIFY_RECOVER | Key can be used to verify signatures with message recovery. This form of a signature verified using the CSSM_DecryptData API with the algorithm mode set to |
CSSM_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. |
The scope of the key header attributes is summarized as follows:
Attribute Name | Pertains to the Application's local copy of the key | Pertains to the CSP-stored copy of the key |
---|---|---|
BlobType | X | |
Format | X | |
AlgorithmId | X | X |
KeyClass | X | X |
LogicalKeySizeInBits | X | X |
KeyAttr | Only the flag bits RETURN_XXX | All the flag bits except RETURN_XXX |
KeyUsage | X | X |
StartDate | X | X |
EndDate | X | X |
WrapAlgorithmId | X | |
WrapMode | X |
typedef struct cssm_key {
CSSM_KEYHEADER KeyHeader; /* Fixed length key header */
CSSM_DATA KeyData; /* Variable length key data */
} CSSM_KEY, *CSSM_KEY_PTR;
typedef CSSM_KEY CSSM_WRAP_KEY, *CSSM_WRAP_KEY_PTR;
typedef enum cssm_csptype {
CSSM_CSP_SOFTWARE = 1,
CSSM_CSP_HARDWARE = CSSM_CSP_SOFTWARE+1,
CSSM_CSP_HYBRID = CSSM_CSP_SOFTWARE+2,
}CSSM_CSPTYPE;
typedef uint32 CSSM_CONTEXT_TYPE;
#define CSSM_ALGCLASS_NONE (0)
#define CSSM_ALGCLASS_CUSTOM (CSSM_ALGCLASS_NONE+1)
#define CSSM_ALGCLASS_SIGNATURE (CSSM_ALGCLASS_NONE+2)
#define CSSM_ALGCLASS_SYMMETRIC (CSSM_ALGCLASS_NONE+3)
#define CSSM_ALGCLASS_DIGEST (CSSM_ALGCLASS_NONE+4)
#define CSSM_ALGCLASS_RANDOMGEN (CSSM_ALGCLASS_NONE+5)
#define CSSM_ALGCLASS_UNIQUEGEN (CSSM_ALGCLASS_NONE+6)
#define CSSM_ALGCLASS_MAC (CSSM_ALGCLASS_NONE+7)
#define CSSM_ALGCLASS_ASYMMETRIC(CSSM_ALGCLASS_NONE+8)
#define CSSM_ALGCLASS_KEYGEN (CSSM_ALGCLASS_NONE+9)
#define CSSM_ALGCLASS_DERIVEKEY (CSSM_ALGCLASS_NONE+10)
typedef uint32 CSSM_ALGORITHMS;
#define CSSM_ALGID_NONE (0)
#define CSSM_ALGID_CUSTOM (CSSM_ALGID_NONE+1)
#define CSSM_ALGID_DH (CSSM_ALGID_NONE+2)
#define CSSM_ALGID_PH (CSSM_ALGID_NONE+3)
#define CSSM_ALGID_KEA (CSSM_ALGID_NONE+4)
#define CSSM_ALGID_MD2 (CSSM_ALGID_NONE+5)
#define CSSM_ALGID_MD4 (CSSM_ALGID_NONE+6)
#define CSSM_ALGID_MD5 (CSSM_ALGID_NONE+7)
#define CSSM_ALGID_SHA1 (CSSM_ALGID_NONE+8)
#define CSSM_ALGID_NHASH (CSSM_ALGID_NONE+9)
#define CSSM_ALGID_HAVAL (CSSM_ALGID_NONE+10)
#define CSSM_ALGID_RIPEMD (CSSM_ALGID_NONE+11)
#define CSSM_ALGID_IBCHASH (CSSM_ALGID_NONE+12)
#define CSSM_ALGID_RIPEMAC (CSSM_ALGID_NONE+13)
#define CSSM_ALGID_DES (CSSM_ALGID_NONE+14)
#define CSSM_ALGID_DESX (CSSM_ALGID_NONE+15)
#define CSSM_ALGID_RDES (CSSM_ALGID_NONE+16)
#define CSSM_ALGID_3DES_3KEY_EDE (CSSM_ALGID_NONE+17)
#define CSSM_ALGID_3DES_2KEY_EDE (CSSM_ALGID_NONE+18)
#define CSSM_ALGID_3DES_1KEY_EEE (CSSM_ALGID_NONE+19)
#define CSSM_ALGID_3DES_3KEY CSSM_ALGID_3DES_3KEY_EDE
#define CSSM_ALGID_3DES_3KEY_EEE (CSSM_ALGID_NONE+20)
#define CSSM_ALGID_3DES_2KEY CSSM_ALGID_3DES_2KEY_EDE
#define CSSM_ALGID_3DES_2KEY_EEE (CSSM_ALGID_NONE+21)
#define CSSM_ALGID_IDEA (CSSM_ALGID_NONE+22)
#define CSSM_ALGID_RC2 (CSSM_ALGID_NONE+23)
#define CSSM_ALGID_RC5 (CSSM_ALGID_NONE+24)
#define CSSM_ALGID_RC4 (CSSM_ALGID_NONE+25)
#define CSSM_ALGID_SEAL (CSSM_ALGID_NONE+26)
#define CSSM_ALGID_CAST (CSSM_ALGID_NONE+27)
#define CSSM_ALGID_BLOWFISH (CSSM_ALGID_NONE+28)
#define CSSM_ALGID_SKIPJACK (CSSM_ALGID_NONE+29)
#define CSSM_ALGID_LUCIFER (CSSM_ALGID_NONE+30)
#define CSSM_ALGID_MADRYGA (CSSM_ALGID_NONE+31)
#define CSSM_ALGID_FEAL (CSSM_ALGID_NONE+32)
#define CSSM_ALGID_REDOC (CSSM_ALGID_NONE+33)
#define CSSM_ALGID_REDOC3 (CSSM_ALGID_NONE+34)
#define CSSM_ALGID_LOKI (CSSM_ALGID_NONE+35)
#define CSSM_ALGID_KHUFU (CSSM_ALGID_NONE+36)
#define CSSM_ALGID_KHAFRE (CSSM_ALGID_NONE+37)
#define CSSM_ALGID_MMB (CSSM_ALGID_NONE+38)
#define CSSM_ALGID_GOST (CSSM_ALGID_NONE+39)
#define CSSM_ALGID_SAFER (CSSM_ALGID_NONE+40)
#define CSSM_ALGID_CRAB (CSSM_ALGID_NONE+41)
#define CSSM_ALGID_RSA (CSSM_ALGID_NONE+42)
#define CSSM_ALGID_DSA (CSSM_ALGID_NONE+43)
#define CSSM_ALGID_MD5WithRSA(CSSM_ALGID_NONE+44)
#define CSSM_ALGID_MD2WithRSA(CSSM_ALGID_NONE+45)
#define CSSM_ALGID_ElGamal (CSSM_ALGID_NONE+46)
#define CSSM_ALGID_MD2Random (CSSM_ALGID_NONE+47)
#define CSSM_ALGID_MD5Random (CSSM_ALGID_NONE+48)
#define CSSM_ALGID_SHARandom (CSSM_ALGID_NONE+49)
#define CSSM_ALGID_DESRandom (CSSM_ALGID_NONE+50)
#define CSSM_ALGID_SHA1WithRSA (CSSM_ALGID_NONE+51)
#define CSSM_ALGID_CDMF (CSSM_ALGID_NONE+52)
#define CSSM_ALGID_CAST3 (CSSM_ALGID_NONE+53)
#define CSSM_ALGID_CAST5 (CSSM_ALGID_NONE+54)
#define CSSM_ALGID_GenericSecret (CSSM_ALGID_NONE+55)
#define CSSM_ALGID_ConcatBaseAndKey (CSSM_ALGID_NONE+56)
#define CSSM_ALGID_ConcatKeyAndBase (CSSM_ALGID_NONE+57)
#define CSSM_ALGID_ConcatBaseAndData (CSSM_ALGID_NONE+58)
#define CSSM_ALGID_ConcatDataAndBase (CSSM_ALGID_NONE+59)
#define CSSM_ALGID_XORBaseAndData (CSSM_ALGID_NONE+60)
#define CSSM_ALGID_ExtractFromKey (CSSM_ALGID_NONE+61)
#define CSSM_ALGID_SSL3PreMasterGen (CSSM_ALGID_NONE+62)
#define CSSM_ALGID_SSL3MasterDerive (CSSM_ALGID_NONE+63)
#define CSSM_ALGID_SSL3KeyAndMacDerive (CSSM_ALGID_NONE+64)
#define CSSM_ALGID_SSL3MD5_MAC (CSSM_ALGID_NONE+65)
#define CSSM_ALGID_SSL3SHA1_MAC (CSSM_ALGID_NONE+66)
#define CSSM_ALGID_MD5_PBE (CSSM_ALGID_NONE+67)
#define CSSM_ALGID_MD2_PBE (CSSM_ALGID_NONE+68)
#define CSSM_ALGID_SHA1_PBE (CSSM_ALGID_NONE+69)
#define CSSM_ALGID_WrapLynks (CSSM_ALGID_NONE+70)
#define CSSM_ALGID_WrapSET_OAEP (CSSM_ALGID_NONE+71)
#define CSSM_ALGID_BATON (CSSM_ALGID_NONE+72)
#define CSSM_ALGID_ECDSA (CSSM_ALGID_NONE+73)
#define CSSM_ALGID_MAYFLY (CSSM_ALGID_NONE+74)
#define CSSM_ALGID_JUNIPER (CSSM_ALGID_NONE+75)
#define CSSM_ALGID_FASTHASH (CSSM_ALGID_NONE+76)
#define CSSM_ALGID_3DES (CSSM_ALGID_NONE+77)
#define CSSM_ALGID_SSL3MD5 (CSSM_ALGID_NONE+78)
#define CSSM_ALGID_SSL3SHA1 (CSSM_ALGID_NONE+79)
#define CSSM_ALGID_FortezzaTimestamp (CSSM_ALGID_NONE+80)
#define CSSM_ALGID_SHA1WithDSA (CSSM_ALGID_NONE+81)
#define CSSM_ALGID_SHA1WithECDSA (CSSM_ALGID_NONE+82)
#define CSSM_ALGID_DSA_BSAFE (CSSM_ALGID_NONE+83)
#define CSSM_ALGID_ECDH (CSSM_ALGID_NONE+84)
#define CSSM_ALGID_ECMQV (CSSM_ALGID_NONE+85)
#define CSSM_ALGID_PKCS12_SHA1_PBE (CSSM_ALGID_NONE+86)
#define CSSM_ALGID_ECNRA (CSSM_ALGID_NONE+87)
#define CSSM_ALGID_SHA1WithECNRA (CSSM_ALGID_NONE+88)
#define CSSM_ALGID_ECES (CSSM_ALGID_NONE+89)
#define CSSM_ALGID_ECAES (CSSM_ALGID_NONE+90)
#define CSSM_ALGID_SHA1HMAC (CSSM_ALGID_NONE+91)
#define CSSM_ALGID_FIPS186Random (CSSM_ALGID_NONE+92)
#define CSSM_ALGID_ECC (CSSM_ALGID_NONE+93)
#define CSSM_ALGID_MQV (CSSM_ALGID_NONE+94)
#define CSSM_ALGID_NRA (CSSM_ALGID_NONE+95)
#define CSSM_ALGID_IntelPlatformRandom (CSSM_ALGID_NONE+96)
#define CSSM_ALGID_UTC (CSSM_ALGID_NONE+97)
#define CSSM_ALGID_HAVAL3 (CSSM_ALGID_NONE+98)
#define CSSM_ALGID_HAVAL4 (CSSM_ALGID_NONE+99)
#define CSSM_ALGID_HAVAL5 (CSSM_ALGID_NONE+100)
#define CSSM_ALGID_TIGER (CSSM_ALGID_NONE+101)
#define CSSM_ALGID_MD5HMAC (CSSM_ALGID_NONE+102)
#define CSSM_ALGID_LAST (0x7FFFFFFF)
/*
* All algorithms IDs that are vendor specific, and not
* part of the CSSM specification should be defined relative
* to CSSM_ALGID_VENDOR_DEFINED.
*/
#define CSSM_ALGID_VENDOR_DEFINED (CSSM_ALGID_NONE+0x80000000)
/* Attribute data type tags */
#define CSSM_ATTRIBUTE_DATA_NONE (0x00000000)
#define CSSM_ATTRIBUTE_DATA_UINT32 (0x10000000)
#define CSSM_ATTRIBUTE_DATA_CSSM_DATA (0x20000000)
#define CSSM_ATTRIBUTE_DATA_CRYPTO_DATA (0x30000000)
#define CSSM_ATTRIBUTE_DATA_KEY (0x40000000)
#define CSSM_ATTRIBUTE_DATA_STRING (0x50000000)
#define CSSM_ATTRIBUTE_DATA_DATE (0x60000000)
#define CSSM_ATTRIBUTE_DATA_RANGE (0x70000000)
#define CSSM_ATTRIBUTE_DATA_ACCESS_CREDENTIALS (0x80000000)
#define CSSM_ATTRIBUTE_DATA_VERSION (0x01000000)
#define CSSM_ATTRIBUTE_DATA_DL_DB_HANDLE (0x02000000)
#define CSSM_ATTRIBUTE_TYPE_MASK (0xFF000000)
typedef enum cssm_attribute_type {
CSSM_ATTRIBUTE_NONE = 0,
CSSM_ATTRIBUTE_CUSTOM = CSSM_ATTRIBUTE_DATA_CSSM_DATA | 1,
CSSM_ATTRIBUTE_DESCRIPTION = CSSM_ATTRIBUTE_DATA_STRING | 2,
CSSM_ATTRIBUTE_KEY = CSSM_ATTRIBUTE_DATA_KEY | 3,
CSSM_ATTRIBUTE_INIT_VECTOR = CSSM_ATTRIBUTE_DATA_CSSM_DATA | 4,
CSSM_ATTRIBUTE_SALT = CSSM_ATTRIBUTE_DATA_CSSM_DATA | 5,
CSSM_ATTRIBUTE_PADDING = CSSM_ATTRIBUTE_DATA_UINT32 | 6,
CSSM_ATTRIBUTE_RANDOM = CSSM_ATTRIBUTE_DATA_CSSM_DATA | 7,
CSSM_ATTRIBUTE_SEED = CSSM_ATTRIBUTE_DATA_CRYPTO_DATA | 8,
CSSM_ATTRIBUTE_PASSPHRASE = CSSM_ATTRIBUTE_DATA_CRYPTO_DATA | 9,
CSSM_ATTRIBUTE_KEY_LENGTH = CSSM_ATTRIBUTE_DATA_UINT32 | 10,
CSSM_ATTRIBUTE_KEY_LENGTH_RANGE = CSSM_ATTRIBUTE_DATA_RANGE | 11,
CSSM_ATTRIBUTE_BLOCK_SIZE = CSSM_ATTRIBUTE_DATA_UINT32 | 12,
CSSM_ATTRIBUTE_OUTPUT_SIZE = CSSM_ATTRIBUTE_DATA_UINT32 | 13,
CSSM_ATTRIBUTE_ROUNDS = CSSM_ATTRIBUTE_DATA_UINT32 | 14,
CSSM_ATTRIBUTE_IV_SIZE = CSSM_ATTRIBUTE_DATA_UINT32 | 15,
CSSM_ATTRIBUTE_ALG_PARAMS = CSSM_ATTRIBUTE_DATA_CSSM_DATA | 16,
CSSM_ATTRIBUTE_LABEL = CSSM_ATTRIBUTE_DATA_CSSM_DATA | 17,
CSSM_ATTRIBUTE_KEY_TYPE = CSSM_ATTRIBUTE_DATA_UINT32 | 18,
CSSM_ATTRIBUTE_MODE = CSSM_ATTRIBUTE_DATA_UINT32 | 19,
CSSM_ATTRIBUTE_EFFECTIVE_BITS = CSSM_ATTRIBUTE_DATA_UINT32 | 20,
CSSM_ATTRIBUTE_START_DATE = CSSM_ATTRIBUTE_DATA_DATE | 21,
CSSM_ATTRIBUTE_END_DATE = CSSM_ATTRIBUTE_DATA_DATE | 22,
CSSM_ATTRIBUTE_KEYUSAGE = CSSM_ATTRIBUTE_DATA_UINT32 | 23,
CSSM_ATTRIBUTE_KEYATTR = CSSM_ATTRIBUTE_DATA_UINT32 | 24,
CSSM_ATTRIBUTE_VERSION = CSSM_ATTRIBUTE_DATA_VERSION | 25,
CSSM_ATTRIBUTE_PRIME = CSSM_ATTRIBUTE_DATA_CSSM_DATA | 26,
CSSM_ATTRIBUTE_BASE = CSSM_ATTRIBUTE_DATA_CSSM_DATA | 27,
CSSM_ATTRIBUTE_SUBPRIME = CSSM_ATTRIBUTE_DATA_CSSM_DATA | 28,
CSSM_ATTRIBUTE_ALG_ID = CSSM_ATTRIBUTE_DATA_UINT32 | 29,
CSSM_ATTRIBUTE_ITERATION_COUNT = CSSM_ATTRIBUTE_DATA_UINT32 | 30,
CSSM_ATTRIBUTE_ROUNDS_RANGE = CSSM_ATTRIBUTE_DATA_RANGE | 31,
CSSM_ATTRIBUTE_CSP_HANDLE = CSSM_ATTRIBUTE_DATA_UINT32 | 34,
CSSM_ATTRIBUTE_DL_DB_HANDLE = CSSM_ATTRIBUTE_DATA_DL_DB_HANDLE | 35,
CSSM_ATTRIBUTE_ACCESS_CREDENTIALS =
CSSM_ATTRIBUTE_DATA_ACCESS_CREDENTIALS | 36,
CSSM_ATTRIBUTE_PUBLIC_KEY_FORMAT = CSSM_ATTRIBUTE_DATA_UINT32 | 37,
CSSM_ATTRIBUTE_PRIVATE_KEY_FORMAT = CSSM_ATTRIBUTE_DATA_UINT32 | 38,
CSSM_ATTRIBUTE_SYMMETRIC_KEY_FORMAT = CSSM_ATTRIBUTE_DATA_UINT32 | 39,
CSSM_ATTRIBUTE_WRAPPED_KEY_FORMAT = CSSM_ATTRIBUTE_DATA_UINT32 | 40,
} CSSM_ATTRIBUTE_TYPE;
typedef uint32 CSSM_ENCRYPT_MODE
#define CSSM_ALGMODE_NONE (0)
#define CSSM_ALGMODE_CUSTOM (CSSM_ALGMODE_NONE+1)
#define CSSM_ALGMODE_ECB (CSSM_ALGMODE_NONE+2)
#define CSSM_ALGMODE_ECBPad (CSSM_ALGMODE_NONE+3)
#define CSSM_ALGMODE_CBC (CSSM_ALGMODE_NONE+4)
#define CSSM_ALGMODE_CBC_IV8 (CSSM_ALGMODE_NONE+5)
#define CSSM_ALGMODE_CBCPadIV8 (CSSM_ALGMODE_NONE+6)
#define CSSM_ALGMODE_CFB (CSSM_ALGMODE_NONE+7)
#define CSSM_ALGMODE_CFB_IV8 (CSSM_ALGMODE_NONE+8)
#define CSSM_ALGMODE_CFBPadIV8 (CSSM_ALGMODE_NONE+9)
#define CSSM_ALGMODE_OFB (CSSM_ALGMODE_NONE+10)
#define CSSM_ALGMODE_OFB_IV8 (CSSM_ALGMODE_NONE+11)
#define CSSM_ALGMODE_OFBPadIV8 (CSSM_ALGMODE_NONE+12)
#define CSSM_ALGMODE_COUNTER (CSSM_ALGMODE_NONE+13)
#define CSSM_ALGMODE_BC (CSSM_ALGMODE_NONE+14)
#define CSSM_ALGMODE_PCBC (CSSM_ALGMODE_NONE+15)
#define CSSM_ALGMODE_CBCC (CSSM_ALGMODE_NONE+16)
#define CSSM_ALGMODE_OFBNLF (CSSM_ALGMODE_NONE+17)
#define CSSM_ALGMODE_PBC (CSSM_ALGMODE_NONE+18)
#define CSSM_ALGMODE_PFB (CSSM_ALGMODE_NONE+19)
#define CSSM_ALGMODE_CBCPD (CSSM_ALGMODE_NONE+20)
#define CSSM_ALGMODE_PUBLIC_KEY (CSSM_ALGMODE_NONE+21)
#define CSSM_ALGMODE_PRIVATE_KEY (CSSM_ALGMODE_NONE+22)
#define CSSM_ALGMODE_SHUFFLE (CSSM_ALGMODE_NONE+23)
#define CSSM_ALGMODE_ECB64 (CSSM_ALGMODE_NONE+24)
#define CSSM_ALGMODE_CBC64 (CSSM_ALGMODE_NONE+25)
#define CSSM_ALGMODE_OFB64 (CSSM_ALGMODE_NONE+26)
#define CSSM_ALGMODE_CFB32 (CSSM_ALGMODE_NONE+28)
#define CSSM_ALGMODE_CFB16 (CSSM_ALGMODE_NONE+29)
#define CSSM_ALGMODE_CFB8 (CSSM_ALGMODE_NONE+30)
#define CSSM_ALGMODE_WRAP (CSSM_ALGMODE_NONE+31)
#define CSSM_ALGMODE_PRIVATE_WRAP (CSSM_ALGMODE_NONE+32)
#define CSSM_ALGMODE_RELAYX (CSSM_ALGMODE_NONE+33)
#define CSSM_ALGMODE_ECB128 (CSSM_ALGMODE_NONE+34)
#define CSSM_ALGMODE_ECB96 (CSSM_ALGMODE_NONE+35)
#define CSSM_ALGMODE_CBC128 (CSSM_ALGMODE_NONE+36)
#define CSSM_ALGMODE_OAEP_HASH (CSSM_ALGMODE_NONE+37)
#define CSSM_ALGMODE_PKCS1_EME_V15 (CSSM_ALGMODE_NONE+38)
#define CSSM_ALGMODE_PKCS1_EME_OAEP (CSSM_ALGMODE_NONE+39)
#define CSSM_ALGMODE_PKCS1_EMSA_V15 (CSSM_ALGMODE_NONE+40)
#define CSSM_ALGMODE_ISO_9796 (CSSM_ALGMODE_NONE+41)
#define CSSM_ALGMODE_X9_31 (CSSM_ALGMODE_NONE+42)
#define CSSM_ALGMODE_LAST (0x7FFFFFFF)
/*
* All algorithms modes that are vendor specific, and
* not part of the CSSM specification should be defined
* relative to CSSM_ALGMODE_VENDOR_DEFINED.
*/
#define CSSM_ALGMODE_VENDOR_DEFINED(CSSM_ALGMODE_NONE+0x80000000)
typedef uint32 CSSM_PADDING
#define CSSM_PADDING_NONE (0)
#define CSSM_PADDING_CUSTOM (CSSM_PADDING_NONE+1)
#define CSSM_PADDING_ZERO (CSSM_PADDING_NONE+2)
#define CSSM_PADDING_ONE (CSSM_PADDING_NONE+3)
#define CSSM_PADDING_ALTERNATE (CSSM_PADDING_NONE+4)
#define CSSM_PADDING_FF (CSSM_PADDING_NONE+5)
#define CSSM_PADDING_PKCS5 (CSSM_PADDING_NONE+6)
#define CSSM_PADDING_PKCS7 (CSSM_PADDING_NONE+7)
#define CSSM_PADDING_CIPHERSTEALING (CSSM_PADDING_NONE+8)
#define CSSM_PADDING_RANDOM (CSSM_PADDING_NONE+9)
#define CSSM_PADDING_PKCS1 (CSSM_PADDING_NONE+10)
/*
* All padding types that are vendor specific, and not
* part of the CSSM specification should be defined
* relative to CSSM_PADDING_VENDOR_DEFINED.
*/
#define CSSM_PADDING_VENDOR_DEFINED(CSSM_PADDING_NONE+0x80000000)
typedef CSSM_ALGORITHMS CSSM_KEY_TYPE;
typedef struct cssm_context_attribute{
CSSM_ATTRIBUTE_TYPE AttributeType;
uint32 AttributeLength;
union cssm_context_attribute_value{
char *String;
uint32 Uint32;
CSSM_ACCESS_CREDENTIALS_PTR AccessCredentials;
CSSM_KEY_PTR Key;
CSSM_DATA_PTR Data;
CSSM_PADDING Padding;
CSSM_DATE_PTR Date;
CSSM_RANGE_PTR Range;
CSSM_CRYPTO_DATA_PTR CryptoData;
CSSM_VERSION_PTR Version;
CSSM_DL_DB_HANDLE_PTR DLDBHandle;
CSSM_KR_PROFILE_PTR KRProfile;
} Attribute;
} CSSM_CONTEXT_ATTRIBUTE, *CSSM_CONTEXT_ATTRIBUTE_PTR;
Identifier | Description | Data Type |
---|---|---|
CSSM_ATTRIBUTE_NONE | No attribute | None |
CSSM_ATTRIBUTE_CUSTOM | Custom data | Void pointer |
CSSM_ATTRIBUTE_DESCRIPTION | Description of attribute | Null-terminated string |
CSSM_ATTRIBUTE_KEY | Key Data | CSSM_KEY |
CSSM_ATTRIBUTE_INIT_VECTOR | Initialization vector | CSSM_DATA |
CSSM_ATTRIBUTE_SALT | Salt | CSSM_DATA |
CSSM_ATTRIBUTE_PADDING | Padding information | uint32 |
CSSM_ATTRIBUTE_RANDOM | Random data | CSSM_DATA |
CSSM_ATTRIBUTE_SEED | Seed | CSSM_CRYPTO_DATA |
CSSM_ATTRIBUTE_PASSPHRASE | Passphrase data | CSSM_CRYPTO_DATA |
CSSM_ATTRIBUTE_DATA_ACCESS_
CREDENTIALS | One or more credentials and samples required as input to use a private key or a secret key | CSSM_ACCESS_CREDENTIALS |
CSSM_ATTRIBUTE_KEY_LENGTH | Key length specified in bits | uint32 |
CSSM_ATTRIBUTE_KEY_LENGTH_
RANGE | Key length range specified in bits | CSSM_RANGE |
CSSM_ATTRIBUTE_BLOCK_SIZE | Block size | uint32 |
CSSM_ATTRIBUTE_OUTPUT_SIZE | Output size | uint32 |
CSSM_ATTRIBUTE_ROUNDS | Number of runs or rounds | uint32 |
CSSM_ATTRIBUTE_IV_SIZE | Size of initialization vector | uint32 |
CSSM_ATTRIBUTE_ALG_PARAMS | Algorithm parameters | CSSM_DATA |
CSSM_ATTRIBUTE_LABEL | Label placed on an object when it is created | CSSM_DATA |
CSSM_ATTRIBUTE_KEY_TYPE | Type of key to generate or derive | uint32 |
CSSM_ATTRIBUTE_MODE | Algorithm mode to use for encryption | uint32 |
CSSM_ATTRIBUTE_EFFECTIVE_
BITS | Effective key size (in bits) | uint32 |
CSSM_ATTRIBUTE_START_DATE | Starting date for an object's validity | CSSM_DATE |
CSSM_ATTRIBUTE_END_DATE | Ending date for an object's validity | CSSM_DATE |
CSSM_ATTRIBUTE_KEYUSAGE | Usage restriction on the key | uint32 |
CSSM_ATTRIBUTE_KEYATTR | Key attribute | uint32 |
CSSM_ATTRIBUTE_VERSION | Version number | CSSM_VERSION |
CSSM_ATTRIBUTE_PRIME | Prime value | CSSM_DATA |
CSSM_ATTRIBUTE_BASE | Base Value | CSSM_DATA |
CSSM_ATTRIBUTE_SUBPRIME | Subprime Value | CSSM_DATA |
CSSM_ATTRIBUTE_CSP_HANDLE | CSP Handle | Uint32 |
CSSM_ATTRIBUTE_DL_DB_
HANDLE | DL DB Handle | |
CSSM_ATTRIBUTE_ALG_ID | Algorithm identifier | uint32 |
CSSM_ATTRIBUTE_ITERATION_
COUNT | Algorithm iterations | uint32 |
CSSM_ATTRIBUTE_ROUNDS_RANGE | ||
T} | Range of number of rounds possible | CSSM_RANGE |
CSSM_KR_PROFILE_PTR | Pointer to the key recovery profile
structure that defines the user parameters with respect to
the key recovery process. See
| Pointer |
The data referenced by a CSSM_ATTRIBUTE_CUSTOM attribute must be a single continuous memory block. This allows the CSSM to appropriately release all dynamically allocated memory resources.
typedef struct cssm_context {
CSSM_CONTEXT_TYPE ContextType;
CSSM_ALGORITHMS AlgorithmType;
uint32 NumberOfAttributes;
CSSM_CONTEXT_ATTRIBUTE_PTR ContextAttributes;
CSSM_CSP_HANDLE CSPHandle;
CSSM_BOOL Privileged;
CSSM_KR_POLICY_FLAGS EncryptionProhibited;
uint32 WorkFactor;
uint32 Reserved;
} CSSM_CONTEXT, *CSSM_CONTEXT_PTR;
Value | Description |
---|---|
CSSM_ALGCLASS_NONE | Null Context type |
CSSM_ALGCLASS_CUSTOM | Custom Algorithms |
CSSM_ALGCLASS_SIGNATURE | Signature Algorithms |
CSSM_ALGCLASS_SYMMETRIC | Symmetric Encryption Algorithms |
CSSM_ALGCLASS_DIGEST | Message Digest Algorithms |
CSSM_ALGCLASS_RANDOMGEN | Random Number Generation Algorithms |
CSSM_ALGCLASS_UNIQUEGEN | Unique ID Generation Algorithms |
CSSM_ALGCLASS_MAC | Message Authentication Code Algorithms |
CSSM_ALGCLASS_ASYMMETRIC | Asymmetric Encryption Algorithms |
CSSM_ALGCLASS_KEYGEN | Key Generation Algorithms |
CSSM_ALGCLASS_DERIVEKEY | Key Derivation Algorithms |
Identifier | Description |
---|---|
CSSM_ALGID_NONE | Null algorithm |
CSSM_ALGID_CUSTOM | Custom algorithm |
CSSM_ALGID_DH | Diffie Hellman key exchange algorithm |
CSSM_ALGID_PH | Pohlig Hellman key exchange algorithm |
CSSM_ALGID_KEA | Key Exchange Algorithm |
CSSM_ALGID_MD2 | MD2 hash algorithm |
CSSM_ALGID_MD4 | MD4 hash algorithm |
CSSM_ALGID_MD5 | MD5 hash algorithm |
CSSM_ALGID_SHA1 | Secure Hash Algorithm |
CSSM_ALGID_NHASH | N-Hash algorithm |
CSSM_ALGID_HAVAL | HAVAL hash algorithm (MD5 variant) |
CSSM_ALGID_RIPEMD | RIPE-MD hash algorithm (MD4 variant developed for the European Community's RIPE project) |
CSSM_ALGID_IBCHASH | IBC-Hash (keyed hash algorithm or MAC) |
CSSM_ALGID_RIPEMAC | RIPE-MAC |
CSSM_ALGID_DES | Data Encryption Standard block cipher |
CSSM_ALGID_DESX | DESX block cipher (DES variant from RSA) |
CSSM_ALGID_RDES | RDES block cipher (DES variant) |
CSSM_ALGID_3DES_3KEY | Triple-DES block cipher (with 3 keys) |
CSSM_ALGID_3DES_2KEY | Triple-DES block cipher (with 2 keys) |
CSSM_ALGID_3DES_1KEY | Triple-DES block cipher (with 1 key) |
CSSM_ALGID_IDEA | IDEA block cipher |
CSSM_ALGID_RC2 | RC2 block cipher |
CSSM_ALGID_RC5 | RC5 block cipher |
CSSM_ALGID_RC4 | RC4 stream cipher |
CSSM_ALGID_SEAL | SEAL stream cipher |
CSSM_ALGID_CAST | CAST block cipher |
CSSM_ALGID_BLOWFISH | BLOWFISH block cipher |
CSSM_ALGID_SKIPJACK | Skipjack block cipher |
CSSM_ALGID_LUCIFER | Lucifer block cipher |
CSSM_ALGID_MADRYGA | Madryga block cipher |
CSSM_ALGID_FEAL | FEAL block cipher |
CSSM_ALGID_REDOC | REDOC 2 block cipher |
CSSM_ALGID_REDOC3 | REDOC 3 block cipher |
CSSM_ALGID_LOKI | LOKI block cipher |
CSSM_ALGID_KHUFU | KHUFU block cipher |
CSSM_ALGID_KHAFRE | KHAFRE block cipher |
CSSM_ALGID_MMB | MMB block cipher (IDEA variant) |
CSSM_ALGID_GOST | GOST block cipher |
CSSM_ALGID_SAFER | SAFER K-40, K-64, K-128 block cipher |
CSSM_ALGID_CRAB | CRAB block cipher |
CSSM_ALGID_RSA | RSA public key cipher |
CSSM_ALGID_DSA | Digital Signature Algorithm |
CSSM_ALGID_MD5WithRSA | MD5/RSA signature algorithm |
CSSM_ALGID_MD2WithRSA | MD2/RSA signature algorithm |
CSSM_ALGID_ElGamal | ElGamal signature algorithm |
CSSM_ALGID_MD2Random | MD2-based random numbers |
CSSM_ALGID_MD5Random | MD5-based random numbers |
CSSM_ALGID_SHARandom | SHA-based random numbers |
CSSM_ALGID_DESRandom | DES-based random numbers |
CSSM_ALGID_SHA1WithRSA | SHA-1/RSA signature algorithm |
CSSM_ALGID_RSA_PKCS | RSA as specified in PKCS #1 |
CSSM_ALGID_RSA_ISO9796 | RSA as specified in ISO 9796 |
CSSM_ALGID_RSA_RAW | Raw RSA as assumed in X.509 |
CSSM_ALGID_CDMF | CDMF block cipher |
CSSM_ALGID_CAST3 | Entrust's CAST3 block cipher |
CSSM_ALGID_CAST5 | Entrust's CAST5 block cipher |
CSSM_ALGID_GenericSecret | Generic secret operations |
CSSM_ALGID_ConcatBaseAndKey | Concatenate two keys, base key first |
CSSM_ALGID_ConcatKeyAndBase | Concatenate two keys, base key last |
CSSM_ALGID_ConcatBaseAndData | Concatenate base key and random data, key first |
CSSM_ALGID_ConcatDataAndBase | Concatenate base key and data, data first |
CSSM_ALGID_XORBaseAndData | XOR a byte string with the base key |
CSSM_ALGID_ExtractFromKey | Extract a key from base key, starting at arbitrary bit position |
CSSM_ALGID_SSL3PreMasterGen | Generate a 48 byte SSL 3 pre-master key |
CSSM_ALGID_SSL3MasterDerive | Derive an SSL 3 key from a pre-master key |
CSSM_ALGID_SSL3KeyAndMacDerive | Derive the keys and MACing keys for the SSL cipher suite |
CSSM_ALGID_SSL3MD5_MAC | Performs SSL 3 MD5 MACing |
CSSM_ALGID_SSL3SHA1_MAC | Performs SSL 3 SHA-1 MACing |
CSSM_ALGID_MD5_PBE | Generate key by MD5 hashing a base key |
CSSM_ALGID_MD2_PBE | Generate key by MD2 hashing a base key |
CSSM_ALGID_SHA1_PBE | Generate key by SHA-1 hashing a base key |
CSSM_ALGID_WrapLynks | Spyrus LYNKS DES based wrapping scheme w/checksum |
CSSM_ALGID_WrapSET_OAEP | SET key wrapping |
CSSM_ALGID_BATON | Fortezza BATON cipher |
CSSM_ALGID_ECDSA | Elliptic Curve DSA |
CSSM_ALGID_MAYFLY | Fortezza MAYFLY cipher |
CSSM_ALGID_JUNIPER | Fortezza JUNIPER cipher |
CSSM_ALGID_FASTHASH | Fortezza FASTHASH |
CSSM_ALGID_3DES | Generix 3DES |
CSSM_ALGID_SSL3MD5 | SSL3 with MD5 |
CSSM_ALGID_SSL3SHA1 | SSL3 with SHA1 |
CSSM_ALGID_FortezzaTimestamp | Fortezza with Timestamp |
CSSM_ALGID_SHA1WithDSA | SHA1 with DSA |
CSSM_ALGID_SHA1WithECDSA | SHA1 with Elliptic Curve DSA |
CSSM_ALGID_DSA_BSAFE | DSA with BSAFE Key format |
CSSM_ALGID_ECDH | Elliptic Curve DiffieHellman Key Exchange algorithm CSSM_ALGID_ECMQV@T{ Elliptic Curve MQV key exchange algorithm |
CSSM_ALGID_PKCS12_SHA1_PBE | PKCS12 SHA-1 PBE key derivation algorithm |
CSSM_ALGID_ECNRA | Elliptic Curve Nyberg-Rueppel |
CSSM_ALGID_SHA1WithECNRA | SHA-1 with Elliptic Curve Nyberg-Rueppel |
CSSM_ALGID_ECES | Elliptic Curve Encryption Scheme |
CSSM_ALGID_ECAES | Elliptic Curve Authenticate Encryption Scheme |
CSSM_ALGID_SHA1HMAC | SHA1-MAC |
CSSM_ALGID_FIPS186Random | FIPS186Random |
CSSM_ALGID_ECC | ECC |
CSSM_ALGID_MQV | Discrete-Log MQV key exchange algorithm@ |
CSSM_ALGID_NRA | Discrete-Log Nyberg-Rueppel Signature scheme |
CSSM_ALGID_IntelPlatformRandom | Random data obtained by querying the Intel Platform Random Number Generator |
CSSM_ALGID_UTC | Time value in the form YYYYMMDDhhmmss |
CSSM_ALGID_RUNNING_COUNTER | Value of a running hardware counter that operates while the device is in operation |
CSSM_ALGID_DES_SK | DES variant |
CSSM_ALGID_HAVAL3 | HAVAL3 Digest |
CSSM_ALGID_HAVAL4 | HAVAL4 Digest |
CSSM_ALGID_HAVAL5 | HAVAL5 Digest |
CSSM_ALGID_TIGER | TIGER Digest |
Some of the above algorithms operate in a variety of modes. The desired
mode is specified using an attribute of type CSSM_ATTRIBUTE_MODE. The
valid values for the mode attribute are as follows:
Value | Description |
---|---|
CSSM_ALGMODE_NONE | Null Algorithm mode |
CSSM_ALGMODE_CUSTOM | Custom mode |
CSSM_ALGMODE_ECB | Electronic Code Book |
CSSM_ALGMODE_ECBPad | ECB with padding |
CSSM_ALGMODE_CBC | Cipher Block Chaining |
CSSM_ALGMODE_CBC_IV8 | CBC with Initialization Vector of 8 bytes } CSSM_ALGMODE_CBCPadIV8@T{ CBC with padding and Initialization Vector of 8 bytes |
CSSM_ALGMODE_CFB | Cipher FeedBack
This mode should be used only for sizes that are not covered by CSSM_ALGMODE_CFB8, CSSM_ALGMODE_CFB16, CSSM_ALGMODE_CFB32, or CSSM_ALGMODE_CFB64. The arbitrary size is specified using the context attribute CSSM_ATTRIBUTE_OUTPUT_SIZE. |
CSSM_ALGMODE_CFB_IV8 | CFB with Initialization Vector of 8 bytes |
CSSM_ALGMODE_CFBPadIV8 | CFB with Initialization Vector of 8 bytes and padding |
CSSM_ALGMODE_OFB | Output FeedBack |
CSSM_ALGMODE_OFB_IV8 | OFB with Initialization Vector of 8 bytes |
CSSM_ALGMODE_OFBPadIV8 | OFB with Initialization Vector of 8 bytes and padding |
CSSM_ALGMODE_COUNTER | Counter |
CSSM_ALGMODE_BC | Block Chaining |
CSSM_ALGMODE_PCBC | Propagating CBC |
CSSM_ALGMODE_CBCC | CBC with Checksum |
CSSM_ALGMODE_OFBNLF | OFB with NonLinear Function |
CSSM_ALGMODE_PBC | Plaintext Block Chaining |
CSSM_ALGMODE_PFB | Plaintext FeedBack |
CSSM_ALGMODE_CBCPD | CBC of Plaintext Difference |
CSSM_ALGMODE_PUBLIC_KEY | Use the public key |
CSSM_ALGMODE_PRIVATE_KEY | Use the private key |
CSSM_ALGMODE_SHUFFLE | Fortezza shuffle mode |
CSSM_ALGMODE_ECB64 | Electronic Code Book 64 bytes |
CSSM_ALGMODE_CBC64 | Cipher Block Chaining 64 bytes |
CSSM_ALGMODE_OFB64 | Output Feedback 64 bytes |
CSSM_ALGMODE_CFB64 | Cipher Feedback 64 bytes |
CSSM_ALGMODE_CFB32 | Cipher Feedback 32 bytes |
CSSM_ALGMODE_CFB16 | Cipher Feedback 16 bytes |
CSSM_ALGMODE_CFB8 | Cipher Feedback 8 bytes |
CSSM_ALGMODE_WRAP | |
CSSM_ALGMODE_PRIVATE_WRAP | |
CSSM_ALGMODE_RELAYX | |
CSSM_ALGMODE_ECB128 | Electronic Code Book 128 bytes |
CSSM_ALGMODE_ECB96 | Electronic Code Book 96 bytes |
CSSM_ALGMODE_CBC128 | Cipher Block Chaining 128 bytes |
CSSM_ALGMODE_OAEP_HASH | Algorithm mode for SET key wrapping |
CSSM_ALGMODE_PKCS1_EME_OAEP | PKCS #1 version 2.0, requires that CSSM_PKCS1_OAEP_PARAMS be included as a context attribute of type CSSM_ATTRIBUTE_ALG_PARAMS |
CSSM_ALGMODE_PKCS1_EME_V15 | PKCS #1 version 1.5: this is the default if no algorithm mode is specified. |
typedef uint32 CSSM_SC_FLAGS;
#define CSSM_CSP_TOK_RNG (0x00000001)
#define CSSM_CSP_TOK_CLOCK_EXISTS (0x00000040)
typedef uint32 CSSM_CSP_READER_FLAGS;
#define CSSM_CSP_RDR_TOKENPRESENT (0x00000001)
/* Token is present in reader/slot */
#define CSSM_CSP_RDR_EXISTS (0x00000002)
/* Device is a reader with a removable token */
#define CSSM_CSP_RDR_HW (0x00000004)
/* Slot is a hardware slot */
typedef uint32 CSSM_CSP_FLAGS;
#define CSSM_CSP_TOK_WRITE_PROTECTED (0x00000002)
#define CSSM_CSP_TOK_LOGIN_REQUIRED (0x00000004)
#define CSSM_CSP_TOK_USER_PIN_INITIALIZED (0x00000008)
#define CSSM_CSP_TOK_PROT_AUTHENTICATION (0x00000100)
#define CSSM_CSP_TOK_USER_PIN_EXPIRED (0x00100000)
#define CSSM_CSP_TOK_SESSION_KEY_PASSWORD (0x00200000)
#define CSSM_CSP_TOK_PRIVATE_KEY_PASSWORD (0x00400000)
#define CSSM_CSP_STORES_PRIVATE_KEYS (0x01000000)
#define CSSM_CSP_STORES_PUBLIC_KEYS (0x02000000)
#define CSSM_CSP_STORES_SESSION_KEYS (0x04000000)
#define CSSM_CSP_STORES_CERTIFICATES (0x08000000)
#define CSSM_CSP_STORES_GENERIC (0x10000000)
typedef uint32 CSSM_PKCS_OAEP_MGF;
typedef uint32 CSSM_PKCS_OAEP_PSOURCE;
#define CSSM_PKCS_OAEP_MGF_NONE (0)
#define CSSM_PKCS_OAEP_MGF1_SHA1 (CSSM_PKCS_OAEP_MGF_NONE+1)
#define CSSM_PKCS_OAEP_MGF1_MD5 (CSSM_PKCS_OAEP_MGF_NONE+2)
#define CSSM_PKCS_OAEP_PSOURCE_NONE (0)
#define CSSM_PKCS_OAEP_PSOURCE_Pspecified (CSSM_PKCS_OAEP_PSOURCE_NONE+1)
typedef struct cssm_pkcs1_oaep_params {
uint32 HashAlgorithm;
CSSM_DATA HashParams;
CSSM_PKCS_OAEP_MGF MGF;
CSSM_DATA MGFParams;
CSSM_PKCS_OAEP_PSOURCE PSource;
CSSM_DATA PSourceParams;
} CSSM_PKCS1_OAEP_PARAMS, *CSSM_PKCS1_OAEP_PARAMS_PTR;
typedef struct cssm_csp_operational_statistics
{
CSSM_BOOL UserAuthenticated;
/* CSSM_TRUE if the user is logged in to the token,
CSSM_FALSE otherwise. */
CSSM_CSP_DEVICE_FLAGS DeviceFlags;
uint32 TokenMaxSessionCount; /* Exported by Cryptoki modules. */
uint32 TokenOpenedSessionCount;
uint32 TokenMaxRWSessionCount;
uint32 TokenOpenedRWSessionCount;
uint32 TokenTotalPublicMem; /* Storage space statistics. */
uint32 TokenFreePublicMem;
uint32 TokenTotalPrivateMem;
uint32 TokenFreePrivateMem;
}
CSSM_CSP_OPERATIONAL_STATISTICS *CSSM_CSP_OPERATIONAL_STATISTICS_PTR;
Definition
UserAuthenticated
CSSM_TRUE if the user is logged in to the token, CSSM_FALSE otherwise
DeviceFlags
Device status flags.
TokenMaxSessionCount
Maximum number of CSP handles referencing the token that may
exist simultaneously.
TokenOpenedSessionCount
Number of existing CSP handles referencing the token.
TokenMaxRWSessionCount
Maximum number of CSP handles that can reference the token
simultaneously in read-write mode.
TokenOpenedRWSessionCount
Number of existing CSP handles referencing the token in read-write mode.
TokenTotalPublicMem
Amount of public storage space in the CSP. This value will be set
to CSSM_VALUE_NOT_AVAILABLE if the CSP does not wish to expose
this information.
TokenFreePublicMem
Amount of public storage space available for use in the CSP.
This value will be set to CSSM_VALUE_NOT_AVAILABLE if the CSP
does not wish to expose this information.
TokenTotalPrivateMem
Amount of private storage space in the CSP. This value will be set
to CSSM_VALUE_NOT_AVAILABLE if the CSP does not wish to expose this information.
TokenFreePrivateMem
Amount of private storage space available for use in the CSP.
This value will be set to CSSM_VALUE_NOT_AVAILABLE if the CSP
does not wish to expose this information.
CSSM_PBE_PARAMS
This structure is used to provide input parameters to key derivation
algorithms based on password based encryption.
typedef struct cssm_pbe_params {
CSSM_DATA Passphrase;
CSSM_DATA InitVector;
} CSSM_PBE_PARAMS, *CSSM_PBE_PARAMS_PTR;
typedef struct cssm_kea_derive_params {
CSSM_DATA Rb;
CSSM_DATA Yb;
} CSSM_KEA_DERIVE_PARAMS, *CSSM_KEA_DERIVE_PARAMS_PTR;
Each CSP function may return any Error Value derived from the
Common Error Codes defined in
Lastly, there is an unclassified set that is specific to certain operations.
Each CSP function will only list the Error Values from the unclassified set that it returns, plus certain CSSM Error Values that relate to invalid contexts.
#define CSSMERR_CSP_INTERNAL_ERROR \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_INTERNAL_ERROR)
#define CSSMERR_CSP_MEMORY_ERROR \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_MEMORY_ERROR)
#define CSSMERR_CSP_MDS_ERROR \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_MDS_ERROR)
#define CSSMERR_CSP_INVALID_POINTER \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_INVALID_POINTER)
#define CSSMERR_CSP_INVALID_INPUT_POINTER \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_INVALID_INPUT_POINTER)
#define CSSMERR_CSP_INVALID_OUTPUT_POINTER \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_INVALID_OUTPUT_POINTER)
#define CSSMERR_CSP_FUNCTION_NOT_IMPLEMENTED \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_FUNCTION_NOT_IMPLEMENTED)
#define CSSMERR_CSP_SELF_CHECK_FAILED \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_SELF_CHECK_FAILED)
#define CSSMERR_CSP_OS_ACCESS_DENIED \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_OS_ACCESS_DENIED)
#define CSSMERR_CSP_FUNCTION_FAILED \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_FUNCTION_FAILED)
#define CSSMERR_CSP_OPERATION_AUTH_DENIED \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_OPERATION_AUTH_DENIED)
#define CSSMERR_CSP_OBJECT_USE_AUTH_DENIED \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_OBJECT_USE_AUTH_DENIED)
#define CSSMERR_CSP_OBJECT_MANIP_AUTH_DENIED \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_OBJECT_MANIP_AUTH_DENIED)
#define CSSMERR_CSP_OBJECT_ACL_NOT_SUPPORTED \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_ACL_NOT_SUPPORTED)
#define CSSMERR_CSP_OBJECT_ACL_REQUIRED \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_OBJECT_ACL_REQUIRED)
#define CSSMERR_CSP_INVALID_ACCESS_CREDENTIALS \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_INVALID_ACCESS_CREDENTIALS)
#define CSSMERR_CSP_INVALID_ACL_BASE_CERTS \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_INVALID_ACL_BASE_CERTS)
#define CSSMERR_CSP_ACL_BASE_CERTS_NOT_SUPPORTED \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_ACL_BASE_CERTS_NOT_SUPPORTED)
#define CSSMERR_CSP_INVALID_SAMPLE_VALUE \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_INVALID_SAMPLE_VALUE)
#define CSSMERR_CSP_SAMPLE_VALUE_NOT_SUPPORTED \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_SAMPLE_VALUE_NOT_SUPPORTED)
#define CSSMERR_CSP_INVALID_ACL_SUBJECT_VALUE \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_INVALID_ACL_SUBJECT_VALUE)
#define CSSMERR_CSP_ACL_SUBJECT_TYPE_NOT_SUPPORTED \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_ACL_SUBJECT_TYPE_NOT_SUPPORTED)
#define CSSMERR_CSP_INVALID_ACL_CHALLENGE_CALLBACK \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_INVALID_ACL_CHALLENGE_CALLBACK)
#define CSSMERR_CSP_ACL_CHALLENGE_CALLBACK_FAILED \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_ACL_CHALLENGE_CALLBACK_FAILED)
#define CSSMERR_CSP_INVALID_ACL_ENTRY_TAG \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_INVALID_ACL_ENTRY_TAG)
#define CSSMERR_CSP_ACL_ENTRY_TAG_NOT_FOUND \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_ACL_ENTRY_TAG_NOT_FOUND)
#define CSSMERR_CSP_INVALID_ACL_EDIT_MODE \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_INVALID_ACL_EDIT_MODE)
#define CSSMERR_CSP_ACL_CHANGE_FAILED \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_ACL_CHANGE_FAILED)
#define CSSMERR_CSP_INVALID_NEW_ACL_ENTRY \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_INVALID_NEW_ACL_ENTRY)
#define CSSMERR_CSP_INVALID_NEW_ACL_OWNER \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_INVALID_NEW_ACL_OWNER)
#define CSSMERR_CSP_ACL_DELETE_FAILED \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_ACL_DELETE_FAILED)
#define CSSMERR_CSP_ACL_REPLACE_FAILED \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_ACL_REPLACE_FAILED)
#define CSSMERR_CSP_ACL_ADD_FAILED \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_ACL_ADD_FAILED)
#define CSSMERR_CSP_INVALID_CONTEXT_HANDLE \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_INVALID_CONTEXT_HANDLE)
#define CSSMERR_CSP_PRIVILEGE_NOT_GRANTED \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_PRIVILEGE_NOT_GRANTED)
#define CSSMERR_CSP_INVALID_DATA \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_INVALID_DATA)
#define CSSMERR_CSP_INVALID_PASSTHROUGH_ID \
(CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_INVALID_PASSTHROUGH_ID)
#define CSSMERR_CSP_BASE_CSP_ERROR \
(CSSM_CSP_BASE_ERROR+CSSM_ERRORCODE_COMMON_EXTENT)
#define CSSMERR_CSP_INPUT_LENGTH_ERROR (CSSM_CSP_BASE_CSP_ERROR+1)
#define CSSMERR_CSP_OUTPUT_LENGTH_ERROR (CSSM_CSP_BASE_CSP_ERROR+2)
#define CSSMERR_CSP_PRIVILEGE_NOT_SUPPORTED (CSSM_CSP_BASE_CSP_ERROR+3)
#define CSSMERR_CSP_DEVICE_ERROR (CSSM_CSP_BASE_CSP_ERROR+4)
#define CSSMERR_CSP_DEVICE_MEMORY_ERROR (CSSM_CSP_BASE_CSP_ERROR+5)
#define CSSMERR_CSP_ATTACH_HANDLE_BUSY (CSSM_CSP_BASE_CSP_ERROR+6)
#define CSSMERR_CSP_NOT_LOGGED_IN (CSSM_CSP_BASE_CSP_ERROR+7)
#define CSSMERR_CSP_INVALID_KEY (CSSM_CSP_BASE_CSP_ERROR+16)
#define CSSMERR_CSP_INVALID_KEY_REFERENCE (CSSM_CSP_BASE_CSP_ERROR+17)
#define CSSMERR_CSP_INVALID_KEY_CLASS (CSSM_CSP_BASE_CSP_ERROR+18)
#define CSSMERR_CSP_ALGID_MISMATCH (CSSM_CSP_BASE_CSP_ERROR+19)
#define CSSMERR_CSP_KEY_USAGE_INCORRECT (CSSM_CSP_BASE_CSP_ERROR+20)
#define CSSMERR_CSP_KEY_BLOB_TYPE_INCORRECT (CSSM_CSP_BASE_CSP_ERROR+21)
#define CSSMERR_CSP_KEY_HEADER_INCONSISTENT (CSSM_CSP_BASE_CSP_ERROR+22)
#define CSSMERR_CSP_UNSUPPORTED_KEY_FORMAT (CSSM_CSP_BASE_CSP_ERROR+23)
#define CSSMERR_CSP_UNSUPPORTED_KEY_SIZE (CSSM_CSP_BASE_CSP_ERROR+24)
#define CSSMERR_CSP_INVALID_KEY_POINTER (CSSM_CSP_BASE_CSP_ERROR+25)
#define CSSMERR_CSP_INVALID_KEYUSAGE_MASK (CSSM_CSP_BASE_CSP_ERROR+26)
#define CSSMERR_CSP_UNSUPPORTED_KEYUSAGE_MASK (CSSM_CSP_BASE_CSP_ERROR+27)
#define CSSMERR_CSP_INVALID_KEYATTR_MASK (CSSM_CSP_BASE_CSP_ERROR+28)
#define CSSMERR_CSP_UNSUPPORTED_KEYATTR_MASK (CSSM_CSP_BASE_CSP_ERROR+29)
#define CSSMERR_CSP_INVALID_KEY_LABEL (CSSM_CSP_BASE_CSP_ERROR+30)
#define CSSMERR_CSP_UNSUPPORTED_KEY_LABEL (CSSM_CSP_BASE_CSP_ERROR+31)
#define CSSMERR_CSP_INVALID_KEY_FORMAT (CSSM_CSP_BASE_CSP_ERROR+32)
#define CSSMERR_CSP_INVALID_DATA_COUNT (CSSM_CSP_BASE_CSP_ERROR+40)
#define CSSMERR_CSP_VECTOR_OF_BUFS_UNSUPPORTED (CSSM_CSP_BASE_CSP_ERROR+41)
#define CSSMERR_CSP_INVALID_INPUT_VECTOR (CSSM_CSP_BASE_CSP_ERROR+42)
#define CSSMERR_CSP_INVALID_OUTPUT_VECTOR (CSSM_CSP_BASE_CSP_ERROR+43)
#define CSSMERR_CSP_INVALID_CONTEXT (CSSM_CSP_BASE_CSP_ERROR+48)
#define CSSMERR_CSP_INVALID_ALGORITHM (CSSM_CSP_BASE_CSP_ERROR+49)
#define CSSMERR_CSP_INVALID_ATTR_MODE (CSSM_CSP_BASE_CSP_ERROR+50)
#define CSSMERR_CSP_INVALID_ATTR_PADDING (CSSM_CSP_BASE_CSP_ERROR+51)
#define CSSMERR_CSP_INVALID_ATTR_INIT_VECTOR (CSSM_CSP_BASE_CSP_ERROR+52)
#define CSSMERR_CSP_INVALID_ATTR_ITERATION_COUNT (CSSM_CSP_BASE_CSP_ERROR+53)
#define CSSMERR_CSP_MISSING_ATTR_KEY (CSSM_CSP_BASE_CSP_ERROR+54)
#define CSSMERR_CSP_INVALID_ATTR_SEED (CSSM_CSP_BASE_CSP_ERROR+55)
#define CSSMERR_CSP_INVALID_ATTR_SALT (CSSM_CSP_BASE_CSP_ERROR+56)
#define CSSMERR_CSP_INVALID_ATTR_ALG_PARAMS (CSSM_CSP_BASE_CSP_ERROR+57)
#define CSSMERR_CSP_INVALID_ATTR_START_DATE (CSSM_CSP_BASE_CSP_ERROR+58)
#define CSSMERR_CSP_INVALID_ATTR_END_DATE (CSSM_CSP_BASE_CSP_ERROR+59)
#define CSSMERR_CSP_INVALID_ATTR_OUTPUT_SIZE (CSSM_CSP_BASE_CSP_ERROR+60)
#define CSSMERR_CSP_INVALID_ATTR_KEY_LENGTH (CSSM_CSP_BASE_CSP_ERROR+61)
#define CSSMERR_CSP_MISSING_ATTR_ACCESS_CREDENTIALS \
(CSSM_CSP_BASE_CSP_ERROR+62)
#define CSSMERR_CSP_INVALID_ATTR_ROUNDS (CSSM_CSP_BASE_CSP_ERROR+63)
#define CSSMERR_CSP_INVALID_ATTR_KEY_TYPE (CSSM_CSP_BASE_CSP_ERROR+64)
#define CSSMERR_CSP_STAGED_OPERATION_IN_PROGRESS \
(CSSM_CSP_BASE_CSP_ERROR+72)
#define CSSMERR_CSP_STAGED_OPERATION_NOT_STARTED \
(CSSM_CSP_BASE_CSP_ERROR+73)
#define CSSMERR_CSP_VERIFY_FAILED (CSSM_CSP_BASE_CSP_ERROR+74)
#define CSSMERR_CSP_INVALID_SIGNATURE (CSSM_CSP_BASE_CSP_ERROR+75)
#define CSSMERR_CSP_QUERY_SIZE_UNKNOWN (CSSM_CSP_BASE_CSP_ERROR+76)
#define CSSMERR_CSP_BLOCK_SIZE_MISMATCH (CSSM_CSP_BASE_CSP_ERROR+77)
#define CSSMERR_CSP_PRIVATE_KEY_NOT_FOUND (CSSM_CSP_BASE_CSP_ERROR+78)
#define CSSMERR_CSP_PUBLIC_KEY_INCONSISTENT (CSSM_CSP_BASE_CSP_ERROR+79)
#define CSSMERR_CSP_DEVICE_VERIFY_FAILED (CSSM_CSP_BASE_CSP_ERROR+80)
#define CSSMERR_CSP_INVALID_LOGIN_NAME (CSSM_CSP_BASE_CSP_ERROR+81)
#define CSSMERR_CSP_ALREADY_LOGGED_IN (CSSM_CSP_BASE_CSP_ERROR+82)
#define CSSMERR_CSP_PRIVATE_KEY_ALREADY_EXISTS \
(CSSM_CSP_BASE_CSP_ERROR+83)
#define CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS (CSSM_CSP_BASE_CSP_ERROR+84)
#define CSSMERR_CSP_INVALID_DIGEST_ALGORITHM (CSSM_CSP_BASE_CSP_ERROR+85)
CSSM_CSP_CreateSignatureContext
CSSM_RETURN CSSMAPI CSSM_CSP_CreateSignatureContext (CSSM_CSP_HANDLE CSPHandle, CSSM_ALGORITHMS AlgorithmID, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_KEY *Key, CSSM_CC_HANDLE *NewContextHandle)
This function creates a signature cryptographic context for sign and verify given a handle of a CSP, an algorithm identification number, a key, and an AccessCredentials structure. The AccessCredentials will be used to unlock the private key when this context is used to perform a signing operation. The cryptographic context handle is returned. The cryptographic context handle can be used to call sign and verify cryptographic functions.
- CSPHandle (input)
The handle that describes the add-in cryptographic service provider module used to perform this function. If a NULL handle is specified, CSSM returns error.
- AlgorithmID (input)
The algorithm identification number for a signature/verification algorithm.
- AccessCred (input/output)
A pointer to the set of one or more credentials required to unlock the private key. The credentials structure can contain an immediate value for the credential, such as a passphrase, or the caller can specify a callback function the CSP can use to obtain one or more credentials. Credentials are required for signature operations, not for verify operations.
- Key (input)
The key used to sign/verify. The caller passes in a pointer to a CSSM_KEY structure containing the key and the key length.
- NewContextHandle (output)
Cryptographic context handle.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.CSSMERR_CSSM_INVALID_ATTRIBUTE
CSSM_SignData()
CSSM_SignDataInit()
CSSM_SignDataUpdate()
CSSM_SignDataFinal()
CSSM_VerifyData()
CSSM_VerifyDataInit()
CSSM_VerifyDataUpdate()
CSSM_VerifyDataFinal()
CSSM_GetContext()
CSSM_SetContext()
CSSM_DeleteContext()
CSSM_GetContextAttribute()
CSSM_UpdateContextAttributes()
CSSM_CSP_CreateSymmetricContext
CSSM_RETURN CSSMAPI CSSM_CSP_CreateSymmetricContext (CSSM_CSP_HANDLE CSPHandle, CSSM_ALGORITHMS AlgorithmID, CSSM_ENCRYPT_MODE Mode, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_KEY *Key, const CSSM_DATA *InitVector, CSSM_PADDING Padding, void *Reserved, CSSM_CC_HANDLE *NewContextHandle)
This function creates a symmetric encryption cryptographic context given a handle of a CSP, an algorithm identification number, a key, an initial vector, padding, and the number of encryption rounds. Algorithm-specific attributes must be added to the context after the initial creation using theCSSM_UpdateContextAttributes() function. The cryptographic context handle is returned. The cryptographic context handle can be used to call symmetric encryption functions and the cryptographic wrap/unwrap functions.Additional attributes can be added to the newly created context using the function
CSSM_UpdateContextAttributes() . Incremental attributes of interest when using this context to unwrap a key include a handle-pair identifying a Data Storage Library service module and an open data store for CSPs that manage multiple persistent key stores. If a CSP does not support multiple key stores, the CSP ignores the presence or absence of this attribute.
- CSPHandle (input)
The handle that describes the add-in cryptographic service provider module used to perform this function. If a NULL handle is specified, CSSM returns error.
- AlgorithmID (input)
The algorithm identification number for symmetric encryption.
- Mode (input)
The mode of the specified algorithm ID.
- AccessCred (input/optional)
A pointer to the set of one or more credentials required to unlock the secret key. The credentials structure can contain an immediate value for the credential, such as a passphrase, or the caller can specify a callback function the CSP can use to obtain one or more credentials. Credentials may be required for encryption, decryption, and wrapping operations.
- Key (input)
The key used for symmetric encryption. The caller passes in a pointer to a CSSM_KEY structure containing the key.
- InitVector (input/optional)
The initial vector for symmetric encryption; typically specified for block ciphers.
- Padding (input/optional)
The method for padding; typically specified for ciphers that pad.
- Reserved (input)
Reserved for future use.
- NewContextHandle (output)
Cryptographic context handle.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
CSSMERR_CSSM_INVALID_ATTRIBUTESee also general error codes and common error codes section
CSSM_EncryptData()
CSSM_QuerySize()
CSSM_EncryptDataInit()
CSSM_EncryptDataUpdate()
CSSM_EncryptDataFinal()
CSSM_DecryptData()
CSSM_DecryptDataInit()
CSSM_DecryptDataUpdate()
CSSM_DecryptDataFinal()
CSSM_GetContext()
CSSM_SetContext()
CSSM_DeleteContext()
CSSM_GetContextAttribute()
CSSM_UpdateContextAttributes()
CSSM_CSP_CreateDigestContext
CSSM_RETURN CSSMAPI CSSM_CSP_CreateDigestContext (CSSM_CSP_HANDLE CSPHandle, CSSM_ALGORITHMS AlgorithmID, CSSM_CC_HANDLE *NewContextHandle)
This function creates a digest cryptographic context, given a handle of a CSP and an algorithm identification number. The cryptographic context handle is returned. The cryptographic context handle can be used to call digest cryptographic functions.
- CSPHandle (input)
The handle that describes the add-in cryptographic service provider module used to perform this function. If a NULL handle is specified, CSSM returns error.
- AlgorithmID (input)
The algorithm identification number for message digests.
- NewContextHandle (output)
Cryptographic context handle.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
CSSMERR_CSSM_INVALID_ATTRIBUTESee also general error codes and common error codes section
CSSM_DigestData()
CSSM_DigestDataInit()
CSSM_DigestDataUpdate()
CSSM_DigestDataFinal()
CSSM_GetContext()
CSSM_SetContext()
CSSM_DeleteContext()
CSSM_GetContextAttribute()
CSSM_UpdateContextAttributes()
CSSM_CSP_CreateMacContext
CSSM_RETURN CSSMAPI CSSM_CSP_CreateMacContext (CSSM_CSP_HANDLE CSPHandle, CSSM_ALGORITHMS AlgorithmID, const CSSM_KEY *Key, CSSM_CC_HANDLE *NewContextHandle)
This function creates a message authentication code cryptographic context, given a handle of a CSP, algorithm identification number, and a key. The cryptographic context handle is returned. The cryptographic context handle can be used to call message authentication code functions.
- CSPHandle (input)
The handle that describes the add-in cryptographic service provider module used to perform this function. If a NULL handle is specified, CSSM returns error.
- AlgorithmID (input)
The algorithm identification number for the MAC algorithm.
- Key (input)
The key used to generate a message authentication code. Caller passes in a pointer to a CSSM_KEY structure containing the key.
- NewContextHandle (output)
Cryptographic context handle.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
CSSMERR_CSSM_INVALID_ATTRIBUTESee also general error codes and common error codes section
CSSM_GenerateMac()
CSSM_GenerateMacInit()
CSSM_GenerateMacUpdate()
CSSM_GenerateMacFinal()
CSSM_VerifyMac()
CSSM_VerifyMacInit()
CSSM_VerifyMacUpdate()
CSSM_VerifyMacFinal()
CSSM_GetContext()
CSSM_SetContext()
CSSM_DeleteContext()
CSSM_GetContextAttribute()
CSSM_UpdateContextAttributes()
CSSM_CSP_CreateRandomGenContext
CSSM_RETURN CSSMAPI CSSM_CSP_CreateRandomGenContext (CSSM_CSP_HANDLE CSPHandle, CSSM_ALGORITHMS AlgorithmID, const CSSM_CRYPTO_DATA *Seed, uint32 Length, CSSM_CC_HANDLE *NewContextHandle)
This function creates a random number generation cryptographic context, given a handle of a CSP, an algorithm identification number, a seed, and the length of the random number in bytes. The cryptographic context handle is returned, and can be used for the random number generation function.
- CSPHandle (input)
The handle that describes the add-in cryptographic service provider module used to perform this function. If a NULL handle is specified, CSSM returns error.
- AlgorithmID (input)
The algorithm identification number for random number generation.
- Seed (input/optional)
A seed used to generate random number. The caller can either pass a seed and seed length in bytes or pass in a callback function. If NULL is passed, the cryptographic service provider will use its default seed handling mechanism.
- Length (input)
The length of the random number to be generated.
- NewContextHandle (output)
Cryptographic context handle.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
CSSMERR_CSSM_INVALID_ATTRIBUTESee also general error codes and common error codes section
CSSM_GenerateRandom()
CSSM_GetContext()
CSSM_SetContext()
CSSM_DeleteContext()
CSSM_GetContextAttribute()
CSSM_UpdateContextAttributes()
CSSM_CSP_CreateAsymmetricContext
CSSM_RETURN CSSMAPI CSSM_CSP_CreateAsymmetricContext (CSSM_CSP_HANDLE CSPHandle, CSSM_ALGORITHMS AlgorithmID, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_KEY *Key, CSSM_PADDING Padding, CSSM_CC_HANDLE *NewContextHandle)
This function creates an asymmetric encryption cryptographic context, given a handle of a CSP, an algorithm identification number, a key, and padding. The cryptographic context handle is returned. The cryptographic context handle can be used to call asymmetric encryption functions and cryptographic wrap/unwrap functions.
- CSPHandle (input)
The handle that describes the add-in cryptographic service provider module used to perform this function. If a NULL handle is specified, CSSM returns an error.
- AlgorithmID (input)
The algorithm identification number for the algorithm used for asymmetric encryption.
- AccessCred (input)
A pointer to the set of one or more credentials required to unlock the private key. The credentials structure can contain an immediate value for the credential, such as a passphrase, or the caller can specify a callback function the CSP can use to obtain one or more credentials. Credentials can be required for encryption and decryption operations.
- Key (input)
The key used for asymmetric encryption. The caller passes a pointer to a CSSM_KEY structure containing the key. When the context is used for a sign operation, AccessCredentials is required to access the private key used for signing. When the context is used for a verify operation, the public key is used to verify the signature. When the context is used for a wrapkey operation, the public key can be used as the wrapping key. When the context is used for an unwrap operation, AccessCredentials is required to access the private key used to perform the unwrapping.
- Padding (input/optional)
The method for padding. Typically specified for ciphers that pad.
- NewContextHandle (output)
Cryptographic context handle.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
CSSMERR_CSSM_INVALID_ATTRIBUTESee also general error codes and common error codes section
CSSM_EncryptData()
CSSM_QuerySize()
CSSM_EncryptDataInit()
CSSM_EncryptDataUpdate()
CSSM_EncryptDataFinal()
CSSM_DecryptData()
CSSM_DecryptDataInit()
CSSM_DecryptDataUpdate()
CSSM_DecryptDataFinal()
CSSM_GetContext()
CSSM_SetContext()
CSSM_DeleteContext()
CSSM_GetContextAttribute()
CSSM_UpdateContextAttributes()
CSSM_CSP_CreateDeriveKeyContext
CSSM_RETURN CSSMAPI CSSM_CSP_CreateDeriveKeyContext (CSSM_CSP_HANDLE CSPHandle, CSSM_ALGORITHMS AlgorithmID, CSSM_KEY_TYPE DeriveKeyType, uint32 DeriveKeyLengthInBits, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_KEY *BaseKey, uint32 IterationCount, const CSSM_DATA *Salt, const CSSM_CRYPTO_DATA *Seed, CSSM_CC_HANDLE *NewContextHandle)
This function creates a cryptographic context to derive a symmetric key given a handle of a CSP, an algorithm, the type of symmetric key to derive, the length of the derived key, and an optional seed or an optional AccessCredentials from which to derive a new key. The cryptographic context handle is returned. The cryptographic context handle can be used for calling the cryptographic derive key function.
- CSPHandle (input)
The handle that describes the add-in cryptographic service provider module used to perform this function. If a NULL handle is specified, CSSM returns an error.
- AlgorithmID (input)
The algorithm identification number for a derived key algorithm.
- DeriveKeyType (input)
The type of symmetric key to derive.
- DeriveKeyLengthInBits (input)
The logical length of the key to be derived in bits ( LogicalKeySizeInBits)
- AccessCred (input/optional)
A pointer to the set of one or more credentials required to access the base key. The credentials structure can contain an immediate value for the credential, such as a passphrase, or the caller can specify a callback function the CSP can use to obtain one or more credentials. If the BaseKey is NULL then this parameter is optional.
- BaseKey (input/optional)
The base key used to derive the new key. The base key may be a public key, a private key, or a symmetric key
- IterationCount (input/optional)
The number of iterations to be performed during the derivation process. Used heavily by password-based derivation methods.
- Salt (input/optional)
A Salt used in deriving the key.
- Seed (input/optional)
A seed used to generate a random number. The caller can either pass a seed and seed length in bytes or pass in a callback function If Seed is NULL, the cryptographic service provider will use its default seed handling mechanism.
- NewContextHandle (output)
Cryptographic context handle.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
CSSMERR_CSSM_INVALID_ATTRIBUTESee also general error codes and common error codes section
CSSM_DeriveKey()
CSSM_CSP_CreateKeyGenContext
CSSM_RETURN CSSMAPI CSSM_CSP_CreateKeyGenContext (CSSM_CSP_HANDLE CSPHandle, CSSM_ALGORITHMS AlgorithmID, uint32 KeySizeInBits, const CSSM_CRYPTO_DATA *Seed, const CSSM_DATA *Salt, const CSSM_DATE *StartDate, const CSSM_DATE *EndDate, const CSSM_DATA *Params, CSSM_CC_HANDLE *NewContextHandle)
This function creates a key generation cryptographic context, given a handle of a CSP, an algorithm identification number, a pass phrase, a modulus size (for public/private keypair generation), a key size (for symmetric key generation), a seed, and a salt. The cryptographic context handle is returned. The cryptographic context handle can be used to call key/keypair generation functions.Additional attributes can be added to the newly created context using the function
CSSM_UpdateContextAttributes() . Incremental attributes of interest for key generation include a handle-pair identifying a Data Storage Library service module and an open data store for CSPs that manage multiple persistent key stores. If a CSP does not support multiple key stores, the CSP ignores the presence or absence of this attribute.
- CSPHandle (input)
The handle that describes the add-in cryptographic service provider module used to perform this function. If a NULL handle is specified, CSSM returns error.
- AlgorithmID (input)
The algorithm identification number of the algorithm used for key generation.
- KeySizeInBits (input)
The logical size of the key (specified in bits). This refers to either the actual key size (for symmetric key generation) or the modulus size (for asymmetric key pair generation).
- Seed (input/optional)
A seed used to generate the key. The caller can either pass a seed and seed length in bytes or pass in a callback function. If NULL is passed, the cryptographic service provider will use its default seed handling mechanism.
- Salt (input/optional)
A Salt used to generate the key.
- StartDate (input/optional)
A start date for the validity period of the key or key pair being generated.
- EndDate (input/optional)
An end date for the validity period of the key or key pair being generated.
- Params (input/optional)
A data buffer containing parameters required to generate a key pair for a specific algorithm.
- NewContextHandle (output)
Cryptographic context handle.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
CSSMERR_CSSM_INVALID_ATTRIBUTESee also general error codes and common error codes section
CSSM_GenerateKey()
CSSM_GenerateKey() Pair
CSSM_GetContext()
CSSM_SetContext()
CSSM_DeleteContext()
CSSM_GetContextAttribute()
CSSM_UpdateContextAttributes()
CSSM_CSP_CreatePassThroughContext
CSSM_RETURN CSSMAPI CSSM_CSP_CreatePassThroughContext (CSSM_CSP_HANDLE CSPHandle, const CSSM_KEY *Key, CSSM_CC_HANDLE *NewContextHandle)
This function creates a custom cryptographic context, given a handle of a CSP and pointer to a custom input data structure. The cryptographic context handle is returned. The cryptographic context handle can be used to call the CSSM pass-through function for the CSP.
- CSPHandle (input)
The handle that describes the add-in cryptographic service provider module used to perform this function. If a NULL handle is specified, CSSM returns error.
- Key (input)
The key to be used for the context. The caller passes in a pointer to a CSSM_KEY structure containing the key.
- NewContextHandle (output)
Cryptographic context handle.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
CSSMERR_CSSM_INVALID_ATTRIBUTESee also general error codes and common error codes section
A CSP can create its own set of custom functions. The context information can be passed through its own data structure. The
CSSM_CSP_PassThrough() function should be used along with the function ID to call the desired custom function.
CSSM_CSP_PassThrough()
CSSM_GetContext()
CSSM_SetContext()
CSSM_DeleteContext()
CSSM_GetContextAttribute()
CSSM_UpdateContextAttributes()
CSSM_GetContext
CSSM_RETURN CSSMAPI CSSM_GetContext (CSSM_CC_HANDLE CCHandle, CSSM_CONTEXT_PTR *Context)
This function retrieves the context information when provided with a context handle.
- CCHandle (input)
The handle to the context information.
- Context (output)
The pointer to the CSSM_CONTEXT_PTR structure that describes the context associated with the handle CCHandle. The pointer will be set to NULL if the function fails. UseCSSM_FreeContext() to free the memory allocated by the CSSM.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CSSM_INVALID_CONTEXT_HANDLE
CSSMERR_CSSM_INVALID_ATTRIBUTE
CSSM_SetContext()
CSSM_FreeContext()
CSSM_FreeContext
CSSM_RETURN CSSMAPI CSSM_FreeContext (CSSM_CONTEXT_PTR Context)
This function frees the memory associated with the context structure.
- Context (input)
The pointer to the memory that describes the context structure.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_GetContext()
CSSM_SetContext
CSSM_RETURN CSSMAPI CSSM_SetContext (CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context)
This function replaces all of the context information associated with an existing context specified by CCHandle. The contents of the basic context structure and all of the attributes included in that structure are replaced by the context structure and attribute values contained in the input parameter Context.
- CCHandle (input)
The handle to the context.
- Context (input)
The context data describing the service to replace the current service associated with context handle CCHandle.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CSSM_INVALID_CONTEXT_HANDLE
CSSMERR_CSSM_INVALID_ATTRIBUTE
CSSM_GetContext()
CSSM_DeleteContext
CSSM_RETURN CSSMAPI CSSM_DeleteContext (CSSM_CC_HANDLE CCHandle)
This function frees the context structure allocated by any of theCSSM_CreateXXXXXContext() functions.
- CCHandle (input)
The handle that describes a context to be deleted.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.CSSMERR_CSSM_INVALID_CONTEXT_HANDLE
CSSM_CSP_CreateSymmetricContext()
CSSM_CSP_CreateAsymmetricContext()
CSSM_CSP_CreateKeyGenContext()
CSSM_CSP_CreateDigestContext()
CSSM_CSP_CreateSignatureContext()
and others.
CSSM_GetContextAttribute
CSSM_RETURN CSSMAPI CSSM_GetContextAttribute (const CSSM_CONTEXT *Context, uint32 AttributeType, CSSM_CONTEXT_ATTRIBUTE_PTR *ContextAttribute)
This function returns the value of a context attribute. Context references the cryptographic context to be searched for the attribute specified by AttributeType. If the specified attribute is not present then a NULL pointer is returned.
- Context (input)
A pointer to the context.
- AttributeType (input)
The attribute type of the desired attribute value.
- ContextAttribute (output)
The pointer to the CSSM_CONTEXT_ATTRIBUTE that describes the context attributes associated with the handle CCHandle and the attribute type. The pointer will be set to NULL if the function fails. CallCSSM_DeleteContextAttributes() to free memory allocated by the CSSM.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.CSSMERR_CSSM_ATTRIBUTE_NOT_IN_CONTEXT
CSSM_DeleteContextAttributes()
CSSM_GetContext()
CSSM_UpdateContextAttributes
CSSM_RETURN CSSMAPI CSSM_UpdateContextAttributes (CSSM_CC_HANDLE CCHandle, uint32 NumberOfAttributes, const CSSM_CONTEXT_ATTRIBUTE *ContextAttributes)
This function updates one or more context attribute values stored as part of an existing context specified by CCHandle. The basic context structure is not modified by this function. Only the context attributes are updated.The parameter NumberOfAttributes specifies the number of attributes to update. The new attribute values are specified in ContextAttributes. If an attribute provided in ContextAttributes is already present in the existing context, the existing value is replaced by the new value. If an attribute provided in ContextAttributes is not present in the existing context, then the new attribute is added. Attribute values are never deleted from the existing context.
- CCHandle (input)
The handle to the context.
- NumberOfAttributes (input)
The number of CSSM_CONTEXT_ATTRIBUTE structures to allocate.
- ContextAttributes (input)
Pointer to data that describes the attributes to be associated with this context.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CSSM_INVALID_CONTEXT_HANDLE
CSSMERR_CSSM_ATTRIBUTE_NOT_IN_CONTEXT
CSSM_GetContextAttribute()
CSSM_DeleteContextAttributes()
CSSM_DeleteContextAttributes
CSSM_RETURN CSSMAPI CSSM_DeleteContextAttributes (CSSM_CC_HANDLE CCHandle, uint32 NumberOfAttributes, const CSSM_CONTEXT_ATTRIBUTE *ContextAttributes)
This function deletes internal data associated with given attribute type of the context handle.
- CCHandle (input)
The handle that describes a context that is to be deleted.
- NumberOfAttributes (input)
The number of attributes to be deleted as specified in the array of context attributes.
- ContextAttributes (input)
The attributes to be deleted from the context. Only the attribute type is required. Any attribute values in the CSSM_CONTEXT_ATTRIBUTE structures are ignored.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CSSM_ATTRIBUTE_NOT_IN_CONTEXT
CSSMERR_CSSM_INVALID_CONTEXT_HANDLE
CSSM_GetContextAttributes()
CSSM_UpdateContextAttributes()
CSSM_CSP_Login
CSSM_RETURN CSSMAPI CSSM_CSP_Login (CSSM_CSP_HANDLE CSPHandle, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_DATA *LoginName, const void *Reserved)
Logs the user into the CSP, allowing for multiple login types.
- CSPHandle (input)
Handle of the CSP to log into.
- AccessCred (input)
A pointer to the set of one or more credentials required to log into the token or cryptographic service provider. The credentials structure can contain an immediate value for the credential, such as a passphrase or PIN, or the caller can specify a callback function the CSP can use to obtain one or more credentials.
- LoginName (input/optional)
A name or ID of the caller. The value is used with the provided AccessCred to authenticate and authorize the caller for login with the CSP. The CSP can require that a name value be provided. If a name value is not provided, the CSP can assume a default name under which to perform the authentication and authorization check, or the login request can fail.
- Reserved (input)
This field is reserved for future use. The value NULL should always be given. (May be used for multiple user support in the future.)
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CSP_INVALID_LOGIN_NAME
CSSMERR_CSP_ALREADY_LOGGED_IN
CSSM_CSP_Logout()
CSSM_CSP_GetLoginAcl()
CSSM_CSP_ChangeLoginAcl()
CSSM_CSP_Logout
CSSM_RETURN CSSMAPI CSSM_CSP_Logout (CSSM_CSP_HANDLE CSPHandle)
Terminates the login session associated with the specified CSP Handle.
- CSPHandle (input)
Handle for the target CSP.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_CSP_Login()
CSSM_CSP_GetLoginAcl()
CSSM_CSP_ChangeLoginAcl()
CSSM_CSP_GetLoginAcl
CSSM_RETURN CSSMAPI CSSM_CSP_GetLoginAcl (CSSM_CSP_HANDLE CSPHandle, const CSSM_STRING *SelectionTag, uint32 *NumberOfAclInfos, CSSM_ACL_ENTRY_INFO_PTR *AclInfos)
This function returns a description of zero or more ACL entries managed by the CSP and used to control login sessions with the CSP. The optional input SelectionTag restricts the returned descriptions to those ACL entries with a matching EntryTag value. If a SelectionTag value is specified and no matches are found, zero descriptions are returned. If no SelectionTag is specified, a description of all ACL entries used to control login sessions are returned by this function.Each AclInfo structure contains:
- Public contents of an ACL entry
- ACL EntryHandle, which is a unique value defined and managed by the service provider
The public ACL entry information returned by this function includes:
- The subject type - A CSSM_LIST structure containing one element identifying the type of subject stored in the ACL entry.
- Delegation flag - A CSSM_BOOL value indicating whether the subject can delegate the permissions recorded in Authorization.
- Authorization array - A CSSM_AUTHORIZATIONGROUP structure defining the set of operations for which permission is granted to the Subject.
- Validity period - A CSSM_ACL_VALIDITY_PERIOD structure containing two elements, the start time and the stop time for which the ACL entry is valid.
- ACL entry tag - A CSSM_STRING containing a user-defined value associated with the ACL entry.
- CSPHandle (input)
The module handle that identifies the Cryptographic service provider to perform this operation.
- SelectionTag (input/optional)
A CSSM_STRING value matching the user-defined tag value associated with one or more ACL entries controlling login sessions. To retrieve a description of all ACL entries controlling login sessions, this parameter must be NULL.
- NumberOfAclInfos (output)
The number of entries in the AclInfos array. If no ACL entry descriptions are returned, this value is zero.
- AclInfos (output)
An array of CSSM_ACL_ENTRY_INFO structures. The unique handle contained in this structure can be used during the current attach session and the current login session to reference specific ACL entries for editing. The structure is allocated by the service provider and must be released by the caller when the structure is no longer needed. If no ACL entry descriptions are returned, this value is NULL.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_CSP_ChangeLoginAcl()
CSSM_CSP_Login()
CSSM_CSP_Logout()
CSSM_CSP_ChangeLoginAcl
CSSM_RETURN CSSMAPI CSSM_CSP_ChangeLoginAcl (CSSM_CSP_HANDLE CSPHandle, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_ACL_EDIT *AclEdit)
This function edits the stored ACL controlling login sessions for a cryptographic service provider (CSP). The ACL is modified according to the edit mode and information provided in AclEdit.The caller must have a login session in process and must be authorized to modify the target ACL. Caller authentication and authorization to edit the ACL is determined based on the caller-provided AccessCred.
The caller must be authorized to add, delete or replace the ACL entries controlling login to the CSP. When adding or replacing an ACL entry, the service provider must reject the creation of duplicate ACL entries.
When adding a new ACL entry to an ACL, the caller must provide a complete ACL entry prototype. All ACL entry items, except the ACL entry Subject must be provided as an immediate value in AclEdit.NewEntry. The ACL entry Subject can be provided as an immediate value, from a verifier with a protected data path, from an external authentication or authorization service, or through a callback function specified in AclEdit.NewEntry.Callback.
- CSPHandle (input)
The module handle that identifies the Cryptographic service provider to perform this operation
- AccessCred (input)
A pointer to the set of one or more credentials used to authenticate and validate the caller's authorization to modify the ACL controlling login sessions with the CSP. Required credentials can include zero or more certificates, zero or more caller names, and one or more samples. Traditionally a caller name has been used to establish the context of a login session. Certificates can be used for the same purpose. If certificates and/or caller names are provided as input these must be provided as immediate values in this structure. The samples can be provided as immediate values or can be obtained through a callback function included in the AccessCred structure.
- AclEdit (input)
A structure containing information that defines the edit operation. Valid operations include adding, replacing and deleting entries in an ACL managed by the service provider. The AclEdit can contain information for a new ACL entry and a handle uniquely identifying an existing ACL entry. The information controls the edit operation as follows:
Value of AclEdit.EditMode Use of AclEdit.NewEntry
and AclEdit.OldEntryHandleCSSM_ACL_EDIT_MODE_ADD Adds a new ACL entry to the set of ACL entries controlling login sessions with the CSP. The new ACL entry is created from the ACL entry prototype contained in NewEntry.
OldEntryHandle is ignored for this EditMode.CSSM_ACL_EDIT_MODE_DELETE Deletes the ACL entry identified by OldEntryHandle and associated with login sessions with the CSP.
NewEntry is ignored for this EditMode.CSSM_ACL_EDIT_MODE_REPLACE Replaces the ACL entry identified by OldEntryHandle and controlling login sessions with the CSP. The existing ACL is replaced based on the ACL entry prototype contained in the NewEntry. When replacing an existing ACL entry, the caller must replace all of the items in an ACL entry. The replacement prototype includes:
- Subject type and value - A CSSM_LIST structure containing a typed Subject. The Subject identifies the entity authorized by this ACL entry.
- Delegation flag - A CSSM_BOOL value indicating whether the subject can delegate the permissions recorded in the authorization array.
- Authorization array - A CSSM_AUTHORIZATIONGROUP structure defining the et of operations for which permission is granted to the Subject.
- Validity period - A CSSM_ACL_VALIDITY_PERIOD structure containing two elements, the start time and the stop time for which the ACL entry is valid.
- ACL entry tag - A CSSM_STRING containing a user-defined value associated with the ACL entry.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_CSP_GetLoginAcl()
CSSM_CSP_Login()
CSSM_CSP_Logout()
CSSM_GetKeyAcl
CSSM_RETURN CSSMAPI CSSM_GetKeyAcl (CSSM_CSP_HANDLE CSPHandle, const CSSM_KEY *Key, const CSSM_STRING *SelectionTag, uint32 *NumberOfAclInfos, CSSM_ACL_ENTRY_INFO_PTR *AclInfos)
This function returns a description of zero or more ACL entries managed by the CSP and associated with the target Key. The optional input SelectionTag restricts the returned descriptions to those ACL entries with a matching EntryTag value. If a SelectionTag value is specified and no matches are found, zero descriptions are returned. If no SelectionTag is specified, a description of all ACL entries associated with the Key are returned by this function.Each AclInfo structure contains:
- Public contents of an ACL entry
- ACL EntryHandle, which is a unique value defined and managed by the service provider
The public ACL entry information returned by this function includes:
- The subject type - A CSSM_LIST structure containing one element identifying the type of subject stored in the ACL entry.
- Delegation flag - A CSSM_BOOL value indicating whether the subject can delegate the permissions recorded in Authorization.
- Authorization array - A CSSM_AUTHORIZATIONGROUP structure defining the set of operations for which permission is granted to the Subject.
- Validity period - A CSSM_ACL_VALIDITY_PERIOD structure containing two elements, the start time and the stop time for which the ACL entry is valid.
- ACL entry tag - A CSSM_STRING containing a user-defined value associated with the ACL entry.
- CSPHandle (input)
The module handle that identifies the Cryptographic service provider to perform this operation.
- Key (input)
A pointer to the target key whose associated ACL entries are scanned and returned.
- SelectionTag (input/optional)
A CSSM_STRING value matching the user-defined tag value associated with one or more ACL entries for the target Key. To retrieve a description of all ACL entries for the target Key, this parameter must be NULL.
- NumberOfAclInfos (output)
The number of entries in the AclInfos array. If no ACL entry descriptions are returned, this value is zero.
- AclInfos (output)
An array of CSSM_ACL_ENTRY_INFO structures. The unique handle contained in this structure can be used during the current attach session to reference specific ACL entries for editing. The structure is allocated by the service provider and must be released by the caller when the structure is no longer needed. If no ACL entry descriptions are returned, this value is NULL.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_ChangeKeyAcl()
CSSM_ChangeKeyAcl
CSSM_RETURN CSSMAPI CSSM_ChangeKeyAcl (CSSM_CSP_HANDLE CSPHandle, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_ACL_EDIT *AclEdit, const CSSM_KEY *Key)
This function edits the stored ACL associated with the target Key. The ACL is modified according to the edit mode and information provided in AclEdit.The caller must be authorized to modify the target ACL. Caller authentication and authorization to edit the ACL is determined based on the caller-provided AccessCred.
The caller must be authorized to add, delete or replace the ACL entries associated with the target Key. When adding or replacing an ACL entry, the service provider must reject the creation of duplicate ACL entries.
When adding a new ACL entry to an ACL, the caller must provide a complete ACL entry prototype. All ACL entry items, except the ACL entry Subject must be provided as an immediate value in AclEdit->NewEntry. The ACL entry Subject can be provided as an immediate value, from a verifier with a protected data path, from an external authentication or authorization service, or through a callback function specified in AclEdit->NewEntry->Callback.
- CSPHandle (input)
The module handle that identifies the Cryptographic service provider to perform this operation
- AccessCred (input)
A pointer to the set of one or more credentials used to authenticate and validate the caller's authorization to modify the ACL associated with the Key. Required credentials can include zero or more certificates, zero or more caller names, and one or more samples. If certificates and/or caller names are provided as input these must be provided as immediate values in this structure. The samples can be provided as immediate values or can be obtained through a callback function included in the AccessCred structure.
- AclEdit (input)
A structure containing information that defines the edit operation. Valid operations include: adding, replacing and deleting entries in an ACL managed by the service provider. The AclEdit can contain information for a new ACL entry and a handle uniquely identifying an existing ACL entry. The information controls the edit operation as follows:
Value of AclEdit.EditMode Use of AclEdit.NewEntry and AclEdit.OldEntryHandle CSSM_ACL_EDIT_MODE_ADD Adds a new ACL entry to the set of ACL entries associated with the specified Key. The new ACL entry is created from the ACL entry prototype contained in NewEntry.
OldEntryHandle is ignored for this edit mode.CSSM_ACL_EDIT_MODE_DELETE Deletes the ACL entry identified by OldEntryHandle and associated with the specified Key.
NewEntry is ignored for this edit mode.CSSM_ACL_EDIT_MODE_REPLACE Replaces the ACL entry identified by OldEntryHandle and associated with the specified Key. The existing ACL is replaced based on the ACL entry prototype contained in the NewEntry. When replacing an existing ACL entry, the caller must replace all of the items in an ACL entry. The replacement prototype includes:
- Subject type and value
A CSSM_LIST structure containing a typed Subject. The Subject identifies the entity authorized by this ACL entry.
- Delegation flag
A CSSM_BOOL value indicating whether the subject can delegate the permissions recorded in the authorization array.
- Authorization array
A CSSM_AUTHORIZATIONGROUP structure defining the set of operations for which permission is granted to the Subject.
- Validity period
A CSSM_ACL_VALIDITY_PERIOD structure containing two elements, the start time and the stop time for which the ACL entry is valid.
- ACL entry tag
A CSSM_STRING containing a user-defined value associated with the ACL entry.
- Key (input)
A pointer to the target key whose associated ACL is being modified.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_GetKeyAcl()
CSSM_GetKeyOwner
CSSM_RETURN CSSMAPI CSSM_GetKeyOwner (CSSM_CSP_HANDLE CSPHandle, const CSSM_KEY *Key, CSSM_ACL_OWNER_PROTOTYPE_PTR Owner)
This function returns a CSSM_ACL_OWNER_PROTOTYPE describing the current Owner of the Key.
- CSPHandle (input)
The module handle that identifies the Cryptographic service provider to perform this operation.
- Key (input)
A pointer to the target key whose associated Owner is returned.
- Owner (output)
A CSSM_ACL_OWNER_PROTOTYPE describing the current Owner of the Key.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_ChangeKeyOwner()
CSSM_ChangeKeyOwner
CSSM_RETURN CSSMAPI CSSM_ChangeKeyOwner (CSSM_CSP_HANDLE CSPHandle, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_KEY *Key, const CSSM_ACL_OWNER_PROTOTYPE *NewOwner)
This function takes a CSSM_ACL_OWNER_PROTOTYPE defining the new Owner of the Key.
- CSPHandle (input)
The module handle that identifies the Cryptographic service provider to perform this operation.
- AccessCred (input)
A pointer to the set of one or more credentials used to prove the caller is the current Owner of the Key. Required credentials can include zero or more certificates, zero or more caller names, and one or more samples. If certificates and/or caller names are provided as input these must be provided as immediate values in this structure. The samples can be provided as immediate values or can be obtained through a callback function included in the AccessCred structure.
- Key (input)
A pointer to the target key whose associated Owner is changed.
- NewOwner (Input)
A CSSM_ACL_OWNER_PROTOTYPE defining the new Owner of the Key.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_GetKeyOwner()
CSSM_CSP_GetLoginOwner
CSSM_RETURN CSSMAPI CSSM_CSP_GetLoginOwner (CSSM_CSP_HANDLE CSPHandle, CSSM_ACL_OWNER_PROTOTYPE_PTR Owner)
This function returns a CSSM_ACL_OWNER_PROTOTYPE describing the current Login Owner of the CSP.
- CSPHandle (input)
The module handle that identifies the Cryptographic service provider to perform this operation.
- Owner (output)
A CSSM_ACL_OWNER_PROTOTYPE describing the Login Owner.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_CSP_ChangeLoginOwner()
CSSM_CSP_ChangeLoginOwner
CSSM_RETURN CSSMAPI CSSM_CSP_ChangeLoginOwner (CSSM_CSP_HANDLE CSPHandle, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_ACL_OWNER_PROTOTYPE *NewOwner)
This function takes a CSSM_ACL_OWNER_PROTOTYPE describing the new Login Owner.
- CSPHandle (input)
The module handle that identifies the Cryptographic service provider to perform this operation.
- AccessCred (input)
A pointer to the set of one or more credentials used to prove the caller is the current Login Owner. Required credentials can include zero or more certificates, zero or more caller names, and one or more samples. If certificates and/or caller names are provided as input these must be provided as immediate values in this structure. The samples can be provided as immediate values or can be obtained through a callback function included in the AccessCred structure.
- NewOwner (Input)
A CSSM_ACL_OWNER_PROTOTYPE defining the new Login Owner.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_CSP_GetLoginOwner()
CSSM_SignData
CSSM_RETURN CSSMAPI CSSM_SignData (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *DataBufs, uint32 DataBufCount, CSSM_ALGORITHMS DigestAlgorithm, CSSM_DATA_PTR Signature)
This function signs all data contained in the set of input buffers using the private key specified in the context. The CSP can require that the cryptographic context include access credentials for authentication and authorization checks when using a private key or a secret key.Signing can include digesting the data and encrypting the digest or signing just the digest (already calculated by the application). If digesting the data and encrypting the digest, then the context should specify the combination digest/encryption algorithm (for example, CSSM_ALGID_MD5WithRSA). In this case, the DigestAlgorithm parameter must be set to CSSM_ALGID_NONE. If signing just the digest, then the context should specify just the encryption algorithm and the DigestAlgorithm parameter should specify the type of digest (for example, CSSM_ALGID_MD5). Also, DataBufCount must be 1.
If the signing algorithm is not reversible or strictly limits the size of the signed data, then the algorithm can specify signing without digesting. In this case, the sign operation is performed on the input data and the size of the input data is restricted by the service provider.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
- DataBufs (input)
A pointer to a vector of CSSM_DATA structures that contain the data to be operated on.
- DataBufCount (input)
The number of DataBufs to be signed.
- DigestAlgorithm (input)
If signing just a digest, specifies the type of digest. In this case, the context should only specify the encryption algorithm. If not signing just a digest, it must be CSSM_ALGID_NONE. In this case, the context should specify the combination digest/encryption algorithm.
- Signature (output)
A pointer to the CSSM_DATA structure for the signature.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CSP_OUTPUT_LENGTH_ERROR
CSSMERR_CSP_INVALID_DIGEST_ALGORITHM
The output is returned to the caller either by filling the caller-specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, pre-allocated output buffer, the caller must provide an array of one or more CSSM_DATA structures each one containing a Length field value greater than zero and a non-NULL Data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures each containing a Length field value equal to zero and a NULL Data pointer field value. The application is always responsible for de-allocating the memory when it is no longer needed. If the CSSM_DATA_PTR parameter is NULL (that is, does not point to an array of CSSM_DATA structures) or the number of CSSM_DATA structures is specified as zero, the error code CSSM_CSP_INVALID_DATA_POINTER is returned.
CSSM_VerifyData()
CSSM_SignDataInit()
CSSM_SignDataUpdate()
CSSM_SignDataFinal()
CSSM_SignDataInit
CSSM_RETURN CSSMAPI CSSM_SignDataInit (CSSM_CC_HANDLE CCHandle)
This function initializes the staged sign data function.For staged operations, a combination operation selecting both a digesting algorithm and a signing algorithm must be specified.
The CSP can require that the cryptographic context include access credentials for authentication and authorization checks when using a private key or a secret key.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_SignData()
CSSM_SignDataUpdate()
CSSM_SignDataFinal()
CSSM_SignDataUpdate
CSSM_RETURN CSSMAPI CSSM_SignDataUpdate (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *DataBufs, uint32 DataBufCount)
This function continues the staged signing process over all data contained in the set of input buffers. Signing is performed using the private key specified in the context.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
- DataBufs (input)
A pointer to a vector of CSSM_DATA structures that contain the data to be operated on.
- DataBufCount (input)
The number of DataBufs to be signed.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSM_SignData()
CSSM_SignDataInit()
CSSM_SignDataFinal()
CSSM_SignDataFinal
CSSM_RETURN CSSMAPI CSSM_SignDataFinal (CSSM_CC_HANDLE CCHandle, CSSM_DATA_PTR Signature)
This function completes the final stage of the sign data function.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
- Signature (output)
A pointer to the CSSM_DATA structure for the signature.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.CSSMERR_CSP_OUTPUT_LENGTH_ERROR
The output is returned to the caller either by filling the caller-specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, pre-allocated output buffer, the caller must provide an array of one or more CSSM_DATA structures each one containing a Length field value greater than zero and a non-NULL Data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures each containing a Length field value equal to zero and a NULL Data pointer field value. The application is always responsible for de-allocating the memory when it is no longer needed. If the CSSM_DATA_PTR parameter is NULL (that is, does not point to an array of CSSM_DATA structures) or the number of CSSM_DATA structures is specified as zero, the error code CSSM_CSP_INVALID_DATA_POINTER is returned.
CSSM_SignData()
CSSM_SignDataInit()
CSSM_SignDataUpdate()
CSSM_VerifyData
CSSM_RETURN CSSMAPI CSSM_VerifyData (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *DataBufs, uint32 DataBufCount, CSSM_ALGORITHMS DigestAlgorithm, const CSSM_DATA *Signature)
This function verifies all data contained in the set of input buffers based on the input signature.Verifying can include digesting the data and decrypting the digest (from the signature) or verifying just the digest (already calculated by the application). If digesting the data and decrypting the digest, then the context should specify both digest and decryption algorithms (for example, CSSM_ALGID_MD5WithRSA). In this case, the DigestAlgorithm parameter must be set to CSSM_ALGID_NONE. If signing just the digest, then the context should specify just the decryption algorithm and the DigestAlgorithm parameter should specify the type of digest (for example, CSSM_ALGID_MD5). Also, DataBufCount must be 1.
If the signing algorithm is not reversible or strictly limits the size of the signed data, then the algorithm can specify verification without digesting. In this case, the verify operation is performed on the input data and the size of the input data is restricted by the service provider.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
- DataBufs (input)
A pointer to a vector of CSSM_DATA structures that contain the data to be operated on.
- DataBufCount (input)
The number of DataBufs to be verified.
- DigestAlgorithm (input)
If verifying just a digest, specifies the type of digest. In this case, the context should only specify the encryption algorithm. If not verifying just a digest, it must be CSSM_ALGID_NONE. In this case, the context should specify the combination digest/encryption algorithm.
- Signature (input)
A pointer to a CSSM_DATA structure which contains the signature and the size of the signature.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CSP_INPUT_LENGTH_ERROR
CSSMERR_CSP_VERIFY_FAILED
CSSMERR_CSP_INVALID_SIGNATURE
CSSMERR_CSP_INVALID_DIGEST_ALGORITHM
CSSM_SignData()
CSSM_VerifyDataInit()
CSSM_VerifyDataUpdate()
CSSM_VerifyDataFinal()
CSSM_VerifyDataInit
CSSM_RETURN CSSMAPI CSSM_VerifyDataInit (CSSM_CC_HANDLE CCHandle)
This function initializes the staged verify data function.For staged operations, a combination operation selecting both a digesting algorithm and a verification algorithm must be specified.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_VerifyDataUpdate()
CSSM_VerifyDataFinal()
CSSM_VerifyData()
CSSM_VerifyDataUpdate
CSSM_RETURN CSSMAPI CSSM_VerifyDataUpdate (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *DataBufs, uint32 DataBufCount)
This function continues the staged verification process over all data contained in the set of input. Verification will be based on the signature presented as input when finalizing the staged verification process.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
- DataBufs (input)
A pointer to a vector of CSSM_DATA structures that contain the data to be operated on.
- DataBufCount (input)
The number of DataBufs to be verified.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_VerifyData()
CSSM_VerifyDataInit()
CSSM_VerifyDataFinal()
CSSM_VerifyDataFinal
CSSM_RETURN CSSMAPI CSSM_VerifyDataFinal (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *Signature)
This function finalizes the staged verify data function.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
- Signature (input)
A pointer to a CSSM_DATA structure which contains the starting address for the signature to verify against and the length of the signature in bytes.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CSP_INPUT_LENGTH_ERROR
CSSMERR_CSP_VERIFY_FAILED
CSSMERR_CSP_INVALID_SIGNATURE
CSSM_VerifyData()
CSSM_VerifyDataInit()
CSSM_VerifyDataUpdate()
CSSM_DigestData
CSSM_RETURN CSSMAPI CSSM_DigestData (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *DataBufs, uint32 DataBufCount, CSSM_DATA_PTR Digest)
This function computes a message digest for all data contained in the set of input buffers.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
- DataBufs (input)
A pointer to a vector of CSSM_DATA structures that contain the data to be operated on.
- DataBufCount (input)
The number of DataBufs.
- Digest (output)
A pointer to the CSSM_DATA structure for the message digest.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.CSSMERR_CSP_OUTPUT_LENGTH_ERROR
The output is returned to the caller either by filling the caller-specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, pre-allocated output buffer, the caller must provide an array of one or more CSSM_DATA structures each one containing a Length field value greater than zero and a non-NULL Data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures each containing a Length field value equal to zero and a NULL Data pointer field value. The application is always responsible for de-allocating the memory when it is no longer needed. If the CSSM_DATA_PTR parameter is NULL (that is, does not point to a CSSM_DATA structure), then the error code CSSM_CSP_INVALID_DATA_POINTER is returned.
CSSM_DigestDataInit
CSSM_DigestDataUpdate
CSSM_DigestDataFinal
CSSM_DigestDataInit
CSSM_RETURN CSSMAPI CSSM_DigestDataInit (CSSM_CC_HANDLE CCHandle)
This function initializes the staged message digest function.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_DigestData()
CSSM_DigestDataUpdate()
CSSM_DigestDataClone()
CSSM_DigestDataFinal()
CSSM_DigestDataUpdate
CSSM_RETURN CSSMAPI CSSM_DigestDataUpdate (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *DataBufs, uint32 DataBufCount)
This function continues the staged process of digesting all data contained in the set of input buffers. The resulting digest value will be returned as part of the staged digesting process.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
- DataBufs (input)
A pointer to a vector of CSSM_DATA structures that contain the data to be operated on.
- DataBufCount (input)
The number of DataBufs.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_DigestData()
CSSM_DigestDataInit()
CSSM_DigestDataClone()
CSSM_DigestDataFinal()
CSSM_DigestDataClone
CSSM_RETURN CSSMAPI CSSM_DigestDataClone (CSSM_CC_HANDLE CCHandle, CSSM_CC_HANDLE *ClonednewCCHandle)
This function clones a given staged message digest context with its cryptographic attributes and intermediate result.
- CCHandle (input)
The handle that describes the context of a staged message digest operation.
- Clonednw CCHandle (output)
The cloned digest context handle. The handle will be set to CSSM_INVALID_HANDLE if the function fails.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
When a digest context is cloned, a new context is created with data associated with the parent context. Changes made to the parent context after calling this function will not be reflected in the cloned context. The cloned context could be used with the CSSM_DigestDataUpdate and CSSM_DigestDataFinal functions.
CSSM_DigestData()
CSSM_DigestDataInit()
CSSM_DigestDataUpdate()
CSSM_DigestDataFinal()
CSSM_DigestDataFinal
CSSM_RETURN CSSMAPI CSSM_DigestDataFinal (CSSM_CC_HANDLE CCHandle, CSSM_DATA_PTR Digest)
This function finalizes the staged message digest function.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
- Digest (output)
A pointer to the CSSM_DATA structure for the message digest.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.CSSMERR_CSP_OUTPUT_LENGTH_ERROR
The output is returned to the caller either by filling the caller-specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, pre-allocated output buffer, the caller must provide an array of one or more CSSM_DATA structures each one containing a Length field value greater than zero and a non-NULL Data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures each containing a Length field value equal to zero and a NULL Data pointer field value. The application is always responsible for de-allocating the memory when it is no longer needed. If the CSSM_DATA_PTR parameter is NULL (that is, does not point to a CSSM_DATA structure), then the error code CSSM_CSP_INVALID_DATA_POINTER is returned.
CSSM_DigestData()
CSSM_DigestDataInit()
CSSM_DigestDataUpdate()
CSSM_DigestDataClone()
CSSM_GenerateMac
CSSM_RETURN CSSMAPI CSSM_GenerateMac (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *DataBufs, uint32 DataBufCount, CSSM_DATA_PTR Mac)
This function computes a message authentication code for all data contained in the set of input buffers.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
- DataBufs (input)
A pointer to a vector of CSSM_DATA structures that contain the data to be operated on.
- DataBufCount (input)
The number of DataBufs.
- Mac (output)
A pointer to the CSSM_TATA structure for the Message Authentication Code.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.CSSMERR_CSP_OUTPUT_LENGTH_ERROR
The output is returned to the caller either by filling the caller-specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, pre-allocated output buffer, the caller must provide an array of one or more CSSM_DATA structures each one containing a Length field value greater than zero and a non-NULL Data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures each containing a Length field value equal to zero and a NULL Data pointer field value. The application is always responsible for de-allocating the memory when it is no longer needed. If the CSSM_DATA_PTR parameter is NULL (that is, does not point to a CSSM_DATA structure), then the error code CSSM_CSP_INVALID_DATA_POINTER is returned.
CSSM_GenerateMacInit()
CSSM_GenerateMacUpdate()
CSSM_GenerateMacFinal()
CSSM_GenerateMacInit
CSSM_RETURN CSSMAPI CSSM_GenerateMacInit (CSSM_CC_HANDLE CCHandle)
This function initializes the staged message authentication code function.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_GenerateMac()
CSSM_GenerateMacUpdate()
CSSM_GenerateMacFinal()
CSSM_GenerateMacUpdate
CSSM_RETURN CSSMAPI CSSM_GenerateMacUpdate (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *DataBufs, uint32 DataBufCount)
This function continues the staged process of computing a message authentication code over all data contained in the set of input buffers. The authentication code will be returned as a result of the final code generation step.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
- DataBufs (input)
A pointer to a vector of CSSM_DATA structures that contain the data to be operated on.
- DataBufCount (input)
The number of DataBufs.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_GenerateMac()
CSSM_GenerateMacInit()
CSSM_GenerateMacFinal()
CSSM_GenerateMacFinal
CSSM_RETURN CSSMAPI CSSM_GenerateMacFinal (CSSM_CC_HANDLE CCHandle, CSSM_DATA_PTR Mac)
This function finalizes the staged message authentication code function.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
- Mac (output)
A pointer to the CSSM_DATA structure for the message authentication code.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.CSSMERR_CSP_OUTPUT_LENGTH_ERROR
The output is returned to the caller either by filling the caller-specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, pre-allocated output buffer, the caller must provide an array of one or more CSSM_DATA structures each one containing a Length field value greater than zero and a non-NULL Data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures each containing a Length field value equal to zero and a NULL Data pointer field value. The application is always responsible for de-allocating the memory when it is no longer needed. If the CSSM_DATA_PTR parameter is NULL (that is, does not point to a CSSM_DATA structure), then the error code CSSM_CSP_INVALID_DATA_POINTER is returned.
CSSM_GenerateMac()
CSSM_GenerateMacInit()
CSSM_GenerateMacUpdate()
CSSM_VerifyMac
CSSM_RETURN CSSMAPI CSSM_VerifyMac (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *DataBufs, uint32 DataBufCount, const CSSM_DATA *Mac)
This function verifies the message authentication code over all data contained in the set of input buffers based on the input signature.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
- DataBufs (input)
A pointer to a vector of CSSM_DATA structures that contain the data to be operated on.
- DataBufCount (input)
The number of DataBufs.
- Mac (input)
A pointer to the CSSM_DATA structure containing the MAC to verify.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CSP_INPUT_LENGTH_ERROR
CSSMERR_CSP_VERIFY_FAILED
CSSMERR_CSP_INVALID_SIGNATURE
CSSM_VerifyMacInit()
CSSM_VerifyMacUpdate()
CSSM_VerifyMacFinal()
CSSM_VerifyMacInit
CSSM_RETURN CSSMAPI CSSM_VerifyMacInit (CSSM_CC_HANDLE CCHandle)
This function initializes the staged message authentication code verification function.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_VerifyMac()
CSSM_VerifyMacUpdate()
CSSM_VerifyMacFinal()
CSSM_VerifyMacUpdate
CSSM_RETURN CSSMAPI CSSM_VerifyMacUpdate (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *DataBufs, uint32 DataBufCount)
This function continues the staged process of verifying the message authentication code over all data in the set of input buffers. Verification will be based on the authentication code presented as input when finalizing the staged verification process.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
- DataBufs (input)
A pointer to a vector of CSSM_DATA structures that contain the data to be operated on.
- DataBufCount (input)
The number of DataBufs.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_VerifyMac()
CSSM_VerifyMacInit()
CSSM_VerifyMacFinal()
CSSM_VerifyMacFinal
CSSM_RETURN CSSMAPI CSSM_VerifyMacFinal (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *Mac)
This function finalizes the staged message authentication code verification function.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
- Mac (input)
A pointer to the CSSM_DATA structure containing the MAC to verify.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CSP_INPUT_LENGTH_ERROR
CSSMERR_CSP_VERIFY_FAILED
CSSMERR_CSP_INVALID_SIGNATURE
CSSM_VerifyMac()
CSSM_VerifyMacInit()
CSSM_VerifyMacUpdate()
CSSM_QuerySize
CSSM_RETURN CSSMAPI CSSM_QuerySize (CSSM_CC_HANDLE CCHandle, CSSM_BOOL Encrypt, uint32 QuerySizeCount, CSSM_QUERY_SIZE_DATA_PTR DataBlockSizes)
This function queries for the size of the output data for a cryptographic operation. If the context is an encryption or decryption context type than the Encrypt parameter will determine which operation is being performed. If Encrypt is set to CSSM_TRUE than it is an encrypt operation, otherwise it is a decrypt operation. For all other context types the Encrypt parameter is ignored. This function can also be used to query the output size requirements for the intermediate steps of a staged cryptographic operation. There may be algorithm-specific and token-specific rules restricting the lengths of data following data update calls.
- CCHandle (input)
The handle for an encryption and decryption context.
- Encrypt (input)
A boolean indicating whether encryption is the operation for which the output data size should be calculated. If CSSM_TRUE, the operation is encryption. If CSSM_FALSE the operation is decryption.
- QuerySizeCount (input)
The number of entries in the array of DataBlockSizes.
- DataBlockSizes (input/output)
An array of data block input sizes and corresponding entries for the data block output sizes that are returned by this function.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.CSSMERR_CSP_QUERY_SIZE_UNKNOWN
CSSM_EncryptData()
CSSM_EncryptDataUpdate()
CSSM_DecryptData()
CSSM_DecryptDataUpdate()
CSSM_SignData()
CSSM_VerifyData()
CSSM_DigestData()
CSSM_GenerateMac()
CSSM_EncryptData
CSSM_RETURN CSSMAPI CSSM_EncryptData (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *ClearBufs, uint32 ClearBufCount, CSSM_DATA_PTR CipherBufs, uint32 CipherBufCount, uint32 *bytesEncrypted, CSSM_DATA_PTR RemData)
This function encrypts all data contained in the set of input buffers using information in the context. TheCSSM_QuerySize() function can be used to estimate the output buffer size required. The minimum number of buffers required to contain the resulting cipher text is produced as output. If the cipher text result does not fit within the set of output buffers, the remaining cipher text is returned in the single output buffer RemData.The CSP can require that the cryptographic context include access credentials for authentication and authorization checks when using a private key or a secret key.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
- ClearBufs (input)
A pointer to a vector of CSSM_DATA structures that contain the data to be operated on.
- ClearBufCount (input)
The number of ClearBufs.
- CipherBufs (output)
A pointer to a vector of CSSM_DATA structures that contain the results of the operation on the data.
- CipherBufCount (input)
The number of CipherBufs.
- bytesEncrypted (output)
A pointer to uint32 for the size of the encrypted data in bytes.
- RemData (output)
A pointer to the CSSM_DATA structure for the remaining cypher text if there is not enough buffer space available in the output data structures.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CSP_BLOCK_SIZE_MISMATCH
CSSMERR_CSP_OUTPUT_LENGTH_ERROR
The output is returned to the caller either by filling the caller-specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, pre-allocated output buffer, the caller must provide an array of one or more CSSM_DATA structures each one containing a Length field value greater than zero and a non-NULL Data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures each containing a Length field value equal to zero and a NULL Data pointer field value. The application is always responsible for de-allocating the memory when it is no longer needed. If the CSSM_DATA_PTR parameter is NULL (that is, does not point to an array of CSSM_DATA structures) or the number of CSSM_DATA structures is specified as zero, the error code CSSM_CSP_INVALID_DATA_POINTER is returned. In-place encryption can be done by supplying the same input and output buffers.
CSSM_QuerySize()
CSSM_DecryptData()
CSSM_EncryptDataInit()
CSSM_EncryptDataUpdate()
CSSM_EncryptDataFinal()
CSSM_EncryptDataP()
CSSM_EncryptDataInitP()
CSSM_DecryptP()
CSSM_DecryptDataInitP()
CSSM_EncryptDataP
CSSM_RETURN CSSMAPI CSSM_EncryptDataP (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *ClearBufs, uint32 ClearBufCount, CSSM_DATA_PTR CipherBufs, uint32 CipherBufCount, uint32 *bytesEncrypted, CSSM_DATA_PTR RemData, CSSM_PRIVILEGE Privilege)
This function is similar toCSSM_EncryptData() . It also accepts a USEE tag as a privilege request parameter. CSSM checks that either its own privilege set or the Application's privilege set (if the Application is signed) includes the tag. If the tag is found, and the service provider privilege set indicates that it is supported, the tag is forwarded to the service provider.
SeeCSSM_EncryptData() .
- Privilege (input)
The privilege to be applied during the cryptographic operation.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CSP_BLOCK_SIZE_MISMATCH
CSSMERR_CSP_OUTPUT_LENGTH_ERROR
CSSM_QuerySize()
CSSM_DecryptData()
CSSM_EncryptDataInit()
CSSM_EncryptDataUpdate()
CSSM_EncryptDataFinal()
CSSM_EncryptDataP()
CSSM_EncryptDataInitP()
CSSM_DecryptP()
CSSM_DecryptDataInitP()
CSSM_EncryptDataInit
CSSM_RETURN CSSMAPI CSSM_EncryptDataInit (CSSM_CC_HANDLE CCHandle)
This function initializes the staged encrypt function. There may be algorithm-specific and token-specific rules restricting the lengths of data following data update calls making use of these parameters.The CSP can require that the cryptographic context include access credentials for authentication and authorization checks when using a private key or a secret key.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_QuerySize()
CSSM_DecryptData()
CSSM_EncryptDataInit()
CSSM_EncryptDataUpdate()
CSSM_EncryptDataFinal()
CSSM_EncryptDataP()
CSSM_EncryptDataInitP()
CSSM_DecryptP()
CSSM_DecryptDataInitP()
CSSM_EncryptDataInitP
CSSM_RETURN CSSMAPI CSSM_EncryptDataInitP (CSSM_CC_HANDLE CCHandle, CSSM_PRIVILEGE Privilege)
This function similar toCSSM_EncryptDataInit() . It also accepts a USEE tag as a privilege request parameter. CSSM checks that either its own privilege set or the Application's privilege set (if the Application is signed) includes the tag. If the tag is found, and the service provider privilege set indicates that it is supported, the tag is forwarded to the service provider.For staged operations using privilege initialization functions
CSSM_EncryptDataInitP() , the completion functionsCSSM_EncryptDataUpdate() andCSSM_EncryptDataFinalize() are used.
SeeCSSM_EncryptDataInit() .
- Privilege (input)
The privilege to be applied during the cryptographic operation.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
SeeCSSM_EncryptDataInit() .
CSSM_QuerySize()
CSSM_DecryptData()
CSSM_EncryptDataInit()
CSSM_EncryptDataUpdate()
CSSM_EncryptDataFinal()
CSSM_EncryptDataP()
CSSM_EncryptDataInitP()
CSSM_DecryptP()
CSSM_DecryptDataInitP()
CSSM_EncryptDataUpdate
CSSM_RETURN CSSMAPI CSSM_EncryptDataUpdate (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *ClearBufs, uint32 ClearBufCount, CSSM_DATA_PTR CipherBufs, uint32 CipherBufCount, uint32 *bytesEncrypted)
This function continues the staged encryption process over all data in the set of input buffers. There can be algorithm-specific and token-specific rules restricting the lengths of data inCSSM_EncryptUpdate() calls, but multiple input buffers are supported. The minimum number of buffers required to contain the resulting cipher text is produced as output. Excess output buffer space is not remembered across staged encryption calls. Each staged call begins filling one or more new output buffers. TheCSSM_QuerySize() function can be used to estimate the output buffer size required for each update call.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
- ClearBufs (input)
A pointer to a vector of CSSM_DATA structures that contain the data to be operated on.
- ClearBufCount (input)
The number of ClearBufs.
- CipherBufs (output)
A pointer to a vector of CSSM_DATA structures that contain the encrypted data resulting from the encryption operation.
- CipherBufCount (input)
The number of CipherBufs.
- bytesEncrypted (output)
A pointer to uint32 for the size of the encrypted data in bytes.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
The output is returned to the caller either by filling the caller-specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, pre-allocated output buffer, the caller must provide an array of one or more CSSM_DATA structures each one containing a Length field value greater than zero and a non-NULL Data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures each containing a Length field value equal to zero and a NULL Data pointer field value. The application is always responsible for de-allocating the memory when it is no longer needed. If the CSSM_DATA_PTR parameter is NULL (that is, does not point to an array of CSSM_DATA structures) or the number of CSSM_DATA structures is specified as zero, the error code CSSM_CSP_INVALID_DATA_POINTER is returned. In-place encryption can be done by supplying the same input and output buffers.
CSSM_QuerySize()
CSSM_DecryptData()
CSSM_EncryptDataInit()
CSSM_EncryptDataUpdate()
CSSM_EncryptDataFinal()
CSSM_EncryptDataP()
CSSM_EncryptDataInitP()
CSSM_DecryptP()
CSSM_DecryptDataInitP()
CSSM_EncryptDataFinal
CSSM_RETURN CSSMAPI CSSM_EncryptDataFinal (CSSM_CC_HANDLE CCHandle, CSSM_DATA_PTR RemData)
This function finalizes the staged encryption process by returning any remaining cipher text not returned in the previous staged encryption call. The cipher text is returned in a single buffer.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
- RemData (output)
A pointer to the CSSM_DATA structure for the last encrypted block containing padded data if necessary.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CSP_BLOCK_SIZE_MISMATCH
CSSMERR_CSP_OUTPUT_LENGTH_ERROR
The output is returned to the caller either by filling the caller-specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, pre-allocated output buffer, the caller must provide an array of one or more CSSM_DATA structures each one containing a Length field value greater than zero and a non-NULL Data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures each containing a Length field value equal to zero and a NULL Data pointer field value. The application is always responsible for de-allocating the memory when it is no longer needed. If the CSSM_DATA_PTR parameter is NULL (that is, does not point to an array of CSSM_DATA structures) or the number of CSSM_DATA structures is specified as zero, the error code CSSM_CSP_INVALID_DATA_POINTER is returned. In-place encryption can be done by supplying the same input and output buffers.
CSSM_QuerySize()
CSSM_DecryptData()
CSSM_EncryptDataInit()
CSSM_EncryptDataUpdate()
CSSM_EncryptDataFinal()
CSSM_EncryptDataP()
CSSM_EncryptDataInitP()
CSSM_DecryptP()
CSSM_DecryptDataInitP()
CSSM_DecryptData
CSSM_RETURN CSSMAPI CSSM_DecryptData (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *CipherBufs, uint32 CipherBufCount, CSSM_DATA_PTR ClearBufs, uint32 ClearBufCount, uint32 *bytesDecrypted, CSSM_DATA_PTR RemData)
This function decrypts all data contained in the set of input buffers using information in the context. TheCSSM_QuerySize() function can be used to estimate the output buffer size required. The minimum number of buffers required to contain the resulting plain text is produced as output. If the plain text result does not fit within the set of output buffers, the remaining plain text is returned in the single output buffer RemData.The CSP can require that the cryptographic context include access credentials for authentication and authorization checks when using a private key or a secret key.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
- CipherBufs (input)
A pointer to a vector of CSSM_DATA structures that contain the data to be operated on.
- CipherBufCount (input)
The number of CipherBufs.
- ClearBufs (output)
A pointer to a vector of CSSM_DATA structures that contain the decrypted data resulting from the decryption operation.
- ClearBufCount (input)
The number of ClearBufs.
- BytesDecrypted (output)
A pointer to uint32 for the size of the decrypted data in bytes.
- RemData (output)
A pointer to the CSSM_DATA structure for the remaining plain text if there is not enough buffer space available in the output data structures.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CSP_BLOCK_SIZE_MISMATCH
CSSMERR_CSP_OUTPUT_LENGTH_ERROR
The output is returned to the caller either by filling the caller-specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, pre-allocated output buffer, the caller must provide an array of one or more CSSM_DATA structures each one containing a Length field value greater than zero and a non-NULL Data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures each containing a Length field value equal to zero and a NULL Data pointer field value. The application is always responsible for de-allocating the memory when it is no longer needed. If the CSSM_DATA_PTR parameter is NULL (that is, does not point to an array of CSSM_DATA structures) or the number of CSSM_DATA structures is specified as zero, the error code
CSSM_QuerySize()
CSSM_EncryptData()
CSSM_DecryptDataInit()
CSSM_DecryptDataUpdate()
CSSM_DecryptDataFinal()
CSSM_DecryptP()
CSSM_DecryptDataInitP()
CSSM_DecryptDataP
CSSM_RETURN CSSMAPI CSSM_DecryptDataP (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *CipherBufs, uint32 CipherBufCount, CSSM_DATA_PTR ClearBufs, uint32 ClearBufCount, uint32 *bytesDecrypted, CSSM_DATA_PTR RemData, CSSM_PRIVILEGE Privilege)
This function similar toCSSM_DecryptData() . It also accepts a USEE tag as a privilege request parameter. CSSM checks that either its own privilege set or the Application's privilege set (if the Application is signed) includes the tag. If the tag is found, and the service provider privilege set indicates that it is supported, the tag is forwarded to the service provider.
SeeCSSM_DecryptData() .
- Privilege (input)
The privilege to be applied during the cryptographic operation.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CSP_BLOCK_SIZE_MISMATCH
CSSMERR_CSP_OUTPUT_LENGTH_ERROR
CSSM_QuerySize()
CSSM_DecryptData()
CSSM_EncryptDataInit()
CSSM_EncryptDataUpdate()
CSSM_EncryptDataFinal()
CSSM_EncryptDataP()
CSSM_EncryptDataInitP()
CSSM_DecryptP()
CSSM_DecryptDataInitP()
CSSM_DecryptDataInit
CSSM_RETURN CSSMAPI CSSM_DecryptDataInit (CSSM_CC_HANDLE CCHandle)
This function initializes the staged decrypt function.The CSP can require that the cryptographic context include access credentials for authentication and authorization checks when using a private key or a secret key.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_DecryptData()
CSSM_DecryptDataUpdate()
CSSM_DecryptDataFinal()
CSSM_DecryptP()
CSSM_DecryptDataInitP()
CSSM_DecryptDataInitP
CSSM_RETURN CSSMAPI CSSM_DecryptDataInitP (CSSM_CC_HANDLE CCHandle, CSSM_PRIVILEGE Privilege)
This function is similar toCSSM_DecryptDataInit() . It also accepts a USEE tag as a privilege request parameter. CSSM checks that either its own privilege set or the Application's privilege set (if the Application is signed) includes the tag. If the tag is found, and the service provider privilege set indicates that it is supported, the tag is forwarded to the service provider.For staged operations using privilege initialization functions
CSSM_DecryptDataInitP() , the completion functionsCSSM_DecryptDataUpdate() andCSSM_DecryptDataFinalize() are used.
SeeCSSM_DecryptDataInit() .
- Privilege (input)
The privilege to be applied during the cryptographic operation.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_QuerySize()
CSSM_DecryptData()
CSSM_EncryptDataInit()
CSSM_EncryptDataUpdate()
CSSM_EncryptDataFinal()
CSSM_EncryptDataP()
CSSM_EncryptDataInitP()
CSSM_DecryptP()
CSSM_DecryptDataInitP()
CSSM_DecryptDataUpdate
CSSM_RETURN CSSMAPI CSSM_DecryptDataUpdate (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *CipherBufs, uint32 CipherBufCount, CSSM_DATA_PTR ClearBufs, uint32 ClearBufCount, uint32 *bytesDecrypted)
This function continues the staged decryption process over all data in the set of input buffers. There can be algorithm-specific and token-specific rules restricting the lengths of data inCSSM_DecryptUpdate() calls, but multiple input buffers are supported. The minimum number of buffers required to contain the resulting plain text is produced as output. Excess output buffer space is not remembered across staged decryption calls. Each staged call begins filling one or more new output buffers. TheCSSM_QuerySize() function can be used to estimate the output buffer size required for each update call.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
- CipherBufs (input)
A pointer to a vector of CSSM_DATA structures that contain the data to be operated on.
- CipherBufCount (input)
The number of CipherBufs.
- ClearBufs (output)
A pointer to a vector of CSSM_DATA structures that contain the decrypted data resulting from the decryption operation.
- ClearBufCount (input)
The number of ClearBufs.
- bytesDecrypted (output)
A pointer to uint32 for the size of the decrypted data in bytes.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
The output is returned to the caller either by filling the caller-specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, pre-allocated output buffer, the caller must provide an array of one or more CSSM_DATA structures each one containing a Length field value greater than zero and a non-NULL Data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures each containing a Length field value equal to zero and a NULL Data pointer field value. The application is always responsible for de-allocating the memory when it is no longer needed. If the CSSM_DATA_PTR parameter is NULL (that is, does not point to an array of CSSM_DATA structures) or the number of CSSM_DATA structures is specified as zero, the error code CSSM_CSP_INVALID_DATA_POINTER is returned. In-place decryption can be done by supplying the same input and output buffers.
CSSM_DecryptData()
CSSM_DecryptDataInit()
CSSM_DecryptDataFinal()
CSSM_QuerySize()
CSSM_DecryptDataFinal
CSSM_RETURN CSSMAPI CSSM_DecryptDataFinal (CSSM_CC_HANDLE CCHandle, CSSM_DATA_PTR RemData)
This function finalizes the staged decryption process by returning any remaining plain text not returned in the previous staged decryption call. The plain text is returned in a single buffer.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
- RemData (output)
A pointer to the CSSM_DATA structure for the last decrypted block, if necessary.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CSP_BLOCK_SIZE_MISMATCH
CSSMERR_CSP_OUTPUT_LENGTH_ERROR
The output is returned to the caller either by filling the caller-specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, pre-allocated output buffer, the caller must provide an array of one or more CSSM_DATA structures each one containing a Length field value greater than zero and a non-NULL Data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures each containing a Length field value equal to zero and a NULL Data pointer field value. The application is always responsible for de-allocating the memory when it is no longer needed. If the CSSM_DATA_PTR parameter is NULL (that is, does not point to an array of CSSM_DATA structures) or the number of CSSM_DATA structures is specified as zero, the error code CSSM_CSP_INVALID_DATA_POINTER is returned. In-place decryption can be done by supplying the same input and output buffers.
CSSM_DecryptData()
CSSM_DecryptDataInit()
CSSM_DecryptDataUpdate()
CSSM_QueryKeySizeInBits
CSSM_RETURN CSSMAPI CSSM_QueryKeySizeInBits (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_KEY *Key, CSSM_KEY_SIZE_PTR KeySize)
This function queries a Cryptographic Service Provider (CSP) for the logical and effective sizes of a specified key.The cryptographic service provider (handle) and the key can be specified either in the cryptographic context or as parameters to the function call. If a valid cryptographic context handle parameter is specified, the CSP handle and key parameters are ignored.
- CSPHandle (input/optional)
The handle that describes the cryptographic service provider module used to perform this function. This parameter is ignored if a valid cryptographic context handle is specified.
- CCHandle (input/optional)
A handle to a context that describes a cryptographic operation. The cryptographic context should contain a handle to the CSP that is being queried and the key about which key-size information is being requested.
- Key (input/optional)
A pointer to a CSSM_KEY structure containing the key about which key-size information is being requested. This parameter is ignored if a valid cryptographic context handle is specified.
- KeySize (output)
Pointer to a CSSM_KEY_SIZE data structure. The logical and effective sizes (in bits) for the key are returned in this structure. If no context handle is provided, only the CSSM_KEY_SIZE LogicalKeySizeInBits field is set.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.CSSMERR_CSP_QUERY_SIZE_UNKNOWN
CSSM_GenerateRandom()
CSSM_GenerateKeyPair()
CSSM_GenerateKey()
CSSM_GenerateKey
CSSM_RETURN CSSMAPI CSSM_GenerateKey (CSSM_CC_HANDLE CCHandle, uint32 KeyUsage, uint32 KeyAttr, const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, CSSM_KEY_PTR Key)
This function generates a symmetric key. The KeyUsage, and KeyAttr are used to initialize the keyheader for the newly created key. These values are not retained in the cryptographic Context, which contains additional parameters for this operation. The CSP may cache keying material associated with the new symmetric key. When the symmetric key is no longer in active use, the application can invoke theCSSM_FreeKey() interface to allow cached keying material associated with the symmetric key to be removed.Authorization policy can restrict the set of callers who can create a new resource. In this case, the caller must present a set of access credentials for authorization. Upon successfully authenticating the credentials, the template that verified the presented samples identifies the ACL entry that will be used in the authorization computation. If the caller is authorized, the new resource is created.
The caller must provide an initial ACL entry to be associated with the newly created resource. This entry is used to control future access to the new resource and (since the subject is deemed to be the "Owner") exercise control over its associated ACL. The caller can specify the following items for initializing an ACL entry:
- Subject - A CSSM_LIST structure, containing the type of the subject and a template value that can be used to verify samples that are presented in credentials when resource access is requested.
- Delegation flag - A value indicating whether the Subject can delegate the permissions recorded in the AuthorizationTag. (This item only applies to public key subjects).
- Authorization tag - The set of permissions that are granted to the Subject.
- Validity period - The start time and the stop time for which the ACL entry is valid.
- ACL entry tag - A user-defined string value associated with the ACL entry.
The service provider can modify the caller-provided initial ACL entry to conform to any innate resource-access policy that the service provider may be required to enforce. If the initial ACL entry provided by the caller contains values or permissions that are not supported by the service provider, then the service provider can modify the initial ACL appropriately or can fail the request to create the new resource. Service providers list their supported AuthorizationTag values in their Module Directory Services primary record.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
- KeyUsage (input)
A bit mask indicating all permitted uses for the new key.
- KeyAttr (input)
A bit mask defining attribute values for the new key.
- CredAndAclEntry (input/optional)
A structure containing one or more credentials authorized for creating a key and the prototype ACL entry that will control future use of the newly created key. The credentials and ACL entry prototype can be presented as immediate values or callback functions can be provided for use by the CSP to acquire the credentials and/or the ACL entry interactively. If the CSP provides public access for creating a key, then the credentials can be NULL. If the CSP defines a default initial ACL entry for the new key, then the ACL entry prototype can be an empty list.
- Key (output)
Pointer to CSSM_KEY structure used to hold the new key. The CSSM_KEY structure should be empty upon input to this function. The CSP will ignore any values residing in this structure at function invocation. Input values should be supplied in the cryptographic context, KeyUsage, KeyAttr, and KeyLabel input parameters.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS
The KeyData field of the CSSM_KEY structure is allocated by the CSP. The application is required to free this memory using the
CSSM_FreeKey() call, or with the memory functions registered for the CSPHandle.
CSSM_GenerateRandom()
CSSM_GenerateKeyPair()
CSSM_GenerateKeyP
CSSM_RETURN CSSMAPI CSSM_GenerateKeyP (CSSM_CC_HANDLE CCHandle, uint32 KeyUsage, uint32 KeyAttr, const CSSM_DATA *KeyLabel, const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, CSSM_KEY_PTR Key, CSSM_PRIVILEGE Privilege)
This function is similar toCSSM_GenerateKey() . It also accepts a USEE tag as a privilege request parameter. CSSM checks that either its own privilege set or the Application's privilege set (if the Application is signed) includes the tag. If the tag is found, and the service provider privilege set indicates that it is supported, the tag is forwarded to the service provider.
SeeCSSM_GenerateKey() .
- Privilege (input)
The privilege to be applied during the cryptographic operation.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
SeeCSSM_GenerateKey() .
CSSM_GenerateRandom()
CSSM_GenerateKeyPairP()
CSSM_GenerateKeyPair
CSSM_RETURN CSSMAPI CSSM_GenerateKeyPair (CSSM_CC_HANDLE CCHandle, uint32 PublicKeyUsage, uint32 PublicKeyAttr, const CSSM_DATA *PublicKeyLabel, CSSM_KEY_PTR PublicKey, uint32 PrivateKeyUsage, uint32 PrivateKeyAttr, const CSSM_DATA *PrivateKeyLabel, const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, CSSM_KEY_PTR PrivateKey)
This function generates an asymmetric key pair. The CSP may cache keying material associated with the new asymmetric keypair. When one or both of the keys are no longer in active use, the application can invoke the CSSM_FreeKey interface to allow cached keying material associated with the key to be removed.Authorization policy can restrict the set of callers who can create a new resource. In this case, the caller must present a set of access credentials for authorization. Upon successfully authenticating the credentials, the template that verified the presented samples identifies the ACL entry that will be used in the authorization computation. If the caller is authorized, the new resource is created.
The caller must provide an initial ACL entry to be associated with the newly created resource. This entry is used to control future access to the new resource and (since the subject is deemed to be the "Owner") exercise control over its associated ACL. The caller can specify the following items for initializing an ACL entry:
- Subject - A CSSM_LIST structure, containing the type of the subject and a template value that can be used to verify samples that are presented in credentials when resource access is requested.
- Delegation flag - A value indicating whether the Subject can delegate the permissions recorded in the AuthorizationTag. (This item only applies to public key subjects).
- Authorization tag - The set of permissions that are granted to the Subject.
- Validity period - The start time and the stop time for which the ACL entry is valid.
- ACL entry tag - A user-defined string value associated with the ACL entry.
The service provider can modify the caller-provided initial ACL entry to conform to any innate resource-access policy that the service provider may be required to enforce. If the initial ACL entry provided by the caller contains values or permissions that are not supported by the service provider, then the service provider can modify the initial ACL appropriately or can fail the request to create the new resource. Service providers list their supported AuthorizationTag values in their Module Directory Services primary record.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
- PublicKeyUsage (input)
A bit mask indicating all permitted uses for the new public key.
- PublicKeyAttr (input)
A bit mask defining attribute values for the new public key.
- PublicKeyLabel (input/optional)
A key label value to be associated with the new public key.
- PublicKey (output)
Pointer to CSSM_KEY structure used to hold the new public key. The CSSM_KEY structure should be empty upon input to this function. The CSP will ignore any values residing in this structure at function invocation. Input values should be supplied in the cryptographic context, PublicKeyUsage, PublicKeyAttr, and PublicKeyLabel input parameters.
- PrivateKeyUsage (input)
A bit mask indicating all permitted uses for the new private key.
- PrivateKeyAttr (input)
A bit mask defining attribute values for the new private key.
- PrivateKeyLabel (input/optional)
A key label value to be associated with the new private key.
CSSM_GenerateKeyPairP
CSSM_RETURN CSSMAPI CSSM_GenerateKeyPairP (CSSM_CC_HANDLE CCHandle, uint32 PublicKeyUsage, uint32 PublicKeyAttr, const CSSM_DATA *PublicKeyLabel, CSSM_KEY_PTR PublicKey, uint32 PrivateKeyUsage, uint32 PrivateKeyAttr, const CSSM_DATA *PrivateKeyLabel, const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, CSSM_KEY_PTR PrivateKey, CSSM_PRIVILEGE Privilege)
This function is similar toCSSM_GenerateKeyPair() . It also accepts a USEE tag as a privilege request parameter. CSSM checks that either its own privilege set or the Application's privilege set (if the Application is signed) includes the tag. If the tag is found, and the service provider privilege set indicates that it is supported, the tag is forwarded to the service provider.
SeeCSSM_GenerateKeyPair() .
- Privilege (input)
The privilege to be applied during the cryptographic operation.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS
SeeCSSM_GenerateKeyPair() .
CSSM_GenerateRandom()
CSSM_GenerateKeyP()
CSSM_GenerateRandom
CSSM_RETURN CSSMAPI CSSM_GenerateRandom (CSSM_CC_HANDLE CCHandle, CSSM_DATA_PTR RandomNumber)
This function generates random data.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
- RandomNumber (output)
Pointer to CSSM_DATA structure used to obtain the random number and the size of the random number in bytes.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
The output is returned to the caller either by filling the caller-specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, pre-allocated output buffer, the caller must provide an array of one or more CSSM_DATA structures each one containing a Length field value greater than zero and a non-NULL Data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures each containing a Length field value equal to zero and a NULL Data pointer field value. The application is always responsible for de-allocating the memory when it is no longer needed. If the CSSM_DATA_PTR parameter is NULL (that is, does not point to an array of CSSM_DATA structures) or the number of CSSM_DATA structures is specified as zero, the error code CSSM_CSP_INVALID_DATA_POINTER is returned.
CSSM_CSP_ObtainPrivateKeyFromPublicKey
CSSM_RETURN CSSMAPI CSSM_CSP_ObtainPrivateKeyFromPublicKey (CSSM_CSP_HANDLE CSPHandle, const CSSM_KEY *PublicKey, CSSM_KEY_PTR PrivateKey)
Given a public key this function returns a reference to the private key. The private key and its associated passphrase can be used as an input to any function requiring a private key value.
- CSPHandle (input)
The handle that describes the module to perform this operation.
- PublicKey (input)
The public key corresponding to the private key being sought.
- PrivateKey (output)
A reference to the private key corresponding to the public key.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.CSSMERR_CSP_PRIVATE_KEY_NOT_FOUND
CSSM_WrapKey
CSSM_RETURN CSSMAPI CSSM_WrapKey (CSSM_CC_HANDLE CCHandle, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_KEY *Key, const CSSM_DATA *DescriptiveData, CSSM_WRAP_KEY_PTR WrappedKey)
This function wraps the supplied key using the context. It allows a key to be exported from a CSP. Four types of wrapping exist:
- Wrap a symmetric key with a symmetric key.
- Wrap a symmetric key with an asymmetric public key.
- Wrap an asymmetric private key with a symmetric key.
- Wrap an asymmetric private key with an asymmetric public key.
For types 1 and 3, a symmetric context should be provided. For types 2 and 4, an asymmetric context is provided. If there is a CSSM_ATTRIBUTE_WRAPPED_KEY_FORMAT argument in the context represented by the CCHandle, the value of the attribute specifies the format of the wrapped key. If this argument is not present, the symmetric key is wrapped according to CMS for types 1 and 3, and according to PKCS8 for types 2 and 4. If the wrapping algorithm in the context is CSSM_ALGID_NONE, then the key is returned in raw format, if permitted and supported by the CSP (in this case the CSSM_ATTRIBUTE_WRAPPED_KEY_FORMAT attribute is ignored). All significant key attributes are incorporated into the KeyHeader of the returned WrappedKey, such that the state of the key can be fully restored by the unwrap process.
The CSP can require that the cryptographic context includes access credentials for authentication and authorization checks when using the secret or private key.
- CCHandle (input)
The handle to the context that describes this cryptographic operation.
- AccessCred (input)
A pointer to the set of one or more credentials required to access the private or secret key to be exported from the CSP. The credentials structure can contain an immediate value for the credential, such as a passphrase, or the caller can specify a callback function the CSP can use to obtain one or more credentials.
- Key (input)
A pointer to the key to be wrapped.
- DescriptiveData (input/optional)
A pointer to a CSSM_DATA structure containing additional descriptive data to be associated and included with the key during the wrapping operation. The caller and the wrapping algorithm incorporate knowledge of the structure of the descriptive data. If the wrapping algorithm does not accept additional descriptive data, then this parameter must be NULL. If the wrapping algorithm accepts descriptive data, the corresponding unwrapping algorithm can be used to extract the descriptive data and the key.
- WrappedKey (output)
A pointer to a CSSM_WRAP_KEY structure that returns the wrapped key.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
The KeyData field of the CSSM_KEY structure is allocated by the CSP. The application is required to free this memory using theCSSM_FreeKey() call.
CSSM_UnwrapKey()
CSSM_UnwrapKey
CSSM_RETURN CSSMAPI CSSM_UnwrapKey (CSSM_CC_HANDLE CCHandle, const CSSM_KEY *PublicKey, const CSSM_WRAP_KEY *WrappedKey, uint32 KeyUsage, uint32 KeyAttr, const CSSM_DATA *KeyLabel, const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, CSSM_KEY_PTR UnwrappedKey, CSSM_DATA_PTR DescriptiveData)
This function unwraps the wrapped key using the context. The wrapped key can be a symmetric key or a private key. If the unwrapping algorithm is a symmetric algorithm, then a symmetric context must be provided. If the unwrapping algorithm is an asymmetric algorithm, then an asymmetric context must be provided. If the key is a private key, then an asymmetric context must be provide describing the unwrapping algorithm. The CSP can require the caller to provide credentials authorizing the caller to store the unwrapped key within the CSP. The CSP can also require that the caller provide an initial ACL entry to control future access to the newly stored key. These credentials and the initial ACL entry value are provided in CredAndAclEntry parameter. If the unwrapping algorithm is CSSM_ALGID_NONE and the wrapped key is actually a raw key (as indicated by its key attributes), then the key is imported into the CSP. Support for a CSSM_ALGID_NONE unwrapping algorithm is at the option of the CSP. The unwrapped key is restored to its original pre-wrap state based on the key attributes recorded by the wrapped key during the wrap operation. These attributes must not be modified by the caller.Authorization policy can restrict the set of callers who can create a new resource. In this case, the caller must present a set of access credentials for authorization. Upon successfully authenticating the credentials, the template that verified the presented samples identifies the ACL entry that will be used in the authorization computation. If the caller is authorized, the new resource is created.
The caller must provide an initial ACL entry to be associated with the newly created resource. This entry is used to control future access to the new resource and (since the subject is deemed to be the "Owner") exercise control over its associated ACL. The caller can specify the following items for initializing an ACL entry:
- Subject - A CSSM_LIST structure, containing the type of the subject and a template value that can be used to verify samples that are presented in credentials when resource access is requested.
- Delegation flag - A value indicating whether the Subject can delegate the permissions recorded in the AuthorizationTag. (This item only applies to public key subjects).
- Authorization tag - The set of permissions that are granted to the Subject.
- Validity period - The start time and the stop time for which the ACL entry is valid.
- ACL entry tag - A user-defined string value associated with the ACL entry.
The service provider can modify the caller-provided initial ACL entry to conform to any innate resource-access policy that the service provider may be required to enforce. If the initial ACL entry provided by the caller contains values or permissions that are not supported by the service provider, then the service provider can modify the initial ACL appropriately or can fail the request to create the new resource. Service providers list their supported AuthorizationTag values in their Module Directory Services primary record.
- CCHandle (input)
The handle that describes the context of this cryptographic operation.
- PublicKey (input/optional)
The public key corresponding to the private key being unwrapped. If a symmetric key is being unwrapped, then this parameter must be NULL.
- WrappedKey (input)
A pointer to the wrapped key. The wrapped key may be a symmetric key or the private key of a public/private key pair. The unwrapping method is specified as meta data within the wrapped key and is not specified outside of the wrapped key.
- KeyUsage (input)
A bit mask indicating all permitted uses for the imported key. If no value is specified, the CSP defines the usage mask for the imported key.
- KeyAttr (input)
A bit mask defining attribute values to be associated with the unwrapped key.
- KeyLabel (input/optional)
Pointer to a byte string that will be used as the label for the unwrapped key.
- CredAndAclEntry (input/optional)
A structure containing one or more credentials authorized for creating a key and the prototype ACL entry that will control future use of the newly created key. The credentials and ACL entry prototype can be presented as immediate values or callback functions can be provided for use by the CSP to acquire the credentials and/or the ACL entry interactively. If the CSP provides public access for creating a key, then the credentials can be NULL. If the CSP defines a default initial ACL entry for the new key, then the ACL entry prototype can be an empty list.
- UnwrappedKey (output)
A pointer to a CSSM_KEY structure that returns the unwrapped key.
- DescriptiveData (output)
A pointer to a CSSM_DATA structure that returns any additional descriptive data that was associated with the key during the wrapping operation. It is assumed that the caller incorporated knowledge of the structure of this data. If no additional data is associated with the imported key, this output value is NULL.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS
CSSMERR_CSP_PUBLIC_KEY_INCONSISTENT
CSSMERR_CSP_PRIVATE_KEY_ALREADY_EXIST
The KeyData field of the CSSM_KEY structure is allocated by the CSP. The application is required to free this memory using the
CSSM_FreeKey() call, or with the memory functions registered for the CSPHandle.
CSSM_WrapKey()
CSSM_WrapKeyP
CSSM_RETURN CSSMAPI CSSM_WrapKeyP (CSSM_CC_HANDLE CCHandle, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_KEY *Key, const CSSM_DATA *DescriptiveData, CSSM_WRAP_KEY_PTR WrappedKey, CSSM_PRIVILEGE Privilege)
This function is similar toCSSM_WrapKey() . It also accepts a USEE tag as a privilege request parameter. CSSM checks that either its own privilege set or the Application's privilege set (if the Application is signed) includes the tag. If the tag is found, and the service provider privilege set indicates that it is supported, the tag is forwarded to the service provider.
SeeCSSM_WrapKey() .
- Privilege (input)
The privilege to be applied during the cryptographic operation.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
SeeCSSM_WrapKey() .
The KeyData field of the CSSM_KEY structure is allocated by the CSP. The application is required to free this memory using theCSSM_FreeKey() call, or with the memory functions registered for the CSPHandle.
CSSM_UnwrapKeyP
CSSM_RETURN CSSMAPI CSSM_UnwrapKeyP (CSSM_CC_HANDLE CCHandle, const CSSM_KEY *PublicKey, const CSSM_WRAP_KEY *WrappedKey, uint32 KeyUsage, uint32 KeyAttr, const CSSM_DATA *KeyLabel, const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, CSSM_KEY_PTR UnwrappedKey, CSSM_DATA_PTR DescriptiveData, CSSM_PRIVILEGE Privilege)
This function is similar toCSSM_UnwrapKey() . It also accepts a USEE tag as a privilege request parameter. CSSM checks that either its own privilege set or the Application's privilege set (if the Application is signed) includes the tag. If the tag is found, and the service provider privilege set indicates that it is supported, the tag is forwarded to the service provider.
SeeCSSM_UnwrapKey() .
- Privilege (input)
The privilege to be applied during the cryptographic operation.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.
CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS
CSSMERR_CSP_PUBLIC_KEY_INCONSISTENT
CSSMERR_CSP_PRIVATE_KEY_ALREADY_EXIST
The KeyData field of the CSSM_KEY structure is allocated by the CSP. The application is required to free this memory using theCSSM_FreeKey() call, or with the memory functions registered for the CSPHandle.
CSSM_DeriveKey
CSSM_RETURN CSSMAPI CSSM_DeriveKey (CSSM_CC_HANDLE CCHandle, CSSM_DATA_PTR Param, uint32 KeyUsage, uint32 KeyAttr, const CSSM_DATA *KeyLabel, const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, CSSM_KEY_PTR DerivedKey)
This function derives a new symmetric key using the context and/or information from the base key in the context. The CSP can require that the cryptographic context include access credentials for authentication and authorization checks when using a private key or a secret key.Authorization policy can restrict the set of callers who can create a new resource. In this case, the caller must present a set of access credentials for authorization. Upon successfully authenticating the credentials, the template that verified the presented samples identifies the ACL entry that will be used in the authorization computation. If the caller is authorized, the new resource is created.
The caller must provide an initial ACL entry to be associated with the newly created resource. This entry is used to control future access to the new resource and (since the subject is deemed to be the "Owner") exercise control over its associated ACL. The caller can specify the following items for initializing an ACL entry:
- Subject - A CSSM_LIST structure, containing the type of the subject and a template value that can be used to verify samples that are presented in credentials when resource access is requested.
- Delegation flag - A value indicating whether the Subject can delegate the permissions recorded in the AuthorizationTag. (This item only applies to public key subjects).
- Authorization tag - The set of permissions that are granted to the Subject.
- Validity period - The start time and the stop time for which the ACL entry is valid.
- ACL entry tag - A user-defined string value associated with the ACL entry.
The service provider can modify the caller-provided initial ACL entry to conform to any innate resource-access policy that the service provider may be required to enforce. If the initial ACL entry provided by the caller contains values or permissions that are not supported by the service provider, then the service provider can modify the initial ACL appropriately or can fail the request to create the new resource. Service providers list their supported AuthorizationTag values in their Module Directory Services primary record.
- CCHandle (input)
The handle that describes the context of this cryptographic operation.
- Param (input/output)
This parameter varies depending on the derivation algorithm.
- KeyUsage (input)
A bit mask indicating all permitted uses for the new derived key.
- KeyAttr (input)
A bit mask defining attribute values for the new derived key.
- KeyLabel (input/optional)
Pointer to a byte string that will be used as the label for the derived key.
- CredAndAclEntry (input/optional)
A structure containing one or more credentials authorized for creating a key and the prototype ACL entry that will control future use of the newly created key. The credentials and ACL entry prototype can be presented as immediate values or callback functions can be provided for use by the CSP to acquire the credentials and/or the subject of the ACL entry interactively. If the CSP provides public access for creating a key, then the credentials can be NULL. If the CSP defines a default initial ACL entry for the new key, then the ACL entry prototype can be empty.
- DerivedKey (output)
A pointer to a CSSM_KEY structure that returns the derived key.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS
The KeyData field of the CSSM_KEY structure is allocated by the CSP. The application is required to free this memory using theCSSM_FreeKey() call, or with the memory functions registered for the CSPHandle.
CSSM_CSP_CreateDeriveKeyContext()
CSSM_FreeKey
CSSM_RETURN CSSMAPI CSSM_FreeKey (CSSM_CSP_HANDLE CSPHandle, const CSSM_ACCESS_CREDENTIALS *AccessCred, CSSM_KEY_PTR KeyPtr, CSSM_BOOL Delete)
This function requests the cryptographic service provider to clean up any key material associated with the key, and to possibly delete the key from the CSP completely. This function also releases the internal storage referenced by the KeyData field of the key structure, which can hold the actual key value. The key reference by KeyPtr can be a persistent key or a transient key. This function clears the cached copy of the key and can have an effect on the long term persistence or transience of the key.
- CSPHandle (input)
The handle that describes the module to perform this operation.
- AccessCred (input/optional)
If the target key referenced by KeyPtr is protected and Delete has the value CSSM_TRUE, this parameter must contain the certificates and samples required to access the target key. The certificates must be presented as immediate values in the input structure. The samples can be immediate values, be obtained through a protected mechanism, or be obtained through a callback function.
- KeyPtr (input)
The key whose associated keying material can be discarded at this time.
- Delete (input)
If this value is CSSM_TRUE, the key data in the key structure will be removed and any internal storage related to that key will also be removed. In this case the key no longer exists in any form, unless previously wrapped out of the CSP by the application. If this value is CSSM_FALSE, then only the resources related to the key structure are released. The key may still be accessible by other means internally to the CSP.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_GenerateAlgorithmParams
CSSM_RETURN CSSMAPI CSSM_GenerateAlgorithmParams (CSSM_CC_HANDLE CCHandle, uint32 ParamBits, CSSM_DATA_PTR Param)
This function generates algorithm parameters for the specified context. These parameters include Diffie-Hellman key agreement parameters and DSA key generation parameters. In most cases the algorithm parameters will be added directly to the cryptographic context, but an algorithm may return some data to the caller via the Param value. The generated parameters are added to the context as an attribute of type CSSM_ATTRIBUTE_ALG_PARAMS.
- CCHandle (input)
The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.
- ParamBits (input)
Used to generate parameters for the algorithm (for example, Diffie-Hellman).
- Param (output)
Pointer to a CSSM_DATA structure used to provide information to the parameter generation process, or to receive information resulting from the generation process that is not required as a parameter to the algorithm. For instance, phase 2 of the KEA algorithm requires a private random value, rA, and a public version, Ra, to be generated. The private value, rA, is added to the context and the public value, Ra, is returned to the caller. In some cases, when both input and output is required, a data structure is passed to the algorithm. In this situation, Param->Data references the structure and Param->Length is set to the length of the structure.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
The output is returned to the caller either by filling the caller-specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, pre-allocated output buffer, the caller must provide an array of one or more CSSM_DATA structures each one containing a Length field value greater than zero and a non-NULL Data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures each containing a Length field value equal to zero and a NULL Data pointer field value. The application is always responsible for de-allocating the memory when it is no longer needed. If the CSSM_DATA_PTR parameter is NULL (that is, does not point to an array of CSSM_DATA structures) or the number of CSSM_DATA structures is specified as zero, the error code CSSM_CSP_INVALID_DATA_POINTER is returned
CSSM_CSP_GetOperationalStatistics
CSSM_RETURN CSSMAPI CSSM_CSP_GetOperationalStatistics (CSSM_CSP_HANDLE CSPHandle, CSSM_CSP_OPERATIONAL_STATISTICS *Statistics)
Obtain the current operational values of a subservice. The information is returned in a structure of type CSSM_CSP_OPERATIONAL_STATISTICS. This information includes login status and available storage space. The data structure to hold the returned results must be provided by the caller. The CSP does not allocate memory on behalf of the caller.
- CSPHandle (input)
Handle of the cryptographic service provider that will perform the operation.
- Statistics (output)
Structure containing the subservice's current statistics.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_GetTimeValue
CSSM_RETURN CSSMAPI CSSM_GetTimeValue (CSSM_CSP_HANDLE CSPHandle, CSSM_ALGORITHMS TimeAlgorithm, CSSM_DATA *TimeData)
This function returns a time value maintained by a CSP. This feature will be supported primarily by hardware tokens with an onboard real time clock.
- CSPHandle (input)
Handle of the cryptographic service provider that will perform the operation.
- TimeAlgorithm (input)
A CSSM algorithm type that indicates the method for fetching the time. The following algorithm types are currently supported:
- CSSM_ALGID_UTC
Returns a time value in the form YYYYMMDDhhmmss (4 characters for the year; 2 characters each for the month, the day, the hour, the minute, and the second). The time returned is GMT.
- CSSM_ALGID_RUNNING_COUNTER
The current value of a running hardware counter that operates while the device is in operation. This value can be read from a processor counter provided by some platform architectures.
- TimeData (output)
The time value of counter value returned in response to the request.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
- The output is returned to the caller either by filling the caller-specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, pre-allocated output buffer, the caller must provide an array of one or more CSSM_DATA structures each one containing a Length field value greater than zero and a non-NULL Data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures each containing a Length field value equal to zero and a NULL Data pointer field value. The application is always responsible for de-allocating the memory when it is no longer needed. If the CSSM_DATA_PTR parameter is NULL (i.e., does not point to an array of CSSM_DATA structures) or the number of CSSM_DATA structures is specified as zero, the error code CSSM_CSP_INVALID_DATA_POINTER is returned.
- Some tokens require authentication before returning a time value.
CSSM_RetrieveUniqueId
CSSM_RETURN CSSMAPI CSSM_RetrieveUniqueId (CSSM_CSP_HANDLE CSPHandle, CSSM_DATA_PTR UniqueID)
This function returns an identifier that could be used to uniquely differentiate the cryptographic device from all other devices from the same vendor or different vendors.
- CSPHandle (input)
The handle that describes the add-in cryptographic service provider module used to perform this function. If a NULL handle is specified, CSSM returns error.
- UniqueID (output)
Pointer to CSSM_DATA structure that contains data that uniquely identifies the cryptographic device.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_RetrieveCounter
CSSM_RETURN CSSMAPI CSSM_RetrieveCounter (CSSM_CSP_HANDLE CSPHandle, CSSM_DATA_PTR Counter)
This function returns the value of a tamper resistant clock/counter of the cryptographic device.
- CSPHandle (input)
The handle that describes the add-in cryptographic service provider module used to perform this function. If a NULL handle is specified, CSSM returns error.
- Counter (output)
Pointer to CSSM_DATA structure that contains data of the tamper resistant clock/counter of the cryptographic device.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
CSSM_VerifyDevice
CSSM_RETURN CSSMAPI CSSM_VerifyDevice (CSSM_CSP_HANDLE CSPHandle, const CSSM_DATA *DeviceCert)
This function triggers the cryptographic module to perform self verification and integrity checking.
- CSPHandle (input)
The handle that describes the add-in cryptographic service provider module used to perform this function. If a NULL handle is specified, CSSM returns error.
- DeviceCert (input)
Pointer to CSSM_DATA structure that contains data that identifies the cryptographic device.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.CSSMERR_CSP_DEVICE_VERIFY_FAILED
CSSM_CSP_PassThrough
CSSM_RETURN CSSMAPI CSSM_CSP_PassThrough (CSSM_CC_HANDLE CCHandle, uint32 PassThroughId, const void *InData, , void **OutData)
TheCSSM_CSP_PassThrough() function is provided to allow CSP developers to extend the crypto functionality of the CSSM API.
- CCHandle (input)
The handle that describes the context of this cryptographic operation.
- PassThroughId (input)
An identifier specifying the custom function to be performed.
- InData (input)
A pointer to a module, implementation-specific structure containing the input data.
- OutData (output)
A pointer to a module, implementation-specific structure containing the output data. The service provider will allocate the memory for this structure. The application should free the memory for the structure.
A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.
See also the Error Codes and Error Values section earlier in this Chapter.CSSMERR_CSP_INVALID_PASSTHROUGH_ID
Contents | Next section | Index |