Previous section.

Common Security: CDSA and CSSM, Version 2 (with corrigenda)
Copyright © 2000 The Open Group

Cryptographic Services

Cryptographic Service Providers

Cryptographic Service Providers (CSPs) are add-in modules which perform cryptographic operations including encryption, decryption, digital signaturing, key and key pair generation, random number generation, message digest, key wrapping, key unwrapping, and key exchange.

Cryptographic services can be implemented by a hardware-software combination or by software only. Besides the traditional cryptographic functions, CSPs may provide other vendor-specific services. The set of services provided can be dynamic even after the CSP has been attached for service by a caller. This means the capabilities registered when the CSP was installed can change during execution, based on changes internal or external to the system.

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 (DL) 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 a PassThrough function.

The nature of the cryptographic functions contained in any particular CSP depends on what task the CSP was designed to perform. For example, a VISA cryptographic hardware token would be able to digitally sign credit card transactions on behalf of the card's owner. A digital employee badge would be able to authenticate a user for physical or electronic access.

A CSP can perform one or more of these cryptographic functions and services:

CDSA Add-In Modules


Figure: CDSA Add-In Module Structure

A CDSA add-in module is a dynamically-linkable library, composed of functions that implement some or all of the CSSM Module Interfaces. Add-in module functionality is partitioned into two areas:

Add-in modules provide one or more categories of security services to applications. In this case it provides CSP Services.

Each module, regardless of the security services it offers, has the same set of administrative responsibilities. Every module must expose functions that allow CSSM to indicate events such as module attach and detach. In addition, as part of the attach operation, every module must be able to verify its own integrity, verify the integrity of CSSM, and register with CSSM. Detailed information about add-in module structure, administration, and interfaces can be found in Part 14 of this Technical Standard.

CDSA CSP Operation

CSSM Infrastructure

The CSSM infrastructure does not implement any cryptography. It has been termed "crypto with a hole." The Cryptographic Services Manager provides applications with access to cryptographic functions that are implemented by Cryptographic Service Provider (CSP) modules. This achieves the objective of centralizing all the cryptography into exchangeable modules.

The Cryptographic Services Manager defines two categories of services:

In CDSA, all cryptographic services requested by applications are channeled to one of the CSPs via the CSSM. CSP vendors only need target their modules to CSSM for all security-conscious applications to gain 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 to select a particular CSP. Once attached, the application can initiate a cryptographic login session with the CSP. The application presents additional credentials, such as a passphrase or PIN, to gain access to specific keys and services managed by the CSP.

Within a module attach session or a cryptographic login session, an application creates, uses and discards cryptographic contexts. A cryptographic context carries the parameters required to perform a cryptographic service. The cryptographic context can be used for:

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 a DeleteContext function. Resources that were allocated for that context can then be reclaimed by the operating system.

Applications can create complex execution models for interacting with one or more CSPs, while a given CSP implementation can have a much simpler execution model. For example, an application could attach to the same CSP multiple times with different threads of execution each time. Each thread would get the appearance of having exclusive access to the CSP. Meanwhile the CSP may be implemented according to a single-threaded model. Additionally, the CSP may be managing multiple installed cards or multiple portable card slots on the system. An application may attach to the same CSP once for each card, as it looks like a different CSP, even though there is a single instance of the CSP attached to the CSSM.

Most applications use the CSSM CSP-APIs directly to request cryptographic operations. Applications also use CSP services indirectly through the certificate-based services of another add-in module (such as a trust policy).

CSP Form Factor

No particular form factor is assumed for a CSP. CSPs can be instantiated in hardware, software or both. Operationally, the distinction must be transparent. The two visible distinctions between hardware and software implementations are the degree of trust the application receives by using a given CSP, and the cost of developing that CSP. A hardware implementation should be more tamper-resistant than a software implementation. Hence a higher level of trust is achieved by the application.

Cryptographic service providers, whose capabilities may change after installation, may make dynamic requests to update profile information stored in the Module Directory Services relation for CSPs, or return that information directly to applications upon request through the CSSM-defined API.

Software CSPs are convenient and portable. Software CSPs can be carried as an executable file on common forms of removable media. The components that implement a CSP must be digitally signed, to authenticate their origin and integrity. This requirement extends to composite implementations involving both software and hardware. Multiple CSPs may be loaded and active within the CSSM at any time. A single application may use multiple CSPs concurrently. Interpreting the resulting level of trust and security is the responsibility of the application or the trust policy module used by the application.

Legacy CSPs

CSPs existed prior to the definition of the CSSM Cryptographic API. These legacy CSPs have defined their own APIs for cryptographic services. These interfaces are CSP-specific, nonstandard, and (in general) low-level, key-based interfaces. They present a considerable development effort to the application developer attempting to secure an application by using those services.

CSSM defines a higher-level interface, based on keys and keypairs associated with certificates. The Cryptographic Services Module Manager defines a Service Provider Interface (SPI) that more closely resembles typical CSP APIs, and provides CSP developers with a single interface to support.

Embracing legacy CSPs, the CSSM architecture defines an optional adaptation layer between the Cryptographic Services Module Manager and a CSP. The adaptation layer allows the CSP vendor to implement a shim to map the CSSM SPI to the legacy CSP's existing API, and to implement any additional management functions that are required for the CSP to function as an add-in module in the extensible CSSM architecture. New CSPs may support the CSSM SPI directly (without the aid of an adaptation layer).

A CSP may or may not have a multi-threaded implementation.

CSP Registration

Each CSP registers a description of its basic functions and services with the Module Directory Services during CSP installation. Applications query this information to select appropriate CSPs for their use. CSPs with dynamic capabilities will not register all their information with MDS. CSPs can add information to MDS at runtime but CSP must also implement an API to query dynamic capabilities at runtime. An application can poll a CSP to become informed of a change in its status.

It is anticipated that some CSP add-in modules will span SPI functional boundaries. For example, a smart card may also register as a data storage module that contains private keys and symmetric keys in tamper-resistant storage.

Cryptographic Services Operations

The security services API calls defined by the CSP Module Manager includes the following service categories:

Applications use these high-level concepts to provide authentication, data integrity, data and communication privacy, and non-repudiation of messages to end-users.

The CSP may implement any algorithm. For example, CSPs may provide one or more of the following algorithms, in one or more modes:

CSPs provide additional services:

The application's associated security context defines parameter values for the low-level variables that control the details of cryptographic operations. Applications use CSPs that provide the services and features required by the application. For example, an application issuing a request to EncryptData may reference a security context that defines the following parameters:

Most applications will use default (predefined) contexts. Typically a distinct context will be used for encrypting, hashing, and signing. For a given application, once initialized, these contexts will change little (if at all) during the application's execution, or between executions. This allows the application developer to implement security by manipulating certificates, using previously-defined security contexts, and maintaining a high-level view of security operations.

Application developers who demand fine-grained control of cryptographic operations can achieve this by directly and repeatedly updating the security context to direct the CSP for each operation, and by using the Cryptographic Services PassThrough call. The PassThrough feature allows a highly knowledgeable application to call low-level CSP functions that are not available through the common Cryptographic API. The CSP Module Manager (CSPMM) first checks the authorization for the call, and if accepted the call is passed through to the specified CSP. The CSPMM will not alter the result of the request, or generate other side effects based on the request. The philosophy of CDSA and the numerous services provided by CSSM is to reduce the need for applications to work at this low level.

Key Management

Every CSP is responsible for implementing its own secure, persistent storage and management of private keys. To support chains of trust across application domains, CSPs must support importing and exporting both public and private keys. This means transferring keys among remote and possibly foreign systems. The ability to transfer keys assumes the ability to convert one key format into any other key format, and to secure the transfer of private and symmetric keys (as required).

Each CSP is responsible for securely storing the private keys it generates or imports from other sources. Additional storage-related operations include retrieving a private key when given its corresponding public key, and wrapping private keys as key blobs for secure exportation to other systems.

Note that each CSP will create and manage its own private-key database. If an application requires that more than one CSP perform operations using the same private key, then that key must be exported from some source and imported to all CSPs needing to use it. Wrapping keys as key blobs manages the problem of different key formats among different CSPs. This assumes that the key length is acceptable to all CSPs using the same key.

Each CSP defines and implements its own key-management functions. Recent CSP implementations, such as Microsoft's Crypto API, define internal storage formats and key-blob wrappers for exporting keys outside of the CSP. CSPs will exchange private keys through secured communication protocols (such as wrappers), rather than through access to a shared database for private keys.

The CSMM API defines how private keys will be passed up and down through the layers of the CDSA, but it does not specify how private keys will be stored within the CSP.

Key Formats for Public Key-Based Algorithms

To ensure interoperability among cryptographic service providers and portability for application developers, CSSM must mandate standard key formats for public key based cryptographic algorithms. Standard key formats have not been defined for many of the algorithms identified by CSSM because these algorithms are not yet in wide spread use. For those algorithms in wide spread use, CDSA adopts existing standard formats or defines a format when no standard exists.

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-encoding of a sequence list containing: 



 

PrimeModulus;    /* p */
PrimeDivisor;    /* q */
OrderQ;          /* g */
PublicKey;       /* y */

A DSA private key is represented as a BER-encoded sequence list containing: 



 

PrimeModulus;    /* p */
PrimeDivisor;    /* q */
OrderQ;          /* g */
PrivateKey;      /* x */

These key components are defined by FIPS 186 and FIPS 186a as follows:

An equation in the source document has not been converted to HTML.

p = a prime modulus, where $2 sup L-1$ < p < $2 sup L$ for 512 <= L <= 1024 and L is a multiple of 64.

PrimeModulus   This is the public prime modulus.

q = a prime divisor of p-1, where $2 sup 159$ < q < $2 sup 160$

PrimeDivisor   Another public prime number dividing (p-1).

g = $h sup (p-1)/q$ mod p, where h is any integer with 1 < h < p-1 such that $h sup (p-1)/q$ mod p > 1.

OrderQ   This public number has order q mod p.

x = a pseudo-randomly generated integer with 0 < x < q.

PrivateKey   The private key.

y = $g sup x$ mod p.

PublicKey   The public key.

An equation in the source document has not been converted to HTML.

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.

Buffer Management for Cryptographic Services

Returning Buffers of Data
If data is returned in a buffer (CSSM_DATA), then the following behavior is defined:

  1. If a data buffer is specified to receive the output value, then the value is written into the buffer if there is enough space and the length value is modified to equal the actual number of bytes written to the buffer. If there is not enough space to receive the output value, then the operation fails with the error code CSSM_CSP_ERR_OUTBUF_LENGTH. The length required for the output buffer can be determined by calling CSSM_QuerySize(). The state of the operation reverts to the state before the operation was attempted. The application can then allocate the correct number of bytes and retry the operation.

  2. 2. If the Length field is set to 0 and the Data field is set to NULL, then the CSP will allocate the correct number of bytes and set the length accordingly.

Vector of Buffers
Many of the CSP APIs allow multiple input and output buffers to be manipulated simultaneously. The behavior of the CSP in these situations is as follows:

Data Structures

CSSM_CC_HANDLE 


typedef CSSM_LONG_HANDLE CSSM_CC_HANDLE; /* Cryptographic Context 
                                        Handle */

CSSM_CSP_HANDLE 


typedef CSSM_MODULE_HANDLE CSSM_CSP_HANDLE /* Cryptographic Service 
                                        Provider Handle */

CSSM_DATE 


typedef struct cssm_date {
    uint8 Year[4];
    uint8 Month[2];
    uint8 Day[2];
} CSSM_DATE, *CSSM_DATE_PTR;
Definition

Year

Four-digit ASCII representation of the year.

Month

Two-digit ASCII representation of the month.

Day

Two-digit ASCII representation of the day.

CSSM_RANGE 


typedef struct cssm_range {
    uint32 Min; /* inclusive minimum value */
    uint32 Max; /* inclusive maximum value */
} CSSM_RANGE, *CSSM_RANGE_PTR;
Definition

Min

Minimum value in the range.

Max

Maximum value in the range.

CSSM_QUERY_SIZE_DATA 


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;
Definition

SizeInputBlock

Size of the data block to be input for processing.

SizeOutputBlock

Size of the output data block that results from processing.

CSSM_HEADERVERSION 


typedef uint32 CSSM_HEADERVERSION;


#define CSSM_KEYHEADER_VERSION (2)
Definition
Represents the version number of a key header structure. This version number is an integer that increments with each format revision. The current revision number is represented by the defined constant CSSM_KEYHEADER_VERSION.

CSSM_KEY_SIZE

This structure holds the key size and the effective key size for a given key. The metric used is bits. The number of effective bits is the number of key bits that can be used in a cryptographic operation compared with the number of bits that may be present in the key. When the number of effective bits is less than the number of actual bits, this is known as "dumbing down". 

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;
Definition

LogicalKeySizeInBits

The logical key size represents the actual size of the key in the case of symmetric algorithms (for example, DES, RC4, RC5) and the modulus size of the key in the case of asymmetric algorithms (for example, RSA, DSA).

EffectiveKeySizeInBits

The effective key size indicates the number of bits of keying material that will be used in the cryptographic operation. The following are instances where the effective key size is different from the logical key size for symmetric algorithms:

CSSM_KEYBLOB_TYPE 


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)

CSSM_KEYBLOB_FORMAT 


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 (0) 
                               /* 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 */

CSSM_KEYCLASS 


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 */

CSSM_KEYATTR_FLAGS 


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)

CSSM_KEYUSE 


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)

CSSM_KEYHEADER

The key header contains meta-data about a key. It contains the GUID of the CSP that owns the data. The CSP initializes the values stored in the key header and returns the header to the application as part of the CSSM_KEY structure. The application can use this key structure as input to other CSP functions. It is highly recommended that applications do not directly alter the values stored in the key header. The cryptographic service function receiving the directly modified key header as an input parameter will typically fail and return an error indicating that the key is invalid.

The key header attributes describe both the CSP-stored copy of the key and the application's local ...

Note:
Editor's note: this update to be completed/resolved.

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;
Definition

HeaderVersion

This is the version of the keyheader structure. The current version is represented by the defined constant CSSM_KEYHEADER_VERSION.

CspId

If known, the GUID of the CSP that generated the key. This value will not be known if a key is received from a third party, or extracted from a certificate.

BlobType

Describes the basic format of the key data. It can be any one of the following values:

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

Format

Describes the detailed format of the key data based on the value of the BlobType field. If the blob type has a non-reference basic type, then a CSSM_KEYBLOB_RAW_FORMAT identifier must be used, otherwise a CSSM_KEYBLOB_REF_FORMAT identifier is used. When a CSSM_KEYBLOB_RAW_FORMAT identifier is used, the key bits are present (in the specified representation) in the KeyData field of the CSSM_KEY structure. When a CSSM_KEYBLOB_REF_FORMAT identifier is used, the KeyData field of the CSSM_KEY structure contains the reference associated with the key bits. This reference can be a number, handle, string, label, or CSP-specific format. Any of the following values are valid as format identifiers.

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

AlgorithmId

The algorithm for which the key was generated. This value does not change when the key is wrapped. Any of the defined CSSM algorithm IDs may be used.

KeyClass

Class of key contained in the key blob. Valid key classes are as follows:

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

LogicalKeySizeInBits

The logical key size represents the actual size of the key in the case of symmetric algorithms (for example, DES, RC4, RC5), and the modulus size of the key in the case of asymmetric algorithms (for example, RSA, DSA).

KeyAttr

Attributes of the key represented by the data. These attributes are used by CSPs and applications to convey information about stored or referenced keys. Some of the attribute values are used only as input or output values for CSP functions, can appear in a keyheader, and some can be used only by the CSP. The attributes are represented by a bitmask. The attribute name, its description, and its usage constraints are summarized in the following:

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.

Key Usage

A bitmask representing the valid uses of the key. Any of the following values are valid:

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.

StartDate

Date from which the corresponding key is valid. All fields of the CSSM_DATA structure will be set to zero if the date is unspecified or unknown.

EndDate

Data that the key expires and can no longer be used. All fields of the CSSM_DATA structure will be set to zero is the date is unspecified or unknown.

WrapAlgorithmId

If the key data contains a wrapped key, this field contains the algorithm used to create the wrapped blob. This field will be set to CSSM_ALGID_NONE if the key is not wrapped.

WrapMode

If the wrapping algorithm supports multiple wrapping modes, this field contains the mode used to wrap the key. This field is ignored if the WrapAlgorithmId is CSSM_ALGID_NONE.

Reserved

This field is reserved for future use. It should always be set to zero.

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  

CSSM_KEY

This structure is used to represent keys in CSSM. 

typedef struct cssm_key {
    CSSM_KEYHEADER KeyHeader; /* Fixed length key header */
    CSSM_DATA KeyData; /* Variable length key data */
} CSSM_KEY, *CSSM_KEY_PTR;
Definition

KeyHeader

Header describing the key.

KeyData

Data representation of the key.

CSSM_WRAP_KEY

This type is used to reference keys that are known to be in wrapped form. 

typedef CSSM_KEY CSSM_WRAP_KEY, *CSSM_WRAP_KEY_PTR;

CSSM_CSP_TYPE 


typedef enum cssm_csptype {
    CSSM_CSP_SOFTWARE = 1,
    CSSM_CSP_HARDWARE = CSSM_CSP_SOFTWARE+1,
    CSSM_CSP_HYBRID = CSSM_CSP_SOFTWARE+2,
}CSSM_CSPTYPE;

CSSM_CONTEXT_TYPE

This type defines a set of constants used different classes of cryptographic algorithms. Each algorithm class corresponds to a context type. See the definition of CSSM_CONTEXT for a description of each algorithm class value. 

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)

CSSM Algorithms

This type defines a set of constants used to identify cryptographic algorithms. See the definition of CSSM_CONTEXT for a description of each algorithm value. 

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_PKCS5_PBKDF1_MD5 (CSSM_ALGID_NONE+67)
#define CSSM_ALGID_PKCS5_PBKDF1_MD2 (CSSM_ALGID_NONE+68)
#define CSSM_ALGID_PKCS5_PBKDF1_SHA1 (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_PKCS5_PBKDF2 (CSSM_ALGID_NONE+103)
#define CSSM_ALGID_RUNNING_COUNTER (CSSM_ALGID_NONE+104)
#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)

CSSM_ATTRIBUTE_TYPE

This type defines a set of constants used to identify the types of attributes store in a cryptographic context. 

/* 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;

CSSM_ENCRYPT_MODE

This type defines a set of constants used to identify encryption modes used by different cryptographic algorithms. See the definition of CSSM_CONTEXT for a description of each encryption mode. 

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)

CSSM_PADDING

This type defines a set of constants used to identify padding methods used by different encryption algorithms. 

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)

CSSM_KEY_TYPE 


typedef CSSM_ALGORITHMS CSSM_KEY_TYPE;
Definition
The cryptographic key type is represented by the cryptographic algorithm where the key will be used. The Cryptographic Service Provider must interpret the algorithm type and deduce the key type required for that algorithm.

CSSM_CONTEXT_ATTRIBUTE 


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;
Definition

AttributeType

An identifier describing the type of attribute. Valid attribute types are as follows:

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

AttributeLength

Length of the attribute data.

Attribute

Union representing the attribute data. The union member used is named after the type of data contained in the attribute. See the attribute types table for the data types associated with each attribute type

CSSM_CONTEXT 


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;
Definition

ContextType

An identifier describing the type of services for this context.

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

AlgorithmType

An ID number indicating the cryptographic algorithm to be used.

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_EDE Triple-DES with 3 keys applied encrypt, decrypt, encrypt (EDE).
CSSM_ALGID_3DES_2KEY_EDE Triple-DES with 2 keys applied encrypt, decrypt, encrypt (EDE), with the first key used for the first and last operation.
CSSM_ALGID_3DES_1KEY_EEE Triple-DES with 1 keys applied encrypt, encrypt, encrypt (EEE), with the first key used for all operations.
CSSM_ALGID_3DES_3KEY Triple-DES with 3 keys.
Alias for CSSM_ALGID_3DES_3KEY_EDE.
CSSM_ALGID_3DES_3KEY_EEE Triple-DES with 3 keys applied encrypt, encrypt, encrypt (EEE).
CSSM_ALGID_3DES_2KEY Triple-DES with 2 keys.
Alias for CSSM_ALGID_3DES_2KEY_EDE.
CSSM_ALGID_3DES_2KEY_EEE Triple-DES with 2 keys applied encrypt, encrypt, encrypt (EEE), with the first key used for the first and last operation.
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_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_PKCS5_PBKDF1_MD5 PKCS #5 key derivation using the PBKDF1 algorithm with MD5.
CSSM_ALGID_PKCS5_PBKDF1_MD2 PKCS #5 key derivation using the PBKDF1 algorithm with MD2.
CSSM_ALGID_PKCS5_PBKDF1_SHA1 PKCS #5 key derivation using the PBKDF1 algorithm with SHA-1.
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 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_HAVAL3 HAVAL3 Digest
CSSM_ALGID_HAVAL4 HAVAL4 Digest
CSSM_ALGID_HAVAL5 HAVAL5 Digest
CSSM_ALGID_TIGER TIGER Digest
CSSM_ALGID_MD5HMAC HMAC-MD5
CSSM_ALGID_PKCS5_PBKDF2 PKCS #5 key derivation using the PBKDF2 algorithm.
CSSM_ALGID_RUNNING_COUNTER Value of a running hardware counter that operates while the device is in operation.
CSSM_ALGID_VENDOR_DEFINED All algorithms IDs that are vendor specific, and not part of the CSSM specification should be defined relative to CSSM_ALGID_VENDOR_DEFINED.

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:

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

NumberOfAttributes

Number of attributes associated with this service.

ContextAttributes

Pointer to data that describes the attributes. To retrieve the next attribute, advance the attribute pointer.

CSPHandle

The handle of the CSP associated with this context.

Privileged

When this flag is CSSM_TRUE, the context can perform crypto operations without being forced to follow the key recovery policy.

EncryptionProhibited

If 0, then encryption is allowed. Otherwise, the flag indicates which policy disallowed encryption (see CSSM_KR_POLICY_FLAGS).

WorkFactor

WorkFactor is the maximum number of key bits that can be left out of key recovery fields when they are generated.

Reserved

An unsigned integer field reserved for future use.

CSSM_SC_FLAGS

A bit mask containing information about a subservice capabilities. This type is used to interpret the ScFlags fields of the "CSP SmartcardInfo Relation" in the MDS. 

typedef uint32 CSSM_SC_FLAGS;


#define CSSM_CSP_TOK_RNG (0x00000001)  
#define CSSM_CSP_TOK_CLOCK_EXISTS (0x00000040)
Definition

CSSM_CSP_TOK_RNG

Subservice has a hardware RNG

CSSM_CSP_TOK_CLOCK_EXISTS

Subservice has a hardware clock

CSSM_CSP_READER_FLAGS

A bit mask containing information about the state of a reader. 

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 */

CSSM_CSP_FLAGS

A bit mask containing information about the state of a service provider. 

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)
Description

CSSM_CSP_TOK_WRITE_PROTECTED

Service provider is write protected.

CSSM_CSP_TOK_LOGIN_REQUIRED

User must login to access private objects.

CSSM_CSP_TOK_USER_PIN_INITIALIZED

User's PIN has been initialized.

CSSM_CSP_TOK_PROT_AUTHENTICATION

Service provider has protected authentication path for entering a user PIN. No password should be supplied to the CSSM_CSP_Login API.

CSSM_CSP_TOK_USER_PIN_EXPIRED

The user PIN must be changed before the service provider can be used.

CSSM_CSP_TOK_SESSION_KEY_PASSWORD

Session keys held by the CSP require individual passwords, possibly in addition to a login password.

CSSM_CSP_TOK_PRIVATE_KEY_PASSWORD

Private keys held by the CSP require individual passwords, possibly in addition to a login password

CSSM_CSP_STORES_PRIVATE_KEYS

CSP can store private keys.

CSSM_CSP_STORES_PUBLIC_KEYS

CSP can store public keys.

CSSM_CSP_STORES_SESSION_KEYS

CSP can store session/secret keys

CSSM_CSP_STORES_CERTIFICATES

Service provider can store certs using DL APIs.

CSSM_CSP_STORES_GENERIC

Service provider can store generic objects using DL APIs.

CSSM_PKCS_OAEP 


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)

CSSM_PKCS_OAEP_PARAMS

When using PKCS #1 RSA with Optimal Asymmetric Encryption Padding (OAEP) encoding, this structure must be added to the asymmetric cryptography context for that operation. The parameter is added as attribute type CSSM_ATTRIBUTE_ALG_PARAMS along with an attribute of type CSSM_ATTRIBUTE_MODE, which specifies OAEP. 

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;
Definition

HashAlgorithm

CSSM algorithm identifier specifying the hash algorithm used during the OAEP encoding.

HashParams

Extra parameters required by a hashing algorithm. For most hash functions this parameter will be empty.

MGF


One of the Mask Generation Function (MGF) identifiers defined in PKCS #1. These values match the functions specified in PKCS #1, but custom MGF functions may be used if supported by the CSP.

MGFParams

Parameter data required by the MGF. The MGF (MGF1 w/SHA-1) function specified in PKCS #1 does not require a parameter.

Psource

One of the source identifiers defined in PKCS #1 for extra data encrypted with the data block. The "specified" mode is the only mode currently made available by PKCS #1.

PsourceParams

Varies depending on the source specified in Psource.

CSSM_CSP_OPERATIONAL_STATISTICS 


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_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;

#define CSSM_VALUE_NOT_AVAILABLE ((uint32)(~0))
Indicates that the statistical value can not be revealed or is not relevant for a CSP
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_PKCS5_PBKDF1_PARAMS

This structure is used to provide input parameters to key derivation algorithms based on password based encryption. 

typedef struct cssm_pkcs5_pbkdf1_params {
    CSSM_DATA Passphrase;
    CSSM_DATA InitVector;
} CSSM_PKCS5_PBKDF1_PARAMS, *CSSM_PKCS5_PBKDF1_PARAMS_PTR;
Definition

Passphrase

The passphrase used as the basis for key derivation.

InitVector

The initialization vector returned as an additional result of the key derivation procedure. If the returned derived key is to be used for CBC mode encryption, InitVector should be used as the initialization vector for the encryption function.

CSSM_PKCS5_PBKDF2_PRF

This type indicates the underlying pseudo-random function (PRF) used by the PKCS #5 v2.0 PBKDF2 key derivation function, CSSM_ALGID_PKCS5_PBKDF2. 

typedef uint32 CSSM_PKCS5_PBKDF2_PRF;

#define CSSM_PKCS5_PBKDF2_PRF_HMAC_SHA1 (0)

CSSM_PKCS5_PBKDF2_PARAMS

This structure is used to provide input parameters to key derivation algorithms based on PKCS #5 v2.0 password based encryption. 

typedef struct cssm_pkcs5_pbkdf2_params {
    CSSM_DATA Passphrase;
    CSSM_PKCS5_PBKDF2_PRF PseudoRandomFunction;
} CSSM_PKCS5_PBKDF2_PARAMS; *CSSM_PKCS5_PBKDF2_PARAMS_PTR;
Definition

Passphrase

The passphrase used as the basis for key derivation.

PseudoRandomFunction

Pseudo-random function to use for the key derivation process.

CSSM_KEA_DERIVE_PARAMS

This structure is used during phase 2 of the Key Exchange Algorithm (KEA). 

typedef struct cssm_kea_derive_params {
    CSSM_DATA Rb;
    CSSM_DATA Yb;
} CSSM_KEA_DERIVE_PARAMS, *CSSM_KEA_DERIVE_PARAMS_PTR;
Definition

Rb
References a buffer containing the Ra value received from the remote party.

Yb
References a buffer containing the public value from the remote party.

Error Codes and Error Values

This section defines Error Values that can be returned by CSP operations.

Each CSP function may return any Error Value derived from the Common Error Codes defined in CSSM Error Handling, if it satisfies the conditions defined for that Error Code. In addition, a number of common sets of Error Values are defined specifically for CSP functions:

  1. A general set that can be returned by any CSP function

  2. A set that can be returned by key operations

  3. A set that can be returned by operations accepting vectors of buffers

  4. A set that can be returned by operations that take a cryptographic context handle

  5. A set that can be returned by staged operations

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.

CSP Error Values Derived from Common Error Codes

See CSSM Error Handling.
Common Error Values for All Module Types 

#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)
Common ACL Error Values 

#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_OBJECT_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)
Common Error Values for Specific Data Types 

#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_INVALID_CRYPTO_DATA \
    (CSSM_CSP_BASE_ERROR+CSSM_ERRCODE_INVALID_CRYPTO_DATA)

General CSP Error Values

These error values can be returned from any CSP function. 

#define CSSM_CSP_BASE_CSP_ERROR \ 
    (CSSM_CSP_BASE_ERROR+CSSM_ERRORCODE_COMMON_EXTENT)

#define CSSMERR_CSP_INPUT_LENGTH_ERROR (CSSM_CSP_BASE_CSP_ERROR+1)
An input buffer does not have the expected length 


#define CSSMERR_CSP_OUTPUT_LENGTH_ERROR (CSSM_CSP_BASE_CSP_ERROR+2)
An output buffer was supplied, but it was too small to hold the output data 


#define CSSMERR_CSP_PRIVILEGE_NOT_SUPPORTED (CSSM_CSP_BASE_CSP_ERROR+3)
The CSP does not support the requested privilege level 


#define CSSMERR_CSP_DEVICE_ERROR (CSSM_CSP_BASE_CSP_ERROR+4)
General device error; Indicates that a hardware subsystem has failed in some way 


#define CSSMERR_CSP_DEVICE_MEMORY_ERROR (CSSM_CSP_BASE_CSP_ERROR+5)
General device error; Indicates that a hardware subsystem has run out of memory 


#define CSSMERR_CSP_ATTACH_HANDLE_BUSY (CSSM_CSP_BASE_CSP_ERROR+6)
The attach handle used to attempt an operation currently has an operation in progress that will not allow other operations to begin until it completes 


#define CSSMERR_CSP_NOT_LOGGED_IN (CSSM_CSP_BASE_CSP_ERROR+7)
The operation can not be performed without authenticating using CSSM_CSP_Login

CSP Key Error Values

These error values can be returned from CSP functions that use a key. The key may be passed directly into the function or specified as an attribute through the cryptographic context. 


#define CSSMERR_CSP_INVALID_KEY (CSSM_CSP_BASE_CSP_ERROR+16)
The supplied key is invalid or incompatible with the operation 


#define CSSMERR_CSP_INVALID_KEY_REFERENCE (CSSM_CSP_BASE_CSP_ERROR+17)
The CSSM_KEY contains a reference that does not indicate a key in the CSP 


#define CSSMERR_CSP_INVALID_KEY_CLASS (CSSM_CSP_BASE_CSP_ERROR+18)
The supplied key is not the proper class (i.e. Public key is supplied for a private key operation) 


#define CSSMERR_CSP_ALGID_MISMATCH (CSSM_CSP_BASE_CSP_ERROR+19)
The algorithm ID in the key header does not match the algorithm to be performed 


#define CSSMERR_CSP_KEY_USAGE_INCORRECT (CSSM_CSP_BASE_CSP_ERROR+20)
The key does not have the proper usage flags to perform the operation 


#define CSSMERR_CSP_KEY_BLOB_TYPE_INCORRECT (CSSM_CSP_BASE_CSP_ERROR+21)
The key data blob type is not the correct type (i.e. The key is wrapped when a raw key or reference is expected) 


#define CSSMERR_CSP_KEY_HEADER_INCONSISTENT (CSSM_CSP_BASE_CSP_ERROR+22)
The key header information is corrupt, or does not match the key data 


#define CSSMERR_CSP_UNSUPPORTED_KEY_FORMAT (CSSM_CSP_BASE_CSP_ERROR+23)
The key format is not supported by the CSP 


#define CSSMERR_CSP_UNSUPPORTED_KEY_SIZE (CSSM_CSP_BASE_CSP_ERROR+24)
The key size is not supported or not allowed by the current privilege or supported by the CSP 


#define CSSMERR_CSP_INVALID_KEY_POINTER (CSSM_CSP_BASE_CSP_ERROR+25)
The pointer to a CSSM_KEY structure is invalid 


#define CSSMERR_CSP_INVALID_KEYUSAGE_MASK (CSSM_CSP_BASE_CSP_ERROR+26)
A requested key usage is not valid for the key type, or two of the uses are not compatible 


#define CSSMERR_CSP_UNSUPPORTED_KEYUSAGE_MASK (CSSM_CSP_BASE_CSP_ERROR+27)
The key usage mask is valid, but not supported by the CSP 


#define CSSMERR_CSP_INVALID_KEYATTR_MASK (CSSM_CSP_BASE_CSP_ERROR+28)
A requested key attribute is not valid for the key type, or two of the attributes are not compatible 


#define CSSMERR_CSP_UNSUPPORTED_KEYATTR_MASK (CSSM_CSP_BASE_CSP_ERROR+29)
The key attribute mask is valid, but not supported by the CSP 


#define CSSMERR_CSP_INVALID_KEY_LABEL (CSSM_CSP_BASE_CSP_ERROR+30)
The label specified for a key is invalid 


#define CSSMERR_CSP_UNSUPPORTED_KEY_LABEL (CSSM_CSP_BASE_CSP_ERROR+31)
The CSP does not support the use of labels for the key. 


#define CSSMERR_CSP_INVALID_KEY_FORMAT (CSSM_CSP_BASE_CSP_ERROR+32)
Invalid key format

CSP Vector of Buffers Error Values

These error values can be returned by APIs that accept a vector of buffers as input or output. 


#define CSSMERR_CSP_INVALID_DATA_COUNT (CSSM_CSP_BASE_CSP_ERROR+40)
Input vector length is invalid; buffer count can not be zero. 


#define CSSMERR_CSP_VECTOR_OF_BUFS_UNSUPPORTED (CSSM_CSP_BASE_CSP_ERROR+41)
The CSP only supports input of a single buffer per API call 


#define CSSMERR_CSP_INVALID_INPUT_VECTOR (CSSM_CSP_BASE_CSP_ERROR+42)
A vector of buffers for input does not contain valid information 


#define CSSMERR_CSP_INVALID_OUTPUT_VECTOR (CSSM_CSP_BASE_CSP_ERROR+43)
A vector of buffers for output does not contain valid information

CSP Cryptographic Context Error Values

These error values can be returned by CSP APIs that take A cryptographic context handle as input. 


#define CSSMERR_CSP_INVALID_CONTEXT (CSSM_CSP_BASE_CSP_ERROR+48)
The cryptographic context and operation types are not compatible 


#define CSSMERR_CSP_INVALID_ALGORITHM (CSSM_CSP_BASE_CSP_ERROR+49)
Algorithm is not supported by the CSP 


#define CSSMERR_CSP_INVALID_ATTR_KEY  (CSSM_CSP_BASE_CSP_ERROR + 54)
#define CSSMERR_CSP_MISSING_ATTR_KEY  (CSSM_CSP_BASE_CSP_ERROR + 55)
The cryptographic key is missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_INIT_VECTOR  (CSSM_CSP_BASE_CSP_ERROR + 56)
#define CSSMERR_CSP_MISSING_ATTR_INIT_VECTOR  (CSSM_CSP_BASE_CSP_ERROR + 57)
The algorithm mode required an initialization vector and it is missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_SALT  (CSSM_CSP_BASE_CSP_ERROR + 58)
#define CSSMERR_CSP_MISSING_ATTR_SALT  (CSSM_CSP_BASE_CSP_ERROR + 59)
The operation requires salt and it is is missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_PADDING  (CSSM_CSP_BASE_CSP_ERROR + 60)
#define CSSMERR_CSP_MISSING_ATTR_PADDING  (CSSM_CSP_BASE_CSP_ERROR + 61)
An algorithm mode with padding is specified and the padding type is missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_RANDOM  (CSSM_CSP_BASE_CSP_ERROR + 62)
#define CSSMERR_CSP_MISSING_ATTR_RANDOM  (CSSM_CSP_BASE_CSP_ERROR + 63)
The operation required random data and it is missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_SEED  (CSSM_CSP_BASE_CSP_ERROR + 64)
#define CSSMERR_CSP_MISSING_ATTR_SEED  (CSSM_CSP_BASE_CSP_ERROR + 65)
The algorithm requires a seed value and it is missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_PASSPHRASE  (CSSM_CSP_BASE_CSP_ERROR + 66)
#define CSSMERR_CSP_MISSING_ATTR_PASSPHRASE  (CSSM_CSP_BASE_CSP_ERROR + 67)
The operation requires a passphrase value and it is missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_KEY_LENGTH  (CSSM_CSP_BASE_CSP_ERROR + 68)
#define CSSMERR_CSP_MISSING_ATTR_KEY_LENGTH  (CSSM_CSP_BASE_CSP_ERROR + 69)
The operation requires a key length and it is missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_BLOCK_SIZE  (CSSM_CSP_BASE_CSP_ERROR + 70)
#define CSSMERR_CSP_MISSING_ATTR_BLOCK_SIZE  (CSSM_CSP_BASE_CSP_ERROR + 71)
The algorithm has a configurable block size and the value is missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_OUTPUT_SIZE  (CSSM_CSP_BASE_CSP_ERROR + 100)
#define CSSMERR_CSP_MISSING_ATTR_OUTPUT_SIZE  (CSSM_CSP_BASE_CSP_ERROR + 101)
The algorithm has a configurable output size and the value is missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_ROUNDS  (CSSM_CSP_BASE_CSP_ERROR + 102)
#define CSSMERR_CSP_MISSING_ATTR_ROUNDS  (CSSM_CSP_BASE_CSP_ERROR + 103)
The algorithm has a configurable number of rounds and the value is missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_ALG_PARAMS  (CSSM_CSP_BASE_CSP_ERROR + 104)
#define CSSMERR_CSP_MISSING_ATTR_ALG_PARAMS  (CSSM_CSP_BASE_CSP_ERROR + 105)
The algorithm required a set of parameters and they are missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_LABEL  (CSSM_CSP_BASE_CSP_ERROR + 106)
#define CSSMERR_CSP_MISSING_ATTR_LABEL  (CSSM_CSP_BASE_CSP_ERROR + 107)
The operation creates an object that requires a label and it is missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_KEY_TYPE  (CSSM_CSP_BASE_CSP_ERROR + 108)
#define CSSMERR_CSP_MISSING_ATTR_KEY_TYPE  (CSSM_CSP_BASE_CSP_ERROR + 109)
The operation requires a key type and the value is missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_MODE  (CSSM_CSP_BASE_CSP_ERROR + 110)
#define CSSMERR_CSP_MISSING_ATTR_MODE  (CSSM_CSP_BASE_CSP_ERROR + 111)
The algorithm requires a mode to be specified and it is missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_EFFECTIVE_BITS  
    (CSSM_CSP_BASE_CSP_ERROR + 112)
#define CSSMERR_CSP_MISSING_ATTR_EFFECTIVE_BITS  
    (CSSM_CSP_BASE_CSP_ERROR + 113)
The algorithm has a configurable number of effective bits and the value it missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_START_DATE  (CSSM_CSP_BASE_CSP_ERROR + 114)
#define CSSMERR_CSP_MISSING_ATTR_START_DATE  (CSSM_CSP_BASE_CSP_ERROR + 115)
The operation creates an object with a validity date and the starting date is missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_END_DATE  (CSSM_CSP_BASE_CSP_ERROR + 116)
#define CSSMERR_CSP_MISSING_ATTR_END_DATE  (CSSM_CSP_BASE_CSP_ERROR + 117)
The operation creates an object with a validity date and the ending date is missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_VERSION  (CSSM_CSP_BASE_CSP_ERROR + 118)
#define CSSMERR_CSP_MISSING_ATTR_VERSION  (CSSM_CSP_BASE_CSP_ERROR + 119)
The operation requires a version number and the value is missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_PRIME  (CSSM_CSP_BASE_CSP_ERROR + 120)
#define CSSMERR_CSP_MISSING_ATTR_PRIME  (CSSM_CSP_BASE_CSP_ERROR + 121)
The operation requires a prime value and it is missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_BASE  (CSSM_CSP_BASE_CSP_ERROR + 122)
#define CSSMERR_CSP_MISSING_ATTR_BASE  (CSSM_CSP_BASE_CSP_ERROR + 123)
The operation requires a base value and it is missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_SUBPRIME  (CSSM_CSP_BASE_CSP_ERROR + 124)
#define CSSMERR_CSP_MISSING_ATTR_SUBPRIME  (CSSM_CSP_BASE_CSP_ERROR + 125)
The operation requires a sub-prime value and it is missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_ITERATION_COUNT  
    (CSSM_CSP_BASE_CSP_ERROR + 126)
#define CSSMERR_CSP_MISSING_ATTR_ITERATION_COUNT  
    (CSSM_CSP_BASE_CSP_ERROR + 127)
The operation has a configurable iteration count and the value is missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_DL_DB_HANDLE  
    (CSSM_CSP_BASE_CSP_ERROR + 128)
#define CSSMERR_CSP_MISSING_ATTR_DL_DB_HANDLE  
    (CSSM_CSP_BASE_CSP_ERROR + 129)
The operation can store new objects in a specific location and the value is missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_ACCESS_CREDENTIALS
    (CSSM_CSP_BASE_CSP_ERROR + 130)
#define CSSMERR_CSP_MISSING_ATTR_ACCESS_CREDENTIALS
    (CSSM_CSP_BASE_CSP_ERROR + 131)
The operation requires access credentials and they are missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_PUBLIC_KEY_FORMAT
    (CSSM_CSP_BASE_CSP_ERROR + 132)
#define CSSMERR_CSP_MISSING_ATTR_PUBLIC_KEY_FORMAT
    (CSSM_CSP_BASE_CSP_ERROR + 133)
The resulting public key format is missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_PRIVATE_KEY_FORMAT
    (CSSM_CSP_BASE_CSP_ERROR + 134)
#define CSSMERR_CSP_MISSING_ATTR_PRIVATE_KEY_FORMAT
    (CSSM_CSP_BASE_CSP_ERROR + 135)
The resulting private key format is missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_SYMMETRIC_KEY_FORMAT
    (CSSM_CSP_BASE_CSP_ERROR + 136)
#define CSSMERR_CSP_MISSING_ATTR_SYMMETRIC_KEY_FORMAT
    (CSSM_CSP_BASE_CSP_ERROR + 137)
The resulting symmetric key format is missing or invalid. 


#define CSSMERR_CSP_INVALID_ATTR_WRAPPED_KEY_FORMAT
    (CSSM_CSP_BASE_CSP_ERROR + 138)
#define CSSMERR_CSP_MISSING_ATTR_WRAPPED_KEY_FORMAT
    (CSSM_CSP_BASE_CSP_ERROR + 139)
The resulting wrapped key format is missing or invalid.

CSP Staged Cryptographic API Error Values

These error values can be returned by staged cryptographic APIs. The names of the staged cryptographic APIs end in "Init", "Update", "Final" and "InitP". 


#define CSSMERR_CSP_STAGED_OPERATION_IN_PROGRESS \
    (CSSM_CSP_BASE_CSP_ERROR+72)
The application has already started a staged operation using the specified CC 


#define CSSMERR_CSP_STAGED_OPERATION_NOT_STARTED \
    (CSSM_CSP_BASE_CSP_ERROR+73)
An "Update" or "Final" API has been called without calling the corresponding "Init"

Other CSP Error Values 


#define CSSMERR_CSP_VERIFY_FAILED (CSSM_CSP_BASE_CSP_ERROR+74)
The signature is not valid 


#define CSSMERR_CSP_INVALID_SIGNATURE (CSSM_CSP_BASE_CSP_ERROR+75)
The signature data is not in the proper format 


#define CSSMERR_CSP_QUERY_SIZE_UNKNOWN (CSSM_CSP_BASE_CSP_ERROR+76)
The size of the output data can not be determined 


#define CSSMERR_CSP_BLOCK_SIZE_MISMATCH (CSSM_CSP_BASE_CSP_ERROR+77)
The size of the input is not equal to a multiple of the algorithm block size; valid for symmetric block ciphers in an unpadded mode 


#define CSSMERR_CSP_PRIVATE_KEY_NOT_FOUND (CSSM_CSP_BASE_CSP_ERROR+78)
The private key matching the public key was not found 


#define CSSMERR_CSP_PUBLIC_KEY_INCONSISTENT (CSSM_CSP_BASE_CSP_ERROR+79)
The public key specified does not match the private key being unwrapped 


#define CSSMERR_CSP_DEVICE_VERIFY_FAILED (CSSM_CSP_BASE_CSP_ERROR+80)
The logical device could not be verified by the service provider 


#define CSSMERR_CSP_INVALID_LOGIN_NAME (CSSM_CSP_BASE_CSP_ERROR+81)
The login name is not recognized by the CSP 


#define CSSMERR_CSP_ALREADY_LOGGED_IN (CSSM_CSP_BASE_CSP_ERROR+82)
The device is already logged in and can not be reauthenticated 


#define CSSMERR_CSP_PRIVATE_KEY_ALREADY_EXISTS \
    (CSSM_CSP_BASE_CSP_ERROR+83)
The private key already exists in the CSP. 


#define CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS (CSSM_CSP_BASE_CSP_ERROR+84)
Key label already exists in the CSP. 


#define CSSMERR_CSP_INVALID_DIGEST_ALGORITHM (CSSM_CSP_BASE_CSP_ERROR+85)
The digest algorithm passed in to the Sign/Verify operation is invalid. 


#define CSSMERR_CSP_CRYPTO_DATA_CALLBACK_FAILED
    (CSSM_CSP_BASE_CSP_ERROR+86)
The crypto data callback failed

Cryptographic Context Operations

The man-page definitions for Cryptographic Context operations are presented in this section.
Previous section.

NAME

CSSM_CSP_CreateSignatureContext

SYNOPSIS


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)

DESCRIPTION

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.

PARAMETERS

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/optional)

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.

RETURN VALUE

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.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO


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()
Previous section.

NAME

CSSM_CSP_CreateSymmetricContext

SYNOPSIS


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)

DESCRIPTION

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

PARAMETERS

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.

RETURN VALUE

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.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO


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()
Previous section.

NAME

CSSM_CSP_CreateDigestContext

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_CSP_CreateDigestContext
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_ALGORITHMS AlgorithmID,
    CSSM_CC_HANDLE *NewContextHandle)

DESCRIPTION

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.

PARAMETERS

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.

RETURN VALUE

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.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO


CSSM_DigestData()
CSSM_DigestDataInit()
CSSM_DigestDataUpdate()
CSSM_DigestDataFinal()
CSSM_GetContext()
CSSM_SetContext()
CSSM_DeleteContext()
CSSM_GetContextAttribute()
CSSM_UpdateContextAttributes()
Previous section.

NAME

CSSM_CSP_CreateMacContext

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_CSP_CreateMacContext
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_ALGORITHMS AlgorithmID,
    const CSSM_KEY *Key,
    CSSM_CC_HANDLE *NewContextHandle)

DESCRIPTION

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.

PARAMETERS

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.

RETURN VALUE

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.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO


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()
Previous section.

NAME

CSSM_CSP_CreateRandomGenContext

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_CSP_CreateRandomGenContext
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_ALGORITHMS AlgorithmID,
    const CSSM_CRYPTO_DATA *Seed,
    uint32 Length,
    CSSM_CC_HANDLE *NewContextHandle)

DESCRIPTION

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.

PARAMETERS

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.

RETURN VALUE

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.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO


CSSM_GenerateRandom()
CSSM_GetContext()
CSSM_SetContext()
CSSM_DeleteContext()
CSSM_GetContextAttribute()
CSSM_UpdateContextAttributes()
Previous section.

NAME

CSSM_CSP_CreateAsymmetricContext

SYNOPSIS


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)

DESCRIPTION

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.

PARAMETERS

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.

RETURN VALUE

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.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO


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()
Previous section.

NAME

CSSM_CSP_CreateDeriveKeyContext

SYNOPSIS


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)

DESCRIPTION

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.

PARAMETERS

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.

RETURN VALUE

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.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO

CSSM_DeriveKey()
Previous section.

NAME

CSSM_CSP_CreateKeyGenContext

SYNOPSIS


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)

DESCRIPTION

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.

PARAMETERS

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.

RETURN VALUE

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.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO


CSSM_GenerateKey()
CSSM_GenerateKeyPair()
CSSM_GetContext()
CSSM_SetContext()
CSSM_DeleteContext()
CSSM_GetContextAttribute()
CSSM_UpdateContextAttributes()
Previous section.

NAME

CSSM_CSP_CreatePassThroughContext

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_CSP_CreatePassThroughContext
    (CSSM_CSP_HANDLE CSPHandle,
    const CSSM_KEY *Key,
    CSSM_CC_HANDLE *NewContextHandle)

DESCRIPTION

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.

PARAMETERS

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.

RETURN VALUE

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.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

COMMENTS

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.

SEE ALSO


CSSM_CSP_PassThrough()
CSSM_GetContext()
CSSM_SetContext()
CSSM_DeleteContext()
CSSM_GetContextAttribute()
CSSM_UpdateContextAttributes()
Previous section.

NAME

CSSM_GetContext

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_GetContext
    (CSSM_CC_HANDLE CCHandle,
    CSSM_CONTEXT_PTR *Context)

DESCRIPTION

This function retrieves the context information when provided with a context handle.

PARAMETERS

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. Use CSSM_FreeContext() to free the memory allocated by the CSSM.

RETURN VALUE

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.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.


CSSMERR_CSSM_INVALID_CONTEXT_HANDLE

SEE ALSO


CSSM_SetContext()
CSSM_FreeContext()
Previous section.

NAME

CSSM_FreeContext

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_FreeContext
    (CSSM_CONTEXT_PTR Context)

DESCRIPTION

This function frees the memory associated with the context structure.

PARAMETERS

Context (input)

The pointer to the memory that describes the context structure.

RETURN VALUE

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.

ERRORS

None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO

CSSM_GetContext()
Previous section.

NAME

CSSM_SetContext

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_SetContext
    (CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context)

DESCRIPTION

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.

PARAMETERS

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.

RETURN VALUE

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.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.


CSSMERR_CSSM_INVALID_CONTEXT_HANDLE
CSSMERR_CSSM_INVALID_ATTRIBUTE

SEE ALSO

CSSM_GetContext()
Previous section.

NAME

CSSM_DeleteContext

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_DeleteContext
    (CSSM_CC_HANDLE CCHandle)

DESCRIPTION

This function frees the context structure allocated by any of the CSSM_CreateXXXXXContext() functions.

PARAMETERS

CCHandle (input)

The handle that describes a context to be deleted.

RETURN VALUE

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.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CSSM_INVALID_CONTEXT_HANDLE

SEE ALSO


CSSM_CSP_CreateSymmetricContext()
CSSM_CSP_CreateAsymmetricContext()
CSSM_CSP_CreateKeyGenContext()
CSSM_CSP_CreateDigestContext()
CSSM_CSP_CreateSignatureContext()
and others.
Previous section.

NAME

CSSM_GetContextAttribute

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_GetContextAttribute
    (const CSSM_CONTEXT *Context,
    uint32 AttributeType,
    CSSM_CONTEXT_ATTRIBUTE_PTR *ContextAttribute)

DESCRIPTION

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.

PARAMETERS

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. Call CSSM_DeleteContextAttributes() to free memory allocated by the CSSM.

RETURN VALUE

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.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CSSM_ATTRIBUTE_NOT_IN_CONTEXT

SEE ALSO


CSSM_DeleteContextAttributes()
CSSM_GetContext()
Previous section.

NAME

CSSM_UpdateContextAttributes

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_UpdateContextAttributes
    (CSSM_CC_HANDLE CCHandle,
    uint32 NumberOfAttributes,
    const CSSM_CONTEXT_ATTRIBUTE *ContextAttributes)

DESCRIPTION

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.

PARAMETERS

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.

RETURN VALUE

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.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.


CSSMERR_CSSM_INVALID_CONTEXT_HANDLE
CSSMERR_CSSM_INVALID_ATTRIBUTE

SEE ALSO


CSSM_GetContextAttribute()
CSSM_DeleteContextAttributes()
Previous section.

NAME

CSSM_DeleteContextAttributes

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_DeleteContextAttributes
    (CSSM_CC_HANDLE CCHandle,
    uint32 NumberOfAttributes,
    const CSSM_CONTEXT_ATTRIBUTE *ContextAttributes)

DESCRIPTION

This function deletes internal data associated with given attribute type of the context handle.

PARAMETERS

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.

RETURN VALUE

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.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.


CSSMERR_CSSM_INVALID_CONTEXT_HANDLE

SEE ALSO


CSSM_GetContextAttributes()
CSSM_UpdateContextAttributes()

Cryptographic Sessions and Controlled Access to Keys

The man-page definitions for Cryptographic Sessions and Controlled Access to Keys are presented in this section.
Previous section.

NAME

CSSM_CSP_Login

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_CSP_Login
    (CSSM_CSP_HANDLE CSPHandle,
    const CSSM_ACCESS_CREDENTIALS *AccessCred,
    const CSSM_DATA *LoginName,
    const void *Reserved)

DESCRIPTION

Logs the user into the CSP, allowing for multiple login types.

PARAMETERS

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

RETURN VALUE

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.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.


CSSMERR_CSP_INVALID_LOGIN_NAME
CSSMERR_CSP_ALREADY_LOGGED_IN

SEE ALSO


CSSM_CSP_Logout()
CSSM_CSP_GetLoginAcl()
CSSM_CSP_ChangeLoginAcl()
Previous section.

NAME

CSSM_CSP_Logout

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_CSP_Logout
    (CSSM_CSP_HANDLE CSPHandle)

DESCRIPTION

Terminates the login session associated with the specified CSP Handle.

PARAMETERS

CSPHandle (input)

Handle for the target CSP.

RETURN VALUE

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.

ERRORS

None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO


CSSM_CSP_Login()
CSSM_CSP_GetLoginAcl()
CSSM_CSP_ChangeLoginAcl()
Previous section.

NAME

CSSM_CSP_GetLoginAcl

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_CSP_GetLoginAcl
    (CSSM_CSP_HANDLE CSPHandle,
    const CSSM_STRING *SelectionTag,
    uint32 *NumberOfAclInfos,
    CSSM_ACL_ENTRY_INFO_PTR *AclInfos)

DESCRIPTION

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:

The public ACL entry information returned by this function includes:

PARAMETERS

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.

RETURN VALUE

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.

ERRORS

None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO


CSSM_CSP_ChangeLoginAcl()
CSSM_CSP_Login()
CSSM_CSP_Logout()
Previous section.

NAME

CSSM_CSP_ChangeLoginAcl

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_CSP_ChangeLoginAcl
    (CSSM_CSP_HANDLE CSPHandle,
    const CSSM_ACCESS_CREDENTIALS *AccessCred,
    const CSSM_ACL_EDIT *AclEdit)

DESCRIPTION

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.

PARAMETERS

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

RETURN VALUE

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.

ERRORS

None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO


CSSM_CSP_GetLoginAcl()
CSSM_CSP_Login()
CSSM_CSP_Logout()
Previous section.

NAME

CSSM_GetKeyAcl

SYNOPSIS


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)

DESCRIPTION

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:

The public ACL entry information returned by this function includes:

PARAMETERS

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.

RETURN VALUE

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.

ERRORS

None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO

CSSM_ChangeKeyAcl()
Previous section.

NAME

CSSM_ChangeKeyAcl

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_ChangeKeyAcl
    (CSSM_CSP_HANDLE CSPHandle,
    const CSSM_ACCESS_CREDENTIALS *AccessCred,
    const CSSM_ACL_EDIT *AclEdit,
    const CSSM_KEY *Key)

DESCRIPTION

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.

PARAMETERS

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.

RETURN VALUE

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.

ERRORS

None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO

CSSM_GetKeyAcl()
Previous section.

NAME

CSSM_GetKeyOwner

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_GetKeyOwner
    (CSSM_CSP_HANDLE CSPHandle,
    const CSSM_KEY *Key,
    CSSM_ACL_OWNER_PROTOTYPE_PTR Owner)

DESCRIPTION

This function returns a CSSM_ACL_OWNER_PROTOTYPE describing the current Owner of the Key.

PARAMETERS

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.

RETURN VALUE

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.

ERRORS

None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO

CSSM_ChangeKeyOwner()
Previous section.

NAME

CSSM_ChangeKeyOwner

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_ChangeKeyOwner
    (CSSM_CSP_HANDLE CSPHandle,
    const CSSM_ACCESS_CREDENTIALS *AccessCred,
    const CSSM_KEY *Key,
    const CSSM_ACL_OWNER_PROTOTYPE *NewOwner)

DESCRIPTION

This function takes a CSSM_ACL_OWNER_PROTOTYPE defining the new Owner of the Key.

PARAMETERS

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.

RETURN VALUE

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.

ERRORS

None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO

CSSM_GetKeyOwner()
Previous section.

NAME

CSSM_CSP_GetLoginOwner

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_CSP_GetLoginOwner
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_ACL_OWNER_PROTOTYPE_PTR Owner)

DESCRIPTION

This function returns a CSSM_ACL_OWNER_PROTOTYPE describing the current Login Owner of the CSP.

PARAMETERS

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.

RETURN VALUE

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.

ERRORS

None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO

CSSM_CSP_ChangeLoginOwner()
Previous section.

NAME

CSSM_CSP_ChangeLoginOwner

SYNOPSIS


CSSM_RETURN CSSMAPI CSSM_CSP_ChangeLoginOwner
    (CSSM_CSP_HANDLE CSPHandle,
    const CSSM_ACCESS_CREDENTIALS *AccessCred,
    const CSSM_ACL_OWNER_PROTOTYPE *NewOwner)

DESCRIPTION

This function takes a CSSM_ACL_OWNER_PROTOTYPE describing the new Login Owner.

PARAMETERS

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.

RETURN VALUE

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.

ERRORS

None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO

CSSM_CSP_GetLoginOwner()

Cryptographic Operations

The man-page definitions for Cryptographic operations are presented in this section.
Previous section.

NAME

CSSM_SignData for the CSSM API
CSP_SignData for the CSP SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_SignData
    (CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *DataBufs,
    uint32 DataBufCount,
    CSSM_ALGORITHMS DigestAlgorithm,
    CSSM_DATA_PTR Signature)

SPI:
CSSM_RETURN CSSMCSPI CSP_SignData
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context,
    const CSSM_DATA *DataBufs,
    uint32 DataBufCount,
    CSSM_ALGORITHMS DigestAlgorithm,
    CSSM_DATA_PTR Signature)

DESCRIPTION

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.

API PARAMETERS

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

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.

ADDITIONAL SPI PARAMETERS

CSPHandle (input)

The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

Context (input)

Pointer to CSSM_CONTEXT structure that describes the attributes with this context.

RETURN VALUE

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.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.


CSSMERR_CSP_OUTPUT_LENGTH_ERROR
CSSMERR_CSP_INVALID_DIGEST_ALGORITHM

COMMENTS FOR API

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.

COMMENTS FOR SPI

The output is returned to the caller as specifed in Buffer Management for Cryptographic Services.

SEE ALSO


For the CSSM API:
CSSM_VerifyData()
CSSM_SignDataInit()
CSSM_SignDataUpdate()
CSSM_SignDataFinal()


For the CSP SPI:
CSP_VerifyData()
CSP_SignDataInit()
CSP_SignDataUpdate()
CSP_SignDataFinal()

Previous section.

NAME

CSSM_SignDataInit for the CSSM API
CSP_SignDataInit for the CSP SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_SignDataInit
    (CSSM_CC_HANDLE CCHandle)

SPI:
CSSM_RETURN CSSMCSPI CSP_SignDataInit
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context)

DESCRIPTION

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.

API PARAMETERS

CCHandle (input)

The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.

ADDITIONAL SPI PARAMETERS

CSPHandle (input)

The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

Context (input)

Pointer to CSSM_CONTEXT structure that describes the attributes with this context.

RETURN VALUE

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.

ERRORS

None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO


For the CSSM API:
CSSM_SignData()
CSSM_SignDataUpdate()
CSSM_SignDataFinal()


For the CSP SPI:
CSP_SignData()
CSP_SignDataUpdate()
CSP_SignDataFinal()

Previous section.

NAME

CSSM_SignDataUpdate for the CSSM API
CSP_SignDataUpdate for the CSP SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_SignDataUpdate
    (CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *DataBufs,
    uint32 DataBufCount)

SPI:
CSSM_RETURN CSSMCSPI CSP_SignDataUpdate
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *DataBufs,
    uint32 DataBufCount)

DESCRIPTION

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.

API PARAMETERS

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.

ADDITIONAL SPI PARAMETER

CSPHandle (input)

The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

RETURN VALUE

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.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO


For the CSSM API:
CSSM_SignData()
CSSM_SignDataInit()
CSSM_SignDataFinal()


For the CSP SPI:
CSP_SignData()
CSP_SignDataInit()
CSP_SignDataFinal()

Previous section.

NAME

CSSM_SignDataFinal for the CSSM API
CSP_SignDataFinal for the CSP SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_SignDataFinal
    (CSSM_CC_HANDLE CCHandle,
    CSSM_DATA_PTR Signature)

SPI:
CSSM_RETURN CSSMCSPI CSP_SignDataFinal
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    CSSM_DATA_PTR Signature)

DESCRIPTION

This function completes the final stage of the sign data function.

API PARAMETERS

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.

ADDITIONAL SPI PARAMETER

CSPHandle (input)

The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

RETURN VALUE

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.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CSP_OUTPUT_LENGTH_ERROR

COMMENTS FOR API

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.

COMMENTS FOR SPI

The output is returned to the caller as specifed in Buffer Management for Cryptographic Services.

SEE ALSO


For the CSSM API:
CSSM_SignData()
CSSM_SignDataInit()
CSSM_SignDataUpdate()


For the CSP SPI:
CSP_SignData()
CSP_SignDataInit()
CSP_SignDataUpdate()

Previous section.

NAME

CSSM_VerifyData for the CSSM API
CSP_VerifyData for the CSP SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_VerifyData
    (CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *DataBufs,
    uint32 DataBufCount,
    CSSM_ALGORITHMS DigestAlgorithm,
    const CSSM_DATA *Signature)

SPI:
CSSM_RETURN CSSMCSPI CSP_VerifyData
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context,
    const CSSM_DATA *DataBufs,
    uint32 DataBufCount,
    CSSM_ALGORITHMS DigestAlgorithm,
    const CSSM_DATA *Signature)

DESCRIPTION

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.

API PARAMETERS

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.

ADDITIONAL SPI PARAMETERS

CSPHandle (input)

The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

Context (input)

Pointer to CSSM_CONTEXT structure that describes the attributes with this context.

RETURN VALUE

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.

ERRORS

See 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

SEE ALSO


For the CSSM API:
CSSM_SignData()
CSSM_VerifyDataInit()
CSSM_VerifyDataUpdate()
CSSM_VerifyDataFinal()


For the CSP SPI:
CSP_SignData()
CSP_VerifyDataInit()
CSP_VerifyDataUpdate()
CSP_VerifyDataFinal()

Previous section.

NAME

CSSM_VerifyDataInit for the CSSM API
CSP_VerifyDataInit for the CSP SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_VerifyDataInit
    (CSSM_CC_HANDLE CCHandle)

SPI:
CSSM_RETURN CSSMCSPI CSP_VerifyDataInit
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context)

DESCRIPTION

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.

API PARAMETERS

CCHandle (input)

The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.

ADDITIONAL SPI PARAMETERS

CSPHandle (input)

The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

Context (input)

Pointer to CSSM_CONTEXT structure that describes the attributes with this context.

RETURN VALUE

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.

ERRORS

None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO


For the CSSM API:
CSSM_VerifyDataUpdate()
CSSM_VerifyDataFinal()
CSSM_VerifyData()


For the CSP SPI:
CSP_VerifyDataUpdate()
CSP_VerifyDataFinal()
CSP_VerifyData()

Previous section.

NAME

CSSM_VerifyDataUpdate for the CSSM API
CSP_VerifyDataUpdate for the CSP SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_VerifyDataUpdate
    (CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *DataBufs,
    uint32 DataBufCount)

SPI:
CSSM_RETURN CSSMCSPI CSP_VerifyDataUpdate
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *DataBufs,
    uint32 DataBufCount)

DESCRIPTION

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.

API PARAMETERS

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.

ADDITIONAL SPI PARAMETER

CSPHandle (input)

The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

RETURN VALUE

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.

ERRORS

None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO


For the CSSM API:
CSSM_VerifyData()
CSSM_VerifyDataInit()
CSSM_VerifyDataFinal()



For the CSP SPI:
CSP_VerifyData()
CSP_VerifyDataInit()
CSP_VerifyDataFinal()

Previous section.

NAME

CSSM_VerifyDataFinal for the CSSM API
CSP_VerifyDataFinal for the CSP SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_VerifyDataFinal
    (CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *Signature)

SPI:
CSSM_BOOL CSSMCSPI CSP_VerifyDataFinal
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *Signature)

DESCRIPTION

This function finalizes the staged verify data function.

API PARAMETERS

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.

ADDITIONAL SPI PARAMETER

CSPHandle (input)

The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

RETURN VALUE

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.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.


CSSMERR_CSP_INPUT_LENGTH_ERROR
CSSMERR_CSP_VERIFY_FAILED
CSSMERR_CSP_INVALID_SIGNATURE

SEE ALSO


For the CSSM API:
CSSM_VerifyData()
CSSM_VerifyDataInit()
CSSM_VerifyDataUpdate()


For the CSP SPI:
CSP_VerifyData()
CSP_VerifyDataInit()
CSP_VerifyDataUpdate()

Previous section.

NAME

CSSM_DigestData for the CSSM API
CSP_DigestData for the CSP SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_DigestData
    (CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *DataBufs,
    uint32 DataBufCount,
    CSSM_DATA_PTR Digest)

SPI:
CSSM_RETURN CSSMCSPI CSP_DigestData
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context,
    const CSSM_DATA *DataBufs,
    uint32 DataBufCount,
    CSSM_DATA_PTR Digest)

DESCRIPTION

This function computes a message digest for all data contained in the set of input buffers.

API PARAMETERS

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.

ADDITIONAL SPI PARAMETERS

CSPHandle (input)

The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

Context (input)

Pointer to CSSM_CONTEXT structure that describes the attributes with this context.

RETURN VALUE

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.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CSP_OUTPUT_LENGTH_ERROR

COMMENTS FOR API

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.

COMMENTS FOR SPI

The output is returned to the caller as specifed in Buffer Management for Cryptographic Services.

SEE ALSO


For the CSSM API:
CSSM_DigestDataInit()
CSSM_DigestDataUpdate()
CSSM_DigestDataFinal()
CSSM_DigestDataClone()


For the CSP SPI:
CSP_DigestDataInit()
CSP_DigestDataUpdate()
CSP_DigestDataFinal()
CSP_DigestDataClone()

Previous section.

NAME

CSSM_DigestDataInit for the CSSM API
CSP_DigestDataInit for the CSP SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_DigestDataInit
    (CSSM_CC_HANDLE CCHandle)

SPI:
CSSM_RETURN CSSMCSPI CSP_DigestDataInit
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context)

DESCRIPTION

This function initializes the staged message digest function.

API PARAMETERS

CCHandle (input)

The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.

ADDITIONAL SPI PARAMETERS

CSPHandle (input)

The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

Context (input)

Pointer to CSSM_CONTEXT structure that describes the attributes with this context.

RETURN VALUE

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.

ERRORS

None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO


For the CSSM API:
CSSM_DigestData()
CSSM_DigestDataUpdate()
CSSM_DigestDataClone()
CSSM_DigestDataFinal()


For the CSP SPI:
CSP_DigestData()
CSP_DigestDataUpdate()
CSP_DigestDataClone()
CSP_DigestDataFinal()

Previous section.

NAME

CSSM_DigestDataUpdate for the CSSM API
CSP_DigestDataUpdate

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_DigestDataUpdate
    (CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *DataBufs,
    uint32 DataBufCount)

SPI:
CSSM_RETURN CSSMCSPI CSP_DigestDataUpdate
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *DataBufs,
    uint32 DataBufCount)

DESCRIPTION

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.

API PARAMETERS

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.

ADDITIONAL SPI PARAMETER

CSPHandle (input)

The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

RETURN VALUE

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.

ERRORS

None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO


For the CSSM API:
CSSM_DigestData()
CSSM_DigestDataInit()
CSSM_DigestDataClone()
CSSM_DigestDataFinal()



For the CSP SPI:
CSP_DigestData()
CSP_DigestDataInit()
CSP_DigestDataClone()
CSP_DigestDataFinal()

Previous section.

NAME

CSSM_DigestDataClone for the CSSM API
CSP_DigestDataClone for the CSP SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_DigestDataClone
    (CSSM_CC_HANDLE CCHandle,
    CSSM_CC_HANDLE *ClonednewCCHandle)

SPI:
CSSM_RETURN CSSMCSPI CSP_DigestDataClone
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    CSSM_CC_HANDLE ClonednewCCHandle)

DESCRIPTION

This function clones a given staged message digest context with its cryptographic attributes and intermediate result.

API PARAMETERS

CCHandle (input)

The handle that describes the context of a staged message digest operation.

ClonednewCCHandle (output)

The cloned digest context handle. The handle will be set to CSSM_INVALID_HANDLE if the function fails.

ADDITIONAL SPI PARAMETER

CSPHandle (input)

The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

RETURN VALUE

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.

ERRORS

None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

COMMENTS

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.

SEE ALSO


For the CSSM API:
CSSM_DigestData()
CSSM_DigestDataInit()
CSSM_DigestDataUpdate()
CSSM_DigestDataFinal()



For the CSP SPI:
CSP_DigestData()
CSP_DigestDataInit()
CSP_DigestDataUpdate()
CSP_DigestDataFinal()

Previous section.

NAME

CSSM_DigestDataFinal for the CSSM API
CSP_DigestDataFinal for the CSP SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_DigestDataFinal
    (CSSM_CC_HANDLE CCHandle,
    CSSM_DATA_PTR Digest)

SPI:
CSSM_RETURN CSSMCSPI CSP_DigestDataFinal
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    CSSM_DATA_PTR Digest)

DESCRIPTION

This function finalizes the staged message digest function.

API PARAMETERS

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.

ADDITIONAL SPI PARAMETER

CSPHandle (input)

The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

RETURN VALUE

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.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CSP_OUTPUT_LENGTH_ERROR

COMMENTS FOR API

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.

COMMENTS FOR SPI

The output is returned to the caller as specified in Buffer Management for Cryptographic Services.

SEE ALSO


For the CSSM API:
CSSM_DigestData()
CSSM_DigestDataInit()
CSSM_DigestDataUpdate()
CSSM_DigestDataClone()


For the CSP SPI:
CSP_DigestData()
CSP_DigestDataInit()
CSP_DigestDataUpdate()
CSP_DigestDataClone()

Previous section.

NAME

CSSM_GenerateMac for the CSSM API
CSP_GenerateMac for the CSP SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_GenerateMac
    (CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *DataBufs,
    uint32 DataBufCount,
    CSSM_DATA_PTR Mac)

SPI:
CSSM_RETURN CSSMCSPI CSP_GenerateMac
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context,
    const CSSM_DATA *DataBufs,
    uint32 DataBufCount,
    CSSM_DATA_PTR Mac)

DESCRIPTION

This function computes a message authentication code for all data contained in the set of input buffers.

API PARAMETERS

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_DATA structure for the Message Authentication Code.

ADDITIONAL SPI PARAMETERS

CSPHandle (input)

The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

Context (input)

Pointer to CSSM_CONTEXT structure that describes the attributes with this context.

RETURN VALUE

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.

ERRORS

See the Error Codes and Error Values section earlier in this Chapter.

CSSMERR_CSP_OUTPUT_LENGTH_ERROR

API COMMENTS

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.

SPI COMMENTS

The output is returned to the caller as specified in Buffer Management for Cryptographic Services.

SEE ALSO


For the CSSM API:
CSSM_GenerateMacInit()
CSSM_GenerateMacUpdate()
CSSM_GenerateMacFinal()


For the CSP SPI:
CSP_GenerateMacInit()
CSP_GenerateMacUpdate()
CSP_GenerateMacFinal()

Previous section.

NAME

CSSM_GenerateMacInit for the CSSM API
CSP_GenerateMacInit for the CSP SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_GenerateMacInit
    (CSSM_CC_HANDLE CCHandle)

SPI:
CSSM_RETURN CSSMCSPI CSP_GenerateMacInit
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context)

DESCRIPTION

This function initializes the staged message authentication code function.

API PARAMETER

CCHandle (input)

The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.

ADDITIONAL SPI PARAMETERS

CSPHandle (input)

The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

Context (input)

Pointer to CSSM_CONTEXT structure that describes the attributes with this context.

RETURN VALUE

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.

ERRORS

None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

SEE ALSO


For the CSSM API:
CSSM_GenerateMac()
CSSM_GenerateMacUpdate()
CSSM_GenerateMacFinal()


For the CSP SPI:
CSP_GenerateMac()
CSP_GenerateMacUpdate()
CSP_GenerateMacFinal()

Previous section.

NAME

CSSM_GenerateMacUpdate for the CSSM API
CSP_GenerateMacUpdate for the CSP SPI

SYNOPSIS


API:
CSSM_RETURN CSSMAPI CSSM_GenerateMacUpdate
    (CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *DataBufs,
    uint32 DataBufCount)

SPI:
CSSM_RETURN CSSMCSPI CSP_GenerateMacUpdate
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *DataBufs,
    uint32 DataBufCount)

DESCRIPTION

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.

API PARAMETERS

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.

ADDITIONAL SPI PARAMETER

CSPHandle (input)

The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

    • RETURN VALUE

    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.

    ERRORS

    None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

    SEE ALSO


    For the CSSM API:
    CSSM_GenerateMac()
    CSSM_GenerateMacInit()
    CSSM_GenerateMacFinal()



    For the CSP SPI:
    CSP_GenerateMac()
    CSP_GenerateMacInit()
    CSP_GenerateMacFinal()

    Previous section.

    NAME

    CSSM_GenerateMacFinal for the CSSM API
    CSP_GenerateMacFinal for the CSP SPI

    SYNOPSIS

    
API:
CSSM_RETURN CSSMAPI CSSM_GenerateMacFinal
    (CSSM_CC_HANDLE CCHandle,
    CSSM_DATA_PTR Mac)

SPI:
CSSM_RETURN CSSMCSPI CSP_GenerateMacFinal
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    CSSM_DATA_PTR Mac)

    DESCRIPTION

    This function finalizes the staged message authentication code function.

    API PARAMETERS

    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.

    ADDITIONAL SPI PARAMETER

    CSPHandle (input)

    The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

    RETURN VALUE

    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.

    ERRORS

    See the Error Codes and Error Values section earlier in this Chapter.

    CSSMERR_CSP_OUTPUT_LENGTH_ERROR

    COMMENTS ON API

    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.

    COMMENTS ON SPI

    The output is returned to the caller as specified in Buffer Management for Cryptographic Services.

    SEE ALSO


    For the CSSM API:
    CSSM_GenerateMac()
    CSSM_GenerateMacInit()
    CSSM_GenerateMacUpdate()


    For the CSP SPI:
    CSP_GenerateMac()
    CSP_GenerateMacInit()
    CSP_GenerateMacUpdate()

    Previous section.

    NAME

    CSSM_VerifyMac for the CSSM API
    CSP_VerifyMac for the CSP SPI

    SYNOPSIS

    
API:
CSSM_RETURN CSSMAPI CSSM_VerifyMac
    (CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *DataBufs,
    uint32 DataBufCount,
    const CSSM_DATA *Mac)

SPI:
CSSM_RETURN CSSMCSPI CSP_VerifyMac
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context,
    const CSSM_DATA *DataBufs,
    uint32 DataBufCount,
    const CSSM_DATA *Mac)

    DESCRIPTION

    This function verifies the message authentication code over all data contained in the set of input buffers based on the input signature.

    API PARAMETERS

    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.

    ADDITIONAL SPI PARAMETERS

    CSPHandle (input)

    The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

    Context (input)

    Pointer to CSSM_CONTEXT structure that describes the attributes with this context.

    RETURN VALUE

    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.

    ERRORS

    See the Error Codes and Error Values section earlier in this Chapter.


    CSSMERR_CSP_INPUT_LENGTH_ERROR
    CSSMERR_CSP_VERIFY_FAILED
    CSSMERR_CSP_INVALID_SIGNATURE

    SEE ALSO


    For the CSSM API:
    CSSM_VerifyMacInit()
    CSSM_VerifyMacUpdate()
    CSSM_VerifyMacFinal()


    For the CSP SPI:
    CSP_VerifyMacInit()
    CSP_VerifyMacUpdate()
    CSP_VerifyMacFinal()

    Previous section.

    NAME

    CSSM_VerifyMacInit for the CSSM API
    CSP_VerifyMacInit for the CSP SPI

    SYNOPSIS

    
API:
CSSM_RETURN CSSMAPI CSSM_VerifyMacInit
    (CSSM_CC_HANDLE CCHandle)

SPI:
CSSM_RETURN CSSMCSPI CSP_VerifyMacInit
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context)

    DESCRIPTION

    This function initializes the staged message authentication code verification function.

    API PARAMETER

    CCHandle (input)

    The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.

    ADDITIONAL SPI PARAMETERS

    CSPHandle (input)

    The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

    Context (input)

    Pointer to CSSM_CONTEXT structure that describes the attributes with this context.

    RETURN VALUE

    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.

    ERRORS

    None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

    SEE ALSO


    For the CSSM API:
    CSSM_VerifyMac()
    CSSM_VerifyMacUpdate()
    CSSM_VerifyMacFinal()


    For the CSP SPI:
    CSP_VerifyMac()
    CSP_VerifyMacUpdate()
    CSP_VerifyMacFinal()

    Previous section.

    NAME

    CSSM_VerifyMacUpdate for the CSSM API
    CSP_VerifyMacUpdate for the CSP SPI

    SYNOPSIS

    
API:
CSSM_RETURN CSSMAPI CSSM_VerifyMacUpdate
    (CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *DataBufs,
    uint32 DataBufCount)

SPI:
CSSM_RETURN CSSMCSPI CSP_VerifyMacUpdate
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *DataBufs,
    uint32 DataBufCount)

    DESCRIPTION

    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.

    API PARAMETERS

    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.

    ADDITIONAL SPI PARAMETER

    CSPHandle (input)

    The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

    RETURN VALUE

    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.

    ERRORS

    None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

    SEE ALSO


    For the CSSM API:
    CSSM_VerifyMac()
    CSSM_VerifyMacInit()
    CSSM_VerifyMacFinal()



    For the CSP SPI:
    CSP_VerifyMac()
    CSP_VerifyMacInit()
    CSP_VerifyMacFinal()

    Previous section.

    NAME

    CSSM_VerifyMacFinal for the CSSM API
    CSP_VerifyMacFinal for the CSP SPI

    SYNOPSIS

    
API:
CSSM_RETURN CSSMAPI CSSM_VerifyMacFinal
    (CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *Mac)

SPI:
CSSM_RETURN CSSMCSPI CSP_VerifyMacFinal
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *Mac)

    DESCRIPTION

    This function finalizes the staged message authentication code verification function.

    API PARAMETERS

    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.

    ADDITIONAL SPI PARAMETER

    CSPHandle (input)

    The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

    RETURN VALUE

    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.

    ERRORS

    See the Error Codes and Error Values section earlier in this Chapter.


    CSSMERR_CSP_INPUT_LENGTH_ERROR
    CSSMERR_CSP_VERIFY_FAILED
    CSSMERR_CSP_INVALID_SIGNATURE

    COMMENTS FOR SPI

    The output is returned to the caller as specified in Buffer Management for Cryptographic Services.

    SEE ALSO


    For the CSSM API:
    CSSM_VerifyMac()
    CSSM_VerifyMacInit()
    CSSM_VerifyMacUpdate()


    For the CSP SPI:
    CSP_VerifyMac()
    CSP_VerifyMacInit()
    CSP_VerifyMacUpdate()

    Previous section.

    NAME

    CSSM_QuerySize for the CSSM API
    CSP_QuerySize for the CSP SPI

    SYNOPSIS

    
API:
CSSM_RETURN CSSMAPI CSSM_QuerySize
    (CSSM_CC_HANDLE CCHandle,
    CSSM_BOOL Encrypt,
    uint32 QuerySizeCount,
    CSSM_QUERY_SIZE_DATA_PTR DataBlockSizes)

SPI:
CSSM_RETURN CSSMCSPI CSP_QuerySize
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context,
    CSSM_BOOL Encrypt,
    uint32 QuerySizeCount,
    CSSM_QUERY_SIZE_DATA_PTR DataBlockSizes)

    DESCRIPTION

    This function queries for the size of the output data for a cryptographic operation. If the context is an encryption or decryption context type then the Encrypt parameter will determine which operation is being performed. If Encrypt is set to CSSM_TRUE then 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.

    API PARAMETERS

    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.

    ADDITIONAL SPI PARAMETERS

    CSPHandle (input)

    The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

    Context (input)

    Pointer to CSSM_CONTEXT structure that describes the attributes with this context.

    RETURN VALUE

    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.

    ERRORS

    See the Error Codes and Error Values section earlier in this Chapter.

    CSSMERR_CSP_QUERY_SIZE_UNKNOWN

    SEE ALSO


    For the CSSM API:
    CSSM_EncryptData()
    CSSM_EncryptDataUpdate()
    CSSM_DecryptData()
    CSSM_DecryptDataUpdate()
    CSSM_SignData()
    CSSM_VerifyData()
    CSSM_DigestData()
    CSSM_GenerateMac()


    For the CSP SPI:
    CSP_EncryptData()
    CSP_EncryptDataUpdate()
    CSP_DecryptData()
    CSP_DecryptDataUpdate()
    CSP_SignData()
    CSP_VerifyData()
    CSP_DigestData()
    CSP_GenerateMac()

    Previous section.

    NAME

    CSSM_EncryptData for the CSSM API
    CSP_EncryptData for the CSP SPI

    SYNOPSIS

    
API:
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)

SPI:
CSSM_RETURN CSSMCSPI CSP_EncryptData
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context,
    const CSSM_DATA *ClearBufs,
    uint32 ClearBufCount,
    CSSM_DATA_PTR CipherBufs,
    uint32 CipherBufCount,
    uint32 *bytesEncrypted,
    CSSM_DATA_PTR RemData,
    CSSM_PRIVILEGE Privilege)

    DESCRIPTION

    This function encrypts all data contained in the set of input buffers using information in the context. The CSSM_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.

    API PARAMETERS

    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.

    ADDITIONAL SPI PARAMETERS

    CSPHandle (input)

    The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

    Context (input)

    Pointer to CSSM_CONTEXT structure that describes the attributes with this context.

    Privilege (input)

    The export privilege to be applied during the cryptographic operation. This parameter is forwarded to the CSP after CSSM verifies the caller and service provider privilege set includes the specified PRIVILEGE.

    RETURN VALUE

    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.

    ERRORS

    See the Error Codes and Error Values section earlier in this Chapter.


    CSSMERR_CSP_BLOCK_SIZE_MISMATCH
    CSSMERR_CSP_OUTPUT_LENGTH_ERROR

    COMMENTS FOR API

    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. In-place encryption can be done by supplying the same input and output buffers.

    COMMENTS FOR SPI

    The output is returned to the caller as specified in Buffer Management for Cryptographic Services.

    SEE ALSO


    For the CSSM API:
    CSSM_QuerySize()
    CSSM_DecryptData()
    CSSM_EncryptDataInit()
    CSSM_EncryptDataUpdate()
    CSSM_EncryptDataFinal()
    CSSM_EncryptDataP()
    CSSM_EncryptDataInitP()
    CSSM_DecryptP()
    CSSM_DecryptDataInitP()


    For the CSP SPI:
    CSP_QuerySize()
    CSP_DecryptData()
    CSP_EncryptDataInit()
    CSP_EncryptDataUpdate()
    CSP_EncryptDataFinal()

    Previous section.

    NAME

    CSSM_EncryptDataP

    SYNOPSIS

    
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)

    DESCRIPTION

    This function is similar to CSSM_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.

    PARAMETERS

    See CSSM_EncryptData().

    Privilege (input)

    The privilege to be applied during the cryptographic operation.

    RETURN VALUE

    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.

    ERRORS

    See the Error Codes and Error Values section earlier in this Chapter.


    CSSMERR_CSP_BLOCK_SIZE_MISMATCH
    CSSMERR_CSP_OUTPUT_LENGTH_ERROR

    SEE ALSO


    CSSM_QuerySize()
    CSSM_DecryptData()
    CSSM_EncryptDataInit()
    CSSM_EncryptDataUpdate()
    CSSM_EncryptDataFinal()
    CSSM_EncryptDataP()
    CSSM_EncryptDataInitP()
    CSSM_DecryptP()
    CSSM_DecryptDataInitP()
    Previous section.

    NAME

    CSSM_EncryptDataInit for the CSSM API
    CSP_EncryptDataInit for the CSP SPI

    SYNOPSIS

    
API:
CSSM_RETURN CSSMAPI CSSM_EncryptDataInit
    (CSSM_CC_HANDLE CCHandle)

SPI:
CSSM_RETURN CSSMCSPI CSP_EncryptDataInit
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context,
    CSSM_PRIVILEGE Privilege)

    DESCRIPTION

    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.

    API PARAMETER

    CCHandle (input)

    The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.

    ADDITIONAL SPI PARAMETERS

    CSPHandle (input)

    The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

    Context (input)

    Pointer to CSSM_CONTEXT structure that describes the attributes with this context.

    Privilege (input)

    The export privilege to be applied during the cryptographic operation. This parameter is forwarded to the CSP after CSSM verifies the caller and service provider privilege set includes the specified PRIVILEGE.

    RETURN VALUE

    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.

    ERRORS

    None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

    SEE ALSO


    For the CSSM API:
    CSSM_QuerySize()
    CSSM_DecryptData()
    CSSM_EncryptDataInit()
    CSSM_EncryptDataUpdate()
    CSSM_EncryptDataFinal()
    CSSM_EncryptDataP()
    CSSM_EncryptDataInitP()
    CSSM_DecryptP()
    CSSM_DecryptDataInitP()


    For the CSP SPI:
    CSP_QuerySize()
    CSP_DecryptData()
    CSP_EncryptDataInit()
    CSP_EncryptDataUpdate()
    CSP_EncryptDataFinal()

    Previous section.

    NAME

    CSSM_EncryptDataInitP

    SYNOPSIS

    
CSSM_RETURN CSSMAPI CSSM_EncryptDataInitP
    (CSSM_CC_HANDLE CCHandle,
    CSSM_PRIVILEGE Privilege)

    DESCRIPTION

    This function similar to CSSM_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 functions CSSM_EncryptDataUpdate() and CSSM_EncryptDataFinalize() are used.

    PARAMETERS

    See CSSM_EncryptDataInit().

    Privilege (input)

    The privilege to be applied during the cryptographic operation.

    RETURN VALUE

    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.

    ERRORS

    See CSSM_EncryptDataInit().

    SEE ALSO


    CSSM_QuerySize()
    CSSM_DecryptData()
    CSSM_EncryptDataInit()
    CSSM_EncryptDataUpdate()
    CSSM_EncryptDataFinal()
    CSSM_EncryptDataP()
    CSSM_EncryptDataInitP()
    CSSM_DecryptP()
    CSSM_DecryptDataInitP()
    Previous section.

    NAME

    CSSM_EncryptDataUpdate for the CSSM API
    CSP_EncryptDataUpdate for the CSP SPI

    SYNOPSIS

    
API:
CSSM_RETURN CSSMAPI CSSM_EncryptDataUpdate
    (CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *ClearBufs,
    uint32 ClearBufCount,
    CSSM_DATA_PTR CipherBufs,
    uint32 CipherBufCount,
    uint32 *bytesEncrypted)

SPI:
CSSM_RETURN CSSMCSPI CSP_EncryptDataUpdate
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *ClearBufs,
    uint32 ClearBufCount,
    CSSM_DATA_PTR CipherBufs,
    uint32 CipherBufCount,
    uint32 *bytesEncrypted)

    DESCRIPTION

    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 in CSSM_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. The CSSM_QuerySize() function can be used to estimate the output buffer size required for each update call.

    API PARAMETERS

    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.

    ADDITIONAL SPI PARAMETER

    CSPHandle (input)

    The handle that describes the add-in cryptographic service provider module used to perform up-calls to CSSM for the memory functions managed by CSSM.

    RETURN VALUE

    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.

    ERRORS

    None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

    COMMENTS FOR API

    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. In-place encryption can be done by supplying the same input and output buffers.

    COMMENTS FOR SPI

    The output is returned to the caller as specified in Buffer Management for Cryptographic Services.

    SEE ALSO


    For the CSSM API:
    CSSM_QuerySize()
    CSSM_DecryptData()
    CSSM_EncryptDataInit()
    CSSM_EncryptDataUpdate()
    CSSM_EncryptDataFinal()
    CSSM_EncryptDataP()
    CSSM_EncryptDataInitP()
    CSSM_DecryptP()
    CSSM_DecryptDataInitP()


    For the CSP SPI:
    CSP_QuerySize()
    CSP_DecryptData()
    CSP_EncryptDataInit()
    CSP_EncryptDataFinal()

    Previous section.

    NAME

    CSSM_EncryptDataFinal for the CSSM API
    CSP_EncryptDataFinal for the CSP SPI

    SYNOPSIS

    
API:
CSSM_RETURN CSSMAPI CSSM_EncryptDataFinal
    (CSSM_CC_HANDLE CCHandle,
    CSSM_DATA_PTR RemData)

SPI:
CSSM_RETURN CSSMCSPI CSP_EncryptDataFinal
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    CSSM_DATA_PTR RemData)

    DESCRIPTION

    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.

    API PARAMETERS

    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.

    ADDITIONAL SPI PARAMETER

    CSPHandle (input)

    The handle that describes the add-in cryptographic service provider module used to perform up-calls to CSSM for the memory functions managed by CSSM.

    RETURN VALUE

    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.

    ERRORS

    See the Error Codes and Error Values section earlier in this Chapter.


    CSSMERR_CSP_BLOCK_SIZE_MISMATCH
    CSSMERR_CSP_OUTPUT_LENGTH_ERROR

    COMMENTS FOR API

    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.

    COMMENTS FOR SPI

    The output is returned to the caller as specified in Buffer Management for Cryptographic Services.

    SEE ALSO


    For the CSSM API:
    CSSM_QuerySize()
    CSSM_DecryptData()
    CSSM_EncryptDataInit()
    CSSM_EncryptDataUpdate()
    CSSM_EncryptDataFinal()
    CSSM_EncryptDataP()
    CSSM_EncryptDataInitP()
    CSSM_DecryptP()
    CSSM_DecryptDataInitP()


    For the CSP SPI:
    CSP_EncryptData()
    CSP_EncryptDataInit()
    CSP_EncryptDataUpdate()

    Previous section.

    NAME

    CSSM_DecryptData for the CSSM API
    CSP_DecryptData for the CSP SPI

    SYNOPSIS

    
API:
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)

SPI:
CSSM_RETURN CSSMCSPI CSP_DecryptData
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context,
    const CSSM_DATA *CipherBufs,
    uint32 CipherBufCount,
    CSSM_DATA_PTR ClearBufs,
    uint32 ClearBufCount,
    uint32 *bytesDecrypted,
    CSSM_DATA_PTR RemData,
    CSSM_PRIVILEGE Privilege)

    DESCRIPTION

    This function decrypts all data contained in the set of input buffers using information in the context. The CSSM_QuerySize() (CSSM API) or CSP_QuerySize() (CSP SPI) 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.

    API PARAMETERS

    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.

    ADDITIONAL SPI PARAMETERS

    CSPHandle (input)

    The handle that describes the add-in cryptographic service provider module used to perform up-calls to CSSM for the memory functions managed by CSSM.

    Context (input)

    Pointer to CSSM_CONTEXT structure that describes the attributes with this context.

    Privilege (input)

    The export privilege to be applied during the cryptographic operation. This parameter is forwarded to the CSP after CSSM verifies the caller and service provider privilege set includes the specified PRIVILEGE.

    RETURN VALUE

    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.

    ERRORS

    See the Error Codes and Error Values section earlier in this Chapter.


    CSSMERR_CSP_BLOCK_SIZE_MISMATCH
    CSSMERR_CSP_OUTPUT_LENGTH_ERROR

    COMMENTS FOR API

    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. In-place decryption can be done by supplying the same input and output buffers.

    COMMENTS FOR SPI

    The output is returned to the caller a specified in Buffer Management for Cryptographic Services.

    SEE ALSO


    For the CSSM API:
    CSSM_QuerySize()
    CSSM_EncryptData()
    CSSM_DecryptDataInit()
    CSSM_DecryptDataUpdate()
    CSSM_DecryptDataFinal()
    CSSM_DecryptP()
    CSSM_DecryptDataInitP()


    For the CSP SPI:
    CSP_QuerySize()
    CSP_EncryptData()
    CSP_DecryptDataInit()
    CSP_DecryptDataUpdate()
    CSP_DecryptDataFinal()

    Previous section.

    NAME

    CSSM_DecryptDataP

    SYNOPSIS

    
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)

    DESCRIPTION

    This function similar to CSSM_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.

    PARAMETERS

    See CSSM_DecryptData().

    Privilege (input)

    The privilege to be applied during the cryptographic operation.

    RETURN VALUE

    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.

    ERRORS

    See the Error Codes and Error Values section earlier in this Chapter.


    CSSMERR_CSP_BLOCK_SIZE_MISMATCH
    CSSMERR_CSP_OUTPUT_LENGTH_ERROR

    SEE ALSO


    CSSM_QuerySize()
    CSSM_DecryptData()
    CSSM_EncryptDataInit()
    CSSM_EncryptDataUpdate()
    CSSM_EncryptDataFinal()
    CSSM_EncryptDataP()
    CSSM_EncryptDataInitP()
    CSSM_DecryptP()
    CSSM_DecryptDataInitP()
    Previous section.

    NAME

    CSSM_DecryptDataInit for the CSSM API
    CSP_DecryptDataInit for the CSP SPI

    SYNOPSIS

    
API:
CSSM_RETURN CSSMAPI CSSM_DecryptDataInit
    (CSSM_CC_HANDLE CCHandle)

SPI:
CSSM_RETURN CSSMCSPI CSSM_CSP_DecryptDataInit
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context,
    CSSM_PRIVILEGE Privilege)

    DESCRIPTION

    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.

    API PARAMETER

    CCHandle (input)

    The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.

    ADDITIONAL SPI PARAMETERS

    CSPHandle (input)

    The handle that describes the add-in cryptographic service provider module used to perform up-calls to CSSM for the memory functions managed by CSSM.

    Context (input)

    Pointer to CSSM_CONTEXT structure that describes the attributes with this context.

    Privilege (input)

    The export privilege to be applied during the cryptographic operation. This parameter is forwarded to the CSP after CSSM verifies the caller and service provider privilege set includes the specified PRIVILEGE.

    RETURN VALUE

    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.

    ERRORS

    None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

    SEE ALSO


    For the CSSM API:
    CSSM_DecryptData()
    CSSM_DecryptDataUpdate()
    CSSM_DecryptDataFinal()
    CSSM_DecryptDataP()
    CSSM_DecryptDataInitP()


    For the CSP SPI:
    CSP_DecryptData()
    CSP_DecryptDataUpdate()
    CSP_DecryptDataFinal()

    Previous section.

    NAME

    CSSM_DecryptDataInitP

    SYNOPSIS

    
CSSM_RETURN CSSMAPI CSSM_DecryptDataInitP
    (CSSM_CC_HANDLE CCHandle,
    CSSM_PRIVILEGE Privilege)

    DESCRIPTION

    This function is similar to CSSM_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 functions CSSM_DecryptDataUpdate() and CSSM_DecryptDataFinalize() are used.

    PARAMETERS

    See CSSM_DecryptDataInit().

    Privilege (input)

    The privilege to be applied during the cryptographic operation.

    RETURN VALUE

    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.

    ERRORS

    None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

    SEE ALSO


    CSSM_QuerySize()
    CSSM_DecryptData()
    CSSM_EncryptDataInit()
    CSSM_EncryptDataUpdate()
    CSSM_EncryptDataFinal()
    CSSM_EncryptDataP()
    CSSM_EncryptDataInitP()
    CSSM_DecryptP()
    CSSM_DecryptDataInitP()
    Previous section.

    NAME

    CSSM_DecryptDataUpdate for the CSSM API
    CSP_DecryptDataUpdate for the CSP SPI

    SYNOPSIS

    
API:
CSSM_RETURN CSSMAPI CSSM_DecryptDataUpdate
    (CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *CipherBufs,
    uint32 CipherBufCount,
    CSSM_DATA_PTR ClearBufs,
    uint32 ClearBufCount,
    uint32 *bytesDecrypted)

SPI:
CSSM_RETURN CSSMCSPI CSP_DecryptDataUpdate
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *CipherBufs,
    uint32 CipherBufCount,
    CSSM_DATA_PTR ClearBufs,
    uint32 ClearBufCount,
    uint32 *bytesDecrypted)

    DESCRIPTION

    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 in CSSM_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. The CSSM_QuerySize() (CSSM API) or CSP_QuerySize() (CSP SPI) function can be used to estimate the output buffer size required for each update call.

    API PARAMETERS

    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.

    ADDITIONAL SPI PARAMETER

    CSPHandle (input)

    The handle that describes the add-in cryptographic service provider module used to perform up-calls to CSSM for the memory functions managed by CSSM.

    RETURN VALUE

    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.

    ERRORS

    None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

    COMMENTS FOR API

    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. In-place decryption can be done by supplying the same input and output buffers.

    COMMENTS FOR SPI

    The output is returned to the caller as specified in Buffer Management for Cryptographic Services.

    SEE ALSO


    For the CSSM API:
    CSSM_QuerySize()
    CSSM_DecryptData()
    CSSM_DecryptDataInit()
    CSSM_DecryptDataFinal()


    For the CSP SPI:
    CSP_QuerySize()
    CSP_DecryptData()
    CSP_DecryptDataInit()
    CSP_DecryptDataFinal()

    Previous section.

    NAME

    CSSM_DecryptDataFinal for the CSSM API
    CSP_DecryptDataFinal for the CSP SPI

    SYNOPSIS

    
API:
CSSM_RETURN CSSMAPI CSSM_DecryptDataFinal
    (CSSM_CC_HANDLE CCHandle,
    CSSM_DATA_PTR RemData)

SPI:
CSSM_RETURN CSSMCSPI CSP_DecryptDataFinal
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    CSSM_DATA_PTR RemData)

    DESCRIPTION

    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.

    API PARAMETERS

    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.

    ADDITIONAL SPI PARAMETER

    CSPHandle (input)

    The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

    RETURN VALUE

    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.

    ERRORS

    See the Error Codes and Error Values section earlier in this Chapter.


    CSSMERR_CSP_BLOCK_SIZE_MISMATCH
    CSSMERR_CSP_OUTPUT_LENGTH_ERROR

    COMMENTS FOR API

    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.

    COMMENTS FOR SPI

    The output is returned to the caller as specified in Buffer Management for Cryptographic Services.

    SEE ALSO


    For the CSSM API:
    CSSM_DecryptData()
    CSSM_DecryptDataInit()
    CSSM_DecryptDataUpdate()


    For the CSP SPI:
    CSP_DecryptData()
    CSP_DecryptDataInit()
    CSP_DecryptDataUpdate()

    Previous section.

    NAME

    CSSM_QueryKeySizeInBits for the CSSM API
    CSP_QueryKeySizeInBits for the CSP SPI

    SYNOPSIS

    
API:
CSSM_RETURN CSSMAPI CSSM_QueryKeySizeInBits
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_KEY *Key,
    CSSM_KEY_SIZE_PTR KeySize)

SPI:
CSSM_RETURN CSSMCSPI CSP_QueryKeySizeInBits
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context,
    const CSSM_KEY *Key,
    CSSM_KEY_SIZE_PTR KeySize)

    DESCRIPTION

    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.

    API PARAMETERS

    CSPHandle (input/optional)

    The handle that describes the cryptographic service provider module used to perform this function.

    For the API, 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.

    For the API, if no context handle is provided, only the CSSM_KEY_SIZE LogicalKeySizeInBits field is set.

    ADDITIONAL SPI PARAMETER

    Context (input)

    Pointer to CSSM_CONTEXT structure that describes the attributes with this context.

    RETURN VALUE

    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.

    ERRORS

    See the Error Codes and Error Values section earlier in this Chapter.

    CSSMERR_CSP_QUERY_SIZE_UNKNOWN

    SEE ALSO


    For the CSSM API:
    CSSM_GenerateRandom()
    CSSM_GenerateKeyPair()
    CSSM_GenerateKey()


    For the CSP SPI:
    CSP_GenerateRandom()
    CSP_GenerateKeyPair()
    CSP_GenerateKey()

    Previous section.

    NAME

    CSSM_GenerateKey for the CSSM API
    CSP_GenerateKey for the CSP SPI

    SYNOPSIS

    
API:
CSSM_RETURN CSSMAPI CSSM_GenerateKey
    (CSSM_CC_HANDLE CCHandle,
    uint32 KeyUsage,
    uint32 KeyAttr,
    const CSSM_DATA *KeyLabel,
    const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry,
    CSSM_KEY_PTR Key)

SPI:
CSSM_RETURN CSSMCSPI CSP_GenerateKey
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context,
    uint32 KeyUsage,
    uint32 KeyAttr,
    const CSSM_DATA *KeyLabel,
    const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry,
    CSSM_KEY_PTR Key)

    DESCRIPTION

    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 the CSSM_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:

    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.

    API PARAMETERS

    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.

    KeyLabel (input/optional)

    Pointer to a byte string that will be used as the label for the 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.

    ADDITIONAL/CHANGED SPI PARAMETERS

    CSPHandle (input)

    The handle that describes the add-in cryptographic service provider module used to perform up-calls to CSSM for the memory functions managed by CSSM.

    Context (input)

    Pointer to CSSM_CONTEXT structure that describes the attributes with this context.

    Key (output)

    Pointer to CSSM_KEY structure used to obtain the key. Upon function invocation, any values in the CSSM_Key structure should be ignored. All input values should be supplied in the cryptographic Context, KeyUsage, KeyAttr, and KeyLabel input parameters.

    RETURN VALUE

    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.

    ERRORS

    See the Error Codes and Error Values section earlier in this Chapter.

    CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS

    COMMENTS

    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() (CSSM API) or CSP_FreeKey() (CSP SPI) call, or with the memory functions registered for the CSPHandle.

    SEE ALSO


    For the CSSM API:
    CSSM_GenerateRandom()
    CSSM_GenerateKeyPair()


    For the CSP SPI:
    CSP_GenerateRandom()
    CSP_GenerateKeyPair()

    Previous section.

    NAME

    CSSM_GenerateKeyP

    SYNOPSIS

    
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)

    DESCRIPTION

    This function is similar to CSSM_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.

    PARAMETERS

    See CSSM_GenerateKey().

    Privilege (input)

    The privilege to be applied during the cryptographic operation.

    RETURN VALUE

    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.

    ERRORS

    See CSSM_GenerateKey().

    SEE ALSO


    CSSM_GenerateRandom()
    CSSM_GenerateKeyPairP()
    Previous section.

    NAME

    CSSM_GenerateKeyPair for the CSSM API
    CSP_GenerateKeyPair for the CSP SPI

    SYNOPSIS

    
API:
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)

SPI:
CSSM_RETURN CSSMCSPI CSP_GenerateKeyPair
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context,
    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)

    DESCRIPTION

    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:

    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.

    API PARAMETERS

    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)

    Pointer to a byte string that will be used as the label for the 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)

    Pointer to a byte string that will be used as the label for the private 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.

    PrivateKey (output)

    Pointer to CSSM_KEY structure used to obtain the private key. Upon function invocation, any values in the CSSM_Key structure should be ignored. All input values should be supplied in the cryptographic Context, PrivateKeyUsage, PrivateKeyAttr, and PrivateKeyLabel input parameters.

    ADDITIONAL SPI PARAMETERS

    CSPHandle (input)

    The handle that describes the add-in cryptographic service provider module used to perform up-calls to CSSM for the memory functions managed by CSSM.

    CCHandle (input)

    The handle that describes the context of this cryptographic operation used to link to the CSP-managed information.

    Context (input)

    Pointer to CSSM_CONTEXT structure that describes the attributes with this context.

    Privilege (input)

    The export privilege to be applied during the cryptographic operation. This parameter is forwarded to the CSP after CSSM verifies the caller and service provider privilege set includes the specified privilege.

    RETURN VALUE

    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.

    ERRORS

    See the Error Codes and Error Values section earlier in this Chapter.

    CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS

    COMMENTS

    The KeyData fields of the CSSM_KEY structures are allocated by the CSP. The application is required to free this memory using the CSSM_FreeKey() (CSSM API) or CSP_FreeKey() (CSP SPI) call, or with the memory functions registered for the CSPHandle.

    SEE ALSO


    For the CSSM API:
    CSSM_GenerateKey()
    CSSM_GenerateRandom()


    For the CSP SPI:
    CSP_GenerateKey()
    CSP_GenerateRandom()

    Previous section.

    NAME

    CSSM_GenerateKeyPairP

    SYNOPSIS

    
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)

    DESCRIPTION

    This function is similar to CSSM_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.

    PARAMETERS

    See CSSM_GenerateKeyPair().

    Privilege (input)

    The privilege to be applied during the cryptographic operation.

    RETURN VALUE

    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.

    ERRORS

    See the Error Codes and Error Values section earlier in this Chapter.

    CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS

    SEE ALSO

    CSSM_GenerateKeyPair().
    Previous section.

    NAME

    CSSM_GenerateRandom for the CSSM API
    CSP_GenerateRandom for the CSP SPI

    SYNOPSIS

    
API:
CSSM_RETURN CSSMAPI CSSM_GenerateRandom
    (CSSM_CC_HANDLE CCHandle,
    CSSM_DATA_PTR RandomNumber)

SPI:
CSSM_RETURN CSSMCSPI CSP_GenerateRandom
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context,
    CSSM_DATA_PTR RandomNumber)

    DESCRIPTION

    This function generates random data.

    API PARAMETERS

    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.

    ADDITIONAL SPI PARAMETERS

    CSPHandle (input)

    The handle that describes the add-in cryptographic service provider module used to perform up-calls to CSSM for the memory functions managed by CSSM.

    Context (input)

    Pointer to CSSM_CONTEXT structure that describes the attributes with this context.

    RETURN VALUE

    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.

    ERRORS

    None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

    COMMENTS FOR API

    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.

    COMMENTS FOR SPI

    The output is returned to the caller as specified in Buffer Management for Cryptographic Services.
    Previous section.

    NAME

    CSSM_CSP_ObtainPrivateKeyFromPublicKey for the CSSM API
    CSP_ObtainPrivateKeyFromPublicKey for the CSP SPI

    SYNOPSIS

    
API:
CSSM_RETURN CSSMAPI CSSM_CSP_ObtainPrivateKeyFromPublicKey
    (CSSM_CSP_HANDLE CSPHandle,
    const CSSM_KEY *PublicKey,
    CSSM_KEY_PTR PrivateKey)

SPI:
CSSM_RETURN CSSMCSPI CSP_ObtainPrivateKeyFromPublicKey
    (CSSM_CSP_HANDLE CSPHandle,
    const CSSM_KEY *PublicKey,
    CSSM_KEY_PTR PrivateKey)

    DESCRIPTION

    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.

    API AND SPI PARAMETERS

    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.

    RETURN VALUE

    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.

    ERRORS

    See the Error Codes and Error Values section earlier in this Chapter.

    CSSMERR_CSP_PRIVATE_KEY_NOT_FOUND

    COMMENTS

    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() (CSSM API) or CSP_FreeKey() (CSP SPI) call, or with the memory functions registered for the CSPHandle.
    Previous section.

    NAME

    CSSM_WrapKey for the CSSM API
    CSP_WrapKey for the CSP SPI

    SYNOPSIS

    
API:
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)

SPI:
CSSM_RETURN CSSMCSPI CSP_WrapKey
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context,
    const CSSM_ACCESS_CREDENTIALS *AccessCred,
    const CSSM_KEY *Key,
    const CSSM_DATA *DescriptiveData,
    CSSM_WRAP_KEY_PTR WrappedKey,
    CSSM_PRIVILEGE Privilege)

    DESCRIPTION

    This function wraps the supplied key using the context. It allows a key to be exported from a CSP. Four types of wrapping exist:

    1. Wrap a symmetric key with a symmetric key.

    2. Wrap a symmetric key with an asymmetric public key.

    3. Wrap an asymmetric private key with a symmetric key.

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

    API PARAMETERS

    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.

    ADDITIONAL SPI PARAMETERS

    CSPHandle (input)

    The handle that describes the add-in cryptographic service provider module used to perform up-calls to CSSM for the memory functions managed by CSSM.

    Context (input)

    Pointer to CSSM_CONTEXT structure that describes the attributes with this context.

    Privilege (input)

    The export privilege to be applied during the cryptographic operation. This parameter is forwarded to the CSP after CSSM verifies the caller and service provider privilege set includes the specified PRIVILEGE.

    RETURN VALUE

    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.

    ERRORS

    None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

    COMMENTS

    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() (CSSM API) or CSP_FreeKey() (CSP SPI) call, or with the memory functions registered for the CSPHandle.

    SEE ALSO


    For the CSSM API:
    CSSM_UnwrapKey()


    For the CSP SPI:
    CSP_UnwrapKey()

    Previous section.

    NAME

    CSSM_WrapKeyP

    SYNOPSIS

    
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)

    DESCRIPTION

    This function is similar to CSSM_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.

    PARAMETERS

    See CSSM_WrapKey().

    Privilege (input)

    The privilege to be applied during the cryptographic operation.

    RETURN VALUE

    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.

    ERRORS

    See CSSM_WrapKey().

    COMMENTS

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

    NAME

    CSSM_UnwrapKey for the CSSM API
    CSP_UnwrapKey for the CSP SPI

    SYNOPSIS

    
API:
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) 

SPI:
CSSM_RETURN CSSMCSPI CSP_UnwrapKey
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context,
    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)

    DESCRIPTION

    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:

    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.

    API PARAMETERS

    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 unwrapped key. If no value is specified, the CSP defines the usage mask for the unwrapped key.

    KeyAttr (input)

    A bit mask defining other 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.

    ADDITIONAL SPI PARAMETERS

    CSPHandle (input)

    The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

    CCHandle (input)

    The handle that describes the context of this cryptographic operation.

    Context (input)

    Pointer to CSSM_CONTEXT structure that describes the attributes with this context.

    Privilege (input)

    The export privilege to be applied during the cryptographic operation. This parameter is forwarded to the CSP after CSSM verifies the caller and service provider privilege set includes the specified PRIVILEGE.

    RETURN VALUE

    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.

    ERRORS

    See 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

    COMMENTS

    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() (CSSM API) or CSP_FreeKey() (CSP SPI) call, or with the memory functions registered for the CSPHandle.

    SEE ALSO


    For the CSSM API:
    CSSM_WrapKey()


    For the CSP SPI:
    CSP_WrapKey()

    Previous section.

    NAME

    CSSM_UnwrapKeyP

    SYNOPSIS

    
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)

    DESCRIPTION

    This function is similar to CSSM_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.

    PARAMETERS

    See CSSM_UnwrapKey().

    Privilege (input)

    The privilege to be applied during the cryptographic operation.

    RETURN VALUE

    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.

    ERRORS

    See 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

    COMMENTS

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

    NAME

    CSSM_DeriveKey for the CSSM API
    CSP_DeriveKey for the CSP SPI

    SYNOPSIS

    
API:
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)

SPI:
CSSM_RETURN CSSMCSPI CSP_DeriveKey
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context,
    CSSM_DATA_PTR Param,
    uint32 KeyUsage,
    uint32 KeyAttr,
    const CSSM_DATA *KeyLabel,
    const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry,
    CSSM_KEY_PTR DerivedKey)

    DESCRIPTION

    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:

    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.

    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.

    API PARAMETERS

    CCHandle (input)

    The handle that describes the context of this cryptographic operation.

    Param (input/output)

    This parameter varies depending on the derivation algorithm. Password based derivation algorithms use this parameter to return a cipher block chaining initialization vector. Concatenation algorithms use this parameter to get the second item to concatenate.

    KeyUsage (input)

    A bit mask indicating all permitted uses for the new derived key.

    KeyAttr (input)

    A bit mask defining other 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.

    ADDITIONAL SPI PARAMETERS

    CSPHandle (input)

    The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

    Context (input)

    Pointer to CSSM_CONTEXT structure that describes the attributes with this context.

    RETURN VALUE

    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.

    ERRORS

    See the Error Codes and Error Values section earlier in this Chapter.

    CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS

    COMMENTS

    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() (CSSM API) or CSP_FreeKey() (CSP SPI) call, or with the memory functions registered for the CSPHandle.

    SEE ALSO


    CSSM_CSP_CreateDeriveKeyContext()
    Previous section.

    NAME

    CSSM_FreeKey for the CSSM API
    CSP_FreeKey for the CSP SPI

    SYNOPSIS

    
API:
CSSM_RETURN CSSMAPI CSSM_FreeKey
    (CSSM_CSP_HANDLE CSPHandle,
    const CSSM_ACCESS_CREDENTIALS *AccessCred,
    CSSM_KEY_PTR KeyPtr,
    CSSM_BOOL Delete)

SPI:
CSSM_RETURN CSSMCSPI CSP_FreeKey
    (CSSM_CSP_HANDLE CSPHandle,
    const CSSM_ACCESS_CREDENTIALS *AccessCred,
    CSSM_KEY_PTR KeyPtr,
    CSSM_BOOL Delete)

    DESCRIPTION

    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.

    API AND SPI PARAMETERS

    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.

    RETURN VALUE

    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.

    ERRORS

    None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
    Previous section.

    NAME

    CSSM_GenerateAlgorithmParams for the CSSM API
    CSP_GenerateAlgorithmParams for the CSP SPI

    SYNOPSIS

    
API:
CSSM_RETURN CSSMAPI CSSM_GenerateAlgorithmParams
    (CSSM_CC_HANDLE CCHandle,
    uint32 ParamBits,
    CSSM_DATA_PTR Param)

SPI:
CSSM_RETURN CSSMCSPI CSP_GenerateAlgorithmParams
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context,
    uint32 ParamBits,
    CSSM_DATA_PTR Param,
    uint32 *NumberOfUpdatedAttributes,
    CSSM_CONTEXT_ATTRIBUTE_PTR *UpdatedAttributes)

    DESCRIPTION

    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 (by returning an array of CSSM_CONTEXT_ATTRIBUTE structures), but an algorithm may return some data to the caller via the Param parameter. The generated parameters are added to the context as an attribute of type CSSM_ATTRIBUTE_ALG_PARAMS. Other attributes returned are added to the context, or replace existing values in the context.

    API PARAMETERS

    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.

    ADDITIONAL SPI PARAMETERS

    CSPHandle (input)

    The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

    Context (input)

    Pointer to CSSM_CONTEXT structure that describes the attributes with this context. Modifying this structure has no effect on the internal structure maintained by the CSSM. It is only a copy of the actual data. Changes to the context attributes must be returned using the UpdatedAttributes return parameter.

    NumberOfUpdatedAttributes (output)

    The number of CSSM_CONTEXT_ATTRIBUTE structures contained in the UpdatedAttributes array. If this value is zero, UpdatedAttributes should be set to NULL.

    UpdatedAttributes (output)

    An array of attributes that will be added to the context should be returned using this parameter. Memory for the attribute structures should be allocated using the CSSM_UPCALLS callbacks provided to the service provider module when CSSM_SPI_ModuleAttach() is called.

    RETURN VALUE

    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.

    ERRORS

    None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

    COMMENTS FOR API

    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.

    COMMENTS FOR SPI

    The output is returned to the caller as specified in Buffer Management for Cryptographic Services.

    Miscellaneous Functions

    The man-page definitions for Miscellaneous CSP functions are presented in this section.
    Previous section.

    NAME

    CSSM_CSP_GetOperationalStatistics for the CSSM API
    CSP_GetOperationalStatistics for the CSP SPI

    SYNOPSIS

    
API:
CSSM_RETURN CSSMAPI CSSM_CSP_GetOperationalStatistics
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CSP_OPERATIONAL_STATISTICS *Statistics)

SPI:
CSSM_RETURN CSSMCSPI CSSM_CSP_GetOperationalStatistics
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CSP_OPERATIONAL_STATISTICS *Statistics)

    DESCRIPTION

    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.

    API AND SPI PARAMETERS

    CSPHandle (input)

    Handle of the cryptographic service provider that will perform the operation.

    Statistics (output)

    Structure containing the subservice's current statistics.

    RETURN VALUE

    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.

    ERRORS

    None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.
    Previous section.

    NAME

    CSSM_GetTimeValue for the CSSM API
    CSP_GetTimeValue for the CSP SPI

    SYNOPSIS

    
API:
CSSM_RETURN CSSMAPI CSSM_GetTimeValue
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_ALGORITHMS TimeAlgorithm,
    CSSM_DATA *TimeData)

SPI:
CSSM_RETURN CSSMCSPI CSP_GetTimeValue
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_ALGORITHMS TimeAlgorithm,
    CSSM_DATA *TimeData)

    DESCRIPTION

    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.

    API AND SPI PARAMETERS

    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.

    RETURN VALUE

    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.

    ERRORS

    None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

    COMMENTS

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

    2. Some tokens require authentication before returning a time value.

    Previous section.

    NAME

    CSSM_RetrieveUniqueId for the CSSM API
    CSP_RetrieveUniqueId for the CSP SPI

    SYNOPSIS

    
API:
CSSM_RETURN CSSMAPI CSSM_RetrieveUniqueId
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_DATA_PTR UniqueID)

SPI:
CSSM_RETURN CSSMCSPI CSP_RetrieveUniqueId
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_DATA_PTR UniqueID)

    DESCRIPTION

    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.

    API AND SPI PARAMETERS

    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.

    RETURN VALUE

    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.

    ERRORS

    None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

    COMMENTS FOR SPI

    The output is returned to the caller as specified in Buffer Management for Cryptographic Services.
    Previous section.

    NAME

    CSSM_RetrieveCounter for the CSSM API
    CSP_RetrieveCounter for the CSP SPI

    SYNOPSIS

    
API:
CSSM_RETURN CSSMAPI CSSM_RetrieveCounter
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_DATA_PTR Counter)

SPI:
CSSM_RETURN CSSMCSPI CSP_RetrieveCounter
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_DATA_PTR Counter)

    DESCRIPTION

    This function returns the value of a tamper resistant clock/counter of the cryptographic device.

    API AND SPI PARAMETERS

    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.

    RETURN VALUE

    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.

    ERRORS

    None specific to this call. See the Error Codes and Error Values section earlier in this Chapter.

    COMMENTS FOR SPI

    The output is returned to the caller as specified in Buffer Management for Cryptographic Services.
    Previous section.

    NAME

    CSSM_VerifyDevice for the CSSM API
    CSP_VerifyDevice for the CSP SPI

    SYNOPSIS

    
API:
CSSM_RETURN CSSMAPI CSSM_VerifyDevice
    (CSSM_CSP_HANDLE CSPHandle,
    const CSSM_DATA *DeviceCert)

SPI:
CSSM_RETURN CSSMCSPI CSP_VerifyDevice
    (CSSM_CSP_HANDLE CSPHandle,
    const CSSM_DATA *DeviceCert)

    DESCRIPTION

    This function triggers the cryptographic module to perform self verification and integrity checking.

    API AND SPI PARAMETERS

    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.

    RETURN VALUE

    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.

    ERRORS

    See the Error Codes and Error Values section earlier in this Chapter.

    CSSMERR_CSP_DEVICE_VERIFY_FAILED

    Extensibility Function

    The PassThrough function is provided to allow CSP developers to extend the crypto functionality of CDSA. Because it is only exposed to CSSM as a function pointer, its name, internal to the CSP, can be assigned at the discretion of the CSP module developer. However, its parameter list and return value must match what is shown below. The error codes given in this chapter constitute the generic error codes which may be used by all CSPs to describe common error conditions.

    Previous section.

    NAME

    CSSM_CSP_PassThrough for the CSSM API
    CSP_PassThrough for the CSP SPI

    SYNOPSIS

    
API:
CSSM_RETURN CSSMAPI CSSM_CSP_PassThrough
    (CSSM_CC_HANDLE CCHandle,
    uint32 PassThroughId,
    const void *InData,
    void **OutData)

SPI:
CSSM_RETURN CSSMCSPI CSP_PassThrough
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context,
    uint32 PassThroughId,
    const void *InData,
    void **OutData)

    DESCRIPTION

    The CSSM_CSP_PassThrough() (CSSM API) or CSP_PassThrough() (CSP SPI) function is provided to allow CSP developers to extend the crypto functionality of the CSSM API.

    API PARAMETERS

    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.

    ADDITIONAL SPI PARAMETERS

    CSPHandle (input)

    Handle of the CSP supporting the PassThrough function.

    Context (input)

    Pointer to CSSM_CONTEXT structure that describes the attributes with this custom context structure.

    RETURN VALUE

    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.

    ERRORS

    See the Error Codes and Error Values section earlier in this Chapter.

    CSSMERR_CSP_INVALID_PASSTHROUGH_ID

    Module Management Function

    The CSP_EventNotify() function is used by the CSSM Core to interact with the CSP module.

    Because this function is only exposed to CSSM as a function pointer, the function name internal to the CSP can be assigned at the discretion of the CSP module developer. However, the parameter list and return value types must match those defined for this function.

    The error codes given in this section constitute the generic error codes, which may be used by all CSP libraries to describe common error conditions. CSP module developers may also define their own module-specific error codes.

    Previous section.

    NAME

    CSP_EventNotify

    SYNOPSIS

    
CSSM_RETURN CSSMCSPI CSP_EventNotify
    (CSSM_MODULE_HANDLE CSPHandle,
    CSSM_CONTEXT_EVENT Event,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context)

    DESCRIPTION

    This function is used to notify the service module of a context event related to a particular attach handle. Valid events include creation, deletion, or modification of a cryptographic context. The service module can examine the new or modified context referenced by pContext to determine whether the context is acceptable to the service module.

    If the cryptographic context is acceptable (of the service module examines the contents of the context only upon use of the context), then the service module should return CSSM_OK. If the cryptographic context is not acceptable, then the service module should return CSSM_FAIL.

    Upon receiving a return value of CSSM_OK, CSSM completes the operation signaled by this event and successfully returns to the calling application. If the return value is CSSM_FAIL, CSSM discards a newly created context or modifications to an existing context, and returns the failed result to the calling application. When deleting a cryptographic context, CSSM always returns success to the calling application.

    PARAMETERS

    CSPHandle (input)

    The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM.

    Event (input)

    One of the event types listed below:

    Event Description
    CSSM_CONTEXT_EVENT_CREATE A caller using this module attach handle has created a new cryptographic context via CSSM_Create<*>Context .
    CSSM_CONTEXT_EVENT_DELETE A caller using this module attach handle has deleted a cryptographic context via CSSM_DeleteContext().
    CSSM_CONTEXT_EVENT_UPDATE A caller using this module attach handle has updated an existing cryptographic context.

    CCHandle (input)

    The cryptographic context handle for the context affected by the Event.

    Context

    A pointer to the cryptographic context affected by the Event. The results of the Event are visible in the context.

    RETURN VALUE

    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


    CSSM_CSP_CreateSignatureContext()
    CSSM_CSP_CreateSymmetricContext()
    CSSM_CSP_CreateDigestContext()
    CSSM_CSP_CreateMacContext()
    CSSM_CSP_CreateRandomContext()
    CSSM_CSP_CreateAsymmetricContext()
    CSSM_CSP_CreateDeriveKeyContext()
    CSSM_CSP_CreateKeyGenContext()
    CSSM_CSP_CreatePassThroughContext()
    CSSM_DeleteContext()
    CSSM_UpdateContextAttributes()

    Contents Next section Index