Common Security: CDSA and CSSM, Version 2
Copyright © 1999 The Open Group

Service Provider Interface

Overview

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 or some approach internal to the CSP. Accessing persistent objects managed by the CSP, other than keys, is performed using CSSM's Data Storage Library APIs.

CSPs optionally support a login sequence. When login is supported, the caller is allowed to change credentials 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 makes these services available to CSP administration tools using the CSSM_Passthrough() function.

All cryptographic services requested by applications will be channeled to one of the CSPs via the CSSM. CSP vendors only need target their modules to CSSM for all security-conscious applications to have access to their product.

Before an application calls a CSP to perform a cryptographic operation, the application uses the Module Directory Service (MDS) to determine what CSPs are available on the system, and what services they provide. Based on this information, the application then can determine which CSP to use for subsequent operations. An application establishes an attach session using CSSM_ModuleAttach() 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:

A one-step cryptographic operation
A cryptographic session of a multi-staged cryptographic service.

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 specify 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 CSSM_DeleteContext(). Resources that were allocated for that context can be reclaimed by the operating system.

Cryptographic operations come in two types-a single call to perform an operation and a staged method of performing the operation. For the single call method, only one call is needed to obtain the result. For the staged method, there is an initialization call followed by one or more update calls, and ending with a completion (final) call. The result is available after the final function completes its execution for most crypto operations-staged encryption/decryption are an exception in that each update call generates a portion of the result.

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:

RSA-based algorithms
DSA-based algorithms

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

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. The error code is CSSM_CSP_ERR_OUTBUF_LENGTH and 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.
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:

The set of input buffers is treated as a single continuous logical buffer.
If the input is transformed into a single output value at the end of the operation, then the value is returned as described for returning buffers of data.
If the input buffers are transformed into a set of output buffers (i.e. encryption, decryption), then the result is returned in one of two ways:
1. If output buffers are specified, then the buffers are filled to the given length with transformed data and the remaining data is placed in the next buffer. The lengths of the buffers are not modified. The total number of bytes is indicated by a separate return parameter that varies by API.
2. If output buffers are not specified (an array of CSSM_DATA structures is passed with no buffer or length values), then the CSP may allocate as many output buffers of any length as it finds necessary up to the number of CSSM_DATA structures passed.
Extra space in the output buffers is not "remembered" by the CSP for use in subsequent calls to an update API. New buffers must be supplied for each call.

Data that does not fit into the output buffers or can not be returned immediately (that is, update calls to staged APIs) is returned using the RemData parameter. This value is treated as a single output value as described above.

Data Structures

This section describes the data structures required by CSPs that are not defined by the CSSM API specification (see Part 2).

CSSM_SPI_CSP_FUNCS

This structure defines the function table for all the cryptographic service provider functions that a service module can return to CSSM. CSSM uses these function pointers to dispatch corresponding application programming interface functions to the service module for processing.


 

typedef struct cssm_spi_csp_funcs {
    CSSM_RETURN (CSSMAPI *EventNotify)
        (CSSM_CSP_HANDLE CspHandle,
        CSSM_CONTEXT_EVENT Event,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_CONTEXT *Context);
    CSSM_RETURN (CSSMAPI *QuerySize)
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_CONTEXT *Context,
        CSSM_BOOL Encrypt,
        uint32 QuerySizeCount,
        CSSM_QUERY_SIZE_DATA_PTR DataBlock);
    CSSM_RETURN (CSSMAPI *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);
    CSSM_RETURN (CSSMAPI *SignDataInit) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_CONTEXT *Context);
    CSSM_RETURN (CSSMAPI *SignDataUpdate) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_DATA *DataBufs,
        uint32 DataBufCount);
    CSSM_RETURN (CSSMAPI *SignDataFinal) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        CSSM_DATA_PTR Signature);
    CSSM_RETURN (CSSMAPI *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);
    CSSM_RETURN (CSSMAPI *VerifyDataInit) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_CONTEXT *Context);
    CSSM_RETURN (CSSMAPI *VerifyDataUpdate) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_DATA *DataBufs,
        uint32 DataBufCount);
    CSSM_RETURN (CSSMAPI *VerifyDataFinal) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_DATA *Signature);
    CSSM_RETURN (CSSMAPI *DigestData) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_CONTEXT *Context,
        const CSSM_DATA *DataBufs,
        uint32 DataBufCount,
        CSSM_DATA_PTR Digest);
    CSSM_RETURN (CSSMAPI *DigestDataInit) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_CONTEXT *Context);
    CSSM_RETURN (CSSMAPI *DigestDataUpdate) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_DATA *DataBufs,
        uint32 DataBufCount);
    CSSM_RETURN (CSSMAPI *DigestDataClone) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        CSSM_CC_HANDLE ClonednewCCHandle);
    CSSM_RETURN (CSSMAPI *DigestDataFinal) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        CSSM_DATA_PTR Digest);
    CSSM_RETURN (CSSMAPI *GenerateMac) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_CONTEXT *Context,
        const CSSM_DATA *DataBufs,
        uint32 DataBufCount,
        CSSM_DATA_PTR Mac);
    CSSM_RETURN (CSSMAPI *GenerateMacInit) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_CONTEXT *Context);
    CSSM_RETURN (CSSMAPI *GenerateMacUpdate) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_DATA *DataBufs,
        uint32 DataBufCount);
    CSSM_RETURN (CSSMAPI *GenerateMacFinal) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        CSSM_DATA_PTR Mac);
    CSSM_RETURN (CSSMAPI *VerifyMac) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_CONTEXT *Context,
        const CSSM_DATA *DataBufs,
        uint32 DataBufCount,
        const CSSM_DATA *Mac);
    CSSM_RETURN (CSSMAPI *VerifyMacInit) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_CONTEXT *Context);
    CSSM_RETURN (CSSMAPI *VerifyMacUpdate) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_DATA *DataBufs,
        uint32 DataBufCount);
    CSSM_RETURN (CSSMAPI *VerifyMacFinal) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_DATA *Mac);
    CSSM_RETURN (CSSMAPI *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); 
    CSSM_RETURN (CSSMAPI *EncryptDataInit)
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_CONTEXT *Context,
        CSSM_PRIVILEGE Privilege);
    CSSM_RETURN (CSSMAPI *EncryptDataUpdate) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_DATA *ClearBufs,
        uint32 ClearBufCount,
        CSSM_DATA_PTR CipherBufs,
        uint32 CipherBufCount,
        uint32 *bytesEncrypted);
    CSSM_RETURN (CSSMAPI *EncryptDataFinal) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        CSSM_DATA_PTR RemData);
    CSSM_RETURN (CSSMAPI *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);
    CSSM_RETURN (CSSMAPI *DecryptDataInit)
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_CONTEXT *Context,
        CSSM_PRIVILEGE Privilege);
    CSSM_RETURN (CSSMAPI *DecryptDataUpdate) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_DATA *CipherBufs,
        uint32 CipherBufCount,
        CSSM_DATA_PTR ClearBufs,
        uint32 ClearBufCount,
        uint32 *bytesDecrypted);
    CSSM_RETURN (CSSMAPI *DecryptDataFinal) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        CSSM_DATA_PTR RemData);
    CSSM_RETURN (CSSMAPI *QueryKeySizeInBits) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_KEY *Key,
        CSSM_KEY_SIZE_PTR KeySize);
    CSSM_RETURN (CSSMAPI *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);
    CSSM_RETURN (CSSMAPI *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);
    CSSM_RETURN (CSSMAPI *GenerateRandom) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_CONTEXT *Context,
        CSSM_DATA_PTR RandomNumber);
    CSSM_RETURN (CSSMAPI *GenerateAlgorithmParams) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CC_HANDLE CCHandle,
        const CSSM_CONTEXT *Context,
        uint32 ParamBits,
        CSSM_DATA_PTR Param,
        uint32 *NumberOfUpdatedAttibutes,
        CSSM_CONTEXT_ATTRIBUTE_PTR *UpdatedAttributes);
    CSSM_RETURN (CSSMAPI *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);
    CSSM_RETURN (CSSMAPI *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);
    CSSM_RETURN (CSSMAPI *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);
    CSSM_RETURN (CSSMAPI *FreeKey) 
        (CSSM_CSP_HANDLE CSPHandle,
        const CSSM_ACCESS_CREDENTIALS *AccessCred,
        CSSM_KEY_PTR KeyPtr,
        CSSM_BOOL Delete);
    CSSM_RETURN (CSSMAPI *PassThrough) 
        (CSSM_CSP_HANDLE CSPHandle, 
        CSSM_CC_HANDLE CCHandle,
        const CSSM_CONTEXT *Context,
        uint32 PassThroughId,
        const void *InData,
        void **OutData);
    CSSM_RETURN (CSSMAPI *Login) 
        (CSSM_CSP_HANDLE CSPHandle,
        const CSSM_ACCESS_CREDENTIALS *AccessCred,
        const CSSM_DATA *LoginName,
        const void *Reserved);
    CSSM_RETURN (CSSMAPI *Logout) 
        (CSSM_CSP_HANDLE CSPHandle);
    CSSM_RETURN (CSSMAPI *ChangeLoginAcl)
        (CSSM_CSP_HANDLE CSPHandle,
        const CSSM_ACCESS_CREDENTIALS *AccessCred,
        const CSSM_ACL_EDIT *AclEdit);
    CSSM_RETURN (CSSMAPI *ObtainPrivateKeyFromPublicKey)
        (CSSM_CSP_HANDLE CSPHandle,
        const CSSM_KEY *PublicKey,
        CSSM_KEY_PTR PrivateKey);
    CSSM_RETURN (CSSMAPI *RetrieveUniqueId) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_DATA_PTR UniqueID);
    CSSM_RETURN (CSSMAPI *RetrieveCounter) 
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_DATA_PTR Counter);
    CSSM_RETURN (CSSMAPI *VerifyDevice) 
        (CSSM_CSP_HANDLE CSPHandle,
        const CSSM_DATA *DeviceCert);
    CSSM_RETURN (CSSMAPI *GetTimeValue)
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_ALGORITHMS TimeAlgorithm,
        CSSM_DATA *TimeData);
    CSSM_RETURN (CSSMAPI *GetOperationalStatistics)
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_CSP_OPERATIONAL_STATISTICS *Statistics);
    CSSM_RETURN (CSSMAPI *GetLoginAcl)
        (CSSM_CSP_HANDLE CSPHandle,
        const CSSM_STRING *SelectionTag,
        uint32 *NumberOfAclInfos,
        CSSM_ACL_ENTRY_INFO_PTR *AclInfos);
    CSSM_RETURN (CSSMAPI *GetKeyAcl)
        (CSSM_CSP_HANDLE CSPHandle,
        const CSSM_KEY *Key,
        const CSSM_STRING *SelectionTag,
        uint32 *NumberOfAclInfos,
        CSSM_ACL_ENTRY_INFO_PTR *AclInfos);
    CSSM_RETURN (CSSMAPI *ChangeKeyAcl)
        (CSSM_CSP_HANDLE CSPHandle,
        const CSSM_ACCESS_CREDENTIALS *AccessCred,
        const CSSM_ACL_EDIT *AclEdit,
        const CSSM_KEY *Key);
    CSSM_RETURN (CSSMAPI *GetKeyOwner)
        (CSSM_CSP_HANDLE CSPHandle,
        const CSSM_KEY *Key,
        CSSM_ACL_OWNER_PROTOTYPE_PTR Owner);
    CSSM_RETURN (CSSMAPI *ChangeKeyOwner)
        (CSSM_CSP_HANDLE CSPHandle,
        const CSSM_ACCESS_CREDENTIALS *AccessCred,
        const CSSM_KEY *Key,
        const CSSM_ACL_OWNER_PROTOTYPE *NewOwner);
    CSSM_RETURN (CSSMAPI *GetLoginOwner)
        (CSSM_CSP_HANDLE CSPHandle,
        CSSM_ACL_OWNER_PROTOTYPE_PTR Owner);
    CSSM_RETURN (CSSMAPI *ChangeLoginOwner)
        (CSSM_CSP_HANDLE CSPHandle,
        const CSSM_ACCESS_CREDENTIALS *AccessCred,
        const CSSM_ACL_OWNER_PROTOTYPE *NewOwner);
} CSSM_SPI_CSP_FUNCS, *CSSM_SPI_CSP_FUNCS_PTR;

Error Return Codes

Refer to the Error Codes and Error Values section in the API definition in Part 2.

Cryptographic Operations

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

Click here to return to the publication details.

NAME

CSP_SignData

SYNOPSIS


CSSM_RETURN CSSMSPI 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 includes 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.

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.

DataBufs (input)

A pointer to one or more CSSM_DATA structures containing 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.

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 corresponding function call definition in Part 2 of this document.

COMMENTS

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

NAME

CSP_SignDataInit

SYNOPSIS


CSSM_RETURN CSSMSPI CSP_SignDataInit
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context)

DESCRIPTION

This function initializes the staged sign data 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.
For staged operations, a combination operation selecting both a digesting algorithm and a signing algorithm must be specified.

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.

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 corresponding function call definition in Part 2 of this document.

NAME

CSP_SignDataUpdate

SYNOPSIS


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

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.

DataBufs (input)

A pointer to one or more CSSM_DATA structures containing the data be signed.

DataBufCount (input)

The number of DataBufs to be signed.

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 corresponding function call definition in Part 2 of this document.

NAME

CSP_SignDataFinal

SYNOPSIS


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

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.

Signature (output)

A pointer to the CSSM_DATA structure for the signature.

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 corresponding function call definition in Part 2 of this document.

COMMENTS

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

NAME

CSP_VerifyData

SYNOPSIS


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

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.

DataBufs (input)

A pointer to one or more CSSM_DATA structures containing the data be verified.

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/decryption algorithm.

Signature (input)

A pointer to a CSSM_DATA structure which contains the signature and the size of the signature.

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 corresponding function call definition in Part 2 of this document.

NAME

CSP_VerifyDataInit

SYNOPSIS


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

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.

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 corresponding function call definition in Part 2 of this document.

NAME

CSP_VerifyDataUpdate

SYNOPSIS


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

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.

DataBufs (input)

A pointer to one or more CSSM_DATA structures containing the data be verified.

DataBufCount (input)

The number of DataBufs to be verified.

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 corresponding function call definition in Part 2 of this document.

NAME

CSP_VerifyDataFinal

SYNOPSIS


CSSM_BOOL CSSMSPI CSP_VerifyDataFinal
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_DATA *Signature)

DESCRIPTION

This function finalizes the staged verify data function.

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.

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.

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 corresponding function call definition in Part 2 of this document.

NAME

CSP_DigestData

SYNOPSIS


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

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.

DataBufs (input)

A pointer to one or more CSSM_DATA structures containing the supplied data.

DataBufCount (input)

The number of DataBufs.

Digest (output)

A pointer to the CSSM_DATA structure for the message digest.

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 corresponding function call definition in Part 2 of this document.

COMMENTS

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

NAME

CSP_DigestDataInit

SYNOPSIS


CSSM_RETURN CSSMSPI CSP_DigestDataInit
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context)

DESCRIPTION

This function initializes the staged message digest function.

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.

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 corresponding function call definition in Part 2 of this document.

NAME

CSP_DigestDataUpdate

SYNOPSIS


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

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.

DataBufs (input)

A pointer to one or more CSSM_DATA structures containing the supplied data.

DataBufCount (input)

The number of DataBufs.

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 corresponding function call definition in Part 2 of this document.

NAME

CSP_DigestDataClone

SYNOPSIS


CSSM_RETURN CSSMSPI 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. The CSSM will assign the new cryptographic context handle. The CSP is responsible for performing the state duplication.

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 of the original staged message digest context that will be cloned by this operation.

ClonednewCCHandle (input)

The new handle that describes the cloned context of a staged message digest 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 corresponding function call definition in Part 2 of this document.

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 is used with the CSP_DigestDataUpdate() and CSP_DigestDataFinal() functions.

NAME

CSP_DigestDataFinal

SYNOPSIS


CSSM_RETURN CSSMSPI CSP_DigestDataFinal
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    CSSM_DATA_PTR Digest)

DESCRIPTION

This function finalizes the staged message digest function.

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.

Digest (output)

A pointer to the CSSM_DATA structure for the message digest.

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 corresponding function call definition in Part 2 of this document.

COMMENTS

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

NAME

CSP_GenerateMac

SYNOPSIS


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

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.

DataBufs (input)

A pointer to one or more CSSM_DATA structures containing the supplied data.

DataBufCount (input)

The number of DataBufs.

Mac (output)

A pointer to the CSSM_DATA structure for the message authentication code.

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 corresponding function call definition in Part 2 of this document.

COMMENTS

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

NAME

CSP_GenerateMacInit

SYNOPSIS


CSSM_RETURN CSSMSPI CSP_GenerateMacInit
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context)

DESCRIPTION

This function initializes the staged message authentication code function.

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.

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 corresponding function call definition in Part 2 of this document.

NAME

CSP_GenerateMacUpdate

SYNOPSIS


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

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.

DataBufs (input)

A pointer to one or more CSSM_DATA structures containing the supplied data.

DataBufCount (input)

The number of DataBufs.

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 corresponding function call definition in Part 2 of this document.

NAME

CSP_GenerateMacFinal

SYNOPSIS


CSSM_RETURN CSSMSPI CSP_GenerateMacFinal
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    CSSM_DATA_PTR Mac)

DESCRIPTION

This function finalizes the staged message authentication code function.

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.

Mac (output)

A pointer to the CSSM_DATA structure for the message authentication code.

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 corresponding function call definition in Part 2 of this document.

COMMENTS

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

NAME

CSP_VerifyMac

SYNOPSIS


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

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.

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.

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 corresponding function call definition in Part 2 of this document.

NAME

CSP_VerifyMacInit

SYNOPSIS


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

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.

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 corresponding function call definition in Part 2 of this document.

NAME

CSP_VerifyMacUpdate

SYNOPSIS


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

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.

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.

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 corresponding function call definition in Part 2 of this document.

NAME

CSP_VerifyMacFinal

SYNOPSIS


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

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.

Mac (input)

A pointer to the CSSM_DATA structure containing the MAC to verify.

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 corresponding function call definition in Part 2 of this document.

COMMENTS

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

NAME

CSP_QuerySize

SYNOPSIS


CSSM_RETURN CSSMSPI CSP_QuerySize
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context,
    CSSM_BOOL Encrypt,
    uint32 QuerySizeCount,
    CSSM_QUERY_SIZE_DATA_PTR DataBlock)

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 than the Encrypt parameter will determine which operation is being performed. If Encrypt is set to CSSM_TRUE than it is an encrypt operation, otherwise it is a decrypt operation. For all other context types the Encrypt parameter is ignored. This function can also be used to query the output size requirements for the intermediate steps of a staged cryptographic operation. There may be algorithm-specific and token-specific rules restricting the lengths of data following data update calls.

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.

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)

This parameter describes number of DataBlocks.

DataBlock (input/output)

An array of data block input sizes and corresponding entries for the data block output sizes that are returned by this function.

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 corresponding function call definition in Part 2 of this document.

NAME

CSP_EncryptData

SYNOPSIS


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

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.

ClearBufs (input)

A pointer to one or more CSSM_DATA structures containing the clear data.

ClearBufCount (input)

The number of ClearBufs.

CipherBufs (output)

A pointer to one or more CSSM_DATA structures for the encrypted 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 cipher text, if there is not enough buffer space available in the output data structures.

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 corresponding function call definition in Part 2 of this document.

COMMENTS

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

NAME

CSP_EncryptDataInit

SYNOPSIS


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

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 corresponding function call definition in Part 2 of this document.

NAME

CSP_EncryptDataUpdate

SYNOPSIS


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

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.

ClearBufs (input)

A pointer to one or more CSSM_DATA structures containing the clear data.

ClearBufCount (input)

The number of ClearBufs.

CipherBufs (output)

A pointer to one or more CSSM_DATA structures for the encrypted data.

CipherBufCount (input)

The number of CipherBufs.

bytesEncrypted (output)

A pointer to uint32 for the size of the encrypted data in bytes.

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 corresponding function call definition in Part 2 of this document.

COMMENTS

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

NAME

CSP_EncryptDataFinal

SYNOPSIS


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

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.

RemData (output)

A pointer to the CSSM_DATA structure for the last encrypted block containing padded data, if necessary.

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 corresponding function call definition in Part 2 of this document.

COMMENTS

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

NAME

CSP_DecryptData

SYNOPSIS


CSSM_RETURN CSSMSPI 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() 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.

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.

CipherBufs (input)

A pointer to one or more CSSM_DATA structures containing the encrypted data.

CipherBufCount (input)

The number of CipherBufs.

ClearBufs (output)

A pointer to one or more CSSM_DATA structures for the decrypted data.

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.

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 corresponding function call definition in Part 2 of this document.

COMMENTS

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

NAME

CSP_DecryptDataInit

SYNOPSIS


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

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 corresponding function call definition in Part 2 of this document.

NAME

CSP_DecryptDataUpdate

SYNOPSIS


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

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.

CipherBufs (input)

A pointer to one or more CSSM_DATA structures containing the encrypted data.

CipherBufCount (input)

The number of CipherBufs.

ClearBufs (output)

A pointer to one or more CSSM_DATA structures for the decrypted data.

ClearBufCount (input)

The number of ClearBufs.

bytesDecrypted (output)

A pointer to uint32 for the size of the decrypted data in bytes.

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 corresponding function call definition in Part 2 of this document.

COMMENTS

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

NAME

CSP_DecryptDataFinal

SYNOPSIS


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

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.

RemData(output)

A pointer to the CSSM_DATA structure for the last decrypted block, if necessary.

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 corresponding function call definition in Part 2 of this document.

COMMENTS

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

NAME

CSP_GenerateKey

SYNOPSIS


CSSM_RETURN CSSMSPI 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:

Subject - A CSSM_LIST structure, containing the type of the subject and a template value that can be used to verify samples that are presented in credentials when resource access is requested.

Delegation flag - A value indicating whether the Subject can delegate the permissions recorded in the AuthorizationTag. (This item only applies to public key subjects).

Authorization tag - The set of permissions that are granted to the Subject.

Validity period - The start time and the stop time for which the ACL entry is valid.

ACL entry tag - A user-defined string value associated with the ACL entry.

The service provider can modify the caller-provided initial ACL entry to conform to any innate resource-access policy that the service provider may be required to enforce. If the initial ACL entry provided by the caller contains values or permissions that are not supported by the service provider, then the service provider can modify the initial ACL appropriately or can fail the request to create the new resource. Service providers list their supported AuthorizationTag values in their Module Directory Services primary record.

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.

KeyUsage (input)

A bit mask specifying how the new key can be used.

KeyAttr (input)

A bit mask specifying other attributes to be associated with 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 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 corresponding function call definition in Part 2 of this document.

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.

NAME

CSP_GenerateKeyPair

SYNOPSIS


CSSM_RETURN CSSMSPI 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:

Subject - A CSSM_LIST structure, containing the type of the subject and a template value that can be used to verify samples that are presented in credentials when resource access is requested.

Delegation flag - A value indicating whether the Subject can delegate the permissions recorded in the Authorization Tag . (This item only applies to public key subjects).

Authorization Tag - The set of permissions that are granted to the Subject.

Validity period - The start time and the stop time for which the ACL entry is valid.

ACL entry tag - A user-defined string value associated with the ACL entry.

The service provider can modify the caller-provided initial ACL entry to conform to any innate resource-access policy that the service provider may be required to enforce. If the initial ACL entry provided by the caller contains values or permissions that are not supported by the service provider, then the service provider can modify the initial ACL appropriately or can fail the request to create the new resource. Service providers list their supported Authorization Tag values in their Module Directory Services primary record.

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

PublicKeyUsage (input)

A bit mask specifying how the new public key can be used.

PublicKeyAttr (input)

A bit mask specifying other attributes to be associated with 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 obtain the public key. Upon function invocation, any values in the CSSM_Key structure should be ignored. All input values should be supplied in the cryptographic Context, PublicKeyUsage, PublicKeyAttr, and PublicKeyLabel input parameters.

PrivateKeyUsage (input)

A bit mask specifying how the new private key can be used.

PrivateKeyAttr (input)

A bit mask specifying other attributes to be associated with 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.

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 corresponding function call definition in Part 2 of this document.

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

NAME

CSP_GenerateRandom

SYNOPSIS


CSSM_RETURN CSSMSPI CSP_GenerateRandom
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context,
    CSSM_DATA_PTR RandomNumber)

DESCRIPTION

This function generates random data.

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.

RandomNumber (output)

Pointer to CSSM_DATA structure used to obtain the random number and the size of the random number in bytes.

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 corresponding function call definition in Part 2 of this document.

COMMENTS

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

Previous section.

NAME

CSP_FreeKey

SYNOPSIS


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

PARAMETERS

CSPHandle (input)

The handle that describes the module to perform this operation.

AccessCred (input/output)

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

See the corresponding function call definition in Part 2 of this document.

Previous section.

NAME

CSP_ObtainPrivateKeyFromPublicKey

SYNOPSIS


CSSM_RETURN CSSMSPI 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 credentials can be used as an input to any function requiring a private key value.

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 corresponding function call definition in Part 2 of this document.

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

CSP_WrapKey

SYNOPSIS


CSSM_RETURN CSSMSPI CSP_WrapKey
    (CSSM_CSP_HANDLE CSPHandle,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context,
    const CSSM_ACCESS_CREDENTIALS *AccessCred,
    CSSM_KEY_PTR Key,
    const CSSM_DATA *DescriptiveData,
    CSSM_WRAP_KEY_PTR WrappedKey,
    CSSM_PRIVILEGE Privilege)

DESCRIPTION

This function wraps the supplied key using the context. The key can be a symmetric key or a reference to a private key. If a symmetric wrapping algorithm is wanted, then a symmetric context must be provided. If an asymmetric algorithm is wanted, then an asymmetric context describing the wrapping algorithm must be provided. If the key is a private key, then an asymmetric context describing the wrapping algorithm, and a set of access credentials that authenticate the caller and authorize extraction of the private key must be provided. If the wrapping key, specified in the cryptographic context is a protected secret key, then the cryptographic context must contain the credentials required for authorized access to the wrapping key. If the specified wrapping algorithm is CSSN_ALGID_NONE, then the key is returned in raw format, if permitted and supported by the CSP. The CSP is responsible for incorporating all of the pertinent key attributes into the wrapped key, ensuring that the state of the key can be fully restored by the unwrap process.

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 to the context that describes this cryptographic operation.

Context (input)

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

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 target key to be wrapped. If a private key is to be wrapped, this is a reference to the private key. If a symmetric key is to be wrapped, the target key is that symmetric key.

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_KEY structure that returns the wrapped key.

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 corresponding function call definition in Part 2 of this document.

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

CSP_UnwrapKey

SYNOPSIS


CSSM_RETURN CSSMSPI 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 CSP must recover the complete state of the unwrapped key based on the key attributes stored in the wrapped key.
Authorization policy can restrict the set of callers who can create a new resource. In this case, the caller must present a set of access credentials for authorization. Upon successfully authenticating the credentials, the template that verified the presented samples identifies the ACL entry that will be used in the authorization computation. If the caller is authorized, the new resource is created.
The caller must provide an initial ACL entry to be associated with the newly created resource. This entry is used to control future access to the new resource and (since the subject is deemed to be the "Owner") exercise control over its associated ACL. The caller can specify the following items for initializing an ACL entry:

Subject - A CSSM_LIST structure, containing the type of the subject and a template value that can be used to verify samples that are presented in credentials when resource access is requested.

Delegation flag - A value indicating whether the Subject can delegate the permissions recorded in the Authorization Tag. (This item only applies to public key subjects).

Authorization Tag - The set of permissions that are granted to the Subject.

Validity period - The start time and the stop time for which the ACL entry is valid.

ACL entry tag - A user-defined string value associated with the ACL entry.

The service provider can modify the caller-provided initial ACL entry to conform to any innate resource-access policy that the service provider may be required to enforce. If the initial ACL entry provided by the caller contains values or permissions that are not supported by the service provider, then the service provider can modify the initial ACL appropriately or can fail the request to create the new resource. Service providers list their supported Authorization Tag values in their Module Directory Services primary record.

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.

PublicKey (input)

The public key corresponding to the private key being unwrapped. This parameter must be NULL when unwrapping a symmetric key.

WrappedKey (input)

A pointer to the wrapped key. The wrapped key may be a symmetric key or the private key of a public/private keypair. 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 specifying how the unwrapped key can be used.

KeyAttr (input)

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

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 corresponding function call definition in Part 2 of this document.

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.

NAME

CSP_DeriveKey

SYNOPSIS


CSSM_RETURN CSSMSPI 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. The CSP can require that the cryptographic context include access credentials for authentication and authorization checks when using a private key or a secret key.
Authorization policy can restrict the set of callers who can create a new resource. In this case, the caller must present a set of access credentials for authorization. Upon successfully authenticating the credentials, the template that verified the presented samples identifies the ACL entry that will be used in the authorization computation. If the caller is authorized, the new resource is created.
The caller must provide an initial ACL entry to be associated with the newly created resource. This entry is used to control future access to the new resource and (since the subject is deemed to be the "Owner") exercise control over its associated ACL. The caller can specify the following items for initializing an ACL entry:

Subject - A CSSM_LIST structure, containing the type of the subject and a template value that can be used to verify samples that are presented in credentials when resource access is requested.

Delegation flag - A value indicating whether the Subject can delegate the permissions recorded in the Authorization Tag . (This item only applies to public key subjects).

Authorization Tag - The set of permissions that are granted to the Subject.

Validity period - The start time and the stop time for which the ACL entry is valid.

ACL entry tag - A user-defined string value associated with the ACL entry.

The service provider can modify the caller-provided initial ACL entry to conform to any innate resource-access policy that the service provider may be required to enforce. If the initial ACL entry provided by the caller contains values or permissions that are not supported by the service provider, then the service provider can modify the initial ACL appropriately or can fail the request to create the new resource. Service providers list their supported Authorization Tag 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.

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.

Param (input/output)

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

KeyUsage (input/optional)

A bit mask specifying how the new key can be used.

KeyAttr (input/optional)

A bit mask specifying other attributes to be associated with the new 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.

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 corresponding function call definition in Part 2 of this document.

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

CSP_GenerateAlgorithmParams

SYNOPSIS


CSSM_RETURN CSSMSPI 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. The parameter data may be returned to the caller either by returning an array of CSSM_CONTEXT_ATTRIBUTE structures or by returning directly to the caller via the Param parameter. In most cases the algorithm parameters will be added directly to the cryptographic context. The generated parameters should be returned as a context attribute of type CSSM_ATTRIBUTE_ALG_PARAMS. Other attributes returned are added to the context, or replace existing values in the context.

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

ParamBits (input)

Algorithm dependent value used in the parameter generation process.

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.

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

See the corresponding function call definition in Part 2 of this document.

COMMENTS

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

Previous section.

NAME

CSP_QueryKeySizeInBits

SYNOPSIS


CSSM_RETURN CSSMSPI 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 key parameter is ignored.

PARAMETERS

CSPHandle (input)

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

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.

Context (input/optional)

Pointer to CSSM_CONTEXT structure that describes the attributes in this context. The pointer to the context should be valid if a valid cryptographic handle is specified.

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_KEYSIZE data structure. The logical and effective sizes (in bits) for the key are returned in this 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 corresponding function call definition in Part 2 of this document.

Cryptographic Sessions and Controlled Access to Keys

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

NAME

CSP_Login

SYNOPSIS


CSSM_RETURN CSSMSPI 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 and parallel operation notification.

PARAMETERS

CSPHandle (input)

Handle of the CSP to log into.

AccessCred (input/optional)

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 corresponding function call definition in Part 2 of this document.

NAME

CSP_Logout

SYNOPSIS


CSSM_RETURN CSSMSPI 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

See the corresponding function call definition in Part 2 of this document.

NAME

CSP_GetLoginAcl

SYNOPSIS


CSSM_RETURN CSSMSPI 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:

Public contents of an ACL entry

ACL EntryHandle, which is a unique value defined and managed by the service provider

The public ACL entry information returned by this function includes:

The subject type - A CSSM_LIST structure containing one element identifying the type of subject stored in the ACL entry.

Delegation flag - A CSSM_BOOL value indicating whether the subject can delegate the permissions recorded in Authorization.

Authorization array - A CSSM_AUTHORIZATIONGROUP structure defining the set of operations for which permission is granted to the Subject.

Validity period - A CSSM_ACL_VALIDITY_PERIOD structure containing two elements, the start time and the stop time for which the ACL entry is valid.

ACL entry tag - A CSSM_STRING containing a user-defined value associated with the ACL entry.

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

See the corresponding function call definition in Part 2 of this document.

COMMENTS

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

NAME

CSP_ChangeLoginAcl

SYNOPSIS


CSSM_RETURN CSSMSPI 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 t he CSP. The new ACL entry is created from the ACL entry prototype contained in f2NewEntry.
OldEntryHandle is ignored for this EditMode.
CSSM_ACL_EDIT_MODE_DELETE Deletes the ACL entry identified by OldEntryHandle and associated with log in 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 proto type contained in the NewEntry.

When replacing an existing ACL entry, the caller must replace all of the items in an ACL entry. The replacement prototype includes:

Subject type and value - A CSSM_LIST structure containing a typed Subject. The Subject identifies the entity authorized by this ACL entry.

Delegation flag - A CSSM_BOOL value indicating whether the subject can delegate the permissions recorded in the authorization array.

Authorization array - A CSSM_AUTHORIZATIONGROUP structure defining the et of ope rations 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.

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 t he CSP. The new ACL entry is created from the ACL entry prototype contained in f2NewEntry. OldEntryHandle is ignored for this EditMode.
CSSM_ACL_EDIT_MODE_DELETE	Deletes the ACL entry identified by OldEntryHandle and associated with log in 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 proto type contained in the NewEntry.

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 corresponding function call definition in Part 2 of this document.

NAME

CSP_GetLoginOwner

SYNOPSIS


CSSM_RETURN CSSMSPI 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. This structure must be empty on input. The CSP will allocate all memory inside the structure. The application must free the memory using the memory functions registered with the CSSM when CSPHandle was attached.

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 corresponding function call definition in Part 2 of this document.

NAME

CSP_ChangeLoginOwner

SYNOPSIS


CSSM_RETURN CSSMSPI 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

See the corresponding function call definition in Part 2 of this document.

NAME

CSP_GetKeyAcl

SYNOPSIS


CSSM_RETURN CSSMSPI CSP_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:

Public contents of an ACL entry

ACL EntryHandle, which is a unique value defined and managed by the service provider

The public ACL entry information returned by this function includes:

The subject type - A CSSM_LIST structure containing one element identifying the type of subject stored in the ACL entry.

Delegation flag - A CSSM_BOOL value indicating whether the subject can delegate the permissions recorded in Authorization.

Authorization array - A CSSM_AUTHORIZATIONGROUP structure defining the set of operations for which permission is granted to the Subject.

Validity period - A CSSM_ACL_VALIDITY_PERIOD structure containing two elements, the start time and the stop time for which the ACL entry is valid.

ACL entry tag - A CSSM_STRING containing a user-defined value associated with the ACL entry.

CSPHandle (input)

The module handle that identifies the cryptographic service provider to perform this operation.

Key (input)

A pointer to the target key whose associated ACL entries are scanned and returned.

SelectionTag (input/optional)

A CSSM_STRING value matching the user-defined tag value associated with one or more ACL entries for the target Key. To retrieve a description of all ACL entries for the target Key, this parameter must be NULL.

NumberOfAclInfos (output)

The number of entries in the AclInfos array. If no ACL entry descriptions are returned, this value is zero.

AclInfos (output)

An array of CSSM_ACL_ENTRY_INFO structures. The unique handle contained in this structure can be used during the current attach session to reference specific ACL entries for editing. The structure is allocated by the service provider and must be released by the caller when the structure is no longer needed. If no ACL entry descriptions are returned, this value is NULL.

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 corresponding function call definition in Part 2 of this document.

COMMENTS

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

NAME

CSP_ChangeKeyAcl

SYNOPSIS


CSSM_RETURN CSSMSPI CSP_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 EditMode.
CSSM_ACL_EDIT_MODE_DELETE Deletes the ACL entry identified by OldEntryHandle and associated with the specified Key.
NewEntry is ignored for this EditMode.
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.

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 EditMode.
CSSM_ACL_EDIT_MODE_DELETE	Deletes the ACL entry identified by OldEntryHandle and associated with the specified Key. NewEntry is ignored for this EditMode.
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.

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 corresponding function call definition in Part 2 of this document.

NAME

CSP_GetKeyOwner

SYNOPSIS


CSSM_RETURN CSSMSPI CSP_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. This structure must be empty on input. The CSP will allocate all memory inside the structure. The application must free the memory using the memory functions registered with the CSSM when CSPHandle was attached.

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 corresponding function call definition in Part 2 of this document.

NAME

CSP_ChangeKeyOwner

SYNOPSIS


CSSM_RETURN CSSMSPI CSP_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

See the corresponding function call definition in Part 2 of this document.

Miscellaneous Functions

The man-page definitions for miscellaneous SPI functions are presented in this section. Previous section.

NAME

CSSM_CSP_GetOperationalStatistics

SYNOPSIS


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

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

See the corresponding function call definition in Part 2 of this document.

Previous section.

NAME

CSSSM_GetTimeValue

SYNOPSIS


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

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

See the corresponding function call definition in Part 2 of this document.

COMMENTS

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

Some tokens require authentication before returning a time value.

Previous section.

NAME

CSP_RetrieveUniqueId

SYNOPSIS


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

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

See the corresponding function call definition in Part 2 of this document.

COMMENTS

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

Previous section.

NAME

CSP_RetrieveCounter

SYNOPSIS


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

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

See the corresponding function call definition in Part 2 of this document.

COMMENTS

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

Previous section.

NAME

CSP_VerifyDevice

SYNOPSIS


CSSM_RETURN CSSMAPI CSP_VerifyDevice 
    (CSSM_CSP_HANDLE CSPHandle,
    const CSSM_DATA *DeviceCert)

DESCRIPTION

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

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 corresponding function call definition in Part 2 of this document.

Extensibility Functions

The CSP_PassThrough() function is provided to allow CSP developers to extend the crypto functionality of the CSSM API. 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 section constitute the generic error codes that may be used by all CSPs to describe common error conditions. CSP developers may also define their own module-specific error codes. Previous section.

NAME

CSP_PassThrough

SYNOPSIS


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

DESCRIPTION

The CSP_PassThrough function is provided to allow CSP developers to extend the crypto functionality of the CSSM API.

PARAMETERS

CSPHandle (input)

Handle of the CSP supporting the passthrough function.

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 custom context structure.

PassThroughId (input)

An identifier specifying the custom function to be performed.

InData (input)

A pointer to void 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.

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 corresponding function call definition in Part 2 of this document.

Module Management Functions

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 CSSMSPI CSP_EventNotify
    (CSSM_MODULE_HANDLE CSPHandle,
    CSSM_CONTEXT_EVENT Event,
    CSSM_CC_HANDLE CCHandle,
    const CSSM_CONTEXT *Context)

DESCRIPTION

This function is used by CSSM 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.

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.

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.

Service Provider Interface

Overview

Key Formats for Public Key-Based Algorithms

Buffer Management for Cryptographic Services

Returning Buffers of Data

Vector of Buffers

Data Structures

CSSM_SPI_CSP_FUNCS

Error Return Codes

Cryptographic Operations

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

ERRORS

COMMENTS

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

ERRORS

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

ERRORS

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

ERRORS

COMMENTS

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

ERRORS

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

ERRORS

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

ERRORS

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

ERRORS

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS

RETURN VALUE

ERRORS

COMMENTS

SEE ALSO

NAME

SYNOPSIS

DESCRIPTION

PARAMETERS