1 CDSA Common Data Security Architecture (CDSA) CDSA is a multiplatform, industry standard security infrastructure. It provides a standards-based, stable programming interface that applications can use to access operating system security services, allowing developers to create cross-platform, security-enabled applications. Applications request security services, such as cryptography and other public key operations, through a dynamically extensible application programming interface (API). These requests are serviced by a set of plug-in security service modules (SPIs), which can be supplemented or changed as business needs and technologies evolve. The heart of CDSA is the Common Security Services Manager (CSSM), which defines both the application API and the service provider interface (SPI) for plug-in security service modules. CSSM includes a set of core services that are common to all categories of security services, performing such functions as integrity verification and authentication. Available types of plug-in modules include cryptographic services (CSP), certificate library (CL), data library (DL), trust policy (TP) and authorization computation (AC). CSSM is extensible. Applications call functions in the CSSM API, which is fully specified by the CDSA technical standard located at http://www.opengroup.org/onlinepubs/009609799/. API function names are prefaced with CSSM_ and sometimes followed by the designation of the module that will actually handle the request. For instance, an application calls CSSM_DL_DbOpen() to direct a DL module to open a data store. The associated service provider interface (SPI) for the module would be DL_DbOpen(). An application begins by initializing its connection to CSSM using the CSSM_Init() routine. It might use Module Directory Services (MDS) to query for available modules and their supported functionality, or it might hardcode to a particular module's global unique identifier (GUID). The application loads the desired module using the CSSM_ModuleLoad() routine and then attaches to it using the CSSM_ModuleAttach() routine. SEE ALSO CDSA guides, located in CDSA_SYSDIR:[DOCS]: · Intel CDSA Application Developer's Guide . Intel CDSA Service Provider Developer's Guide . Intel CDSA Manifest Signing Tools User's Guide For Open Source CDSA information and source: http://sourceforge.net/projects/cdsa/ For general CDSA and security information: · http://www.intel.com/ial/security/ · http://www.opengroup.org/security/l2-cdsa.htm 2 CDSA_API 3 AC_AuthCompute AC_AuthCompute - Compute authorization (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMACI CSSM_AC_AuthCompute (CSSM_AC_HANDLE ACHandle, const CSSM_TUPLEGROUP *BaseAuthorizations, const CSSM_TUPLEGROUP *Credentials, uint32 NumberOfRequestors, const CSSM_LIST *Requestors, const CSSM_LIST *RequestedAuthorizationPeriod, const CSSM_LIST *RequestedAuthorization, CSSM_TUPLEGROUP_PTR AuthorizationResult) SPI: CSSM_RETURN CSSMACI AC_AuthCompute (CSSM_AC_HANDLE ACHandle, const CSSM_TUPLEGROUP *BaseAuthorizations, const CSSM_TUPLEGROUP *Credentials, uint32 NumberOfRequestors, const CSSM_LIST *Requestors, const CSSM_LIST *RequestedAuthorizationPeriod, const CSSM_LIST *RequestedAuthorization, CSSM_TUPLEGROUP_PTR AuthorizationResult) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS ACHandle, BaseAuthorizations, Credentials, NumberOfRequestors, Requestors, RequestedAuthorizationPeriod, RequestedAuthorization, AuthorizationResult DESCRIPTION This function performs an authorization computation and returns the results as a group of tuple certificates. The computation is based on the following input values: Requestors One or more items that identify the requestor. These items are matched against subject fields in BaseAuthorizations or Credentials. These will be of any form that occurs in an ACL or certificate, and the class of entries is extensible. AuthCompute uses these fields to compare against Subject fields of TUPLES but does not interpret them, so it does not need to be aware of these extensions. Requestors, taken together with RequestedAuthorization and RequestedAuthorizationPeriod, form request tuples of the form "who requests what, when." Requestors can be public keys that verify some signed request, hashes of objects submitted for proof of permission, etc. In general, there will be only one Requestor, typically the public key of some keyholder signing a request or authenticating a connection. RequestedAuthorization The authorization against which the Requestors are being tested in this computation. RequestedAuthorizationPeriod The time range of an authorization computation. BaseAuthorizations The group of ACL entries (unsigned certificates) provided as the basis for this computation. Credentials A group of tuple-certificates used with the BaseAuthorizations to grant authorizations to the Requestors. ___________________________________________________________ Kind of Subject Example Requestor ___________________________________________________________ Public key (public-key (rsa-pkcs1-sha1 (e #03#) (n ##))) (hash md5 #900150983cd24fb0d6963f7d28e17f72#) Hash of object, key, template, etc. ___________________________________________________________ The most likely Requestor is a public key that signs a request. In common practice there will be one Requestor per computation, but it is possible for an ACL or certificate to require multiple signatures or other forms of identification before an action is authorized. In that case, there must be multiple Requestors. This function can be used in the following modes: · To verify the authorization of a specific request, backed up by specific Requestors · To compute the set of authorizations that a particular set of Requestors has been granted by the BaseAuthorizations and Credentials. When using this function to verify an authorization, the RequestedAuthorization is the specific authorization being requested and the RequestedAuthorizationPeriod gives the date and time of that request (typically the current date and time) using both NOT_BEFORE and NOT_AFTER dates. The result, if any, should be an ACL entry with the same authorization that was requested. If such an ACL entry is produced by the computation, then the request is authorized. Requested Authorization Example (http http://private.cdsa.hp.com/local-data.html ) (ftp ftp://private.cdsa.hp.com/users/cme/private/test.txt write) Requested Authorization Period Example (valid (not-before "1999-07-28_17:00:44") (not-after "1999-07- 28_17:00:44")) When using this function to compute the full set of possible authorizations from a set of credentials, rather than to verify a specific access request, the inputs should be of the following form: · RequestedAuthorizationPeriod is either an empty list or the list "valid", indicating "all time". · RequestedAuthorization is the list "*", indicating all possible authorizations. The result of this computation, if any, will be one or more ACL entries representing all the granted authorizations for the indicated requestor. The scope of ACLs output from this function is limited to the local system. Each ACL should be interpreted to mean: "for this machine, under these base authorization ACLs and the provided certificates, relative to the specified requestors, the following authorizations have been deduced". Those authorizations are available only on the current platform (and possibly only for the application providing the ACL) and are therefore in the form of an ACL. They are not intended to be used by any other machine or application instance. However, the resulting ACLs can be transferred and used outside of the local scope by an entity with authority in the target scope/environment. The transfer and use is a three-step process: 1. Convert the ACL into one or more certificates. The certificates must be signed by some private key with appropriate authority in the target scope/environment. 2. Transfer the certificates to the target environment. 3. Use the signed certificates as input Credentials to this function in the target scope/environment. If the function is successful, check (*AuthorizationResult)->NumCerts to determine the precise number of authorizations granted by this computation. If 0, then the requestors were not authorized. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_AC_INVALID_BASE_ACLS CSSMERR_AC_INVALID_ENCODING CSSMERR_AC_INVALID_REQUESTOR CSSMERR_AC_INVALID_REQUEST_DESCRIPTOR CSSMERR_AC_INVALID_TUPLE_CREDENTIALS CSSMERR_AC_INVALID_VALIDITY_PERIOD SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_TP_CertGroupToTupleGroup CSSM_TP_TupleGroupToCertGroup Functions for the AC SPI: TP_CertGroupToTupleGroup TP_TupleGroupToCertGroup 4 ACHandle (input) The handle that describes the authorization computation module used to perform this function. 4 BaseAuthorizations (input) A pointer to a CSSM_TUPLEGROUP containing at least one ACL certificate, specifying the authorization granted to certain root keys, named entities or combinations thereof. A NULL group of BaseAuthorizations always results in a NULL AuthorizationResult. 4 Credentials (input/optional) A pointer to a CSSM_TUPLEGROUP containing a group of certificates, in TUPLE form. The tuple-certificates define the delegation of authorizations from the BaseAuthorizations to the Requestors. If no additional authorization-granting tuples are provided, then this value is NULL and the BaseAuthorizations are the only source of trusted authorizations used as input to the authorization computation. 4 NumberOfRequestors (input) The number of entries in the Requestors array. 4 Requestors (input) A pointer to a list of requestors that define the "who" portion of the request. The list can be of type CSSM_LIST_TYPE_SEXPR. Typical exhibits include: · Public keys · Hashes of keys · Hashes of other objects offered for proof. 4 RequestedAuthorizationPeriod (input/optional) A list defining a validity period or NULL (implying "all time"). This is the "when" portion of the request. If the list is of type CSSM_LIST_TYPE_SEXPR, then the validity interval is specified as a two-element list containing the values ((not-before )(not-after )). Note that each element is a two-element sublist. The is represented by an ASCII byte-string, in the format (for example) "1998-11-24_15:06:16" and is assumed to be GMT. Open-ended time intervals are specified by omitting either of the interval ends. For example, ((not-before 1997-1-1_00:00:0)) specifies all dates and times beginning on January 1, 1997 going forward indefinitely. For programming convenience, when testing for authorization at a single point in time, the date is represented by a one-element list containing (). 4 RequestedAuthorization (input) A list defining the "what" portion of the authorization being requested. If the list is of type CSSM_LIST_TYPE_SEXPR, then the list presents an authorization request in SPKI format. If a specific authorization is being requested, then this input is a two-element SEXPR list containing (tag ). The valid values for are application-specific. If this is a request to derive all possible authorizations based on the BaseAuthorizations, Credentials, and Requestors, then this input value must be the two-element list containing (tag (*)). This list corresponds to "all authorizations". With this input, the function tests the provided ACL and certificates against the Requestors (and possibly RequestedAuthorizationPeriod) to yield all authorizations for which the provided Exhibits qualify. 4 AuthorizationResult (output) A CSSM_TUPLEGROUP structure, giving the result of the authorization computation. Typically there will be one result, but there could be as many as there are entries in the BaseAuthorizations. Each of these results says, in effect: "for this machine, under this ACL and the provided certificates, relative to the specified Requestors, the following authorizations have been deduced". Those authorizations are available only on the current platform (and possibly only for the application providing the ACL), and are therefore in the form of an ACL. They are not intended to be used by any other machine or application instance, necessarily, and need to be converted into certificates signed by some private key available to the caller if they are to be so used. 3 AC_PassThrough NAME AC_PassThrough, CSSM_AC_PassThrough - Call exported module-specific operations (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_AC_PassThrough (CSSM_AC_HANDLE ACHandle, CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DL_DB_LIST *DBList, uint32 PassThroughId, const void *InputParams, void **OutputParams) SPI: CSSM_RETURN CSSMACI AC_PassThrough (CSSM_AC_HANDLE ACHandle, CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DL_DB_LIST *DBList, uint32 PassThroughId, const void *InputParams, void **OutputParams) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS ACHandle, TPHandle, CLHandle, CCHandle, DBList, PassThroughId, InputParams, OutputParams DESCRIPTION This function allows applications to call authorization computation module-specific operations that have been exported. Such operations might include queries or services specific to the domain represented by the AC module. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_AC_INVALID_CL_HANDLE CSSMERR_AC_INVALID_CONTEXT_HANDLE CSSMERR_AC_INVALID_DBLIST_POINTER CSSMERR_AC_INVALID_DB_LIST CSSMERR_AC_INVALID_DB_HANDLE CSSMERR_AC_INVALID_DL_HANDLE CSSMERR_AC_INVALID_PASSTHROUGH_ID CSSMERR_AC_INVALID_TP_HANDLE SEE ALSO Intel CDSA Application Developer's Guide (see CDSA) 4 ACHandle (input) The handle that describes the authorization computation module used to perform this function. 4 TPHandle (input/optional) The handle that describes the trust policy module that can be used by the authorization computation service to implement this function. If no trust policy module is specified, the AC module uses an assumed TP module, if required. 4 CLHandle (input/optional) The handle that describes the add-in certificate library module that can be used to manipulate the subject certificate and anchor certificates. If no certificate library module is specified, the AC module uses an assumed CL module, if required. 4 CCHandle (input/optional) The handle that describes the cryptographic context containing a handle that describes the add-in cryptographic service provider module that can be used to perform cryptographic operations as required to perform the requested operation. If no cryptographic context is specified, the AC module uses an assumed cryptographic context and CSP module, if required. 4 DBList (input/optional) A list of handle pairs specifying a data storage library module and a data store managed by that module. These data stores can contain certificates, CRLs, and policy objects for use by the AC module. If no DL and DB handle pairs are specified, the AC module uses an assumed DL module and an assumed data store for this operation. 4 PassThroughId (input) An identifier assigned by the AC module to indicate the exported function to perform. 4 InputParams (input) A pointer to a module, implementation-specific structure containing parameters to be interpreted in a function-specific manner by the requested AC module. If the passthrough function requires access to a private key located in the CSP referenced by CSPHandle, then InputParams should contain a passphrase, or a callback or cryptographic context that can be used to obtain the passphrase. 4 OutputParams (output/optional) A pointer to a module, implementation-specific structure containing the output data. The service provider will allocate the memory for this structure. The application must free the memory for the structure. 3 CL_CertAbortCache NAME CL_CertAbortCache, CSSM_CL_CertAbortCache - Terminate a certificate cache handle (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CertAbortCache (CSSM_CL_HANDLE CLHandle, CSSM_HANDLE CertHandle) SPI: CSSM_RETURN CSSMAPI CSSM_CL_CertAbortCache (CSSM_CL_HANDLE CLHandle, CSSM_HANDLE CertHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the certificate library module used to perform this function. CertHandle (input) The handle that identifies the cached certificate. DECRIPTION This function terminates a certificate cache handle created and returned by the function CSSM_CL_CertCache() (CSSM API) or CL_CertCache() (CL SPI). The Certificate Library module releases all cache space and state information associated with the cached certificate. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_CACHE_HANDLE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CertCache Functions for the CLI SPI: CL_CertCache 3 CL_CertAbortQuery NAME CL_CertAbortQuery, CSSM_CL_CertAbortQuery function - Terminate a results handle (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CertAbortQuery (CSSM_CL_HANDLE CLHandle, CSSM_HANDLE ResultsHandle) SPI: CSSM_RETURN CSSMAPI CSSM_CL_CertAbortQuery (CSSM_CL_HANDLE CLHandle, CSSM_HANDLE ResultsHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in certificate library module used to perform this function. ResultsHandle (input) A pointer to the handle that identifies the results of a CSSM_CL_GetFieldValue() (CSSM API), or CL_GetFieldValue() (CLI SPI) request. DESCRIPTION This function terminates a results handle used to access multiple certificate fields identified by a single OID. The ResultsHandle was created and returned by CSSM_CL_CertGetFirstFieldValue() (CSSM API), or CL_CertGetFirstFieldValue() (CL SPI), or CSSM_CL_CertGetFirstCachedFieldValue() (CSSM API), or CL_CertGetFirstCachedFieldValue() (CL SPI). The CL releases all intermediate state information associated with the repeating-value query. Once this function has been invoked, the results handle is invalid. Applications must invoke this function to terminate the ResultsHandle. Using CSSM_CL_CertGetNextFieldValue() (CSSM API), or CL_CertGetNextFieldValue() (CL SPI), or CSSM_CL_CertGetNextCachedFieldValue() (CSSM API), or CL_CertGetNextCachedFieldValue() (CL SPI), to access all of the attributes named by a single OID does not terminate the ResultsHandle. This function can be invoked to terminate the results handle without accessing all values identified by the single OID. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_RESULTS_HANDLE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CertGetFirstFieldValue CSSM_CL_CertGetNextFieldValue CSSM_CL_CertGetFirstCachedFieldValue CSSM_CL_CertGetNextCachedFieldValue Functions for the CLI SPI: CL_CertGetFirstFieldValue CL_CertGetNextFieldValue CL_CertGetFirstCachedFieldValue CL_CertGetNextCachedFieldValue 3 CL_CertCache NAME CL_CertCache, CSSM_CL_CertCache - Cache a copy of a certificate (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CertCache (CSSM_CL_HANDLE CLHandle, const CSSM_DATA *Cert, CSSM_HANDLE_PTR CertHandle) SPI: CSSM_RETURN CSSMAPI CSSM_CL_CertCache (CSSM_CL_HANDLE CLHandle, const CSSM_DATA *Cert, CSSM_HANDLE_PTR CertHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the certificate library module used to perform this function. Cert (input) A pointer to the CSSM_DATA structure containing the encoded certificate. CertHandle (output) A pointer to the CSSM_HANDLE that should be used in all future references to the cached certificate. DESCRIPTION This function caches a copy of a certificate for subsequent accesses using the functions CSSM_CL_CertGetFirstCachedFieldValue() (CSSM API), or CL_CertGetFirstCachedFieldValue() (CL SPI), and CSSM_CL_CertGetNextCachedFieldValue() (CSSM API), or CL_CertGetNextCachedFieldValue() (CL SPI). The input certificate must be in an encoded representation. The Certificate Library module can cache the certificate in any appropriate internal representation. Parsed or incrementally parsed representations are common. The selected representation is opaque to the caller. The application must call CSSM_CL_CertAbortCache() (CSSM API), or CL_CertAbortCache() (CL SPI), to remove the cached copy when additional get operations will not be performed on the cached certificate. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_CERT_POINTER CSSMERR_CL_UNKNOWN_FORMAT SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CertGetFirstCachedFieldValue CSSM_CL_CertGetNextCachedFieldValue CSSM_CL_CertAbortQuery CSSM_CL_CertAbortCache Functions for the CLI SPI: CL_CertGetFirstCachedFieldValue CL_CertGetNextCachedFieldValue CL_CertAbortQuery CL_CertAbortCache 3 CL_CertCreateTemplate NAME CL_CertCreateTemplate, CSSM_CL_CertCreateTemplate - Allocate and initialize memory for a certificate template (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CertCreateTemplate (CSSM_CL_HANDLE CLHandle, uint32 NumberOfFields, const CSSM_FIELD *CertFields, CSSM_DATA_PTR CertTemplate) SPI: CSSM_RETURN CSSMCLI CL_CertCreateTemplate (CSSM_CL_HANDLE CLHandle, uint32 NumberOfFields, const CSSM_FIELD *CertFields, CSSM_DATA_PTR CertTemplate) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the certificate library module used to perform this function. NumberOfFields (input) The number of certificate field values specified in the CertFields. CertFields (input) A pointer to an array of OID/value pairs that identify the field values to initialize a new certificate. CertTemplate (output) A pointer to a CSSM_DATA structure that will contain the unsigned certificate template as a result of this function. DESCRIPTION This function allocates and initializes memory for an encoded certificate template output in CertTemplate->Data. The template values are specified by the input OID/value pairs contained in CertFields. The initialization process includes encoding all certificate field values according to the certificate type and certificate encoding supported by the certificate library module. The memory for CertTemplate->Data is allocated by the service provider using the calling application's memory management routines. The application must deallocate the memory. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_FIELD_POINTER CSSMERR_CL_UNKNOWN_TAG CSSMERR_CL_INVALID_NUMBER_OF_FIELDS SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CertGetAllTemplateFields CSSM_CL_CertSign Functions for the CLI SPI: CL_CertGetAllTemplateFields CL_CertSign 3 CL_CertDescribeFormat NAME CL_CertDescribeFormat, CSSM_CL_CertDescribeFormat - Return a list of the CSSM_OID values (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CertDescribeFormat (CSSM_CL_HANDLE CLHandle, uint32 *NumberOfOids, CSSM_OID_PTR *OidList) SPI: CSSM_RETURN CSSMAPI CSSM_CL_CertDescribeFormat (CSSM_CL_HANDLE CLHandle, uint32 *NumberOfOids, CSSM_OID_PTR *OidList) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in certificate library module used to perform this function. NumberOfOids (output) The length of the returned array of OIDs. OidList (output) A pointer to the array of CSSM_OIDs that represent the supported certificate format. The OID list is allocated by the service provider and must be deallocated by the application. DESCRIPTION This function returns a list of the CSSM_OID values this certificate library module uses to name and reference fields of a certificate. Multiple CSSM_OID values can correspond to a single field. These OIDs can be provided as input to CSSM_CL_CertGetFirstFieldValue() (CSSM API), or CL_CertGetFirstFieldValue() (CL SPI), to retrieve field values from the certificate. The OID also implies the data format of the returned value. When multiple OIDs name the same field of a certificate, those OIDs have different return data formats associated with them. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CertGetAllFields CSSM_CL_CertGetFirstFieldValue CSSM_CL_CertGetFirstCachedFieldValue Functions for the CLI SPI: CL_CertGetAllFields CL_CertGetFirstFieldValue CL_CertGetFirstCachedFieldValue 3 CL_CertGetAllFields NAME CL_CertGetAllFields, CSSM_CL_CertGetAllFields - Return a list of input certificate values (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CertGetAllFields (CSSM_CL_HANDLE CLHandle, const CSSM_DATA *Cert, uint32 *NumberOfFields, CSSM_FIELD_PTR *FieldList) SPI: CSSM_RETURN CSSMCLI CL_CertGetAllFields (CSSM_CL_HANDLE CLHandle, const CSSM_DATA *Cert, uint32 *NumberOfFields, CSSM_FIELD_PTR *FieldList) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in certificate library module used to perform this function. Cert (input) A pointer to the CSSM_DATA structure containing the certificate whose fields will be returned. NumberOfFields (output) The length of the returned array of fields. FieldList (output) A pointer to an array of CSSM_FIELD structures that contain the values of all fields of the input certificate. The field list is allocated by the service provider and must be deallocated by the application by calling CSSM_CL_FreeFields() (CSSM API), or CL_FreeFields() (CL SPI). DESCRIPTION This function returns a list of the values stored in the input certificate. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_CERT_POINTER CSSMERR_CL_UNKNOWN_FORMAT SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics For the CSSM API: CSSM_CL_CertGetFirstFieldValue, CSSM_CL_CertDescribeFormat CSSM_CL_FreeFields For the CLI SPI: CL_CertGetFirstFieldValue CL_CertDescribeFormat CL_FreeFields 3 CL_CertGetAllTemplateFields NAME CL_CertGetAllTemplateFields, CSSM_CL_CertGetAllTemplateFields - Extract and return values stored in CertTemplate (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CertGetAllTemplateFields (CSSM_CL_HANDLE CLHandle, const CSSM_DATA *CertTemplate, uint32 *NumberOfFields, CSSM_FIELD_PTR *CertFields) SPI: CSSM_RETURN CSSMCLI CL_CertGetAllTemplateFields (CSSM_CL_HANDLE CLHandle, const CSSM_DATA *CertTemplate, uint32 *NumberOfFields, CSSM_FIELD_PTR *CertFields) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the certificate library module used to perform this function. CertTemplate (input) A pointer to the CSSM_DATA structure containing the packed, encoded certificate template. NumberOfFields (output) The length of the output array of fields. CertFields (output) A pointer to an array of CSSM_FIELD structures which contains the OIDs and values of the fields of the input certificate template. DESCRIPTION This function extracts and returns a copy of the values stored in the encoded CertTemplate. The memory for the CertFields output is allocated by the service provider using the calling application's memory management routines. The application must deallocate the memory by calling CSSM_CL_FreeFields() (CSSM API), or CL_FreeFields() (CL SPI). 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_UNKNOWN_FORMAT SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_FreeFields CSSM_CL_CertCreateTemplate Functions for the CLI SPI: CL_FreeFields CL_CertCreateTemplate 3 CL_CertGetFirstCachedFieldValue NAME CL_CertGetFirstCachedFieldValue, CSSM_CL_CertGetFirstCachedFieldValue - Return values from the cached certificate (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CertGetFirstCachedFieldValue (CSSM_CL_HANDLE CLHandle, CSSM_HANDLE CertHandle, const CSSM_OID *CertField, CSSM_HANDLE_PTR ResultsHandle, uint32 *NumberOfMatchedFields, CSSM_DATA_PTR *FieldValue) SPI: CSSM_RETURN CSSMAPI CSSM_CL_CertGetFirstCachedFieldValue (CSSM_CL_HANDLE CLHandle, CSSM_HANDLE CertHandle, const CSSM_OID *CertField, CSSM_HANDLE_PTR ResultsHandle, uint32 *NumberOfMatchedFields, CSSM_DATA_PTR *FieldValue) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in certificate library module used to perform this function. CertHandle (input) A handle identifying a certificate that the application has temporarily cached with the Certificate Library module. The referenced certificate is searched for the field value named by CertField. CertField (input) A pointer to an object identifier that identifies the field value to be extracted from the Cert. ResultsHandle (output) A pointer to the CSSM_HANDLE that should be used to obtain any additional matching fields. NumberOfMatchedFields (output) The total number of fields that match the CertField OID. This count includes the first match, which was returned by this function. FieldValue (output) A pointer to the structure containing the value of the requested field. The structure and the field at I "(*FieldValue)->Data" are allocated by the service provider. The CSSM_CL_FreeFieldValue() (CSSM API), or CL_FreeFieldValue() (CL SPI), function can be used to deallocate FieldValue and (*FieldValue)->Data. DESCRIPTION This function returns a single structure containing a set of field values from the cached certificate identified by CertHandle. The selected fields are designated by the CSSM_OID CertField and returned in the output parameter FieldValue. The OID also identifies the data format of the values returned to the caller. If multiple OIDs designate the same certificate field, then each such OID defines a distinct data format for the returned values. The function CSSM_CL_CertDescribeFormat() (CSSM API), or CL_CertDescribeFormat() (CL SPI), provides a list of all CSSM_OID values supported by a certificate library module for naming fields of a certificate. The CertField OID can identify a single occurrence of a set of certificate fields, or multiple occurrences of a set of certificate fields. If the CertField OID matches more than one occurrence, this function outputs the total number of matches and a ResultsHandle to be used as input to CSSM_CertGetNextCachedFieldValue() (CSM API), or CertGetNextCachedFieldValue() (CL SPI), to retrieve the remaining matches. The first match is returned as the return value of this function. This function determines the complete set of matches. The number of matches and the selected field values do not change between this function and subsequent calls to CSSM_CL_CertGetNextCachedFieldValue() (CSSM API), or CL_CertGetNextCachedFieldValue() (CL SPI). 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_CACHE_HANDLE CSSMERR_CL_UNKNOWN_TAG CSSMERR_CL_NO_FIELD_VALUES SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CertGetNextCachedFieldValue CSSM_CL_CertAbortCache CSSM_CL_CertAbortQuery CSSM_CL_CertGetAllFields CSSM_CL_CertDescribeFormat CSSM_CL_FreeFieldValue Functions for the CLI SPI: CL_CertGetNextCachedFieldValue CL_CertAbortCache CL_CertAbortQuery CL_CertGetAllFields CL_CertDescribeFormat CL_FreeFieldValue 3 CL_CertGetFirstFieldValue NAME CL_CertGetFirstFieldValue, CSSM_CL_CertGetFirstFieldValue - Return the value of the certificate field (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CertGetFirstFieldValue (CSSM_CL_HANDLE CLHandle, const CSSM_DATA *Cert, const CSSM_OID *CertField, CSSM_HANDLE_PTR ResultsHandle, uint32 *NumberOfMatchedFields, CSSM_DATA_PTR *Value) SPI: CSSM_RETURN CSSMCLI CL_CertGetFirstFieldValue (CSSM_CL_HANDLE CLHandle, const CSSM_DATA *Cert, const CSSM_OID *CertField, CSSM_HANDLE_PTR ResultsHandle, uint32 *NumberOfMatchedFields, CSSM_DATA_PTR *Value) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in certificate library module used to perform this function. Cert (input) A pointer to the CSSM_DATA structure containing the certificate. CertField (input) A pointer to an object identifier which identifies the field value to be extracted from the Cert. ResultsHandle (output) A pointer to the CSSM_HANDLE that should be used to obtain any additional matching fields. NumberOfMatchedFields (output) The total number of fields that match the CertField OID. This count includes the first match, which was returned by this function. Value (output) A pointer to the structure containing the value of the requested field. The structure and the field at I "(*Value)->Data" are allocated by the service provider. The CSSM_CL_FreeFieldValue() (CSSM API) or CL_FreeFieldValue() (CL SPI) function can be used to deallocate *Value and (*Value)->Data. DESCRIPTION This function returns the value of the certificate field designated by the CSSM_OID CertField. The OID also identifies the data format for the field value returned to the caller. If multiple OIDs name the same certificate field, then each such OID defines a distinct data format for the returned field value. The function CSSM_CL_CertDescribeFormat() (CSSM API), or CL_CertDescribeFormat() (CL SPI), provides a list of all CSSM_OID values supported by a certificate library module for naming fields of a certificate. If more than one field matches the CertField OID, the first matching field will be returned. The number of matching fields is an output parameter, as is the ResultsHandle to be used to retrieve the remaining matching fields. The set of matching fields is determined by this function. The number of matching fields and the field values do not change between this function and subsequent calls to CSSM_CL_CertGetNextFieldValue() (CSSM API), or CL_CertGetNextFieldValue() (CL SPI). 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_CERT_POINTER CSSMERR_CL_UNKNOWN_FORMAT CSSMERR_CL_UNKNOWN_TAG CSSMERR_CL_NO_FIELD_VALUES SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CertGetNextFieldValue CSSM_CL_CertAbortQuery CSSM_CL_CertGetAllField CSSM_CL_FreeFieldValue CSSM_CL_CertDescribeFormat CSSM_CL_FreeFieldValue Functions for the CLI SPI: CL_CertGetNextFieldValue CL_CertAbortQuery CL_CertGetAllField CL_FreeFieldValue CL_CertDescribeFormat CL_FreeFieldValue 3 CL_CertGetKeyInfo NAME CL_CertGetKeyInfo, CSSM_CL_CertGetKeyInfo - Return the public key and integral information (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CertGetKeyInfo (CSSM_CL_HANDLE CLHandle, const CSSM_DATA *Cert, CSSM_KEY_PTR *Key) SPI: CSSM_RETURN CSSMCLI CL_CertGetKeyInfo (CSSM_CL_HANDLE CLHandle, const CSSM_DATA *Cert, CSSM_KEY_PTR *Key) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in certificate library module used to perform this function. Cert (input) A pointer to the CSSM_DATA structure containing the certificate from which to extract the public key information. Key (output) A pointer to the CSSM_KEY structure containing the public key and possibly other key information. The CSSM_KEY structure and its substructures are allocated by the service provider and must be deallocated by the application. DESCRIPTION This function returns the public key and integral information about the key from the specified certificate. The key structure returned is a compound object. It can be used in any function requiring a key, such as creating a 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. ERRORS Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_CERT_POINTER CSSMERR_CL_UNKNOWN_FORMAT SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CertGetFirstFieldValue CSSM_CL_FreeFieldValue Functions for the CLI SPI: CL_CertGetFirstFieldValue CL_FreeFieldValue 3 CL_CertGetNextCachedFieldValue NAME CL_CertGetNextCachedFieldValue, CSSM_CL_CertGetNextCachedFieldValue - Return the value of a certificate field (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CertGetNextCachedFieldValue (CSSM_CL_HANDLE CLHandle, CSSM_HANDLE ResultsHandle, CSSM_DATA_PTR *FieldValue) SPI: CSSM_RETURN CSSMAPI CSSM_CL_CertGetNextCachedFieldValue (CSSM_CL_HANDLE CLHandle, CSSM_HANDLE ResultsHandle, CSSM_DATA_PTR *FieldValue) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the certificate library module used to perform this function. ResultsHandle (input) The handle that identifies the results of a certificate query. FieldValue (output) A pointer to the structure containing the value of the requested field. The structure and the field at I "(*FieldValue)->Data" are allocated by the service provider. The CSSM_CL_FreeFieldValue() (CSSM API), or CL_FreeFieldValue() (CL SPI) function can be used to deallocate *FieldValue and (*FieldValue)->Data. DESCRIPTION This function returns the value of a certificate field, when that field occurs multiple times in a certificate. Certificates with repeated fields (such as multiple signatures) have multiple field values corresponding to a single OID. A call to the function CSSM_CL_CertGetFirstCachedFieldValue() (CSSM API), or CL_CertGetFirstCachedFieldValue() (CL SPI), returns a ResultsHandle identifying the size and values contained in the result set. The CSSM_CL_CertGetNextCachedFieldValue() (CSSMAPI), or CL_CertGetNextCachedFieldValue() (CL SPI), function can be called repeatedly to obtain these values, one at a time. The result set does not change in size or value between calls to 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_RESULTS_HANDLE CSSMERR_CL_NO_FIELD_VALUES SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CertGetFirstCachedFieldValue CSSM_CL_CertAbortCache CSSM_CL_CertAbortQuery CSSM_CL_CertGetAllFields CSSM_CL_CertDescribeFormat CSSM_CL_FreeFieldValue Functions for the CLI SPI: CL_CertGetFirstCachedFieldValue CL_CertAbortCache CL_CertAbortQuery CL_CertGetAllFields CL_CertDescribeFormat CL_FreeFieldValue 3 CL_CertGetNextFieldValue NAME CL_CertGetNextFieldValue, CSSM_CL_CertGetNextFieldValue - Return the value of a certificate field (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CertGetNextFieldValue (CSSM_CL_HANDLE CLHandle, CSSM_HANDLE ResultsHandle, CSSM_DATA_PTR *Value) SPI: CSSM_RETURN CSSMCLI CL_CertGetNextFieldValue (CSSM_CL_HANDLE CLHandle, CSSM_HANDLE ResultsHandle, CSSM_DATA_PTR *Value) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in certificate library module used to perform this function. ResultsHandle (input) The handle that identifies the results of a certificate query. Value (output) A pointer to the structure containing the value of the requested field. The structure and the field at I "(*Value)->Data" are allocated by the service provider. The CSSM_CL_FreeFieldValue() (CSSM API) or CL_FreeFieldValue() (CL SPI), function can be used to deallocate *Value and (*Value)->Data. DESCRIPTION This function returns the value of a certificate field, when that field occurs multiple times in a certificate. Certificates with repeated fields (such as multiple signatures) have multiple field values corresponding to a single OID. A call to the function CSSM_CL_CertGetFirstFieldValue() (CSSM API), or CL_CertGetFirstFieldValue() (CL SPI), returns a results handle identifying the size and values contained in the result set. The CSSM_CL_CertGetNextFieldValue() (CSSM API), or CL_CertGetNextFieldValue() (CL SPI), function can be called repeatedly to obtain these values, one at a time. The result set does not change in size or value between calls to 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_RESULTS_HANDLE CSSMERR_CL_NO_FIELD_VALUES SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CertGetFirstFieldValue CSSM_CL_CertAbortQuery CSSM_CL_FreeFieldValue Functions for the CLI SPI: CL_CertGetFirstFieldValue CL_CertAbortQuery CL_FreeFieldValue 3 CL_CertGroupFromVerifiedBundle NAME CL_CertGroupFromVerifiedBundle, CSSM_CL_CertGroupFromVerifiedBundle - Verify the signature of a bundle (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CertGroupFromVerifiedBundle (CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CERT_BUNDLE *CertBundle, const CSSM_DATA *SignerCert, CSSM_CERTGROUP_PTR *CertGroup) SPI: CSSM_RETURN CSSMCLI CL_CertGroupFromVerifiedBundle (CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CERT_BUNDLE *CertBundle, const CSSM_DATA *SignerCert, CSSM_CERTGROUP_PTR *CertGroup) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in certificate library module used to perform this function. CCHandle (input/optional) The handle of the cryptographic context to control the verification operation. CertBundle (input) A structure containing a reference to a signed, encoded bundle of certificates and to descriptors of the type and encoding of the bundle. The bundled certificates are to be separated into a certificate group (list of individual encoded certificates). If the bundle type and bundle encoding are not specified, the add-in module might either attempt to decode the bundle assuming a default type and encoding or might immediately fail. SignerCert (input/optional) The certificate to be used to verify the signature on the certificate bundle. If the bundle is signed but this field is not specified, then the module will assume a default certificate for verification. CertGroup (output) A pointer to the certificate group, represented as an array of individual, encoded certificates. The certificate group and CSSM_CERTGROUP substructures are allocated by the serivce provider and must be deallocated by the application. The group contains all certificates contained in the certificate bundle. DESCRIPTION This function accepts as input a certificate bundle (a codified and signed aggregation of the certificates in the group), verifies the signature of the bundle (if a signature is present), and returns a certificate group (as an array of individual certificates) including every certificate contained in the bundle. The signature on the certificate aggregate is verified using the cryptographic context and possibly using the input signer certificate. The CL module embeds the knowledge of the verification scope for the bundle types that it supports. A CL module's supported bundle types and encodings are available to applications by querying the CSSM registry. The type and encoding of the certificate bundle must be specified with the input bundle. If signature verification is successful, the certificate aggregate will be parsed into a certificate group whose order corresponds to the certificate aggregate ordering. This certificate group will then be returned to the calling application. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_CONTEXT_HANDLE CSSMERR_CL_INVALID_BUNDLE_POINTER CSSMERR_CL_INVALID_BUNDLE_INFO CSSMERR_CL_INVALID_CERT_POINTER CSSMERR_CL_INVALID_CERTGROUP_POINTER CSSMERR_CL_UNKNOWN_FORMAT SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CertGroupToSignedBundle Functions for the CLI SPI: CL_CertGroupToSignedBundle 3 CL_CertGroupToSignedBundle NAME CL_CertGroupToSignedBundle, CSSM_CL_CertGroupToSignedBundle - Convert a certificate group to a certificate bundle (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CertGroupToSignedBundle (CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CERTGROUP *CertGroupToBundle, const CSSM_CERT_BUNDLE_HEADER *BundleInfo, CSSM_DATA_PTR SignedBundle) SPI: CSSM_RETURN CSSMCLI CL_CertGroupToSignedBundle (CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CERTGROUP *CertGroupToBundle, const CSSM_CERT_BUNDLE_HEADER *BundleInfo, CSSM_DATA_PTR SignedBundle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in certificate library module used to perform this function. CCHandle (input/optional) The handle of the cryptographic context to control the signing operation. The operation will fail if a signature is required for this type of bundle and the cryptographic context is not valid. CertGroupToBundle (input) An array of individual, encoded certificates. All certificates in this list will be included in the resulting certificate bundle. BundleInfo (input/optional) A structure containing the type and encoding of the bundle to be created. If the type and the encoding are not specified, then the module will use a default bundle type and bundle encoding. SignedBundle (output) The function returns a pointer to a signed certificate bundle containing all certificates in the certificate group. The bundle is of the type and encoding requested by the caller or is the default type defined by the library module if the BundleInfo was not specified by the caller. The SignedBundle->Data is allocated by the service provider and must be deallocated by the application. DESCRIPTION This function accepts as input a certificate group (as an array of individual certificates) and returns a certificate bundle (a codified and signed aggregation of the certificates in the group). The certificate group will first be encoded according to the BundleInfo input by the user. If BundleInfo is NULL, the library will perform a default encoding for its default bundle type. If possible, the certificate group ordering will be maintained in this certificate aggregate encoding. After encoding, the certificate aggregate will be signed using the input context. The CL module embeds knowledge of the signing scope for the bundle types it supports. The signature is then associated with the certificate aggregate according to the bundle type and encoding rules and is returned as a bundle to the calling application. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_CONTEXT_HANDLE CSSMERR_CL_INVALID_CERTGROUP_POINTER CSSMERR_CL_INVALID_CERT_POINTER CSSMERR_CL_UNKNOWN_FORMAT CSSMERR_CL_INVALID_BUNDLE_POINTER CSSMERR_CL_INVALID_BUNDLE_INFO SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CertGroupFromVerifiedBundle Functions for the CLI SPI: CL_CertGroupFromVerifiedBundle 3 CL_CertSign NAME CL_CertSign, CSSM_CL_CertSign - Sign a certificate (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CertSign (CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *CertTemplate, const CSSM_FIELD *SignScope, uint32 ScopeSize, CSSM_DATA_PTR SignedCert) SPI: CSSM_RETURN CSSMCLI CL_CertSign (CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *CertTemplate, const CSSM_FIELD *SignScope, uint32 ScopeSize, CSSM_DATA_PTR SignedCert) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in certificate library module used to perform this function. CCHandle (input) A signature context defining the CSP, signing algorithm, and private key that must be used to perform the operation. The passphrase for the private key is also provided. CertTemplate (input) A pointer to a CSSM_DATA structure containing a certificate template in the default format supported by this CL. The template contains values that are currently contained in or will be contained in a signed certificate. SignScope (input/optional) A pointer to the CSSM_FIELD array containing the OID/value pairs of the fields to be signed. A null input signs all the fields provided by CertTemplate. ScopeSize (input) The number of entries in the SignScope list. If the sign scope is not specified, the input value for scope size must be zero. SignedCert (output) A pointer to the CSSM_DATA structure containing the signed certificate. DESCRIPTION This function signs a certificate using the private key and signing algorithm specified in the CCHandle. The result is a signed, encoded certificate in SignedCert. The certificate field values are specified in the input certificate template. The template is constructed using CSSM_CL_CertCreateTemplate() (CSSM API), or CL_CertCreateTemplate() (CL SPI). The template is in the default format for this CL. The CCHandle must be a signature context created using the function CSSM_CSP_CreateSignatureContext() (CSSM API), or CSP_CreateSignatureContext() (SPI). The context must specify the Cryptographic Services Provider (CSP) module, the signing algorithm, and the signing key that must be used to perform this operation. The context must also provide the passphrase or a callback function to obtain the passphrase required to access and use the private key. The fields included in the signing operation are identified by the OIDs in the optional SignScope array. The memory for the SignedCert->Data output is allocated by the service provider using the calling application's memory management routines. The application must deallocate the memory. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_CONTEXT_HANDLE CSSMERR_CL_UNKNOWN_FORMAT CSSMERR_CL_INVALID_FIELD_POINTER CSSMERR_CL_UNKNOWN_TAG CSSMERR_CL_INVALID_SCOPE CSSMERR_CL_INVALID_NUMBER_OF_FIELDS CSSMERR_CL_SCOPE_NOT_SUPPORTED SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CertVerify CSSM_CL_CertCreateTemplate Functions for the CLI SPI: CL_CertVerify CL_CertCreateTemplate 3 CL_CertVerify NAME CL_CertVerify, CSSM_CL_CertVerify - Verify a signed certificate (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CertVerify (CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *CertToBeVerified, const CSSM_DATA *SignerCert, const CSSM_FIELD *VerifyScope, uint32 ScopeSize) SPI: CSSM_RETURN CSSMAPI CSSM_CL_CertVerify (CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *CertToBeVerified, const CSSM_DATA *SignerCert, const CSSM_FIELD *VerifyScope, uint32 ScopeSize) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETER CLHandle (input) The handle that describes the add-in certificate library module used to perform this function. CCHandle (input/optional) The handle that describes the context of this cryptographic operation. CertToBeVerified (input) A pointer to the CSSM_DATA structure with a certificate containing at least one signature for verification. An unsigned certificate template cannot be verified. SignerCert (input/optional) A pointer to the CSSM_DATA structure containing the certificate used to sign the subject certificate. This certificate provides the public key to use in the verification process and if the certificate being verified contains multiple signatures, the signer's certificate indicates which signature is to be verified. VerifyScope (input/optional) A pointer to the CSSM_FIELD array containing the tag/value pairs of the fields to be used in verifying the signature. (This should include all fields that were used to calculate the signature.) If the verify scope is null, the certificate library module assumes that its default set of certificate fields were used to calculate the signature, and those same fields are used in the verification process. ScopeSize (input) The number of entries in the verify scope list. If the verification scope is not specified, the input value for scope size must be zero. DESCRIPTION This function verifies that the signed certificate has not been altered since it was signed by the designated signer. Only one signature is verified by this function. If the certificate to be verified includes multiple signatures, this function must be applied once for each signature to be verified. This function verifies a digital signature over the certificate fields specified by VerifyScope. If the verification scope fields are not specified, the function performs verification using a preselected set of fields in the certificate. The caller can specify a Cryptographic Service Provider (CSP) and verification algorithm that the CL can use to perform the verification. The handle for the CSP is contained in the cryptographic context identified by CCHandle. The verification process requires that the caller must specify the necessary verification algorithm parameters. These parameter values are specified in one of two locations: · As a field value in the SignerCert parameter · As a set of algorithm parameters contained in the cryptographic context identified by CCHandle If both of the preceding arguments are supplied, a consistency check is performed to ensure that they result in the same verification algorithm parameters. If they are not consistent, an error is returned. If only one of the above arguments is supplied, that argument is used to generate the verification algorithm parameters. If no algorithm parameters are found, the certificate cannot be verified and the operation fails. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_CONTEXT_HANDLE CSSMERR_CL_INVALID_CERT_POINTER CSSMERR_CL_UNKNOWN_FORMAT CSSMERR_CL_INVALID_FIELD_POINTER CSSMERR_CL_UNKNOWN_TAG CSSMERR_CL_INVALID_SCOPE CSSMERR_CL_INVALID_NUMBER_OF_FIELDS CSSMERR_CL_SCOPE_NOT_SUPPORTED CSSMERR_CL_VERIFICATION_FAILURE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CertSign Functions for the CLI SPI: CL_CertSign 3 CL_CertVerifyWithKey NAME CL_CertVerifyWithKey, CSSM_CL_CertVerifyWithKey - Verify with a key (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CertVerifyWithKey (CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *CertToBeVerified) SPI: CSSM_RETURN CSSMCLI CL_CertVerifyWithKey (CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *CertToBeVerified) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the certificate library service module used to perform this function. CCHandle (input) A signature verification context defining the CSP, verification algorithm, and public key that must be used to perform the operation. CertToBeVerified (input) A signed certificate whose signature is to be verified. DESCRIPTION This function verifies that the CertToBeVerified parameter was signed using a specific private key and that the certificate has not been altered since it was signed using that private key. The public key corresponding to the private signing key is used in the verification process. The CCHandle, must be a signature verification context created using the function CSSM_CSP_CreateSignatureContext() (CSSM API), or CSP_CreateSignatureContext() (SPI). The context must specify the Cryptographic Services Provider (CSP) module, the verification algorithm, and the public verification key that must be used to perform this 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_CONTEXT_HANDLE CSSMERR_CL_INVALID_CERT_POINTER CSSMERR_CL_UNKNOWN_FORMAT CSSMERR_CL_VERIFICATION_FAILURE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CertVerify CSSM_CL_CrlVerify Functions for the CLI SPI: CL_CertVerify CL_CrlVerify 3 CL_CrlAbortCache NAME CL_CrlAbortCache, CSSM_CL_CrlAbortCache - Terminate a CRL cache handle (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CrlAbortCache (CSSM_CL_HANDLE CLHandle, CSSM_HANDLE CrlHandle) SPI: CSSM_RETURN CSSMCLI CL_CrlAbortCache (CSSM_CL_HANDLE CLHandle, CSSM_HANDLE CrlHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the certificate library module used to perform this function. CrlHandle (input) The handle that identifies the cached CRL. DESCRIPTION This function terminates a CRL cache handle created and returned by the function CSSM_CL_CrlCache() (CSSM API), or CL_CrlCache() (CL SPI). The Certificate Library module releases all cache space and state information associated with the cached CRL. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_CACHE_HANDLE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CrlCache Functions for the CLI SPI: CL_CrlCache 3 CL_CrlAbortQuery NAME CL_CrlAbortQuery, CSSM_CL_CrlAbortQuery - Terminate a query (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CrlAbortQuery (CSSM_CL_HANDLE CLHandle, CSSM_HANDLE ResultsHandle) SPI: CSSM_RETURN CSSMCLI CL_CrlAbortQuery (CSSM_CL_HANDLE CLHandle, CSSM_HANDLE ResultsHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in certificate library module used to perform this function. ResultsHandle (input) The handle that identifies the results of a CRL query. DESCRIPTION This function terminates the query initiated by CSSM_CL_CrlGetFirstFieldValue() or CSSM_CL_CrlGetFirstCachedFieldValue() function (or their CL SPI equivalents), and allows the CL to release all intermediate state information associated with the repeating-value get operation. Once this function has been invoked, the results handle is invalid. Applications must invoke this function to terminate the ResultsHandle. Using CSSM_CL_CrlGetNextFieldValue() or CSSM_CL_CrlGetNextCachedFieldValue() (or their CL SPI equivalents), to access all of the attributes named by a single OID does not terminate the ResultsHandle. This function can be invoked to terminate the results handle without accessing all of the values identified by the single OID. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_RESULTS_HANDLE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CrlGetFirstFieldValue CSSM_CL_CrlGetNextFieldValue CSSM_CL_CrlGetFirstCachedFieldValue CSSM_CL_CrlGetNextCachedFieldValue Functions for the CL SPI: CL_CrlGetFirstFieldValue CL_CrlGetNextFieldValue CL_CrlGetFirstCachedFieldValue CL_CrlGetNextCachedFieldValue 3 CL_CrlAddCert NAME CL_CrlAddCert, CSSM_CL_CrlAddCert - Revoke an input certificate (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CrlAddCert (CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *Cert, uint32 NumberOfFields, const CSSM_FIELD *CrlEntryFields, const CSSM_DATA *OldCrl, CSSM_DATA_PTR NewCrl) SPI: CSSM_RETURN CSSMCLI CL_CrlAddCert (CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *Cert, uint32 NumberOfFields, const CSSM_FIELD *CrlEntryFields, const CSSM_DATA *OldCrl, CSSM_DATA_PTR NewCrl) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in certificate library module used to perform this function. CCHandle (input) The handle that describes the context of this cryptographic operation. Cert (input) A pointer to the CSSM_DATA structure containing the certificate to be revoked. NumberOfFields (input) The number of OID/value pairs specified in the CrlEntryFields input parameter. CrlEntryFields (input) An array of OID/value pairs specifying the initial values for descriptive data fields of the new CRL entry. OldCrl (input) A pointer to the CSSM_DATA structure containing the CRL to which the newly revoked certificate will be added. NewCrl (output) A pointer to the CSSM_DATA structure containing the updated CRL. The NewCrl->Data is allocated by the service provider and must be deallocated by the application. DESCRIPTION This function revokes the input certificate by adding a record representing the certificate to the CRL. The values for the new entry in the CRL are specified by the list of OID/value input pairs. The reason for revocation is a typical value specified in the list. The new CRL entry is signed using the private key and signing algorithm specified in the CCHandle. The CCHandle must be a context created using the function CSSM_CSP_CreateSignatureContext() (CSSM API), or CSP_CreateSignatureContext() (CL SPI). The context must specify the Cryptographic Services Provider (CSP) module, the signing algorithm, and the signing key that must be used to perform this operation. The context must also provide the passphrase or a callback function to obtain the passphrase required to access and use the private key. The operation is valid only if the CRL has not been closed by the process of signing the CRL, by calling CSSM_CL_CrlSign() (CSSM API), or CL_CrlSign() (CL SPI). Once the CRL has been signed, entries cannot be added or removed. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_CONTEXT_HANDLE CSSMERR_CL_INVALID_CERT_POINTER CSSMERR_CL_UNKNOWN_FORMAT CSSMERR_CL_INVALID_FIELD_POINTER CSSMERR_CL_UNKNOWN_TAG CSSMERR_CL_INVALID_NUMBER_OF_FIELDS CSSMERR_CL_INVALID_CRL_POINTER CSSMERR_CL_CRL_ALREADY_SIGNED SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CrlRemoveCert Functions for the CLI SPI: CL_CrlRemoveCert 3 CL_CrlCache NAME CL_CrlCache, CSSM_CL_CrlCache - Cache a copy of a certificate revocation list (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CrlCache (CSSM_CL_HANDLE CLHandle, const CSSM_DATA *Crl, CSSM_HANDLE_PTR CrlHandle) SPI: CSSM_RETURN CSSMCLI CL_CrlCache (CSSM_CL_HANDLE CLHandle, const CSSM_DATA *Crl, CSSM_HANDLE_PTR CrlHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the certificate library module used to perform this function. Crl (input) A pointer to the CSSM_DATA structure containing the encoded CRL. CrlHandle (output) A pointer to the CSSM_HANDLE that should be used in all future references to the cached CRL. DESCRIPTION This function caches a copy of a CertificateRevocationList (CRL) for subsequent accesses using the functions CSSM_CL_CrlGetFirstFieldValue() and CSSM_CL_CrlGetNextFieldValue() (or their CL SPI equivalents). The input CRL must be in an encoded representation. The Certificate Library module can cache the CRL in any appropriate internal representation. Parsed or incrementally parsed representations are common. The selected representation is opaque to the caller. The application must call CSSM_CL_CrlCacheAbort() (CSSM API), or CL_CrlCacheAbort() (CL SPI), to remove the cached copy when additional get operations will not be performed on the cached CRL. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_CRL_POINTER CSSMERR_CL_UNKNOWN_FORMAT SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CrlGetFirstCachedFieldValue CSSM_CL_CrlGetNextCachedFieldValue CSSM_CL_IsCertInCachedCrl CSSM_CL_CrlAbortQuery CSSM_CL_CrlAbortCache Functions for the CLI SPI: CL_CrlGetFirstCachedFieldValue CL_CrlGetNextCachedFieldValue CL_IsCertInCachedCrl CL_CrlAbortQuery CL_CrlAbortCache 3 CL_CrlCreateTemplate NAME CL_CrlCreateTemplate, CSSM_CL_CrlCreateTemplate - Create an unsigned, memory-resident CRL (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CrlCreateTemplate (CSSM_CL_HANDLE CLHandle, uint32 NumberOfFields, const CSSM_FIELD *CrlTemplate, CSSM_DATA_PTR NewCrl) SPI: CSSM_RETURN CSSMCLI CL_CrlCreateTemplate (CSSM_CL_HANDLE CLHandle, uint32 NumberOfFields, const CSSM_FIELD *CrlTemplate, CSSM_DATA_PTR NewCrl) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in Certificate Library module used to perform this function. NumberOfFields (input) The number of OID/value pairs specified in the CrlTemplate input parameter. CrlTemplate (input) An array of OID/value pairs specifying the initial values for descriptive data fields of the new CRL. NewCrl (output) A pointer to the CSSM_DATA structure containing the new CRL. The NewCrl-> Data is allocated by the service provider and must be deallocated by the application. DESCRIPTION This function creates an unsigned, memory-resident CRL. Fields in the CRL are initialized with the descriptive data specified by the OID/value input pairs. The specified OID/value pairs can initialize all or a subset of the general attribute fields in the new CRL. Subsequent values can be set using the CSSM_CL_CrlSetFields() (CSSM API) or the CL_CrlSetFields() (CL SPI) function. The new CRL contains no revocation records. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_FIELD_POINTER CSSMERR_CL_UNKNOWN_TAG CSSMERR_CL_INVALID_NUMBER_OF_FIELDS CSSMERR_CL_INVALID_CRL_POINTER SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CrlSetFields CSSM_CL_CrlAddCert CSSM_CL_CrlSign CSSM_CL_CertGetFirstFieldValue Functions for the CLI SPI: CL_CrlSetFields CL_CrlAddCert CL_CrlSign CL_CertGetFirstFieldValue 3 CL_CrlDescribeFormat NAME CL_CrlDescribeFormat, CSSM_CL_CrlDescribeFormat - Return a list of the CSSM_OID values (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CrlDescribeFormat (CSSM_CL_HANDLE CLHandle, uint32 *NumberOfOids, CSSM_OID_PTR *OidList) SPI: CSSM_RETURN CSSMCLI CL_CrlDescribeFormat (CSSM_CL_HANDLE CLHandle, uint32 *NumberOfOid, CSSM_OID_PTR *OidList) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in certificate library module used to perform this function. NumberOfOids (output) The length of the returned array of OIDs. OidList (output) A pointer to the array of CSSM_OIDs that represent the supported CRL format. The OID list is allocated by the service provider and must be deallocated by the application. DESCRIPTION This function returns a list of the CSSM_OID values the Certificate Library module uses to name and reference fields of a CRL. Multiple CSSM_OID values can correspond to a single field. These OIDs can be provided as input to CSSM_CL_CrlGetFirstFieldValue() (CSSM API), or CL_CrlGetFirstFieldValue() (CL SPI), calls to retrieve field values from the CRL. The OID also implies the data format of the returned value. When multiple OIDs name the same field of a CRL, those OIDs have different return data formats associated with them. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Intel CDSA Application Developer's Guide (see CDSA) 3 CL_CrlGetAllCachedRecordFields NAME CL_CrlGetAllCachedRecordFields, CSSM_CL_CrlGetAllCachedRecordFields - Return field values from a CRL record (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CrlGetAllCachedRecordFields (CSSM_CL_HANDLE CLHandle, CSSM_HANDLE CrlHandle, const CSSM_DATA *CrlRecordIndex, uint32 *NumberOfFields, CSSM_FIELD_PTR *Fields) SPI: CSSM_RETURN CSSMCLI CL_CrlGetAllCachedRecordFields (CSSM_CL_HANDLE CLHandle, CSSM_HANDLE CrlHandle, const CSSM_DATA *CrlRecordIndex, uint32 *NumberOfFields, CSSM_FIELD_PTR *Fields) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in certificate library module used to perform this function. CrlHandle (input) A handle identifying a CRL that the application has temporarily cached with the Certificate Library module. The referenced CRL must contain the CRL record identified by CrlRecordIndex. CrlRecordIndex (input) An index value identifying a particular revocation record in a cached CRL. NumberOfFields (output) The number of OID-value pairs returned by this function. Fields (output) A pointer to an array of CSSM_FIELD structures, describing the contents of the preselected CRL record using OID-value pairs. The field list is allocated by the service provider and must be deallocated by the application by calling CSSM_CL_FreeFields() (CSSM API), or CL_FreeFields() (CL SPI). DESCRIPTION This function returns all field values from a prelocated, cached CRL record. The scanned CRL record is identified by CrlRecordIndex, which is returned by the function CSSM_CL_IsCertInCachedCrl() (CSSM API), or CL_IsCertInCachedCrl() (CL SPI). Fields are returned as a set of OID-value pairs. The OID identifies the CRL record field and the data format of the value extracted from that field. The Certificate Library module defines and uses a preferred data format for returning field values in this function. Each CRL record may be digitally signed when it is added to the CRL using the function CSSM_CL_CrlAddCert() (CSSM API), or CL_CrlAddCert() (CL SPI). This function does not perform any signature verification on the CRL record. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_CACHE_HANDLE CSSMERR_CL_INVALID_CRL_INDEX SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_IsCertInCachedCrl CSSM_CL_CrlCache CSSM_CL_CrlAbortCache CSSM_CL_FreeFields Functions for the CLI SPI: CL_IsCertInCachedCrl CL_CrlCache CL_CrlAbortCache CL_FreeFields 3 CL_CrlGetAllFields NAME CL_CrlGetAllFields, CSSM_CL_CrlGetAllFields - Get the field values from the CRL (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CrlGetAllFields (CSSM_CL_HANDLE CLHandle, const CSSM_DATA *Crl, uint32 *NumberOfCrlFields, CSSM_FIELD_PTR *CrlFields) SPI: CSSM_RETURN CSSMCLI CL_CrlGetAllFields (CSSM_CL_HANDLE CLHandle, const CSSM_DATA *Crl, uint32 *NumberOfCrlFields, CSSM_FIELD_PTR *CrlFields) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in Certificate Library module used to perform this function. Crl (input) A pointer to the CSSM_DATA structure that contains the encoded, packed CRL from which field values are to be extracted. NumberOfCrlFields (output) The number of entries in the array CrlFields. CrlFields (output) A pointer to an array of OID-value pairs that describe the contents of the CRL. The extracted CRL fields are returned as the value portion of each OID-value pair. The field list is allocated by the service provider and must be deallocated by the application by calling CSSM_CL_FreeFields() (CSSM API), or CL_FreeFields() (CL SPI). DESCRIPTION This function returns one or more structures. Each structure contains a set of field values from the encoded, packed CRL contained in Crl. Each structure is returned in the FieldValue entry of the CSSM_FIELD structure CrlFields. The parameter NumberOfCrlFields indicates the number of returned structures. The CRL can be signed or unsigned. This function does not perform any signature verification on the CRL fields or the CRL records. Each CRL record can be digitally signed when it is added to the CRL using the function CSSM_CL_CrlAddCert() (CSSM API), or CL_CrlAddCert() (CL SPI). 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_CRL_POINTER CSSMERR_CL_UNKNOWN_FORMAT SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_FreeFields Functions for the CLI SPI: CL_FreeFields 3 CL_CrlGetFirstCachedFieldValue NAME CL_CrlGetFirstCachedFieldValue, CSSM_CL_CrlGetFirstCachedFieldValue - Get field values from the cached CRL (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CrlGetFirstCachedFieldValue (CSSM_CL_HANDLE CLHandle, CSSM_HANDLE CrlHandle, const CSSM_DATA *CrlRecordIndex, const CSSM_OID *CrlField, CSSM_HANDLE_PTR ResultsHandle, uint32 *NumberOfMatchedFields, CSSM_DATA_PTR *FieldValue) SPI: CSSM_RETURN CSSMCLI CL_CrlGetFirstCachedFieldValue (CSSM_CL_HANDLE CLHandle, CSSM_HANDLE CrlHandle, const CSSM_DATA *CrlRecordIndex, const CSSM_OID *CrlField, CSSM_HANDLE_PTR ResultsHandle, uint32 *NumberOfMatchedFields, CSSM_DATA_PTR *FieldValue) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in Certificate Library module used to perform this function. CrlHandle (input) A handle identifying a CRL that the application has temporarily cached with the Certificate Library module. The referenced CRL is searched for the field values identified by CrlField. CrlRecordIndex (input/optional) An index value identifying a particular revocation record in a cached CRL. If an index value is supplied, the scan for the field values identified by CrlField is limited to the preselected revocation record. CrlField (input) A pointer to an object identifier that identifies the field value to be extracted from the CRL. ResultsHandle (output) A pointer to the CSSM_HANDLE that should be used to obtain any additional matching fields. NumberOfMatchedFields (output) The total number of fields that match the CrlField OID. This count includes the first match, which was returned by this function. FieldValue (output) A pointer to the structure containing the value of the requested field. The structure and the field at I "(*FieldValue)->Data" are allocated by the service provider. The CSSM_CL_FreeFieldValue() (CSSM API), or CL_FreeFieldValue() (CL SPI), function can be used to deallocate *FieldValue and (*FieldValue)->Data. DESCRIPTION This function returns a single structure containing a set of field values from the cached CRL identified by CrlHandle parameter. The selected fields are designated by the CSSM_OID CrlField parameter and returned in the output parameter FieldValue. The OID also identifies the data format of the values returned to the caller. If multiple OIDs designate the same CRL field, then each such OID defines a distinct data format for the returned values. The function CSSM_CL_CrlDescribeFormat() (CSSM API), or CL_CrlDescribeFormat() (CL SPI), provides a list of all CSSM_OID values supported by a CL module for naming fields of a CRL. The search can be limited to a particular revocation record within the CRL. A single record is identified by the CrlRecordIndex parameter, which is returned by the function CSSM_CL_IsCertInCachedCrl() (CSSM API), or CL_IsCertInCachedCrl() (CL SPI). If no record index is supplied, the search is initiated from the beginning of the CRL. The CRL can be signed or unsigned. This function does not perform any signature verification on the CRL fields or the CRL records. Each CRL record can be digitally signed when it is added to the CRL using the function CSSM_CL_CrlAddCert() (CSSM API), or CL_CrlAddCert() (CL SPI). The caller can examine fields in the CRL and CRL records at any time using this function. The CrlField OID can identify a single occurrence of a set of CRL fields or multiple occurrences of a set of CRL fields. If the CrlField OID matches more than one occurrence, this function outputs the total number of matches and a ResultsHandle to be used as input to CSSM_CrlGetNextFieldValue() (CSSM API), or CrlGetNextFieldValue() (CL SPI), to retrieve the remaining matches. The first match is returned as the return value of this function. This function determines the complete set of matches. The number of matches and the selected field values do not change between this function and subsequent calls to CSSM_CL_CrlGetNextFieldValue() (CSSM API), or CL_CrlGetNextFieldValue() (CL SPI). 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_CACHE_HANDLE CSSMERR_CL_INVALID_CRL_INDEX CSSMERR_CL_UNKNOWN_TAG CSSMERR_CL_NO_FIELD_VALUES SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CrlGetNextCachedFieldValue CSSM_CL_IsCertInCachedCrl CSSM_CL_CrlAbortQuery CSSM_CL_CrlCache CSSM_CL_CrlAbortCache CSSM_CL_CrlDescribeFormat CSSM_CL_FreeFieldValue Functions for the CLI SPI: CL_CrlGetNextCachedFieldValue CL_IsCertInCachedCrl CL_CrlAbortQuery CL_CrlCache CL_CrlAbortCache CL_CrlDescribeFormat CL_FreeFieldValue 3 CL_CrlGetFirstFieldValue NAME CL_CrlGetFirstFieldValue, CSSM_CL_CrlGetFirstFieldValue - Get the value of the first CRL field (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CrlGetFirstFieldValue (CSSM_CL_HANDLE CLHandle, const CSSM_DATA *Crl, const CSSM_OID *CrlField, CSSM_HANDLE_PTR ResultsHandle, uint32 *NumberOfMatchedFields, CSSM_DATA_PTR *Value) SPI: CSSM_RETURN CSSMCLI CL_CrlGetFirstFieldValue (CSSM_CL_HANDLE CLHandle, const CSSM_DATA *Crl, const CSSM_OID *CrlField, CSSM_HANDLE_PTR ResultsHandle, uint32 *NumberOfMatchedFields, CSSM_DATA_PTR *Value) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in Certificate Library module used to perform this function. Crl (input) A pointer to the CSSM_DATA structure that contains the CRL from which the field is to be retrieved. CrlField (input) An object identifier that identifies the field value to be extracted from the CRL. ResultsHandle (output) A pointer to the CSSM_HANDLE that should be used to obtain any additional matching fields. NumberOfMatchedFields (output) The total number of fields that match the CrlField OID. This count includes the first match, which was returned by this function. Value (output) A pointer to the structure containing the value of the requested field. The structure and the field at I "(*Value)->Data" are allocated by the service provider. The CSSM_CL_FreeFieldValue() (CSSM API), or CL_FreeFieldValue() (CL SPI), function can be used to deallocate *Value and (*Value)->Data. DESCRIPTION This function returns the value of the CRL field designated by the CSSM_OID CrlField. The OID also identifies the data format for the field value returned to the caller. If multiple OIDs name the same CRL field, then each OID defines a distinct data format for the returned field value. The function CSSM_CL_CrlDescribeFormat() (CSSM API), or CL_CrlDescribeFormat() (CL SPI), provides a list of all CSSM_OID values supported by a Certificate Library module for naming fields of a CRL. If more than one field matches the CrlField OID, the first matching field will be returned. The number of matching fields is an output parameter, as is the ResultsHandle to be used to retrieve the remaining matching fields. The set of matching fields is determined by this function. The number of matching fields and the field values do not change between this function and subsequent calls to CSSM_CL_CrlGetNextFieldValue() (CSSM API), or CL_CrlGetNextFieldValue() (CL SPI). 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_CRL_POINTER CSSMERR_CL_UNKNOWN_FORMAT CSSMERR_CL_UNKNOWN_TAG CSSMERR_CL_NO_FIELD_VALUES SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CrlGetNextFieldValue CSSM_CL_CrlAbortQuery CSSM_CL_CrlGetAllFields Functions for the CLI SPI: CL_CrlGetNextFieldValue CL_CrlAbortQuery CL_CrlGetAllFields 3 CL_CrlGetNextCachedFieldValue NAME CL_CrlGetNextCachedFieldValue, CSSM_CL_CrlGetNextCachedFieldValue - Get the value of the next cached CRL field (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CrlGetNextCachedFieldValue (CSSM_CL_HANDLE CLHandle, CSSM_HANDLE ResultsHandle, CSSM_DATA_PTR *FieldValue) SPI: CSSM_RETURN CSSMCLI CL_CrlGetNextCachedFieldValue (CSSM_CL_HANDLE CLHandle, CSSM_HANDLE ResultsHandle, CSSM_DATA_PTR *FieldValue) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in Certificate Library module used to perform this function. ResultsHandle (input) The handle that identifies the results of a CRL query. FieldValue (output) A pointer to the structure containing the value of the requested field. The structure and the field at I "(*FiledValue)->Data" are allocated by the service provider. The CSSM_CL_FreeFieldValue() (CSSM API), or CL_FreeFieldValue() (CL SPI), function can be used to deallocate *FieldValue and (*FieldValue)->Data. DESCRIPTION This function returns the value of a CRL field, when that field occurs multiple times in a CRL. CRLs with repeated fields (such as revocation records) have multiple field values corresponding to a single OID. A call to the function CSSM_CL_CrlGetFirstCachedFieldValue() (CSSM API), or CL_CrlGetFirstCachedFieldValue() (CL SPI), initiates the process and returns a ResultsHandle identifying the size and values contained in the result set. The CSSM_CL_CrlGetNextCachedFieldValue() (CSSM API), or CL_CrlGetNextCachedFieldValue() (CL SPI), function can be called repeatedly to obtain these values, one at a time. The result set does not change in size or value between calls to this function. The result set selected by CSSM_CL_CrlGetFirstCachedFieldValue() (CSSM API), or CL_CrlGetFirstCachedFieldValue() (CL SPI), and identified by ResultsHandle can reference CRL fields repeated across multiple revocation records or within one revocation record. The scope of the scan was set by an optional CrlRecordIndex input to the function CSSM_CL_CrlGetFirstCachedFieldValue() (CSSM API), or CL_CrlGetFirstCachedFieldValue() (CL SPI). If the record index was specified, then the results set is the revocation record identified by the index. If no record index was specified, then the results set can include repeated fields from multiple revocation records in a CRL. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_RESULTS_HANDLE CSSMERR_CL_NO_FIELD_VALUES SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CrlGetFirstCachedFieldValue CSSM_CL_CrlAbortQuery CSSM_CL_IsCertInCachedCrl CSSM_CL_CrlCache CSSM_CL_CrlAbortCache CSSM_CL_FreeFieldValue Functions for the CLI SPI: CL_CrlGetFirstCachedFieldValue CL_CrlAbortQuery CL_IsCertInCachedCrl CL_CrlCache CL_CrlAbortCache CL_FreeFieldValue 3 CL_CrlGetNextFieldValue NAME CL_CrlGetNextFieldValue, CSSM_CL_CrlGetNextFieldValue - Get the value of the next CRL field (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CrlGetNextFieldValue (CSSM_CL_HANDLE CLHandle, CSSM_HANDLE ResultsHandle, CSSM_DATA_PTR *Value) SPI: CSSM_RETURN CSSMCLI CL_CrlGetNextFieldValue (CSSM_CL_HANDLE CLHandle, CSSM_HANDLE ResultsHandle, CSSM_DATA_PTR *Value) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in Certificate Library module used to perform this function. ResultsHandle (input) The handle that identifies the results of a CRL query. Value (output) A pointer to the structure containing the value of the requested field. The structure and the field at I "(*Value)->Data" are allocated by the service provider. The CSSM_CL_FreeFieldValue() (CSSM API), or CL_FreeFieldValue() (CL SPI), function can be used to deallocate *Value and (*Value)->Data. DESCRIPTION This function returns the value of a CRL field, when that field occurs multiple times in a CRL. CRLs with repeated fields (such as revocation records) have multiple field values corresponding to a single OID. A call to the function CSSM_CL_CrlGetFirstFieldValue() (CSSM API), or CL_CrlGetFirstFieldValue() (CL SPI), initiates the process and returns a results handle identifying the size and values contained in the result set. The CSSM_CL_CrlGetNextFieldValue() (CSSM API), or CL_CrlGetNextFieldValue() (CL SPI), function can be called repeatedly to obtain these values, one at a time. The result set does not change in size or value between calls to 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_RESULTS_HANDLE CSSMERR_CL_NO_FIELD_VALUES SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CrlGetFirstFieldValue CSSM_CL_CrlAbortQuery Functions for the CLI SPI: CL_CrlGetFirstFieldValue CL_CrlAbortQuery 3 CL_CrlRemoveCert NAME CL_CrlRemoveCert, CSSM_CL_CrlRemoveCert - Reinstate a certificate (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CrlRemoveCert (CSSM_CL_HANDLE CLHandle, const CSSM_DATA *Cert, const CSSM_DATA *OldCrl, CSSM_DATA_PTR NewCrl) SPI: CSSM_RETURN CSSMCLI CL_CrlRemoveCert (CSSM_CL_HANDLE CLHandle, const CSSM_DATA *Cert, const CSSM_DATA *OldCrl, CSSM_DATA_PTR NewCrl) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in Certificate Library module used to perform this function. Cert (input) A pointer to the CSSM_DATA structure containing the certificate to be reinstated. OldCrl (input) A pointer to the CSSM_DATA structure containing the CRL from which the certificate is to be removed. NewCrl (output) A pointer to the CSSM_DATA structure containing the updated CRL. The NewCrl->Data is allocated by the service provider and must be deallocated by the application. DESCRIPTION This function reinstates a certificate by removing it from the specified CRL. The operation is valid only if the CRL has not been closed by the process of signing the CRL by executing CSSM_CL_CrlSign() (CSSM API), or CL_CrlSign() (CL SPI). Once the CRL has been signed, entries cannot be added or removed. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_CERT_POINTER CSSMERR_CL_INVALID_CRL_POINTER CSSMERR_CL_UNKNOWN_FORMAT CSSMERR_CL_CRL_ALREADY_SIGNED SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CrlAddCert Functions for the CLI SPI: CL_CrlAddCert 3 CL_CrlSetFields NAME CL_CrlSetFields, CSSM_CL_CrlSetFields - Set new field values (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CrlSetFields (CSSM_CL_HANDLE CLHandle, uint32 NumberOfFields, const CSSM_FIELD *CrlTemplate, const CSSM_DATA *OldCrl, CSSM_DATA_PTR ModifiedCrl) SPI: CSSM_RETURN CSSMCLI CL_CrlSetFields (CSSM_CL_HANDLE CLHandle, uint32 NumberOfFields, const CSSM_FIELD *CrlTemplate, const CSSM_DATA *OldCrl, CSSM_DATA_PTR ModifiedCrl) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in Certificate Library module used to perform this function. NumberOfFields (input) The number of OID value pairs specified in the CrlTemplate input parameter. CrlTemplate (input) Any array of field OID value pairs containing the values to initialize the CRL attribute fields. OldCrl (input) The CRL to be updated with the new attribute values. The CRL must be unsigned and available for update. ModifiedCrl (output) A pointer to the modified, unsigned CRL. The ModifiedCrl->Data is allocated by the service provider and must be deallocated by the application. DESCRIPTION This function will set the fields of the input CRL to the new values, specified by the input OID/value pairs. If there is more than one possible instance of an OID (for example, as in an extension or CRL record), then a new field with the specified value is added to the CRL. This function should be used to update any of the CRL field values. If a specified field was initialized by CSSM_CL_CrlCreateTemplate() (CSSM API), or CL_CrlCreateTemplate() (CL SPI), the field value is set to the new specified value. If a specified field was not initialized by the CSSM_CL_CrlCreateTemplate() (CSSM API), or CL_CrlCreateTemplate() (CL SPI), the field is set to the new specified value. The OldCrl must be unsigned. Once a CRL has been signed using CSSM_CL_CrlSign() (CSSM API), or CL_CrlSign() (CL SPI), the signed CRL's field values cannot be modified. Modification would invalidate the cryptographic signature of the CRL. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_FIELD_POINTER CSSMERR_CL_UNKNOWN_TAG CSSMERR_CL_INVALID_NUMBER_OF_FIELDS CSSMERR_CL_UNKNOWN_FORMAT CSSMERR_CL_INVALID_CRL_POINTER CSSMERR_CL_CRL_ALREADY_SIGNED SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CrlCreateTemplate CSSM_CL_CrlAddCert CSSM_CL_CrlSign CSSM_CL_CertGetFirstFieldValue Functions for the CLI SPI: CL_CrlCreateTemplate CL_CrlAddCert CL_CrlSign CL_CertGetFirstFieldValue 3 CL_CrlSign NAME CL_CrlSign, CSSM_CL_CrlSign - Sign a CRL (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CrlSign (CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *UnsignedCrl, const CSSM_FIELD *SignScope, uint32 ScopeSize, CSSM_DATA_PTR SignedCrl) SPI: CSSM_RETURN CSSMCLI CL_CrlSign (CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *UnsignedCrl, const CSSM_FIELD *SignScope, uint32 ScopeSize, CSSM_DATA_PTR SignedCrl) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in Certificate Library module used to perform this function. CCHandle (input) The handle that describes the context of this cryptographic operation. UnsignedCrl (input) A pointer to the CSSM_DATA structure containing the CRL to be signed. SignScope (input/optional) A pointer to the CSSM_FIELD array containing the tag/value pairs of the fields to be signed. If the signing scope is null, the Certificate Library module includes a default set of CRL fields in the signing process. ScopeSize (input) The number of entries in the sign scope list. If the signing scope is not specified, the input scope size must be zero. SignedCrl (output) A pointer to the CSSM_DATA structure containing the signed CRL. The SignedCrl->Data is allocated by the service provider and must be deallocated by the application. DESCRIPTION This function signs a CRL using the private key and signing algorithm specified in the CCHandle parameter. The result is a signed, encoded certificate revocation list in SignedCrl. The unsigned CRL is specified in the input UnsignedCrl. The UnsignedCrl is constructed using the CSSM_CL_CrlCreateTemplate(), CSSM_CL_CrlSetFields(), CSSM_CL_CrlAddCert(), and CSSM_CL_CrlRemoveCert() functions (for the CSSM API), or their CL SPI equivalents. The CCHandle must be context created using the function CSSM_CSP_CreateSignatureContext() (CSSM API), or CSP_CreateSignatureContext() (SPI). The context must specify the Cryptographic Services Provider module, the signing algorithm, and the signing key that must be used to perform this operation. The context must also provide the passphrase or a callback function to obtain the passphrase required to access and use the private key. The fields included in the signing operation are identified by the OIDs in the optional SignScope array. Once the CRL has been signed it cannot be modified. This means that entries cannot be added or removed from the CRL through application of the CSSM_CL_CrlAddCert() or CSSM_CL_CrlRemoveCertCSSM_CL_CrlRemoveCert() (or their CL SPI equivalent operations. A signed CRL can be verified, applied to a data store, and searched for values. The memory for the SignedCrl->Data output is allocated by the service provider using the calling application's memory management routines. The application must deallocate the memory. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_CONTEXT_HANDLE CSSMERR_CL_INVALID_CRL_POINTER CSSMERR_CL_UNKNOWN_FORMAT CSSMERR_CL_INVALID_FIELD_POINTER CSSMERR_CL_UNKNOWN_TAG CSSMERR_CL_INVALID_SCOPE CSSMERR_CL_SCOPE_NOT_SUPPORTED CSSMERR_CL_INVALID_NUMBER_OF_FIELDS CSSMERR_CL_CRL_ALREADY_SIGNED SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CrlVerify CSSM_CL_CrlVerifyWithKey Functions for the CLI SPI: CL_CrlVerify CL_CrlVerifyWithKey 3 CL_CrlVerify NAME CL_CrlVerify, CSSM_CL_CrlVerify - Verify a signed CRL has not been altered (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CrlVerify (CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *CrlToBeVerified, const CSSM_DATA *SignerCert, const CSSM_FIELD *VerifyScope, uint32 ScopeSize) SPI: CSSM_RETURN CSSMCLI CL_CrlVerify (CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *CrlToBeVerified, const CSSM_DATA *SignerCert, const CSSM_FIELD *VerifyScope, uint32 ScopeSize) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in Certificate Library module used to perform this function. CCHandle (input/optional) The handle that describes the context of this cryptographic operation. CrlToBeVerified (input) A pointer to the CSSM_DATA structure containing the CRL to be verified. SignerCert (input/optional) A pointer to the CSSM_DATA structure containing the certificate used to sign the CRL. VerifyScope (input/optional) A pointer to the CSSM_FIELD array containing the tag/value pairs of the fields to be verified. If the verification scope is null, the Certificate Library module assumes that a default set of fields were used in the signing process and those same fields are used in the verification process. ScopeSize (input) The number of entries in the verify scope list. If the verification scope is not specified, the input value for scope size must be zero. DESCRIPTION This function verifies that the signed CRL has not been altered since it was signed by the designated signer. It does this by verifying the digital signature over the fields specified by the VerifyScope parameter. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_CONTEXT_HANDLE CSSMERR_CL_INVALID_CERT_POINTER CSSMERR_CL_INVALID_CRL_POINTER CSSMERR_CL_UNKNOWN_FORMAT CSSMERR_CL_INVALID_FIELD_POINTER CSSMERR_CL_UNKNOWN_TAG CSSMERR_CL_INVALID_SCOPE CSSMERR_CL_INVALID_NUMBER_OF_FIELDS CSSMERR_CL_SCOPE_NOT_SUPPORTED CSSMERR_CL_VERIFICATION_FAILURE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CrlSign Functions for the CLI SPI: CL_CrlSign 3 CL_CrlVerifyWithKey NAME CL_CrlVerifyWithKey, CSSM_CL_CrlVerifyWithKey - Verify a CRL with a specific key (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_CrlVerifyWithKey (CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *CrlToBeVerified) SPI: CSSM_RETURN CSSMCLI CL_CrlVerifyWithKey (CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *CrlToBeVerified) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the Certificate Library service module used to perform this function. CCHandle (input) A signature verification context defining the Cryptographic Services Provider (CSP), verification algorithm, and public key that must be used to perform the operation. CrlToBeVerified (input) A signed certificate revocation list whose signature is to be verified. DESCRIPTION This function verifies that the CrlToBeVerified parameter was signed using a specific private key and that the certificate revocation list has not been altered since it was signed using that private key. The public key corresponding to the private signing key is used in the verification process. The cryptographic context indicated by the CCHandle parameter must be a signature verification context created using the function CSSM_CSP_CreateSignatureContext() (CSSM API) or CSP_CreateSignatureContext() (CL SPI). The context must specify the Cryptographic Services Provider (CSP) module, the verification algorithm, and the public verification key that must be used to perform this 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_CONTEXT_HANDLE CSSMERR_CL_INVALID_CRL_POINTER CSSMERR_CL_UNKNOWN_FORMAT CSSMERR_CL_VERIFICATION_FAILURE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CrlVerify Functions for the CLI SPI: CL_CrlVerify 3 CL_FreeFieldValue NAME CL_FreeFieldValue, CSSM_CL_FreeFieldValue - Free field data (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_FreeFieldValue (CSSM_CL_HANDLE CLHandle, const CSSM_OID *CertOrCrlOid, CSSM_DATA_PTR Value) SPI: CSSM_RETURN CSSMCLI CL_FreeFieldValue (CSSM_CL_HANDLE CLHandle, const CSSM_OID *CertOrCrlOid, CSSM_DATA_PTR Value) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in Certificate Library module used to perform this function. CertOrCrlOid (input) A pointer to the CSSM_OID structure describing the type of the Value to be freed. Value (input) A pointer to the CSSM_DATA structure containing the Data to be freed. DESCRIPTION This function frees the data specified by Value and Value->Data. CertOrCrlOid indicates the type of the data in Value. This function should be used only to free CSSM_DATA values returned from calls CSSM_CL_CertGetFirstFieldValue(), CSSM_CL_CertGetNextFieldValue(), CSSM_CL_CertGetFirstCachedFieldValue(), CSSM_CL_CertGetNextCachedFieldValue(), CSSM_CL_CrlGetFirstFieldValue(), CSSM_CL_CrlGetNextFieldValue(), CSSM_CL_CrlGetFirstCachedFieldValue(), CSSM_CL_CrlGetNextCachedFieldValue(), or their CLI SPI equivalents. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_UNKNOWN_TAG SEE ALSO Intel CDSA Application Developer's Guide (see CDSA) 3 CL_FreeFields NAME CL_FreeFields, CSSM_CL_FreeFields - Free fields (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_FreeFields (CSSM_CL_HANDLE CLHandle, uint32 NumberOfFields, CSSM_FIELD_PTR *FieldArray) SPI: CSSM_RETURN CSSMCLI CL_FreeFields (CSSM_CL_HANDLE CLHandle, uint32 NumberOfFields, CSSM_FIELD_PTR *FieldArray) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in Certificate Library module used to perform this function. NumberOfFields (input) The length of the array of fields in FieldArray. FieldArray (input) A pointer to an array of CSSM_FIELD structures that need to be deallocated. DEFINITIONS This function frees the fields in the FieldArray by freeing the data pointers for both the FieldOid and FieldValue fields. It also frees the top level FieldArray pointer. This function should be used only to free CSSM_FIELD_PTR values returned from calls CSSM_TP_CertGetAllTemplateFields(), CSSM_CL_CertGetAllTemplateFields(), CSSM_CL_CertGetAllFields(), CSSM_CL_CrlGetAllFields(), CSSM_CL_CrlGetAllCachedRecordFields(), or their SPI equivalent calls. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Intel CDSA Application Developer's Guide (see CDSA) 3 CL_IsCertInCachedCrl NAME CL_IsCertInCachedCrl, CSSM_CL_IsCertInCachedCrl - Search cached CRL for a record (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_IsCertInCachedCrl (CSSM_CL_HANDLE CLHandle, const CSSM_DATA *Cert, CSSM_HANDLE CrlHandle, CSSM_BOOL *CertFound, CSSM_DATA_PTR CrlRecordIndex) SPI: CSSM_RETURN CSSMCLI CL_IsCertInCachedCrl (CSSM_CL_HANDLE CLHandle, const CSSM_DATA *Cert, CSSM_HANDLE CrlHandle, CSSM_BOOL *CertFound, CSSM_DATA_PTR CrlRecordIndex) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in Certificate Library module used to perform this function. Cert (input) A pointer to the CSSM_DATA structure containing an encoded, packed certificate. CrlHandle (input) A handle identifying a CRL that the application has temporarily cached with the Certificate Library module. The referenced CRL is searched for a revocation record matching the specified Cert. CertFound (output) A pointer to a CSSM_BOOL indicating success or failure in finding the specified certificate in the CRL. CSSM_TRUE signifies that the certificate was found in the CRL. CSSM_FALSE indicates that the certificate was not found in the CRL. CrlRecordIndex (output) A pointer to a CSSM_DATA structure containing an index descriptor for direct access to the located CRL record. CrlRecordIndex->Data is allocated by the service provider and must be deallocated by the application. DESCRIPTION This function searches the cached CRL for a record corresponding to the certificate. The result of the search is returned in CertFound. The CRL and the records within the CRL must be digitally signed. This function does not verify either signature. The caller should use CSSM_TP_CrlVerify() or CSSM_CL_CrlVerify() (or their SPI equivalents) before invoking this function. Once the CRL has been verified, the caller can invoke this function repeatedly without repeating the verification process. If the certificate is found in the CRL, the CL module returns an index descriptor CrlRecordIndex for use with other Certificate Library CRL functions. The index provides more direct access to the selected CRL record. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_CERT_POINTER CSSMERR_CL_UNKNOWN_FORMAT CSSMERR_CL_INVALID_CACHE_HANDLE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CrlGetFirstCachedFieldValue CSSM_CL_CrlGetNextCachedFieldValue CSSM_CL_CrlGetAllCachedRecordField CSSM_CL_CrlCache CSSM_CL_CrlAbortCache Functions for the CLI SPI: CL_CrlGetFirstCachedFieldValue CL_CrlGetNextCachedFieldValue CL_CrlGetAllCachedRecordField CL_CrlCache CL_CrlAbortCache 3 CL_IsCertInCrl NAME CL_IsCertInCrl, CSSM_CL_IsCertInCrl - Search CRL for a certificate record (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_IsCertInCrl (CSSM_CL_HANDLE CLHandle, const CSSM_DATA *Cert, const CSSM_DATA *Crl, CSSM_BOOL *CertFound) SPI: CSSM_RETURN CSSMCLI CL_IsCertInCrl (CSSM_CL_HANDLE CLHandle, const CSSM_DATA *Cert, const CSSM_DATA *Crl, CSSM_BOOL *CertFound) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in Certificate Library module used to perform this function. Cert (input) A pointer to the CSSM_DATA structure containing the certificate to be located. Crl (input) A pointer to the CSSM_DATA structure containing the CRL to be searched. CertFound (output) A pointer to a CSSM_BOOL indicating success or failure in finding the specified certificate in the CRL. CSSM_TRUE signifies that the certificate was found in the CRL. CSSM_FALSE indicates that the certificate was not found in the CRL. DESCRIPTION This function searches the CRL for a record corresponding to the certificate. The result of the search is returned in CertFound. The CRL and the records within the CRL must be digitally signed. This function does not verify either signature. The caller should use CSSM_TP_CrlVerify() or CSSM_CL_CrlVerify() (or their SPI equivalents) before invoking this function. Once the CRL has been verified, the caller can invoke this function repeatedly without repeating the verification process. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_CERT_POINTER CSSMERR_CL_INVALID_CRL_POINTER CSSMERR_CL_UNKNOWN_FORMAT SEE ALSO Intel CDSA Application Developer's Guide (see CDSA) 3 CL_PassThrough NAME CL_PassThrough, CSSM_CL_PassThrough - Extend certificate library functionality (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CL_PassThrough (CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, uint32 PassThroughId, const void *InputParams, void **OutputParams) SPI: CSSM_RETURN CSSMCLI CL_PassThrough (CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, uint32 PassThroughId, const void *InputParams, void **OutputParams) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CLHandle (input) The handle that describes the add-in Certificate Library module used to perform this function. CCHandle (input/optional) The handle that describes the context of the cryptographic operation. If the module-specific operation does not perform any cryptographic operations, a cryptographic context is not required. PassThroughId (input) An identifier assigned by the CL module to indicate the exported function to perform. InputParams (input/optional) A pointer to a module, implementation-specific structure containing parameters to be interpreted in a function-specific manner by the requested CL module. OutputParams (output/optional) A pointer to a module, implementation-specific structure containing the output data. The service provider allocates the memory for substructures. The application must free the memory for the substructures. DESCRIPTION This function allows applications to call certificate library module- specific operations. Such operations might include queries or services that are specific to the domain represented by the CL module. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CL_INVALID_CONTEXT_HANDLE CSSMERR_CL_INVALID_PASSTHROUGH_ID CSSMERR_CL_INVALID_DATA SEE ALSO Intel CDSA Application Developer's Guide (see CDSA) 3 CSP_EventNotify NAME CSP_EventNotify - Notify service module of a context event (CDSA) SYNOPSIS # include CSSM_RETURN CSSMSPI CSP_EventNotify (CSSM_MODULE_HANDLE CSPHandle, CSSM_CONTEXT_EVENT Event, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform calls to CSSM for the memory functions managed by CSSM. Event (input) One of the following event types listed: _______________________________________________________________ Event Description _______________________________________________________________ CSSM_CONTEXT_EVENT_CREATE A caller using this module attach handle has created a new cryptographic context using CSSM_Create***Context. CSSM_CONTEXT_EVENT_DELETE A caller using this module attach handle has deleted a cryptographic context using 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. DESCRIPTION This function is used to notify the service module of a context event related to a particular attach handle. Valid events include creation, deletion, or modification of a cryptographic context. The service module can examine the new or modified context referenced by pContext to determine whether the context is acceptable to the service module. If the cryptographic context is acceptable (if 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 returns to the calling application. If the return value is CSSM_FAIL, CSSM deletes 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. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_CSP_CreateSignatureContext CSSM_CSP_CreateDigestContext CSSM_CSP_CreateSymmetricContext CSSM_CSP_CreateMacContext CSSM_CSP_CreateRandomGenContext CSSM_CSP_CreateAsymmetricContext CSSM_CSP_CreateDeriveKeyContext CSSM_CSP_CreateKeyGenContext CSSM_CSP_CreatePassThroughContext CSSM_DeleteContext CSSM_UpdateContextAttributes 3 CSSM_CSP_ChangeLoginAcl NAME CSSM_CSP_ChangeLoginAcl - Edit a stored CSP ACL login session (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_CSP_ChangeLoginAcl (CSSM_CSP_HANDLE CSPHandle, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_ACL_EDIT *AclEdit) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) 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 parameter can contain information for a new ACL entry and a handle uniquely identifying an existing ACL entry. The information controls the edit operation as follows: _____________________________________________________________ Value of AclEdit.EditMode Use of AclEdit.NewEntry and AclEdit.OldEntryHandle _____________________________________________________________ CSSM_ACL_EDIT_MODE_ADD Adds a new ACL entry to the set of ACL entries controlling login sessions with the CSP. The new ACL entry is created from the ACL entry prototype contained in NewEntry. OldEntryHandle is ignored for this EditMode. CSSM_ACL_EDIT_MODE_DELETE Deletes the ACL entry identified by OldEntryHandle and associated with login sessions with the CSP. NewEntry is ignored for this EditMode. CSSM_ACL_EDIT_MODE_REPLACE Replaces the ACL entry identified by OldEntryHandle and controlling login sessions with the CSP. The existing ACL is replaced based on the ACL entry prototype contained in the NewEntry. _____________________________________________________________ When replacing an existing ACL entry, the caller must replace all 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. 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. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_CSP_GetLoginACL CSSM_CSP_Login CSSM_CSP_Logout 3 CSSM_CSP_ChangeLoginOwner NAME CSSM_CSP_ChangeLoginOwner - Define a new login owner (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_CSP_ChangeLoginOwner (CSSM_CSP_HANDLE CSPHandle, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_ACL_OWNER_PROTOTYPE *NewOwner) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) 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. DESCRIPTION This function takes a CSSM_ACL_OWNER_PROTOTYPE describing 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_CSP_GetLoginOwner 3 CSSM_CSP_CreateAsymmetricContext NAME CSSM_CSP_CreateAsymmetricContext - Create an asymmetric encryption cryptographic context (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_CSP_CreateAsymmetricContext (CSSM_CSP_HANDLE CSPHandle, CSSM_ALGORITHMS AlgorithmID, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_KEY *Key, CSSM_PADDING Padding, CSSM_CC_HANDLE *NewContextHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform this function. If a NULL handle is specified, CSSM returns an error. AlgorithmID (input) The algorithm identification number for the algorithm used for asymmetric encryption. AccessCred (input) A pointer to the set of one or more credentials required to unlock the private key. The credentials structure can contain an immediate value for the credential, such as a passphrase, or the caller can specify a callback function the CSP can use to obtain one or more credentials. Credentials can be required for encryption and decryption operations. Key (input) The key used for asymmetric encryption. The caller passes a pointer to a CSSM_KEY structure containing the key. When the context is used for a sign operation, AccessCredentials is required to access the private key used for signing. When the context is used for a verify operation, the public key is used to verify the signature. When the context is used for a wrapkey operation, the public key can be used as the wrapping key. When the context is used for an unwrap operation, AccessCredentials is required to access the private key used to perform the unwrapping. Padding (input/optional) The method for padding. Typically specified for ciphers that pad. NewContextHandle (output) Cryptographic context handle. DESCRIPTION This function creates an asymmetric encryption cryptographic context, given a handle of a CSP, an algorithm identification number, a key, and padding. The cryptographic context handle is returned. The cryptographic context handle can be used to call asymmetric encryption functions and cryptographic wrap or unwrap functions. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_DecryptData CSSM_DecryptDataInit CSSM_DecryptDataUpdate CSSM_DecryptDataFinal CSSM_DeleteContext CSSM_EncryptData CSSM_EncryptDataInit CSSM_EncryptDataUpdate CSSM_EncryptDataFinal CSSM_GetContext CSSM_GetContextAttribute CSSM_QuerySize CSSM_SetContext CSSM_UpdateContextAttributes 3 CSSM_CSP_CreateDeriveKeyContext NAME CSSM_CSP_CreateDeriveKeyContext - Create a cryptographic context to derive a symmetric key (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_CSP_CreateDeriveKeyContext (CSSM_CSP_HANDLE CSPHandle, CSSM_ALGORITHMS AlgorithmID, CSSM_KEY_TYPE DeriveKeyType, uint32 DeriveKeyLengthInBits, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_KEY *BaseKey, uint32 IterationCount, const CSSM_DATA *Salt, const CSSM_CRYPTO_DATA *Seed, CSSM_CC_HANDLE *NewContextHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform this function. If a NULL handle is specified, CSSM returns an error. AlgorithmID (input) The algorithm identification number for a derived key algorithm. DeriveKeyType (input) The type of symmetric key to derive. DeriveKeyLengthInBits (input) The logical length of the key in bits to be derived ( LogicalKeySizeInBits) AccessCred (input/optional) A pointer to the set of one or more credentials required to access the base key. The credentials structure can contain an immediate value for the credential, such as a passphrase, or the caller can specify a callback function the CSP can use to obtain one or more credentials. If the BaseKey is NULL, then this parameter is optional. BaseKey (input/optional) The base key used to derive the new key. The base key can be a public key, a private key, or a symmetric key IterationCount (input/optional) The number of iterations to be performed during the derivation process. Used heavily by password-based derivation methods. Salt (input/optional) A Salt used in deriving the key. Seed (input/optional) A seed used to generate a random number. The caller can either pass a seed and seed length in bytes or pass a callback function. If Seed is NULL, the cryptographic service provider will use its default seed-handling mechanism. NewContextHandle (output) Cryptographic context handle. DESCRIPTION This function creates a cryptographic context to derive a symmetric key, given a handle of a CSP, an algorithm, the type of symmetric key to derive, the length of the derived key, and an optional seed or an optional AccessCredentials structure from which to derive a new key. The cryptographic context handle is returned. The cryptographic context handle can be used for calling the cryptographic derive key function. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_DeriveKey 3 CSSM_CSP_CreateDigestContext NAME CSSM_CSP_CreateDigestContext - Create a digest cryptographic context (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_CSP_CreateDigestContext (CSSM_CSP_HANDLE CSPHandle, CSSM_ALGORITHMS AlgorithmID, CSSM_CC_HANDLE *NewContextHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform this function. If a NULL handle is specified, CSSM returns error. AlgorithmID (input) The algorithm identification number for message digests. NewContextHandle (output) Cryptographic context handle. DESCRIPTION This function creates a digest cryptographic context, given a handle of a CSP and an algorithm identification number. The cryptographic context handle is returned. The cryptographic context handle can be used to call digest cryptographic functions. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_DigestData CSSM_DigestDataInit CSSM_DigestDataUpdate CSSM_DigestDataFinal CSSM_GetContext CSSM_SetContext CSSM_DeleteContext CSSM_GetContextAttribute CSSM_UpdateContextAttributes 3 CSSM_CSP_CreateKeyGenContext NAME CSSM_CSP_CreateKeyGenContext - Create a key generation cryptographic context (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_CSP_CreateKeyGenContext (CSSM_CSP_HANDLE CSPHandle, CSSM_ALGORITHMS AlgorithmID, uint32 KeySizeInBits, const CSSM_CRYPTO_DATA *Seed, const CSSM_DATA *Salt, const CSSM_DATE *StartDate, const CSSM_DATE *EndDate, const CSSM_DATA *Params, CSSM_CC_HANDLE *NewContextHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform this function. If a NULL handle is specified, CSSM returns an error. AlgorithmID (input) The algorithm identification number of the algorithm used for key generation. KeySizeInBits (input) The logical size of the key (specified in bits). This refers to either the actual key size (for symmetric key generation) or the modulus size (for asymmetric key pair generation). Seed (input/optional) A seed used to generate the key. The caller can either pass a seed and seed length in bytes or pass a callback function. If NULL is passed, the cryptographic service provider will use its default seed-handling mechanism. Salt (input/optional) A salt used to generate the key. StartDate (input/optional) A start date for the validity period of the key or key pair being generated. EndDate (input/optional) An end date for the validity period of the key or key pair being generated. Params (input/optional) A data buffer containing parameters required to generate a key pair for a specific algorithm. NewContextHandle (output) Cryptographic context handle. DESCRIPTION This function creates a key generation cryptographic context, given a handle of a CSP, an algorithm identification number, a pass phrase, a modulus size (for public or private keypair generation), a key size (for symmetric key generation), a seed, and a salt. The cryptographic context handle is returned. The cryptographic context handle can be used to call key/ or keypair generation functions. Additional attributes can be added to the newly created context using the CSSM_UpdateContextAttributes() function. Incremental attributes of interest for key generation include a handle-pair identifying a Data Storage Library service module and an open data store for CSPs that manage multiple persistent key stores. If a CSP does not support multiple key stores, the CSP ignores the presence or absence of this attribute. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_GenerateKey CSSM_GenerateKeyPair CSSM_GetContext CSSM_SetContext CSSM_DeleteContext CSSM_GetContextAttribute CSSM_UpdateContextAttributes 3 CSSM_CSP_CreateMacContext NAME CSSM_CSP_CreateMacContext - Create a message authentication code cryptographic context (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_CSP_CreateMacContext (CSSM_CSP_HANDLE CSPHandle, CSSM_ALGORITHMS AlgorithmID, const CSSM_KEY *Key, CSSM_CC_HANDLE *NewContextHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform this function. If a NULL handle is specified, CSSM returns error. AlgorithmID (input) The algorithm identification number for the MAC algorithm. Key (input) The key used to generate a message authentication code. Caller passes a pointer to a CSSM_KEY structure containing the key. NewContextHandle (output) Cryptographic context handle. DESCRIPTION This function creates a message authentication code cryptographic context, given a handle of a CSP, algorithm identification number, and a key. The cryptographic context handle is returned. The cryptographic context handle can be used to call message authentication code functions. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_GenerateMac CSSM_GenerateMacInit CSSM_GenerateMacUpdate CSSM_GenerateMacFinal CSSM_VerifyMac CSSM_VerifyMacInit CSSM_VerifyMacUpdate CSSM_VerifyMacFinal CSSM_GetContext CSSM_SetContext CSSM_DeleteContext CSSM_GetContextAttribute CSSM_UpdateContextAttributes 3 CSSM_CSP_CreatePassThroughContext NAME CSSM_CSP_CreatePassThroughContext - Create a custom cryptographic context (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_CSP_CreatePassThroughContext (CSSM_CSP_HANDLE CSPHandle, const CSSM_KEY *Key, CSSM_CC_HANDLE *NewContextHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform this function. If a NULL handle is specified, CSSM returns an error. Key (input) The key to be used for the context. The caller passes a pointer to a CSSM_KEY structure containing the key. NewContextHandle (output) Cryptographic context handle. DESCRIPTION This function creates a custom cryptographic context, given a handle of a CSP and a pointer to a custom input data structure. The cryptographic context handle is returned. The cryptographic context handle can be used to call the CSSM pass-through function for the CSP. NOTES A CSP can create its own set of custom functions. The context information can be passed through its own data structure. The CSSM_CSP_PassThrough() function should be used with the function ID to call the desired custom 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. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_CSP_PassThrough CSSM_GetContext CSSM_SetContext CSSM_DeleteContext CSSM_GetContextAttribute CSSM_UpdateContextAttributes 3 CSSM_CSP_CreateRandomGenContext NAME CSSM_CSP_CreateRandomGenContext - Create a random number generation cryptographic context (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_CSP_CreateRandomGenContext (CSSM_CSP_HANDLE CSPHandle, CSSM_ALGORITHMS AlgorithmID, const CSSM_CRYPTO_DATA *Seed, uint32 Length, CSSM_CC_HANDLE *NewContextHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform this function. If a NULL handle is specified, CSSM returns AN error. AlgorithmID (input) The algorithm identification number for random number generation. Seed (input/optional) A seed used to generate THE random number. The caller can either pass a seed and seed length in bytes or pass a callback function. If NULL is passed, the cryptographic service provider will use its default seed-handling mechanism. Length (input) The length of the random number to be generated. NewContextHandle (output) Cryptographic context handle. DESCRIPTION This function creates a random number generation cryptographic context, given a handle of a CSP, an algorithm identification number, a seed, and the length of the random number in bytes. The cryptographic context handle is returned and can be used for the random number generation function. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_GenerateRandom CSSM_GetContext CSSM_SetContext CSSM_DeleteContext CSSM_GetContextAttribute CSSM_UpdateContextAttributes 3 CSSM_CSP_CreateSignatureContext NAME CSSM_CSP_CreateSignatureContext - Create a signature cryptographic context (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_CSP_CreateSignatureContext (CSSM_CSP_HANDLE CSPHandle, CSSM_ALGORITHMS AlgorithmID, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_KEY *Key, CSSM_CC_HANDLE *NewContextHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform this function. If a NULL handle is specified, CSSM returns error. AlgorithmID (input) The algorithm identification number for a signature/verification algorithm. AccessCred (input/optional) A pointer to the set of one or more credentials required to unlock the private key. The credentials structure can contain an immediate value for the credential, such as a passphrase, or the caller can specify a callback function the CSP can use to obtain one or more credentials. Credentials are required for signature operations, not for verify operations. Key (input) The key used to sign and verify. The caller passes a pointer to a CSSM_KEY structure containing the key and the key length. NewContextHandle (output) Cryptographic context handle. DESCRIPTION This function creates a signature cryptographic context for sign and verify, given a handle of a CSP, an algorithm identification number, a key, and an AccessCredentials structure. The AccessCredentials structure will be used to unlock the private key when this context is used to perform a signing operation. The cryptographic context handle is returned. The cryptographic context handle can be used to call sign and verify cryptographic functions. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_SignData CSSM_SignDataInit CSSM_SignDataUpdate CSSM_SignDataFinal CSSM_VerifyData CSSM_VerifyDataInit CSSM_VerifyDataUpdate CSSM_VerifyDataFinal CSSM_GetContext CSSM_SetContext CSSM_DeleteContext CSSM_GetContextAttribute CSSM_UpdateContextAttributes 3 CSSM_CSP_CreateSymmetricContext NAME CSSM_CSP_CreateSymmetricContext - Create a symmetric encryption cryptographic context (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_CSP_CreateSymmetricContext (CSSM_CSP_HANDLE CSPHandle, CSSM_ALGORITHMS AlgorithmID, CSSM_ENCRYPT_MODE Mode, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_KEY *Key, const CSSM_DATA *InitVector, CSSM_PADDING Padding, void *Reserved, CSSM_CC_HANDLE *NewContextHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform this function. If a NULL handle is specified, CSSM returns error. AlgorithmID (input) The algorithm identification number for symmetric encryption. Mode (input) The mode of the specified algorithm ID. AccessCred (input/optional) A pointer to the set of one or more credentials required to unlock the private key. The credentials structure can contain an immediate value for the credential, such as a passphrase, or the caller can specify a callback function the CSP can use to obtain one or more credentials. Credentials may be required for encryption, decryption, and wrapping operations. Key (input) The key used for symmetric encryption. The caller passes a pointer to a CSSM_KEY structure containing the key. InitVector (input/optional) The initial vector for symmetric encryption. This is typically specified for block ciphers. Padding (input/optional) The method for padding. This is typically specified for ciphers that pad. Reserved (input) Reserved for future use. NewContextHandle (output) Cryptographic context handle. DESCRIPTION This function creates a symmetric encryption cryptographic context, given a handle of a CSP, an algorithm identification number, a key, an initial vector, padding, and the number of encryption rounds. Algorithm-specific attributes must be added to the context after the initial creation using the CSSM_UpdateContextAttributes() function. The cryptographic context handle is returned. The cryptographic context handle can be used to call symmetric encryption functions and the cryptographic wrap or unwrap functions. Additional attributes can be added to the newly created context using the CSSM_UpdateContextAttributes() function . Incremental attributes of interest when using this context to unwrap a key include a handle-pair identifying a Data Storage Library service module and an open data store for CSPs that manage multiple, persistent key stores. If a CSP does not support multiple key stores, the CSP ignores the presence or absence of this attribute. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_DecryptData CSSM_DecryptDataInit CSSM_DecryptDataUpdate CSSM_DecryptDataFinal CSSM_DeleteContext CSSM_EncryptData CSSM_EncryptDataInit CSSM_EncryptDataUpdate CSSM_EncryptDataFinal CSSM_GetContext CSSM_GetContextAttribute CSSM_QuerySize CSSM_SetContext CSSM_UpdateContextAttributes 3 CSSM_CSP_GetLoginAcl NAME CSSM_CSP_GetLoginAcl - Get description of CSP ACL entries (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_CSP_GetLoginAcl (CSSM_CSP_HANDLE CSPHandle, const CSSM_STRING *SelectionTag, uint32 *NumberOfAclInfos, CSSM_ACL_ENTRY_INFO_PTR *AclInfos) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) 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. 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 parameter 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: · 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 the authorization array. · Authorization array -- A CSSM_AUTHORIZATIONGROUP structure defining the set of operations for which permission is granted to the subject. · Validity period -- A CSSM_ACL_VALIDITY_PERIOD structure containing two elements, the start time and the stop time for which the ACL entry is valid. · ACL entry tag -- A CSSM_STRING containing a user-defined value associated with the ACL entry. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. ERRORS Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_CSP_Login CSSM_CSP_LoginAcl CSSM_CSP_Logout 3 CSSM_CSP_GetLoginOwner NAME CSSM_CSP_GetLoginOwner - Get login owner data (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_CSP_GetLoginOwner (CSSM_CSP_HANDLE CSPHandle, CSSM_ACL_OWNER_PROTOTYPE_PTR Owner) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) 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. DESCRIPTION This function returns a CSSM_ACL_OWNER_PROTOTYPE describing the current login owner of 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_CSP_ChangeLoginOwner 3 CSSM_CSP_Login NAME CSSM_CSP_Login - Log user in to the CSP (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_CSP_Login (CSSM_CSP_HANDLE CSPHandle, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_DATA *LoginName, const void *Reserved) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CSPHandle (input) Handle of the CSP to log in to. AccessCred (input) A pointer to the set of one or more credentials required to log in to 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.) DESCRIPTION Logs the user in to the CSP, allowing for multiple login types. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_INVALID_LOGIN_NAME CSSMERR_CSP_ALREADY_LOGGED_IN SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_CSP_GetLoginAcl CSSM_CSP_ChangeLoginAcl CSSM_CSP_Logout 3 CSSM_CSP_Logout NAME CSSM_CSP_Logout - Terminate the login session (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_CSP_Logout (CSSM_CSP_HANDLE CSPHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CSPHandle (input) Handle for the target CSP. DESCRIPTION Terminates the login session associated with the specified CSP handle. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. ERRORS Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_CSP_Login, CSSM_CSP_GetLoginAcl, CSSM_CSP_ChangeLoginAcl 3 CSSM_ChangeKeyAcl NAME CSSM_ChangeKeyAcl - Edit a stored ACL associated with the target key (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_ChangeKeyAcl (CSSM_CSP_HANDLE CSPHandle, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_ACL_EDIT *AclEdit, const CSSM_KEY *Key) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CSPHandle (input) The module handle that identifies the cryptographic service provider to perform this operation AccessCred (input) A pointer to the set of one or more credentials used to authenticate and validate the caller's authorization to modify the ACL associated with the key. Required credentials can include zero or more certificates, zero or more caller names, and one or more samples. If certificates and/or caller names are provided as input, these must be provided as immediate values in this structure. The samples can be provided as immediate values or can be obtained through a callback function included in the AccessCred structure. AclEdit (input) A structure containing information that defines the edit operation. Valid operations include: adding, replacing, and deleting entries in an ACL managed by the service provider. The AclEdit can contain information for a new ACL entry and a handle uniquely identifying an existing ACL entry. The information controls the edit operation as follows: ______________________________________________________________ Value of AclEdit.EditMode Use of AclEdit.NewEntry and AclEdit.OldEntryHandle ______________________________________________________________ CSSM_ACL_EDIT_MODE_ADD Adds a new ACL entry to the set of ACL entries associated with the specified Key. The new ACL entry is created from the ACL entry prototype contained in NewEntry. OldEntryHandle is ignored for this edit mode. CSSM_ACL_EDIT_MODE_DELETE Deletes the ACL entry identified by OldEntryHandle and associated with the specified Key. NewEntry is ignored for this edit mode. CSSM_ACL_EDIT_MODE_REPLACE Replaces the ACL entry identified by OldEntryHandle and associated with the specified Key. The existing ACL is replaced based on the ACL entry prototype contained in the NewEntry. ______________________________________________________________ When replacing an existing ACL entry, the caller must replace all of the items in an ACL entry. The replacement prototype includes: Subject type and value A CSSM_LIST structure containing a typed Subject. The Subject identifies the entity authorized by this ACL entry. Delegation flag A CSSM_BOOL value indicating whether the subject can delegate the permissions recorded in the authorization array. Authorization array A CSSM_AUTHORIZATIONGROUP structure defining the set of operations for which permission is granted to the Subject. Validity period A CSSM_ACL_VALIDITY_PERIOD structure containing two elements, the start time and the stop time for which the ACL entry is valid. ACL entry tag A CSSM_STRING containing a user-defined value associated with the ACL entry. Key (input) A pointer to the target key whose associated ACL is being modified. 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. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_GetKeyAcl 3 CSSM_ChangeKeyOwner NAME CSSM_ChangeKeyOwner - Change the owner of a key (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_ChangeKeyOwner (CSSM_CSP_HANDLE CSPHandle, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_KEY *Key, const CSSM_ACL_OWNER_PROTOTYPE *NewOwner) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) 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 Oowner 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. DESCRIPTION This function takes 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_GetKeyOwner 3 CSSM_DeleteContext NAME CSSM_DeleteContext - Free the context structure (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_DeleteContext (CSSM_CC_HANDLE CCHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CCHandle (input) The handle that describes a context to be deleted. DESCRIPTION This function frees the context structure allocated by any of the CSSM_Createxxxxx context functions. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSSM_INVALID_CONTEXT_HANDLE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_CSP_CreateAsymmetricContext CSSM_CSP_CreateKeyGenContext CSSM_CSP_CreateDigestContext CSSM_CSP_CreateSignatureContext CSSM_CSP_CreateSymmetricContext 3 CSSM_DeleteContextAttributes NAME CSSM_DeleteContextAttributes - Delete internal data (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_DeleteContextAttributes (CSSM_CC_HANDLE CCHandle, uint32 NumberOfAttributes, const CSSM_CONTEXT_ATTRIBUTE *ContextAttributes) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CCHandle (input) The handle that describes a context that is to be deleted. NumberOfAttributes (input) The number of attributes to be deleted as specified in the array of context attributes. ContextAttributes (input) The attributes to be deleted from the context. Only the attribute type is required. Any attribute values in the CSSM_CONTEXT_ATTRIBUTE structures are ignored. DESCRIPTION This function deletes internal data associated with the given attribute type of the context handle. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. ERRORS Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSSM_INVALID_CONTEXT_HANDLE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_GetContextAttributes CSSM_UpdateContextAttributes 3 CSSM_FreeContext NAME CSSM_FreeContext - Free memory associated with the context structure (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_FreeContext (CSSM_CONTEXT_PTR Context) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS Context (input) The pointer to the memory that describes the context structure. DESCRIPTION This function frees the memory associated with the context structure. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. ERRORS Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_GetContext 3 CSSM_GetAPIMemoryFunctions NAME CSSM_GetAPIMemoryFunctions - Retrieve the memory function table associated with the security service module SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_GetAPIMemoryFunctions (CSSM_MODULE_HANDLE AddInHandle, CSSM_API_MEMORY_FUNCS_PTR AppMemoryFuncs) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS AddInHandle (input) The handle to the security service module that is associated with the requested memory function table. AppMemoryFuncs (output) The pointer to an empty memory functions table. Upon function return, the table is filled with the memory function pointers associated with the specified attach handle. Caller has to allocate the buffer. DESCRIPTION This function retrieves the memory function table associated with the security service module identified by the input handle. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. ERRORS Errors are described in the CDSA technical standard. See CDSA. SEE ALSO Intel CDSA Application Developer's Guide (see CDSA) 3 CSSM_GetContext NAME CSSM_GetContext - Get context information (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_GetContext (CSSM_CC_HANDLE CCHandle, CSSM_CONTEXT_PTR *Context) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CCHandle (input) The handle to the context information. Context (output) The pointer to the CSSM_CONTEXT_PTR structure that describes the context associated with the CCHandle handle. The pointer will be set to NULL if the function fails. Use CSSM_FreeContext() to free the memory allocated by the CSSM. DESCRIPTION This function retrieves the context information when provided with a context handle. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. ERRORS Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSSM_INVALID_CONTEXT_HANDLE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_FreeContext CSSM_SetContext 3 CSSM_GetContextAttribute NAME CSSM_GetContextAttribute - Get context attribute (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_GetContextAttribute (const CSSM_CONTEXT *Context, uint32 AttributeType, CSSM_CONTEXT_ATTRIBUTE_PTR *ContextAttribute) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS Context (input) A pointer to the context. AttributeType (input) The attribute type of the desired attribute value. ContextAttribute (output) The pointer to the CSSM_CONTEXT_ATTRIBUTE that describes the context attributes associated with the CCHandle handle and the attribute type. The pointer will be set to NULL if the function fails. Call CSSM_DeleteContextAttributes() to free memory allocated by the CSSM. DESCRIPTION This function returns the value of a context attribute. Context references the cryptographic context to be searched for the attribute specified by AttributeType. If the specified attribute is not present, then a NULL pointer is returned. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSSM_ATTRIBUTE_NOT_IN_CONTEXT SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_DeleteContextAttributes CSSM_GetContext 3 CSSM_GetKeyAcl NAME CSSM_GetKeyAcl - Get ACL entries by key (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_GetKeyAcl (CSSM_CSP_HANDLE CSPHandle, const CSSM_KEY *Key, const CSSM_STRING *SelectionTag, uint32 *NumberOfAclInfos, CSSM_ACL_ENTRY_INFO_PTR *AclInfos) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CSPHandle (input) The module handle that identifies the cryptographic service provider to perform this operation. Key (input) A pointer to the target key whose associated ACL entries are scanned and returned. SelectionTag (input/optional) A CSSM_STRING value matching the user-defined tag value associated with one or more ACL entries for the target Key. To retrieve a description of all ACL entries for the target Key, this parameter must be NULL. NumberOfAclInfos (output) The number of entries in the AclInfos array. If no ACL entry descriptions are returned, this value is zero. AclInfos (output) An array of CSSM_ACL_ENTRY_INFO structures. The unique handle contained in this structure can be used during the current attach session to reference specific ACL entries for editing. The structure is allocated by the service provider and must be released by the caller when the structure is no longer needed. If no ACL entry descriptions are returned, this value is NULL. 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 is 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: Subject type and value 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 the authorization array. Authorization array A CSSM_AUTHORIZATIONGROUP structure defining the set of operations for which permission is granted to the subject. Validity period A CSSM_ACL_VALIDITY_PERIOD structure containing two elements, the start time and the stop time for which the ACL entry is valid. ACL entry tag A CSSM_STRING containing a user-defined value associated with the ACL entry. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. ERRORS Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_ChangeKeyAcl 3 CSSM_GetKeyOwner NAME CSSM_GetKeyOwner - Get data describing key owner (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_GetKeyOwner (CSSM_CSP_HANDLE CSPHandle, const CSSM_KEY *Key, CSSM_ACL_OWNER_PROTOTYPE_PTR Owner) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) 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. DESCRIPTION This function returns a CSSM_ACL_OWNER_PROTOTYPE describing the current Owner of the Key. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. ERRORS Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_ChangeKeyOwner 3 CSSM_GetModuleGUIDFromHandle NAME CSSM_GetModuleGUIDFromHandle - Get GUID of the attached module (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_GetModuleGUIDFromHandle (CSSM_MODULE_HANDLE ModuleHandle, CSSM_GUID_PTR ModuleGUID) PARAMETERS ModuleHandle (input) The handle of the module for which the GUID should be returned. ModuleGUID (output) The GUID of the module associated with ModuleHandle.n. DESCRIPTION This function returns the GUID of the attached module identified by the specified handle. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. ERRORS Errors are described in the CDSA technical standard. See CDSA. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_GetSubserviceUIDFromHandle 3 CSSM_GetPrivilege NAME CSSM_GetPrivilege - Get CSSM privilege value (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_GetPrivilege (CSSM_PRIVILEGE *Privilege); LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS Privilege (output) The CSSM_PRIVILEGE value currently set. DESCRIPTION The CSSM_GetPrivilege() function returns the CSSM_PRIVILEGE value currently established in the framework. ERRORS Errors are described in the CDSA technical standard. See CDSA. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 CSSM_GetSubserviceUIDFromHandle NAME CSSM_GetSubserviceUIDFromHandle - Complete a subservice unique identifier structure (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_GetSubserviceUIDFromHandle (CSSM_MODULE_HANDLE ModuleHandle, CSSM_SUBSERVICE_UID_PTR SubserviceUID) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS ModuleHandle (input) Handle of the module subservice for which the subservice unique identifier should be returned. SubserviceUID (output) Subservice UID value associated with ModuleHandle. The caller has to allocate the buffer. DESCRIPTION This function completes a structure containing the persistent unique identifier of the attached module subservice, as identified by the input handle. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. ERRORS Errors are described in the CDSA technical standard. See CDSA. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_GetModuleGUIDFromHandle 3 CSSM_Init NAME CSSM_Init - Initialize CSSM (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_Init( const CSSM_VERSION *Version, CSSM_PRIVILEGE_SCOPE Scope, const CSSM_GUID * CallerGuid, CSSM_KEY_HIERARCHY KeyHierarchy, CSSM_PVC_MODE *PvcPolicy, const void *Reserved) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS Version (input) The major and minor version number of the CSSM release the application is compatible with. Scope (input) The scope of the global privilege value. The scope may either process scope wide (CSSM_PRIVILEGE_SCOPE_PROCESS) or thread wide (CSSM_PRIVILEGE_SCOPE_THREAD). This parameter is ignored after the first call to CSSM_Init(). CallerGuid (input) The GUID associated with the caller. This GUID is used to locate the caller's credentials when evaluating the request for privileges. KeyHierarchy (input) The CSSM_KEY_HIERARCHY option directing CSSM what embedded key to use when verifying integrity of the named module. PvcPolicy (input/output) Configures the way in which pointer validation checks will be performed. If not the first call to CSSM_Init(), the previously configured policy is returned in the PvcPolicy bitmask and the CSSM_Init() call continues processing. If successfully completed, the error code CSSMERR_CSSM_PVC_ALREADY_CONFIGURED is returned. _______________________________________________________________ Value Description _______________________________________________________________ 0 PVC validation is not performed 1 PVC validation is performed on application modules 2 PVC validation is performed on service provider modules 3 Both types of PVC validations are performed _______________________________________________________________ Reserved (input) A reserved input. DESCRIPTION This function initializes CSSM and verifies that the version of CSSM expected by the application is compatible with the version of CSSM on the system. This function should be called at least once by the application. It is an error to call any function of the CSSM API other than CSSM_Init() before a call to CSSM_Init() has returned successfully (that is, with CSSM_OK). Implementations of CSSM might have platform specific characteristics associated with the implementation of CSSM_SetPrivilege() API. The privilege value might have thread specific scope or process specific scope. The application can specify the anticipated scope at CSSM_Init(). If the anticipated scope is not appropriate for the implementation, an error is returned. The scope can be configured only once. Subsequent attempts to configure scope are ignored. CSSM integrity model includes the ability to make and check assertions about trusted dynamically loaded libraries. Checking assertions happens while the program executes. It is known as Pointer Validation Checking (PVC). Pointer validation checking can be applied every time execution flow crosses the CSSM API or SPI interfaces. Performing pointer validation checks has two purposes: · It allows exportation of CSSM. · It aids in detering unanticipated run-time modification of the program. The CSSM can be configured to bypass pointer validation under some circumstances. Pointer validation cannot be bypassed when privileged operations are being performed. The prerequisites for performing PVC on another module, be it service provider, CSSM, or other library, are: · The module must have been signed and have an accompanying signed manifest. · The module must be loaded into process address space. · An entry-point into the module must be available. Typically, the entry points are discovered when a module's functions are called by another module. The CSSM performs pointer validation checks based on the configured checking policy. Checking policies are established by the manufacturers of CSSM and other libraries. The checking policy to be applied during execution is configured using the CSSM_Init() call. The policy can be configured once during the life of the process and occurs the first time CSSM_Init() is called. PVC POLICY CONFIGURATION OPTIONS Pointer validation checking can be applied at the CSSM API interface, the CSSM SPI interface, or both. The CSSM vendor can configure a default policy through instructions contained in the CSSM signed manifest. Manifest attributes pertaining to pointer validation checking are defined as follows: Module Tag Value Description ------ --- ----- ----------- CSSM CDSA_PVC_API unspecified CSSM will perform PVC checks at the API boundary. CSSM CDSA_PVC_API OFF CSSM will not perform PVC checks at the API boundary. CSSM CDSA_PVC_SPI unspecified CSSM will perform PVC checks at the SPI boundary. CSSM CDSA_PVC_SPI OFF CSSM will not perform PVC checks at the SPI boundary. App CDSA_PVC_API EXEMPT The calling module is allowed to override the CSSM policy for the API boundary. App CDSA_PVC_API unspecified The calling module cannot weaken the CSSM API policy. App CDSA_PVC_SPI EXEMPT The calling module is allowed to override the CSSM policy for the SPI boundary. App CDSA_PVC_SPI unspecified The calling module cannot weaken the CSSM SPI policy. The PvcPolicy parameter to CSSM_Init() configures the run-time policy for the process. The PvcPolicy parameter is a bitmask allowing both API and SPI policies to be specified simultaneously. Unspecified policies default to the most conservative operational mode. CSSM performs pointer validation checks unless explicitly disabled. Application modules cannot override CSSM policy unless exemptions are explicitly granted. The following table shows the what policies can be configured for various manifest attribute values: CSSM Manifest Calling Module Manifest Acceptable PvcPolicy Values ------------ ----------------------- -------------------- CDSA_PVC_API= CDSA_PVC_API=EXEMPT API checks: off (0) or on (1) CDSA_PVC_API=OFF CDSA_PVC_API=EXEMPT API checks: off (0) or on (1) CDSA_PVC_API= CDSA_PVC_API= API checks: on (1) CDSA_PVC_API=OFF CDSA_PVC_API= API checks: off (0) or on (1) The following table shows the PvcPolicy configuations available for the SPI: SSM Manifest Calling Module Manifest Acceptable PvcPolicy Values ------------ ----------------------- -------------------- CDSA_PVC_SPI= CDSA_PVC_SPI=EXEMPT SPI checks: off (0) or on (2) CDSA_PVC_SPI=OFF CDSA_PVC_SPI=EXEMPT SPI checks: off (0) or on (2) CDSA_PVC_SPI= CDSA_PVC_SPI= SPI checks: on (2) CDSA_PVC_SPI=OFF CDSA_PVC_SPI= SPI checks: off (0) or on (2) If an application module does not have a manifest and CSSM requires the application module be subject to pointer validation checks, then pointer validation checks fail and CSSM will not operate with the anonymous module. All service provider modules are expected to have signed manifests. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSSM_SCOPE_NOT_SUPPORTED CSSMERR_CSSM_PVC_ALREADY_CONFIGURED CSSMERR_CSSM_INVALID_PVC SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) 3 CSSM_Introduce NAME CSSM_Introduce - Identify an executable module (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_Introduce (const CSSM_GUID *ModuleID, CSSM_KEY_HIERARCHY KeyHierarchy) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS ModuleID (input) The CSSM_GUID of the calling library or other library that might call CDSA interfaces. The GUID is used to locate the signed manifest credentials of the named module to calculate module integrity information. KeyHierarchy (input) The CSSM_KEY_HIERARCHY option directing CSSM what embedded key to use when verifying integrity of the named module. DESCRIPTION The CSSM_Introduce() function identifies a dynamically loadable executable module (for example, DLL) to the CSSM framework. CSSM uses the ModuleID information to locate the signed manifest and library on the host platform. The Module Directory Service (MDS) should be used to obtain the information. CSSM performs an integrity cross-check on the module identified by ModuleID and caches the result in an internal structure. The integrity cross-check uses the KeyHierarchy information to determine which classes of embedded public keys must serve as anchors when doing certificate path validation. If the export key hierarchy is specified, the set of export privileges contained in the manifest are retrieved from the manifest and saved with the integrity state information in the cache. Privileges granted to a module are accepted only if the manifest sections containing the privilege set have been signed by a principal in the export key hierarchy class and that hash of the module binary is part of the hash of the privilege attributes. The CSSM_Introduce() can be called at any time after CSSM_Init(), by any module, on behalf of any module. Once a module is introduced into CSSM the load location of the module must not change. If the load location changes then the module must be reintroduced. Once introduced, the module load location, integrity, and privilege information is held until CSSM_Terminate() is called or the process terminates. Initialization of internal data structures maintaining the table of introductions is performed when CSSM_Init() is called. If CSSM_Introduce() is called on behalf of another module, then the caller needs to make sure that the other module is loaded into the process address space. If the library is already loaded into process address space, but a reference to the library cannot be obtained, a different error is returned (CSSMERR_CSSM_LIB_REF_NOT_FOUND). 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSSM_INVALID_KEY_HIERARCHY CSSMERR_CSSM_LIB_REF_NOT_FOUND SEE ALSO Intel CDSA Application Developer's Guide (see CDSA) 3 CSSM_ListAttachedModuleManagers NAME CSSM_ListAttachedModuleManagers - Get a list of GUIDs for the attached module manager(CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_ListAttachedModuleManagers (uint32 *NumberOfModuleManagers, CSSM_GUID_PTR ModuleManagerGuids) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS NumberOfModuleManagers (input/output) The number of GUIDs in the array. If the array is not large enough, then the actual number needed is returned and the error CSSMERR_CSSM_BUFFER_TOO_SMALL is returned. The caller should then allocate an appropriately sized list and call the function again. If the supplied list is larger than needed, the number of module managers found is returned and no error is set. ModuleManagerGuids (input/output) A pointer to an array of CSSM_GUID structures, one per active module manager. The caller allocates this array. DESCRIPTION This function returns a list of GUIDs for the currently attached and active module managers in the CSSM environment. ERRORS Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSSM_BUFFER_TOO_SMALL CSSMERR_CSSM_INVALID_GUID SEE ALSO Intel CDSA Application Developer's Guide (see CDSA) 3 CSSM_ModuleAttach NAME CSSM_ModuleAttach - Attach and verify a service provider module (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_ModuleAttach (const CSSM_GUID *ModuleGuid, const CSSM_VERSION *Version, const CSSM_API_MEMORY_FUNCS *MemoryFuncs, uint32 SubserviceID, CSSM_SERVICE_TYPE SubServiceType, CSSM_ATTACH_FLAGS AttachFlags, CSSM_KEY_HIERARCHY KeyHierarchy, CSSM_FUNC_NAME_ADDR *FunctionTable, uint32 NumFunctionTable, const void *Reserved, CSSM_MODULE_HANDLE_PTR NewModuleHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS ModuleGuid (input) A pointer to the CSSM_GUID structure containing the global unique identifier for the CSP module. Version (input) The major and minor version number of CDSA that the application is compatible with. MemoryFuncs (input) A structure containing pointers to the memory routines. SubserviceID (input) A SubServiceID identifying a particular subservice within the module. Subservice IDs can be obtained from MDS or gleaned from insertion events reported through the callback function installed through CSSM_ModuleLoad(). Modules that provide only one service can use zero as their subservice ID. SubServiceType (input) A service mask describing the type of service the caller is requesting of the service provider module. AttachFlags (input) A mask representing the caller's request for session-specific services. KeyHierarchy (input) The CSSM_KEY_HIERARCHY option directing CSSM what embedded key to use when verifying integrity of the named module. FunctionTable (input/output/optional) A table of function-name and API function-pointer pairs. The caller provides the name of the functions as input. The corresponding API function pointers are returned on output. The function table allows dynamic linking of CDSA interfaces, including interfaces to Elective Module Managers (EMMs), which are transparently loaded by CSSM during CSSM_ModuleAttach(). NumFunctionTable (input) The number of entries in the FunctionTable parameter. If no FunctionTable is provided, this value must be zero. Reserved (input) This field is reserved for future use. It should always be set to zero NewModuleHandle (output) A new module handle that can be used to interact with the requested service provider. The value will be set to CSSM_INVALID_HANDLE if the function fails. DESCRIPTION This function attaches the service provider module and verifies that the version of the module expected by the application is compatible with the version on the system. The module can implement subservices (described in your service provider's documentation). The caller can specify a specific subservice provided by the module. If the subservice is supported as part of the CSSM framework as well as by an EMM, ModuleAttach attaches the Service Provider to the CSSM framework. If the subservice is supported only by an EMM, ModuleAttach loads the appropriate EMM. The service provider is given an indication of whether it is being attached to the CSSM framework or an EMM. The caller can provide a function table containing function names for the desired services. On output each function name is matched with an API function pointer. The caller can use the pointers to invoke service module operations through CSSM. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. ERRORS Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSSM_INVALID_ADDIN_FUNCTION_TABLE CSSMERR_CSSM_EMM_AUTHENTICATE_FAILED CSSMERR_CSSM_ADDIN_AUTHENTICATE_FAILED CSSMERR_CSSM_INVALID_SERVICE_MASK CSSMERR_CSSM_MODULE_NOT_LOADED CSSMERR_CSSM_INVALID_SUBSERVICEID CSSMERR_CSSM_INVALID_KEY_HIERARCHY CSSMERR_CSSM_INVALID_GUID SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_ModuleDetach 3 CSSM_ModuleDetach NAME CSSM_ModuleDetach - Detach application from service provider module (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_ModuleDetach (CSSM_MODULE_HANDLE ModuleHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS ModuleHandle (input) The handle that describes the service provider module. DESCRIPTION This function detaches the application from the service provider module. 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 Errors are described in the CDSA technical standard. See CDSA. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_ModuleAttach 3 CSSM_ModuleLoad NAME CSSM_ModuleLoad - Initialize the security service module (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_ModuleLoad (const CSSM_GUID *ModuleGuid, CSSM_KEY_HIERARCHY KeyHierarchy, CSSM_API_ModuleEventHandler AppNotifyCallback, void* AppNotifyCallbackCtx) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS ModuleGuid (input) The GUID of the module selected for loading. KeyHierarchy (input) The CSSM_KEY_HIERARCHY option directing CSSM what embedded key to use when verifying integrity of the named module. AppNotifyCallback (input/optional) The event notification function provided by the caller. This defines the callback for event notifications from the loaded (and later attached) service module. AppNotifyCallbackCtx (input/optional) When the selected service module raises an event, this context is passed as an input to the event handler specified by AppNotifyCallback. CSSM does not interpret or modify the value of AppNotifyCallbackCtx. DESCRIPTION This function initializes the security service module. Initialization includes registering the application's module-event handler and enabling events with the security service service module. The application can choose to provide an event handler function to receive notification of insert, remove, and fault events. The specified event handler is the single callback point for all attached sessions with the specified service module. The function CSSM_Init() must be invoked prior to calling CSSM_ModuleLoad(). The function CSSM_ModuleAttach() can be invoked multiple times per call to CSSM_ModuleLoad(). 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSSM_INVALID_GUID CSSMERR_CSSM_ADDIN_LOAD_FAILED CSSMERR_CSSM_EMM_LOAD_FAILED CSSMERR_CSSM_INVALID_KEY_HIERARCHY SEE ALSO Intel CDSA Application Developer's Guide (see CDSA) 3 CSSM_ModuleUnload NAME CSSM_ModuleUnload - Deregister event notification callbacks (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_ModuleUnload (const CSSM_GUID *ModuleGuid, CSSM_API_ModuleEventHandler AppNotifyCallback, void* AppNotifyCallbackCtx) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS ModuleGuid (input) The GUID of the module selected for unloading. AppNotifyCallback (input/optional) The event notification function to be deregistered. The function must have been provided by the caller in CSSM_ModuleLoad(). AppNotifyCallbackCtx (input/optional) The event notification context that was provided in the corresponding call to CSSM_ModuleLoad(). DESCRIPTION The function deregisters event notification callbacks for the caller identified by ModuleGuid. The CSSM_ModuleUnload() function is the analog call to CSSM_ModuleLoad(). If all callbacks registered with CSSM are removed, then CSSM unloads the service module that was loaded by calls to CSSM_ModuleLoad(). Calls to CSSM_ModuleUnload() that are not matched with a previous call to CSSM_ModuleLoad() result in an error. The CSSM uses the three input parameters ModuleGuid, AppNotifyCallback, and AppNotifyCallbackCtx to uniquely identify registered callbacks. This function should be invoked after all necessary calls to CSSM_ModuleDetach() have been performed. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSSM_ADDIN_UNLOAD_FAILED CSSMERR_CSSM_EMM_UNLOAD_FAILED CSSMERR_CSSM_EVENT_NOTIFICATION_CALLBACK_NOT_FOUND SEE ALSO Intel CDSA Application Developer's Guide (see CDSA) 3 CSSM_SPI_ModuleAttach NAME CSSM_SPI_ModuleAttach - Attach a service provider module(CDSA) SYNOPSIS # include CSSM_RETURN CSSMSPI CSSM_SPI_ModuleAttach (const CSSM_GUID *ModuleGuid, const CSSM_VERSION *Version, uint32 SubserviceID, CSSM_SERVICE_TYPE SubServiceType, CSSM_ATTACH_FLAGS AttachFlags, CSSM_MODULE_HANDLE ModuleHandle, CSSM_KEY_HIERARCHY KeyHierarchy, const CSSM_GUID *CssmGuid, const CSSM_GUID *ModuleManagerGuid, const CSSM_GUID *CallerGuid, const CSSM_UPCALLS *Upcalls, CSSM_MODULE_FUNCS_PTR *FuncTbl) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS ModuleGuid (input) The CSSM_GUID of the invoked service provider module. Version (input) The major and minor version number of the required level of system services and features. The service module must determine whether its services are compatible with the required version. SubserviceId (input) The identifier for the requested subservice within this module. If only one service is provided by the module, then subserviceId can be zero. SubServiceType (output) A CSSM_SERVICE_MASK indicating the type of services provided by the service module and the ordering of the function table returned in the output parameter FuncTbl. AttachFlags (input) A mask representing the caller's request for session-specific services. ModuleHandle (input) The CSSM_HANDLE value assigned by CSSM and associated with the attach session being created by this function. KeyHierarchy (input) The CSSM_KEY_HIERARCHY option directing CSSM which embedded key or keys to use when verifying integrity of the named modules. CssmGuid (input) The CSSM_GUID of the CSSM invoking this function. ModuleManagerGuid (input) The CSSM_GUID of the module that will route calls to the service provider. CallerGuid (input) The CSSM_GUID of the caller who invoked CSSM_ModuleAttach(), which resulted in CSSM invoking this function. Upcalls (input) A set of function pointers the service module must use to obtain selected CSSM services and to manage application memory. The memory management functions are provided when the application invokes CSSM_ModuleAttach(). CSSM forwards these function pointers with CSSM service function pointers to the module. FuncTbl (output) A CSSM_MODULE_FUNCS table containing pointers to the service module functions the caller can use. CSSM uses this table to proxy calls from an application caller to the add-in service module. DESCRIPTION This function is invoked by CSSM once for each invocation of CSSM_ModuleAttach(), specifying the module identified by ModuleGuid. Four entities are stakeholders in this function and each is identified by a CSSM_GUID value: Service Module The executing service provider performing the CSSM_SPI_ModuleAttach() operation. The module is identified by ModuleGuid. CSSM The CSSM that invoked the service module. CSSM is identified by CssmGuid. ModuleManagerGuid The module that will be routing calls to the service provider. This value will be the same as CssmGuid if CSSM is managing the calls to this service provider. Caller The entity that invoked CSSM through the CSSM_ModuleAttach() function. The caller is identified by CallerGuid. The service provider module should perform an integrity check of CSSM. CssmGuid can be used to locate CSSM's signed manifest credentials. The service provider can require an integrity check of the Caller. The CallerGuid parameter can be used to locate the Caller's signed manifest credentials. The KeyHierarchy flag identifies the class of embedded public keys CSSM will use to check the integrity of the service provider. If the manifest for the target module does not encounter an embedded key for all the key classes in KeyHierarchy, the integrity cross-check fails. The service module must verify compatibility with the system version level specified by Version. If the version is not compatible, then this function fails. The service module should perform all initializations required to support the new attached session and should return a function table for the SPI entry points that can be invoked by CSSM in response to API invocations by CallerGuid. CSSM uses this function table to dispatch requests for the attach session created by this function. Each attach session has its own function table. 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 Errors are described in the CDSA technical standard. See CDSA. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_SPI_ModuleDetach CSSM_SPI_ModuleLoad 3 CSSM_SPI_ModuleDetach NAME CSSM_SPI_ModuleDetach - Notify service module of a context event (CDSA) SYNOPSIS # include CSSM_RETURN CSSMSPI CSSM_SPI_ModuleDetach (CSSM_MODULE_HANDLE ModuleHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS ModuleHandle (input) The CSSM_HANDLE value associated with the attach session being terminated by this function. DESCRIPTION This function is invoked by CSSM once for each invocation of CSSM_ModuleDetach() specifying the attach-session identified by ModuleHandle. The function entry point for CSSM_SPI_ModuleDetach is included in the module function table CSSM_MODULE_FUNCS returned to CSSM as output of a successful CSSM_SPI_ModuleAttach. The service module must perform all cleanup operations associated with the specified attach handle. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. ERRORS Errors are described in the CDSA technical standard. See CDSA. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_SPI_ModuleAttach CSSM_SPI_ModuleUnload 3 CSSM_SPI_ModuleLoad NAME CSSM_SPI_ModuleLoad - Initialize process between CSSM and the add-in service module (CDSA) SYNOPSIS # include CSSM_RETURN CSSMSPI CSSM_SPI_ModuleLoad (const CSSM_GUID *CssmGuid, const CSSM_GUID *ModuleGuid, CSSM_SPI_ModuleEventHandler CssmNotifyCallback, void* CssmNotifyCallbackCtx) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CssmGuid (input) The CSSM_GUID of the caller. Used to locate the caller's signed manifest credentials. ModuleGuid (input) The CSSM_GUID of the invoked service provider module. Used to locate the module's signed manifest credentials. CssmNotifyCallback (input) A function pointer for the CSSM event handler that manages events of type CSSM_MODULE_EVENT. CssmNotifyCallbackCtx (input) The context to be returned to CSSM as input on each callback to the event handler defined by CssmNotifyCallback. DESCRIPTION This function completes the module initialization process between CSSM and the add-in service module. Before invoking this function, CSSM verifies the add-in service module's manifest credentials. If the credentials verify this module is loaded (physically if required), the CSSM_SPI_ModuleLoad() function is invoked. The CssmGuid parameter identifies the caller and should be used by the module to locate the caller's signed manifest credentials and to complete integrity verification and secure linkage checks on the caller. The ModuleGuid identifies the invoked module and should be used by the module to locate its credentials and to complete an integrity self-check. The CssmNotifyCallback and CssmNotifyCallbackCtx parameters define a callback and callback context respectively. The module must retain this information for later use. The module should use the callback to notify CSSM of module events of type CSSM_MODULE_EVENT in any ongoing, attached sessions. 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 Errors are described in the CDSA technical standard. See CDSA. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_SPI_ModuleAttach CSSM_SPI_ModuleUnload 3 CSSM_SPI_ModuleUnload NAME CSSM_SPI_ModuleUnload - Disable events and deregister CSSM event notification (CDSA) SYNOPSIS # include CSSM_RETURN CSSMSPI CSSM_SPI_ModuleUnload (const CSSM_GUID *CssmGuid, const CSSM_GUID *ModuleGuid, CSSM_SPI_ModuleEventHandler CssmNotifyCallback, void* CssmNotifyCallbackCtx) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CssmGuid (input) The CSSM_GUID of the caller. ModuleGuid (input) The CSSM_GUID of the invoked service provider module. CssmNotifyCallback (input) A function pointer for the CSSM event handler that manages events of type CSSM_MODULE_EVENT. CssmNotifyCallbackCtx (input) The context to be returned to CSSM as input on each callback to the event handler defined by CssmNotifyCallback. DESCRIPTION This function disables events and deregisters the CSSM event- notification function. The add-in service module can perform cleanup operations, reversing the initialization performed in CSSM_SPI_ModuleLoad(). 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 Errors are described in the CDSA technical standard. See CDSA. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_SPI_ModuleDetach CSSM_SPI_ModuleLoad 3 CSSM_SetContext NAME CSSM_SetContext - Replace all context information (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_SetContext (CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CCHandle (input) The handle to the context. Context (input) The context data describing the service to replace the current service associated with context handle CCHandle. DESCRIPTION This function replaces all context information associated with an existing context specified by CCHandle. The contents of the basic context structure and all attributes included in that structure are replaced by the context structure and attribute values contained in the Context input parameter. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSSM_INVALID_ATTRIBUTE CSSMERR_CSSM_INVALID_CONTEXT_HANDLE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_GetContext 3 CSSM_SetPrivilege NAME CSSM_SetPrivilege - Store privilege value in CSSM framework (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_SetPrivilege (CSSM_PRIVILEGE Privilege) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS Privilege (input) The CSSM_PRIVILEGE value to be applied to subsequent calls to CSSM interfaces. DESCRIPTION The CSSM_SetPrivilege() function accepts as input a privilege value and stores it in the CSSM framework. The integrity credentials of the module calling CSSM_SetPrivilege() must be verified by CSSM before the privilege value is updated. Integrity credentials are established using CSSM_Introduce(). CSSM will perform a pointer validation check to ensure the caller has been previously introduced. The CSSM_SetPrivilege() function will fail if no integrity information can be found for the caller. After pointer validation checks, CSSM verifies the requested privilege is authorized. This is done by comparing Privilege with the set of privileges contained in the caller manifest. If Privilege is not a member, the CSSM_SetPrivilege() call fails. Subsequent calls to the framework that require privileges inherit the privilege value previously established by CSSM_SetPrivilege(). CSSM will perform pointer validation checks on the API caller before servicing the API call. If OK, then the Privilege value is supplied to the SPI function. Internally, CSSM builds and maintains privilege information based on the chosen scope of the implementation. The scope may be dictated by the capabilities of the platform hosting the CSSM. If threading is available, the privilege value can be associated with the thread ID of the currently executing thread. In this scenario, CSSM can manage a table of tuples consisting of threadID and privilege value. If threading is not available, the privilege value can be global to the process. Because the selected privilege value is shared, the application programmer should take precautions to reset the privilege value whenever program flow leaves the caller's module and again when control flow returns. In general, any time there is a possibility for CSSM_SetPrivilege() to be called while within the context of the security critical section, CSSM_SetPrivilege() should be called again. Otherwise, the module receiving execution control could have called CSSM_SetPrivilege(), resulting in the privilege value being reset. Data structures used to maintain the global privilege value should be initialized in CSSM_Init(). This includes lock initialization and preliminary resource allocation. The CSSM_Init() function is assumed to be idempotent with respect to shared structure initialization. This means CSSM_Init() will ensure a single thread initializes the shared structure and subsequent calls to CSSM_Init() will not reinitialize it. A reference count of calls to CSSM_Init() is needed to ensure matching calls to CSSM_Terminate() are handled. Resource cleanup is performed at CSSM_Terminate() after the reference count falls to zero. The last call to CSSM_Terminate() results in shared resources being freed and lock structures being released. ERRORS Errors are described in the CDSA technical standard. See CDSA. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 CSSM_TP_RetrieveCredResult NAME CSSM_TP_RetrieveCredResult - Return the results of the credentials request (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_TP_RetrieveCredResult (CSSM_TP_HANDLE TPHandle, const CSSM_DATA *ReferenceIdentifier, const CSSM_TP_CALLERAUTH_CONTEXT *CallerAuthCredentials, sint32 *EstimatedTime, CSSM_BOOL *ConfirmationRequired, CSSM_TP_RESULT_SET_PTR *RetrieveOutput) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS TPHandle (input) The handle that describes the certification authority module used to perform this function. ReferenceIdentifier (input) A reference identifier that uniquely identifies the CSSM_TP_SubmitCredRequest() call that initiated the certificate service request whose results are returned by this function. The identifier persists across application executions and becomes undefined when all local processing of the request has completed. Local processing is completed in one of two ways: · For certificate services that do not require explicit confirmation by the requester, the reference identifier is invalidated when the corresponding CSSM_TP_RetrieveCredResult() function completes (by returning valid results or by failure, which blocks returned results). · For certificate services that require explicit confirmation by the requester, the reference identifier is invalidated by successfully invoking the function CSSM_TP_ConfirmCredResult(). CallerAuthCredentials (input/optional) This structure contains a set of caller authentication credentials. The authentication information can be a passphrase, a PIN, a completed registration form, a certificate, or a template of user-specific data. The required set of credentials is defined by the service provider module and recorded in a record in the MDS Primary relation. Multiple credentials can be required. If the local service provider module does not require credentials from a caller, then the Credentials field of this verification context structure can be NULL. The structure optionally contains additional credentials that can be used to support the authentication process. Authentication credentials required by the authority should be included in the RequestInput. The local TP module can forward information from CallerAuthCredentials to the authority, as appropriate, but is not required to do so. EstimatedTime (output) The number of seconds estimated before the results of a requested service will be returned to the requester. When the local TP module or the authority process cannot estimate the time required to perform the requested service, the output value for estimated time is CSSM_ESTIMATED_TIME_UNKNOWN. ConfirmationRequired (output) A Boolean value indicating whether the caller must invoke CSSM_TP_ConfirmCredResult() to acknowledge retrieving the results of the service request. CSSM_TRUE indicates the caller must call CSSM_TP_ConfirmCredResult(). CSSM_FALSE indicates that the caller must not call CSSM_TP_ConfirmCredResult(). The value of this output parameter is not applicable until CSSM_TP_RetrieveCredResult() completes by returning results of the request or terminates in unrecoverable failure. RetrieveOutput (output) A pointer to the results returned by the authority in response to the service requests submitted by CSSM_TP_SubmitCredRequest(). The output results are ordered corresponding to the requests. The structure of the response set is determined by the type of request. The caller and the service provider must retain knowledge of the request type associated with the ReferenceIdentifier. DESCRIPTION This function returns the results of a CSSM_TP_SubmitCredRequest() call. The single identifier ReferenceIdentifier denotes the CSSM_TP_SubmitCredRequest() invocation that initiated the request. It is possible that the results are not ready to be retrieved when this call is made. In that case, an EstimatedTime to complete processing is returned. The caller must attempt to retrieve the results again after the estimated time to completion has elapsed. This function can fail in total for any one of the following reasons: · The reference identifier is invalid. · The TP process cannot be located. · The TP process encountered a fatal error when attempting to process the requests. When this function completes, the set of return results is ordered corresponding to the order of the originating request. Some certificate services require the requester to confirm retrieval of the results. The ConfirmationRequired parameter indicates whether the caller must confirm completion of CSSM_TP_RetrieveCredResult() by calling CSSM_TP_ConfirmCredResult(). RETURN VALUE A CSSM_RETURN value combined with estimated time to indicate one of three results: Complete Function Function Return RetrieveOutput EstimatedTime Result Value ----------------- --------------- -------------- ------------- Request results CSSM_OK Non-NULL pointer NA returned to caller Request results not CSSM_OK NULL pointer CSSM_ESTIMATED_ ready, but expected TIME_UNKNOWN or in the future Fatal Error, results (!CSSM_OK) NA NA will never be returned The (!CSSM_OK) return value represents a specific error code. ERRORS Errors are described in the CDSA technical standard. See CDSA. CSSMERR_TP_INVALID_IDENTIFIER_POINTER CSSMERR_TP_INVALID_IDENTIFIER CSSMERR_TP_INVALID_CALLERAUTH_CONTEXT_POINTER CSSMERR_TP_INVALID_POLICY_IDENTIFIERS CSSMERR_TP_INVALID_TIMESTRING CSSMERR_TP_INVALID_STOP_ON_POLICY CSSMERR_TP_INVALID_CALLBACK CSSMERR_TP_INVALID_ANCHOR_CERT CSSMERR_TP_CERTGROUP_INCOMPLETE CSSMERR_TP_INVALID_DL_HANDLE CSSMERR_TP_INVALID_DB_HANDLE CSSMERR_TP_INVALID_DB_LIST_POINTER CSSMERR_TP_INVALID_DB_LIST CSSMERR_TP_AUTHENTICATION_FAILED CSSMERR_TP_INSUFFICIENT_CREDENTIALS CSSMERR_TP_NOT_TRUSTED CSSMERR_TP_CERT_REVOKED CSSMERR_TP_CERT_SUSPENDED CSSMERR_TP_CERT_EXPIRED CSSMERR_TP_CERT_NOT_VALID_YET CSSMERR_TP_INVALID_CERT_AUTHORITY CSSMERR_TP_INVALID_SIGNATURE CSSMERR_TP_INVALID_NAME CSSMERR_TP_REQUEST_LOST CSSMERR_TP_REQUEST_REJECTED SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_TP_SubmitCredRequest Functions for the TP SPI: TP_SubmitCredRequest 3 CSSM_Terminate NAME CSSM_Terminate - Terminate the use of CSSM (CDSA) SYNOPSIS # include LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS None DESCRIPTION This function terminates the caller's use of CSSM. CSSM can clean up all internal states associated with the calling application. This function must be called once by each application. CSSM_Terminate() must be called one time for each time CSSM_Init() was previously called. CSSM services remain available to the program until the final call to CSSM_Terminate() completes. After that final call, all information introduced by the caller (including privileges, handles, contexts, introduced libraries, and so forth) is lost, and it is an error to subsequently call any CSSM API function other than CSSM_Init(). 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 Errors are described in the CDSA technical standard. See CDSA. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions CSSM_Init 3 CSSM_Unintroduce NAME CSSM_Unintroduce - Remove module (CDSA) SYNOPSIS # include CSSM_RETURN CSSM_Unintroduce (const CSSM_GUID *ModuleID) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS ModuleID (input) The CSSM_GUID of the calling library or other library that can call CDSA interfaces. The GUID is used to locate the module integrity and privilege information. If the ModuleID is NULL, then the caller will be unintroduced. DESCRIPTION The CSSM_Unintroduce() function removes the module referenced by ModuleID from the list of module information maintained by the CSSM framework. A caller can unintroduce modules other than itself if the caller has been previously introduced. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSSM_INVALID_GUID SEE ALSO Intel CDSA Application Developer's Guide (see CDSA) 3 CSSM_UpdateContextAttributes NAME CSSM_UpdateContextAttributes - Update context attribute values (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_UpdateContextAttributes (CSSM_CC_HANDLE CCHandle, uint32 NumberOfAttributes, const CSSM_CONTEXT_ATTRIBUTE *ContextAttributes) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CCHandle (input) The handle to the existing context. NumberOfAttributes (input) The number of CSSM_CONTEXT_ATTRIBUTE structures to allocate. ContextAttributes (input) Pointer to data that describes the attributes to be associated with this context. DESCRIPTION This function updates one or more context attribute values stored as part of an existing context specified by CCHandle. The basic context structure is not modified by this function. Only the context attributes are updated. The NumberOfAttributes parameter specifies the number of attributes to update. The new attribute values are specified in ContextAttributes. If an attribute provided in ContextAttributes is already present in the existing context, the existing value is replaced by the new value. If an attribute provided in ContextAttributes is not present in the existing context, then the new attribute is added. Attribute values are never deleted from the existing context. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSSM_INVALID_CONTEXT_HANDLE CSSMERR_CSSM_INVALID_ATTRIBUTE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_DeleteContextAttributes CSSM_GetContextAttribute 3 DL_Authenticate NAME DL_Authenticate, CSSM_DL_Authenticate - Provide authentication credentials (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DL_Authenticate (CSSM_DL_DB_HANDLE DLDBHandle, CSSM_DB_ACCESS_TYPE AccessRequest, const CSSM_ACCESS_CREDENTIALS *AccessCred) SPI: CSSM_RETURN CSSMDLI DL_Authenticate (CSSM_DL_DB_HANDLE DLDBHandle, CSSM_DB_ACCESS_TYPE AccessRequest, const CSSM_ACCESS_CREDENTIALS *AccessCred) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS DLDBHandle (input) The handle pair that describes the add-in data storage library module used to perform this function and the data store to which access is being requested. If the form of authentication being requested is authentication to the DL module in general, then the data store handle must be NULL. AccessRequest (input) An indicator of the requested access mode for the data store or DL module in general. AccessCred (input) A pointer to the set of one or more credentials being presented for authentication by the caller. The credentials can apply to the DL module in general or to a particular data store managed by this service module. The credentials required for creating new data stores is defined by the DL and recorded in a record in the MDS Primary DL relation. The required set of credentials to access a particular data store is defined by the DbInfo record containing meta-data for the specified data store. The credentials structure can contain multiple types of credentials, as required for multi-factor authentication. The credential data can be an immediate value, such as a passphrase, PIN, certificate, or template of user-specific data, or the caller can specify a callback function the DL can use to obtain one or more credentials. DESCRIPTION This function allows the caller to provide authentication credentials to the DL module at a time other than data store creation, deletion, open, import, and export. AccessRequest defines the type of access to be associated with the caller. If the authentication credential applies to access and use of a DL module in general, then the data store handle specified in the DLDBHandle must be NULL. When the authorization credential is to apply to a specific data store, the handle for that data store must be specified in the DLDBHandle pair. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_DL_INVALID_ACCESS_REQUEST CSSMERR_DL_INVALID_DB_HANDLE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 DL_ChangeDbAcl NAME DL_ChangeDbAcl, CSSM_DL_ChangeDbAcl - Edit stored ACL (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DL_ChangeDbAcl (CSSM_DL_DB_HANDLE DLDBHandle, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_ACL_EDIT *AclEdit) SPI: CSSM_RETURN CSSMDLI DL_ChangeDbAcl (CSSM_DL_DB_HANDLE DLDBHandle, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_ACL_EDIT *AclEdit) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS DLDBHandle (input) The handle pair that describes the data storage library module to be used to perform this function, and the open data store whose associated ACL entries are to be updated. 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 target data base. 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 the set of ACL entries managed by the service provider. The AclEdit can contain information for a new ACL entry and a unique handle 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 data base. The new ACL entry is created from the prototype ACL entry 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 data base. NewEntry is ignored for this EditMode. CSSM_ACL_EDIT_MODE_REPLACE Replaces the ACL entry identified by OldEntryHandle and associated with the specified data base. The existing ACL is replaced based on the ACL entry prototype contained in 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. DESCRIPTION This function edits the stored ACL associated with the target data base identified by DLDBHandle.DBHandle. 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 data base. 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 TypedSubject 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. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_DL_INVALID_DB_HANDLE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DL_GetDbAcl Functions for the DL SPI: DL_GetDbAcl 3 DL_ChangeDbOwner NAME DL_ChangeDbOwner, CSSM_DL_ChangeDbOwner - Define a new data base owner (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DL_ChangeDbOwner (CSSM_DL_DB_HANDLE DLDBHandle, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_ACL_OWNER_PROTOTYPE *NewOwner) SPI: CSSM_RETURN CSSMDLI DL_ChangeDbOwner (CSSM_DL_DB_HANDLE DLDBHandle, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_ACL_OWNER_PROTOTYPE *NewOwner) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS DLDBHandle (input) The handle pair that describes the data storage library module to be used to perform this function, and the open data store whose associated Owner is to be updated. AccessCred (input) A pointer to the set of one or more credentials used to prove the caller is the current Owner of the Data Base. 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 Owner of the Data Base. DESCRIPTION This function takes a CSSM_ACL_OWNER_PROTOTYPE defining the new Owner of the Data Base. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_DL_INVALID_DB_HANDLE CSSMERR_DL_INVALID_NEW_OWNER SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DL_GetDbOwner Functions for the DL SPI: DL_GetDbOwner 3 DL_CreateRelation NAME DL_CreateRelation, CSSM_DL_CreateRelation - Create a new persistent relation (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DL_CreateRelation (CSSM_DL_DB_HANDLE DLDBHandle, CSSM_DB_RECORDTYPE RelationID, const char *RelationName, uint32 NumberOfAttributes, const CSSM_DB_SCHEMA_ATTRIBUTE_INFO *pAttributeInfo, uint32 NumberOfIndexes, const CSSM_DB_SCHEMA_INDEX_INFO *pIndexInfo) SPI: CSSM_RETURN CSSMDLI DL_CreateRelation (CSSM_DL_DB_HANDLE DLDBHandle, CSSM_DB_RECORDTYPE RelationID, const char *RelationName, uint32 NumberOfAttributes, const CSSM_DB_SCHEMA_ATTRIBUTE_INFO *pAttributeInfo, uint32 NumberOfIndexes, const CSSM_DB_SCHEMA_INDEX_INFO *pIndexInfo) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS DLDBHandle (input) The handle pair that describes the add-in data storage library module to be used to perform this function and the open data store in which to insert the new relation record. The database should be opened in administrative mode using the CSSM_DB_ACCESS_PRIVILEGED flag. RelationID (input) Indicates the type of relation record being added to the data store. RelationName (input) Indicates the name of the relation being added to the data store. NumberOfAttributes (input) Indicates the number of attributes specified in pAttributeInfo. pAttributeInfo (input) A list of structures containing the meta information (schema) describing the attributes for the relation being added to the specified data store. The list contains at most one entry per attribute in the specified record type. NumberOfIndexes (input) Indicates the number of indexes specified in pIndexInfo. pIndexInfo (input) A list of structures containing the meta information (schema) describing the indexes for the relation being added to the specified data store. The list contains at most one entry per index in the specified record type. DESCRIPTION This function creates a new persistent relation of the specified type by inserting it into the specified data store. The pAttributeInfo and pIndexInfo specify the values contained in the new relation record. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE CSSMERR_DL_INVALID_ATTRIBUTE_INFO CSSMERR_DL_INVALID_DB_HANDLE CSSMERR_DL_INVALID_INDEX_INFO CSSMERR_DL_INVALID_RECORDTYPE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DL_DestroyRelation Functions for the DL SPI: DL_DestroyRelation 3 DL_DataAbortQuery NAME DL_DataAbortQuery, CSSM_DL_DataAbortQuery - Terminate DL_DataGetFirst query (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DL_DataAbortQuery (CSSM_DL_DB_HANDLE DLDBHandle, CSSM_HANDLE ResultsHandle) SPI: CSSM_RETURN CSSMDLI DL_DataAbortQuery (CSSM_DL_DB_HANDLE DLDBHandle, CSSM_HANDLE ResultsHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS DLDBHandle (input) The handle pair that describes the add-in data storage library module to be used to perform this function and the open data store from which records were selected by the initiating query. ResultsHandle (input) The selection handle returned from the initial query function. DESCRIPTION This function terminates the query initiated by DL_DataGetFirst() and allows a DL to release all intermediate state information associated with the query, and release any locks on the resource. The user/application must call CSSM_DL_DataAbortQuery() at the termination. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_DL_INVALID_DB_HANDLE CSSMERR_DL_INVALID_RESULTS_HANDLE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DL_DataGetFirst CSSM_DL_DataGetNext Functions for the DL SPI: DL_DataGetFirst DL_DataGetNext 3 DL_DataDelete NAME DL_DataDelete, CSSM_DL_DataDelete - Remove data record (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DL_DataDelete (CSSM_DL_DB_HANDLE DLDBHandle, const CSSM_DB_UNIQUE_RECORD *UniqueRecordIdentifier) SPI: CSSM_RETURN CSSMDLI DL_DataDelete (CSSM_DL_DB_HANDLE DLDBHandle, const CSSM_DB_UNIQUE_RECORD *UniqueRecordIdentifier) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS DLDBHandle (input) The handle pair that describes the add-in data storage library module to be used to perform this function and the open data store from which to delete the specified data record. UniqueRecordIdentifier (input) A pointer to a CSSM_DB_UNIQUE_RECORD identifier containing unique identification of the data record to be deleted from the data store. Once the associated record has been deleted, this unique record identifier cannot be used in future references, except as an argument to DL_FreeUniqueRecord() which must still be called. DESCRIPTION This function removes the data record specified by the unique record identifier from the specified data store. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_DL_INVALID_DB_HANDLE CSSMERR_DL_INVALID_RECORD_UID CSSMERR_DL_RECORD_NOT_FOUND SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DL_DataInsert Functions for the DL SPI: DL_DataInsert 3 DL_DataGetFirst NAME DL_DataGetFirst, CSSM_DL_DataGetFirst - Get first data record (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DL_DataGetFirst (CSSM_DL_DB_HANDLE DLDBHandle, const CSSM_QUERY *Query, CSSM_HANDLE_PTR ResultsHandle, CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes, CSSM_DATA_PTR Data, CSSM_DB_UNIQUE_RECORD_PTR *UniqueId) SPI: CSSM_RETURN CSSMDLI DL_DataGetFirst (CSSM_DL_DB_HANDLE DLDBHandle, const CSSM_QUERY *Query, CSSM_HANDLE_PTR ResultsHandle, CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes, CSSM_DATA_PTR Data, CSSM_DB_UNIQUE_RECORD_PTR *UniqueId) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS DLDBHandle (input) The handle pair that describes the add-in data storage library module to be used to perform this function and the open data store to search for records satisfying the query. Query (input/optional) The query structure specifying the selection predicate(s) used to query the data store. The structure contains meta information about the search fields and the relational and conjunctive operators forming the selection predicate. The comparison values to be used in the search are specified in the Attributes field of this Query structure. If a search attribute is of type CSSM_DB_ATTRIBUTE_FORMAT_STRING and the search value specified for that string includes a null- terminator, then the length count for that string should include the terminating character. (If null-terminators are used they should be used consistently, storing the terminator as part of the string in the data store, otherwise selection predicates will not locate expected matches.) The Query structure attributes also identify the particular attributes to be searched by this query. If no query is specified, the DL module can return the first record in the data store, performing sequential retrieval, or return an error. If no selection predicates are specified, the DL module can return the first record in the data store, performing sequential retrieval, or return an error (CSSM_DL_UNSUPPORTED_NUM_SELECTION_PREDS). When selection predicates are specified, the NumberOfValues of the Attribute of each selection predicate must be 1. If any selection predicate does not satisfy this requirement, the error CSSMERR_DL_INVALID_QUERY is returned. ResultsHandle (output) This handle should be used to retrieve subsequent records that satisfied this query. Attributes (optional-input/output) If the Attributes structure pointer is NULL, no values are returned. Otherwise, the DataRecordType, NumberOfAttributes and AttributeData fields are read. AttributeData must be an array of NumberOfAttributes CSSM_DB_RECORD_ATTRIBUTE elements. Only the Info field of each element is used on input. The AttributeFormat field of the Info field is ignored on input. On output, a CSSM_DB_RECORD_ATTRIBUTE structure containing a list of all or the requested attribute values (subset) from the retrieved record. The SemanticInformation field is set. For each CSSM_DB_ATTRIBUTE_DATA contained in the AttributeData array, the NumberOfValues field is set to reflect the size of the Value array which is allocated by the DL using the application specified allocators. Each CSSM_DATA in the Value array will have it's Data field as a pointer to data allocated using the application specified allocators containing the attributes value, and have it's Length set to the length of the value. All values for an attribute are returned (this could be 0). All fields in the Info field of the CSSM_DB_ATTRIBUTE_DATA are left unchanged except for the AttributeFormat field, which is set to reflect the schema. Data (optional-input/output) Data values contained in the referenced memory are ignored during processing and are overwritten with the retrieved opaque object. On output, a CSSM_DATA structure containing the opaque object stored in the retrieved record. UniqueId (output) If successful and (at least) a record satisfying the query has been found, then this parameter returns a pointer to a CSSM_UNIQUE_RECORD_PTR structure containing a unique identifier associated with the retrieved record. This unique identifier structure can be used in future references to this record using this DLDBHandle pairing. It may not be valid for other DLHandles targeted to this DL module or to other DBHandles targeted to this data store. If there are no records satisfying the query, then this pointer is NULL and CSSM_DL_DataGetFirst() must return CSSM_DL_ENDOFDATA; in this case a normal termination condition has occurred. The CSSM_DL_FreeUniqueRecord() must be used to de-allocate this structure. DESCRIPTION This function retrieves the first data record in the data store that matches the selection criteria. The selection criteria (including selection predicate and comparison values) is specified in the Query structure. If the Query specifies an attribute that is not defined in the database's meta-information, an error condition is returned. The DL module can use internally-managed indexing structures to enhance the performance of the retrieval operation. This function selects the first record satisfying the query based on the list of Attributes and the opaque Data object. The output buffers for the retrieved record are allocated by this function using the memory management functions provided during the module attach operation. This function also returns a results handle to be used when retrieving subsequent records satisfying the query. Additional matching records are iteratively retrieved using the CSSM_DL_DataGetNext() function . The data storage module supports one of two retrieval models: · Transactional - all query results are determined at initial query evaluation. Results do not change during an incremental retrieval process. · File System Scan - query results are selected during the incremental retrieval process. Records matching the query may be added to or deleted from the underlying data store during the iterative retrieval. The caller may receive the new matching records and not received the deleted records. The caller can determine which retrieval model is supported by examining the encapsulated product description for this data storage module. If the query selection criteria also specifies time for space limits for executing the query, those limits also apply ro retrieval of the additional selected data records retrieved using the CSSM_DL_DataGetNext() function. Finally, this function returns a unique record identifier associated with the retrieved record. This structure can be used in future references to the retrieved data record. Once a user has finished using a certain query, it must call CSSM_DataAbortQuery() for releasing resources that CSSM uses. If all records satisfying the query have been retrieved, then query is automatically terminated. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_DL_ENDOFDATA CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT CSSMERR_DL_INVALID_DB_HANDLE CSSMERR_DL_INVALID_FIELD_NAME CSSMERR_DL_INVALID_PARSING_MODULE CSSMERR_DL_INVALID_QUERY CSSMERR_DL_INVALID_RECORDTYPE CSSMERR_DL_INVALID_RECORD_UID CSSMERR_DL_UNSUPPORTED_FIELD_FORMAT CSSMERR_DL_UNSUPPORTED_NUM_SELECTION_PREDS CSSMERR_DL_UNSUPPORTED_OPERATOR CSSMERR_DL_UNSUPPORTED_QUERY CSSMERR_DL_UNSUPPORTED_QUERY_LIMITS SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DL_DataGetNext CSSM_DL_DataAbortQuery Functions for the DL SPI: DL_DataGetNext DL_DataAbortQuery 3 DL_DataGetFromUniqueRecordId NAME DL_DataGetFromUniqueRecordId, CSSM_DL_DataGetFromUniqueRecordId - Get data record (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DL_DataGetFromUniqueRecordId (CSSM_DL_DB_HANDLE DLDBHandle, const CSSM_DB_UNIQUE_RECORD_PTR UniqueRecord, CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes, CSSM_DATA_PTR Data) SPI: CSSM_RETURN CSSMDLI DL_DataGetFromUniqueRecordId (CSSM_DL_DB_HANDLE DLDBHandle, const CSSM_DB_UNIQUE_RECORD_PTR UniqueRecord, CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes, CSSM_DATA_PTR Data) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS DLDBHandle (input) The handle pair that describes the add-in data storage library module to be used to perform this function and the open data store to search for the data record. UniqueRecord (input) The pointer to a unique record structure returned from a DL_DataInsert, DL_DataGetFirst, or DL_DataGetNext operation. Attributes (optional-input/output) If the Attributes structure pointer is NULL, no values are returned. Otherwise, the DataRecordType, NumberOfAttributes and AttributeData fields are read. AttributeData must be an array of NumberOfAttributes CSSM_DB_RECORD_ATTRIBUTE elements. Only the Info field of each element is used on input. The AttributeFormat field of the Info field is ignored on input. On output, a CSSM_DB_RECORD_ATTRIBUTE structure containing a list of all or the requested attribute values (subset) from the retrieved record. The SemanticInformation field is set. For each CSSM_DB_ATTRIBUTE_DATA contained in the AttributeData array, the NumberOfValues field is set to reflect the size of the Value array which is allocated by the DL using the application specified allocators. Each CSSM_DATA in the Value array will have it's Data field as a pointer to data allocated using the application specified allocators containing the attributes value, and have it's Length set to the length of the value. All values for an attribute are returned (this could be 0). All fields in the Info field of the CSSM_DB_ATTRIBUTE_DATA are left unchanged except for the AttributeFormat field, which is set to reflect the schema. Data (optional-input/output) Data values contained in the referenced memory are ignored during processing and are overwritten with the retrieved opaque object. On output, a CSSM_DATA structure containing the opaque object stored in the retrieved record. If the pointer is data structure pointer is NULL, the opaque object is not returned. DESCRIPTION This function retrieves the data record and attributes associated with this unique record identifier. The Attributes parameter can specify a subset of the attributes to be returned. If Attributes specifies an attribute that is not defined in the database's meta- information, an error condition is returned. The output buffers for the retrieved record are allocated by this function using the memory management functions provided during the module attach operation. The DL module can use an indexing structure identified in the UniqueRecordId to enhance the performance of the retrieval operation. The DL should assume that the value of CSSM_QUERY_FLAGS is when performing this operation. In particular this means that if the data of a key record is being retrieved, the DL will return a CSSM_KEY structure with a key reference. If the record referenced by UniqueRecordIdentifier has been modified since the last time it was retrieved, the error (warning) CSSMERR_DL_RECORD_MODIFIED is returned but the requested attributes and data of the new record is returned. The caller should be advised that other attributes (or the data) might have changed that were not fetched from the DL with this call. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT CSSMERR_DL_INVALID_DB_HANDLE CSSMERR_DL_INVALID_FIELD_NAME CSSMERR_DL_INVALID_RECORDTYPE CSSMERR_DL_INVALID_RECORD_UID SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DL_DataInsert CSSM_DL_DataGetFirst CSSM_DL_DataGetNext Functions for the DL SPI: CSSM_DL_DataInsert CSSM_DL_DataGetFirst CSSM_DL_DataGetNext 3 DL_DataGetNext NAME DL_DataGetNext, CSSM_DL_DataGetNext - Get next data record (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DL_DataGetNext (CSSM_DL_DB_HANDLE DLDBHandle, CSSM_HANDLE ResultsHandle, CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes, CSSM_DATA_PTR Data, CSSM_DB_UNIQUE_RECORD_PTR *UniqueId) SPI: CSSM_RETURN CSSMDLI DL_DataGetNext (CSSM_DL_DB_HANDLE DLDBHandle, CSSM_HANDLE ResultsHandle, CSSM_DB_RECORD_ATTRIBUTE_DATA_PTR Attributes, CSSM_DATA_PTR Data, CSSM_DB_UNIQUE_RECORD_PTR *UniqueId) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS DLDBHandle (input) The handle pair that describes the add-in data storage library module to be used to perform this function, and the open data store from which records were selected by the initiating query. ResultsHandle (input) The handle identifying a set of records retrieved by a query executed by the CSSM_DL_DataGetFirst() function. Attributes (optional-input/output) If the Attributes structure pointer is NULL, no values are returned. Otherwise, the DataRecordType, NumberOfAttributes and AttributeData fields are read. AttributeData must be an array of NumberOfAttributes CSSM_DB_RECORD_ATTRIBUTE elements. Only the Info field of each element is used on input. The AttributeFormat field of the Info field is ignored on input. On output, a CSSM_DB_RECORD_ATTRIBUTE structure containing a list of all or the requested attribute values (subset) from the retrieved record. The SemanticInformation field is set. For each CSSM_DB_ATTRIBUTE_DATA contained in the AttributeData array, the NumberOfValues field is set to reflect the size of the Value array which is allocated by the DL using the application specified allocators. Each CSSM_DATA in the Value array will have it's Data field as a pointer to data allocated using the application specified allocators containing the attributes value, and have it's Length set to the length of the value. All values for an attribute are returned (this could be 0). All fields in the Info field of the CSSM_DB_ATTRIBUTE_DATA are left unchanged except for the AttributeFormat field, which is set to reflect the schema. Data (optional-input/output) Data values contained in the referenced memory are ignored during processing and are overwritten with the retrieved opaque object. On output, a CSSM_DATA structure containing the opaque object stored in the retrieved record. If the pointer is data structure pointer is NULL, the opaque object is not returned. UniqueId (output) If successful and (at least) a record satisfying the query has been found, then this parameter returns a pointer to a CSSM_UNIQUE_RECORD_PTR structure containing a unique identifier associated with the retrieved record. This unique identifier structure can be used in future references to this record using this DLDBHandle pairing. It may not be valid for other DLHandles targeted to this DL module or to other DBHandles targeted to this data store. If there are no more records satisfying the query, then this pointer is NULL and CSSM_DL_DataGetNext() must return CSSM_DL_ENDOFDATA; in this case a normal termination condition has occurred. The CSSM_DL_FreeUniqueRecord() must be used to de-allocate this structure. DESCRIPTION This function returns the next data record referenced by the ResultsHandle. The ResultsHandle references a set of records selected by an invocation of the DataGetFirst function. The Attributes parameter can specify a subset of the attributes to be returned. If Attributes specifies an attribute that is not defined in the database's meta-information, an error condition is returned. The record values are returned in the Attributes and Data parameters. The output buffers for the retrieved record are allocated by this function using the memory management functions provided during the module attach operation. The function also returns a unique record identifier for the return record. The data storage module supports one of two retrieval models: transactional or file system scan. The transactional model freezes the set of records to be retrieved at query initiation. The file system scan model selects from a potentially changing set of records during the retrieval process. The EndOfDataStore() function indicates when all matching records have been retrieved. The caller can determine which retrieval model is supported by examining the encapsulated product description for this data storage module. Once a user has finished using a certain query, it must call CSSM_DataAbortQuery() for releasing resources that CSSM uses. If all records satisfying the query have been retrieved, then query is automatically terminated. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_DL_ENDOFDATA CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT CSSMERR_DL_INVALID_DB_HANDLE CSSMERR_DL_INVALID_FIELD_NAME CSSMERR_DL_INVALID_RECORDTYPE CSSMERR_DL_INVALID_RECORD_UID CSSMERR_DL_INVALID_RESULTS_HANDLE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DL_DataGetFirst CSSM_DL_DataAbortQuery Functions for the DL SPI: DL_DataGetFirst DL_DataAbortQuery 3 DL_DataInsert NAME DL_DataInsert, CSSM_DL_DataInsert - Create new persistent data record (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DL_DataInsert (CSSM_DL_DB_HANDLE DLDBHandle, CSSM_DB_RECORDTYPE RecordType, const CSSM_DB_RECORD_ATTRIBUTE_DATA *Attributes, const CSSM_DATA *Data, CSSM_DB_UNIQUE_RECORD_PTR *UniqueId) SPI: CSSM_RETURN CSSMDLI DL_DataInsert (CSSM_DL_DB_HANDLE DLDBHandle, CSSM_DB_RECORDTYPE RecordType, const CSSM_DB_RECORD_ATTRIBUTE_DATA *Attributes, const CSSM_DATA *Data, CSSM_DB_UNIQUE_RECORD_PTR *UniqueId) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS DLDBHandle (input) The handle pair that describes the add-in data storage library module to be used to perform this function and the open data store in which to insert the new data record. RecordType (input) Indicates the type of data record being added to the data store Attributes (input/optional) A list of structures containing the attribute values to be stored in that attribute, and the meta information (schema) describing those attributes. The list contains at most one entry per attribute in the specified record type. The specified AttributeFormat for each attribute must match that of the database schema, otherwise the error CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT is returned. If an attribute is of type CSSM_DB_ATTRIBUTE_FORMAT_STRING and the value specified for that string includes a null-terminator, then the length count in the CSSM_DATA structure containing the input string should include the terminating character. (If null-terminators are used, they should be used consistently when storing, searching, and retrieving the string value, otherwise selection predicates will not locate expected matches.) For those attributes that are not assigned values by the caller, the DL module may assume the values to be the empty set, or assume default values, or return an error. If the specified record type does not contain any attributes, this parameter must be NULL. Data (input/optional) A pointer to the CSSM_DATA structure which contains the opaque data object to be stored in the new data record. If the specified record type does not contain an opaque data object, this parameter must be NULL. UniqueId (output) A pointer to a CSSM_DB_UNIQUE_RECORD_PTR containing a unique identifier associated with the new record. This unique identifier structure can be used in future references to this record during the current open data base session. The pointer will be set to NULL if the function fails. The CSSM_DL_FreeUniqueRecord() function must be used to deallocate this structure. DESCRIPTION This function creates a new persistent data record of the specified type by inserting it into the specified data store. The values contained in the new data record are specified by the Attributes and the Data. The attribute value list contains zero or more attribute values. The Attributes parameter also specifies a record type. This type must be the same as the type specified by the RecordType input parameter. The DL module may require initial values for the CSSM pre-defined attributes. The DL module can assume default values for any unspecified attribute values or can return an error condition when DLM-required attribute values are not specified by the caller. The Data is an opaque object to be stored in the new data record. If a primary key (concatination of all unique indexes in the relation) exists, the error CSSMERR_DL_INVALID_UNIQUE_INDEX_DATA is returned. The client should call CSSM_DL_DataGetFirst(), followed by CSSM_DL_DataModify() to change an existing record. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT CSSMERR_DL_INVALID_FIELD_NAME CSSMERR_DL_INVALID_DB_HANDLE CSSMERR_DL_INVALID_PARSING_MODULE CSSMERR_DL_INVALID_RECORDTYPE CSSMERR_DL_INVALID_RECORD_UID CSSMERR_DL_INVALID_UNIQUE_INDEX_DATA CSSMERR_DL_INVALID_VALUE CSSMERR_DL_MISSING_VALUE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DL_DataDelete Functions for the DL SPI: DL_DataDelete 3 DL_DataModify NAME DL_DataModify, CSSM_DL_DataModify - Modify persistent data record (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DL_DataModify (CSSM_DL_DB_HANDLE DLDBHandle, CSSM_DB_RECORDTYPE RecordType, CSSM_DB_UNIQUE_RECORD_PTR UniqueRecordIdentifier, const CSSM_DB_RECORD_ATTRIBUTE_DATA *AttributesToBeModified, const CSSM_DATA *DataToBeModified, CSSM_DB_MODIFY_MODE ModifyMode) SPI: CSSM_RETURN CSSMDLI DL_DataModify (CSSM_DL_DB_HANDLE DLDBHandle, CSSM_DB_RECORDTYPE RecordType, CSSM_DB_UNIQUE_RECORD_PTR UniqueRecordIdentifier, const CSSM_DB_RECORD_ATTRIBUTE_DATA *AttributesToBeModified, const CSSM_DATA *DataToBeModified, CSSM_DB_MODIFY_MODE ModifyMode) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS DLDBHandle (input) The handle pair that describes the add-in data storage library module to be used to perform this function and the open data store to search for records satisfying the query. RecordType (input) Indicates the type of data record being modified. UniqueRecordIdentifier (input/output) A pointer to a CSSM_DB_UNIQUE_RECORD containing a unique identifier associated with the record to modify. If the modification succeeds, the UniqueRecordIdentifier points to a CSSM_DB_UNIQUE_RECORD containing a unique identifier associated with the updated record. If the modification fails, the UniqueRecordIdentifier is not modified. AttributesToBeModified (input/optional) A list of structures containing the attribute values to be stored in that attribute and the meta information (schema) describing those attributes. The list contains at most one entry per attribute in the specified record type. The specified AttributeFormat for each attribute must match that of the database schema, otherwise the error CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT is returned. If an attribute is of type CSSM_DB_ATTRIBUTE_FORMAT_STRING and the value specified for that string includes a null-terminator, then the length count in the CSSM_DATA structure containing the input string should include the terminating character. (If null-terminators are used, they should be used consistently when storing, searching, and retrieving the string value, otherwise selection predicates will not locate expected matches.) Each attribute specified is modified according to the value of ModifyMode (see table in the DESCRIPTION section of this definition). Those attributes that are not specified as part of this parameter remain unchanged. If the AttributesToBeModified parameter is NULL, no attribute modification occurs. DataToBeModified (input/optional) A pointer to the CSSM_DATA structure which contains the opaque data object to be stored in the data record. If this parameter is NULL, no Data modification occurs. ModifyMode (input) A CSSM_DB_MODIFY_MODE value indicating the type of modification to be performed on the record attributes identified by AttributesToBeModified. If no attributes are specified, then this value must be CSSM_DB_MODIFY_ATTRIBUTE_NONE. DESCRIPTION This function modifies the persistent data record identified by the UniqueRecordIdentifier. The modifications are specified by the Attributes and Data parameters. The ModifyMode indicates how the attributes are to be updated. The ModifyMode has no affect on updating the data blob contained in the record. If the data blob is the only record attribute being updated by this function call, then the modification mode must be 0. The current modification modes behave as follows: ModifyMode Value Function Behavior ---------------- ----------------- CSSM_DB_MODIFY_ATTRIBUTE_NONE No Attributes are being updated. CSSM_DB_MODIFY_ATTRIBUTE_ADD The specified values are added to the set of current values for each attribute. If 0 values are specified then the error CSSMERR_DL_INVALID_MODIFY_MODE is returned. If a DL does not support multiple values per attribute, the error CSSMERR_DL_MULTIPLE_VALUES_ UNSUPPORTED is returned. CSSM_DB_MODIFY_ATTRIBUTE_DELETE The specified values are removed from the set of current values for each attribute. If 0 values are specified then all values are deleted or the attributes value is replaced with the default for this attribute. If a DL does not support multiple values per attribute, the error CSSMERR_DL_MULTIPLE_VALUES_ UNSUPPORTED is returned. CSSM_DB_MODIFY_ATTRIBUTE_REPLACE The values for each attribute are replaced with the specified set of values for each attribute. If no values are specified then all values are deleted or the attributes value is replaced with the default for this attribute. If a DL does not support multiple values per attribute, the error CSSMERR_DL_MULTIPLE_VALUES_UNSUPPORTED is returned when more than 1 value is specified. If the attribute lists specifies an attribute that is not defined in the database's meta-information, an error condition is returned. For each attribute-value pair, the value replaces the corresponding attribute value in the record. If a data value is specified, the record's data value is replaced with the specified value. A record's data value or attribute values can be set to NULL or zero to represent deletion or the lack of a known value. If the record referenced by UniqueRecordIdentifier has been modified since the last time it was updated, the error CSSMERR_DL_STALE_UNIQUE_RECORD is returned and no modification takes place. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT CSSMERR_DL_INVALID_DB_HANDLE CSSMERR_DL_INVALID_FIELD_NAME CSSMERR_DL_INVALID_MODIFY_MODE CSSMERR_DL_INVALID_RECORDTYPE CSSMERR_DL_INVALID_RECORD_UID CSSMERR_DL_INVALID_UNIQUE_INDEX_DATA CSSMERR_DL_INVALID_VALUE CSSMERR_DL_MULTIPLE_VALUES_UNSUPPORTED CSSMERR_DL_STALE_UNIQUE_RECORD SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DL_DataInsert CSSM_DL_DataDelete Functions for the DL SPI: DL_DataInsert DL_DataDelete 3 DL_DbClose NAME DL_DbClose, CSSM_DL_DbClose - Close open data store (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DL_DbClose (CSSM_DL_DB_HANDLE DLDBHandle) SPI: CSSM_RETURN CSSMDLI DL_DbClose (CSSM_DL_DB_HANDLE DLDBHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS DLDBHandle (input) A handle structure containing the DL handle for the attached DL module and the DB handle for an open data store managed by the DL. This specifies the open data store to be closed. DESCRIPTION This function closes an open data store. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_DL_INVALID_DB_HANDLE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DL_DbOpen Functions for the DL SPI: DL_DbOpen 3 DL_DbCreate NAME DL_DbCreate, CSSM_DL_DbCreate - Create and open new data store (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DL_DbCreate (CSSM_DL_HANDLE DLHandle, const char *DbName, const CSSM_NET_ADDRESS *DbLocation, const CSSM_DBINFO *DBInfo, CSSM_DB_ACCESS_TYPE AccessRequest, const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, const void *OpenParameters, CSSM_DB_HANDLE *DbHandle) SPI: CSSM_RETURN CSSMDLI DL_DbCreate (CSSM_DL_HANDLE DLHandle, const char *DbName, const CSSM_NET_ADDRESS *DbLocation, const CSSM_DBINFO *DBInfo, CSSM_DB_ACCESS_TYPE AccessRequest, const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, const void *OpenParameters, CSSM_DB_HANDLE *DbHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS DLHandle (input) The handle that describes the add-in data storage library module used to perform this function. DbName (input) The logical name for the new data store. DbLocation (input/optional) A pointer to a network address directly or indirectly identifying the location of the storage service process. If the input is NULL, the module can assume a default storage service process location. If the DbName does not distinguish the storage service process, the service cannot be performed and the operation fails. DBInfo (input) A pointer to a structure describing the format/schema of each record type that will be stored in the new data store. AccessRequest (input) An indicator of the requested access mode for the data store, such as read-only or read-write. CredAndAclEntry (input/optional) A structure containing one or more credentials authorized for creating a data base 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 DL to acquire the credentials and/or the ACL entry interactively. If the DL provides public access for creating a data base, then the credentials can be NULL. If the DL defines a default initial ACL entry for the new data base, then the ACL entry prototype can be an empty list. OpenParameters (input/optional) A pointer to a module-specific set of parameters required to open the data store. DbHandle (output) The handle to the newly created and open data store. The value will be set to CSSM_INVALID_HANDLE if the function fails. DESCRIPTION This function creates and opens a new data store. The name of the new data store is specified by the input parameter DbName. The record schema for the data store is specified in the DBINFO structure. If any RecordType defined in the DBINFO structure does not have an associated parsing module, then the ModuleSubserviceUid specified for that record type must be zero. The newly created data store is opened under the specified access mode. If user authentication credentials are required, they must be provided. Also, additional open parameters may be required and are supplied in OpenParameters. If user authentication credentials are required, they must be provided. 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. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_DL_DATASTORE_ALREADY_EXISTS CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT CSSMERR_DL_INVALID_ACCESS_REQUEST CSSMERR_DL_INVALID_DB_LOCATION CSSMERR_DL_INVALID_DB_NAME CSSMERR_DL_INVALID_FIELD_NAME CSSMERR_DL_INVALID_OPEN_PARAMETERS CSSMERR_DL_INVALID_PARSING_MODULE CSSMERR_DL_INVALID_RECORDTYPE CSSMERR_DL_INVALID_RECORD_INDEX CSSMERR_DL_UNSUPPORTED_FIELD_FORMAT CSSMERR_DL_UNSUPPORTED_INDEX_INFO CSSMERR_DL_UNSUPPORTED_LOCALITY CSSMERR_DL_UNSUPPORTED_NUM_ATTRIBUTES CSSMERR_DL_UNSUPPORTED_NUM_INDEXES CSSMERR_DL_UNSUPPORTED_NUM_RECORDTYPES CSSMERR_DL_UNSUPPORTED_RECORDTYPE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DL_DbOpen CSSM_DL_DbClose CSSM_DL_DbDelete Functions for the DL SPI: DL_DbOpen DL_DbClose DL_DbDelete 3 DL_DbDelete NAME DL_DbDelete, CSSM_DL_DbDelete - Delete all records (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DL_DbDelete (CSSM_DL_HANDLE DLHandle, const char *DbName, const CSSM_NET_ADDRESS *DbLocation, const CSSM_ACCESS_CREDENTIALS *AccessCred) SPI: CSSM_RETURN CSSMDLI DL_DbDelete (CSSM_DL_HANDLE DLHandle, const char *DbName, const CSSM_NET_ADDRESS *DbLocation, const CSSM_ACCESS_CREDENTIALS *AccessCred) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS DLHandle (input) The handle that describes the add-in data storage library module to be used to perform this function. DbName (input) A pointer to the string containing the logical name of the data store. DbLocation (input/optional) A pointer to a network address directly or indirectly identifying the location of the storage service process. If the input is NULL, the module can assume a default storage service process location. If the DbName does not distinguish the storage service process, the service cannot be performed and the operation fails. AccessCred (input/optional) A pointer to the set of one or more credentials being presented for authentication by the caller. These credentials are required to obtain access to the specified data store. The credentials structure can contain multiple types of credentials, as required for multi-factor authentication. The credential data can be an immediate value, such as a passphrase, PIN, certificate, or template of user-specific data, or the caller can specify a callback function the DL can use to obtain one or more credentials. The required set of credentials to access a particular data store is defined by the DbInfo record containing meta-data for the specified data store. If credentials are not required to access the specified data store, then this field can be NULL. DESCRIPTION This function deletes all records from the specified data store and removes all state information associated with that data store. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_DL_DATASTORE_DOESNOT_EXIST CSSMERR_DL_DATASTORE_IS_OPEN CSSMERR_DL_INVALID_DB_LOCATION CSSMERR_DL_INVALID_DB_NAME SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DL_DbCreate CSSM_DL_DbOpen CSSM_DL_DbClose Functions for the DL SPI: DL_DbCreate DL_DbOpen DL_DbClose 3 DL_DbOpen NAME DL_DbOpen, CSSM_DL_DbOpen - Open a data store (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DL_DbOpen (CSSM_DL_HANDLE DLHandle, const char *DbName, const CSSM_NET_ADDRESS *DbLocation, CSSM_DB_ACCESS_TYPE AccessRequest, const CSSM_ACCESS_CREDENTIALS *AccessCred, const void *OpenParameters, CSSM_DB_HANDLE *DbHandle) SPI: CSSM_RETURN CSSMDLI DL_DbOpen (CSSM_DL_HANDLE DLHandle, const char *DbName, const CSSM_NET_ADDRESS *DbLocation, CSSM_DB_ACCESS_TYPE AccessRequest, const CSSM_ACCESS_CREDENTIALS *AccessCred, const void *OpenParameters, CSSM_DB_HANDLE *DbHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS DLHandle (input) The handle that describes the add-in data storage library module to be used to perform this function. DbName (input) A pointer to the string containing the logical name of the data store. DbLocation (input/optional) A pointer to a network address directly or indirectly identifying the location of the storage service process. If the input is NULL, the module can determine a storage service process and its location based on the DbName (for existing data stores) or can assume a default storage service process location. If the DbName does not distinguish the storage service process, the service cannot be performed and the operation fails. AccessRequest (input) An indicator of the requested access mode for the data store, such as read-only or read-write. AccessCred (input/optional) A pointer to the set of one or more credentials being presented for authentication by the caller. These credentials are required to obtain access to the specified data store. The credentials structure can contain multiple types of credentials, as required for multi-factor authentication. The credential data can be an immediate value, such as a passphrase, PIN, certificate, or template of user-specific data, or the caller can specify a callback function the DL can use to obtain one or more credentials. The required set of credentials to access a particular data store is defined by the DbInfo record containing meta-data for the specified data store. If credentials are not required to access the specified data store, then this field can be NULL. OpenParameters (input/optional) A pointer to a module-specific set of parameters required to open the data store. DbHandle (output) The handle to the opened data store. The value will be set to CSSM_INVALID_HANDLE if the function fails. DESCRIPTION This function opens the data store with the specified logical name under the specified access mode. If user authentication credentials are required, they must be provided. Also, additional open parameters may be required to open a given data store, and are supplied in the OpenParameters. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_DL_DB_LOCKED CSSMERR_DL_INVALID_ACCESS_REQUEST CSSMERR_DL_INVALID_DB_LOCATION CSSMERR_DL_INVALID_DB_NAME CSSMERR_DL_DATASTORE_DOESNOT_EXIST CSSMERR_DL_INVALID_PARSING_MODULE CSSMERR_DL_INVALID_OPEN_PARAMETERS SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DL_DbClose Functions for the DL SPI: DL_DbClose 3 DL_DestroyRelation NAME DL_DestroyRelation, CSSM_DL_DestroyRelation - Destroy an existing relation (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DL_DestroyRelation (CSSM_DL_DB_HANDLE DLDBHandle, CSSM_DB_RECORDTYPE RelationID) SPI: CSSM_RETURN CSSMDLI DL_DestroyRelation (CSSM_DL_DB_HANDLE DLDBHandle, CSSM_DB_RECORDTYPE RelationID) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS DLDBHandle (input) The handle pair that describes the add-in data storage library module to be used to perform this function and the open data store from which to delete the relation record. RelationID (input) Indicates the type of relation record being deleted from the data store. DESCRIPTION This function destroys an existing relation of the specified type by removing its entry from the specified data store. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_DL_INVALID_DB_HANDLE CSSMERR_DL_INVALID_RECORDTYPE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DL_CreateRelation Functions for the DL SPI: DL_CreateRelation 3 DL_FreeNameList NAME DL_FreeNameList, CSSM_DL_FreeNameList - Free the list of the logical data store names (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DL_FreeNameList (CSSM_DL_HANDLE DLHandle, CSSM_NAME_LIST_PTR NameList) SPI: CSSM_RETURN CSSMDLI DL_FreeNameList (CSSM_DL_HANDLE DLHandle, CSSM_NAME_LIST_PTR NameList) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS DLHandle (input) The handle that describes the add-in data storage library module to be used to perform this function. NameList (input) A pointer to the CSSM_NAME_LIST. DESCRIPTION This function frees the list of the logical data store names that was returned by CSSM_DL_GetDbNames. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DL_GetDbNames Functions for the DL SPI: DL_GetDbNames 3 DL_FreeUniqueRecord NAME DL_FreeUniqueRecord, CSSM_DL_FreeUniqueRecord - Free data store memory (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DL_FreeUniqueRecord (CSSM_DL_DB_HANDLE DLDBHandle, CSSM_DB_UNIQUE_RECORD_PTR UniqueRecord) SPI: CSSM_RETURN CSSMDLI DL_FreeUniqueRecord (CSSM_DL_DB_HANDLE DLDBHandle, CSSM_DB_UNIQUE_RECORD_PTR UniqueRecord) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS DLDBHandle (input) The handle pair that describes the add-in data storage library module to be used to perform this function and the open data store from which the UniqueRecord identifier was assigned. UniqueRecord(input) The pointer to the memory that describes the data store unique record structure. DESCRIPTION This function frees the memory associated with the data store unique record 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_DL_INVALID_DB_HANDLE CSSMERR_DL_INVALID_RECORD_UID SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DL_DataInsert CSSM_DL_DataGetFirst CSSM_DL_DataGetNext Functions for the DL SPI: DL_DataInsert DL_DataGetFirst DL_DataGetNext 3 DL_GetDbAcl NAME DL_GetDbAcl, CSSM_DL_GetDbAcl - Get ACL description (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DL_GetDbAcl (CSSM_DL_DB_HANDLE DLDBHandle, const CSSM_STRING *SelectionTag, uint32 *NumberOfAclInfos, CSSM_ACL_ENTRY_INFO_PTR *AclInfos) SPI: CSSM_RETURN CSSMDLI DL_GetDbAcl (CSSM_DL_DB_HANDLE DLDBHandle, const CSSM_STRING *SelectionTag, uint32 *NumberOfAclInfos, CSSM_ACL_ENTRY_INFO_PTR *AclInfos) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS DLDBHandle (input) The handle pair that identifies the Data Storage service provider to perform this operation and the target data store 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 data base. To retrieve a description of all ACL entries for the target data base, 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 each structure can be used during the current attach session to reference the ACL entry 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. DESCRIPTION This function returns a description of zero or more ACL entries managed by the data storage service provider module and associated with the target database identified by DLDBHandle.DBHandle. 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 target data base 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. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_DL_INVALID_DB_HANDLE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DL_ChangeDbAcl Functions for the DL SPI: DL_ChangeDbAcl 3 DL_GetDbNameFromHandle NAME DL_GetDbNameFromHandle, CSSM_DL_GetDbNameFromHandle - Get data source name (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DL_GetDbNameFromHandle (CSSM_DL_DB_HANDLE DLDBHandle, char **DbName) SPI: CSSM_RETURN CSSMDLI DL_GetDbNameFromHandle (CSSM_DL_DB_HANDLE DLDBHandle, char **DbName) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS DLDBHandle (input) The handle pair that identifies the add-in data storage library module and the open data store whose name should be retrieved. DbName (output) Returns a zero terminated string which contains a data store name. The memory is allocated by the service provider and must be deallocated by the application. DESCRIPTION This function retrieves the data source name corresponding to an opened data store handle. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. ERRORS Errors are described in the CDSA technical standard. See CDSA. CSSMERR_DL_INVALID_DB_HANDLE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DL_GetDbNames Functions for the DL SPI: DL_GetDbNames 3 DL_GetDbNames NAME DL_GetDbNames, CSSM_DL_GetDbNames - Get list of logical data store names (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DL_GetDbNames (CSSM_DL_HANDLE DLHandle, CSSM_NAME_LIST_PTR *NameList) SPI: CSSM_RETURN CSSMDLI DL_GetDbNames (CSSM_DL_HANDLE DLHandle, CSSM_NAME_LIST_PTR *NameList) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS DLHandle (input) The handle that describes the add-in data storage library module to be used to perform this function. NameList (output) Returns a list of data store names in a CSSM_NAME_LIST_PTR structure. DESCRIPTION This function returns the list of logical data store names for all data stores that are known by and accessible to the specified DL module. This list also includes the number of data store names in the return list. The CSSM_DL_FreeNameList() function must be called to de-allocate memory containing the list. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DL_GetDbNameFromHandle CSSM_DL_FreeNameList Functions for the DL SPI: DL_GetDbNameFromHandle DL_FreeNameList 3 DL_GetDbOwner NAME DL_GetDbOwner, CSSM_DL_GetDbOwner - Get data base owner (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DL_GetDbOwner (CSSM_DL_DB_HANDLE DLDBHandle, CSSM_ACL_OWNER_PROTOTYPE_PTR Owner) SPI: CSSM_RETURN CSSMDLI DL_GetDbOwner (CSSM_DL_DB_HANDLE DLDBHandle, CSSM_ACL_OWNER_PROTOTYPE_PTR Owner) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETER DLDBHandle (input) The handle pair that describes the data storage library module to be used to perform this function, and the open data store whose associated Owner is to be retrieved. Owner (output) A CSSM_ACL_OWNER_PROTOTYPE describing the current Owner of the Data Base. DESCRIPTION This function returns a CSSM_ACL_OWNER_PROTOTYPE describing the current Owner of the Data Base. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_DL_INVALID_DB_HANDLE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DL_ChangeDbOwner Functions for the DL SPI: DL_ChangeDbOwner 3 DL_PassThrough NAME DL_PassThrough, CSSM_DL_PassThrough - Extend data storage module functionality (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DL_PassThrough (CSSM_DL_DB_HANDLE DLDBHandle, uint32 PassThroughId, const void *InputParams, void **OutputParam) SPI: CSSM_RETURN CSSMDLI DL_PassThrough (CSSM_DL_DB_HANDLE DLDBHandle, uint32 PassThroughId, const void *InputParams, void **OutputParam) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS DLDBHandle (input) The handle pair that describes the add-in data storage library module to be used to perform this function and the open data store upon which the function is to be performed. PassThroughId (input) An identifier assigned by a DL module to indicate the exported function to be performed. InputParams (input) A pointer to a module implementation-specific structure containing parameters to be interpreted in a function- specific manner by the requested DL module. OutputParams (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. DESCRIPTION This function allows applications to call data storage library module-specific operations that have been exported. Such operations may include queries or services that are specific to the domain represented by a DL module. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_DL_INVALID_DB_HANDLE CSSMERR_DL_INVALID_PASSTHROUGH_ID SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 DecryptData NAME DecryptData, CSSM_DecryptData, CSP_DecryptData - Decrypt buffer data (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DecryptData (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *CipherBufs, uint32 CipherBufCount, CSSM_DATA_PTR ClearBufs, uint32 ClearBufCount, uint32 *bytesDecrypted, CSSM_DATA_PTR RemData) SPI: CSSM_RETURN CSSMCSPI CSP_DecryptData (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context, const CSSM_DATA *CipherBufs, uint32 CipherBufCount, CSSM_DATA_PTR ClearBufs, uint32 ClearBufCount, uint32 *bytesDecrypted, CSSM_DATA_PTR RemData, CSSM_PRIVILEGE Privilege) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. CipherBufs (input) A pointer to a vector of CSSM_DATA structures that contain the data to be decrypted. CipherBufCount (input) The number of CipherBufs. ClearBufs (output) A pointer to a vector of CSSM_DATA structures that contain the decrypted data resulting from the decryption operation. ClearBufCount (input) The number of ClearBufs. bytesDecrypted (output) A pointer to uint32 for the size of the decrypted data in bytes. RemData (output) A pointer to the CSSM_DATA structure for the remaining plain text if there is not enough buffer space available in the output data structures. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform calls to CSSM for the memory functions managed by CSSM. Context (input) A 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. DESCRIPTION This function decrypts all data contained in the set of input buffers using information in the context. The CSSM_QuerySize() (CSSM API), or CSP_QuerySize() (CSP SPI), function can be used to estimate the output buffer size required. The minimum number of buffers required to contain the resulting plain text is produced as output. If the plain text result does not fit within the set of output buffers, the remaining plain text is returned in the single output buffer RemData. The CSP can require that the cryptographic context include access credentials for authentication and authorization checks when using a private key or a secret key. NOTES FOR API The output is returned to the caller either by filling the caller- specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, pre-allocated output buffer, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value greater than zero and a non-NULL data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value equal to zero and a NULL data pointer field value. The application is always responsible for deallocating the memory when it is no longer needed. In-place decryption can be done by supplying the same input and output buffers. NOTES FOR SPI The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_BLOCK_SIZE_MISMATCH CSSMERR_CSP_OUTPUT_LENGTH_ERROR SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_QuerySize CSSM_EncryptData CSSM_DecryptDataInit CSSM_DecryptDataUpdate CSSM_DecryptDataFinal CSSM_DecryptP CSSM_DecryptDataInitP Functions for the CSP SPI: CSP_QuerySize CSP_EncryptData CSP_DecryptDataInit CSP_DecryptDataUpdate CSP_DecryptDataFinal 3 DecryptDataFinal NAME DecryptDataFinal, CSSM_DecryptDataFinal, CSP_DecryptDataFinal - Finalize staged decryption process (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DecryptDataFinal (CSSM_CC_HANDLE CCHandle, CSSM_DATA_PTR RemData) SPI: CSSM_RETURN CSSMCSPI CSP_DecryptDataFinal (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, CSSM_DATA_PTR RemData) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. RemData (output) A pointer to the CSSM_DATA structure for the last decrypted block, if necessary. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform calls to CSSM for the memory functions managed by CSSM. 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. NOTES FOR API The output is returned to the caller either by filling the caller- specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, pre-allocated output buffer, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value greater than zero and a non-NULL data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value equal to zero and a NULL data pointer field value. The application is always responsible for deallocating the memory when it is no longer needed. NOTES FOR SPI The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_BLOCK_SIZE_MISMATCH CSSMERR_CSP_OUTPUT_LENGTH_ERROR SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DecryptData CSSM_DecryptDataInit CSSM_DecryptDataUpdate Functions for the CSP SPI: CSP_DecryptData CSP_DecryptDataInit CSP_DecryptDataUpdate 3 DecryptDataInit NAME DecryptDataInit, CSSM_DecryptDataInit, CSP_DecryptDataInit - Initialize the staged decrypt function(CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DecryptDataInit (CSSM_CC_HANDLE CCHandle) SPI: CSSM_RETURN CSSMCSPI CSSM_CSP_DecryptDataInit (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context, CSSM_PRIVILEGE Privilege) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform calls to CSSM for the memory functions managed by CSSM. Context (input) Pointer to CSSM_CONTEXT structure that describes the attributes with this context. Privilege (input) The export privilege to be applied during the cryptographic operation. This parameter is forwarded to the CSP after CSSM verifies the caller and service provider privilege set includes the specified PRIVILEGE. 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. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DecryptData CSSM_DecryptDataUpdate CSSM_DecryptDataFinal CSSM_DecryptDataP CSSM_DecryptDataInitP Functions for the CSP SPI: CSP_DecryptData CSP_DecryptDataUpdate CSP_DecryptDataFinal 3 DecryptDataInitP NAME DecryptDataInitP - Intialize the staged decrypt function with privilege (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_DecryptDataInitP (CSSM_CC_HANDLE CCHandle, CSSM_PRIVILEGE Privilege) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS Privilege (input) The privilege to be applied during the cryptographic operation. See CSSM_DecryptDataInit() for other parameters. DESCRIPTION This function is similar to CSSM_DecryptDataInit(). It also accepts a USEE tag as a privilege request parameter. CSSM checks that either its own privilege set or the application's privilege set (if the application is signed) includes the tag. If the tag is found and the service provider privilege set indicates that it is supported, the tag is forwarded to the service provider. For staged operations using privilege initialization functions CSSM_DecryptDataInitP(), the completion functions CSSM_DecryptDataUpdate() and CSSM_DecryptDataFinalize() are used. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_DecryptData CSSM_EncryptDataInit CSSM_EncryptDataUpdate CSSM_EncryptDataFinal CSSM_EncryptDataP CSSM_EncryptDataInitP CSSM_DecryptP CSSM_DecryptDataInitP CSSM_QuerySize 3 DecryptDataP NAME DecryptDataP - Decrypt data with privilege (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_DecryptDataP (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *CipherBufs, uint32 CipherBufCount, CSSM_DATA_PTR ClearBufs, uint32 ClearBufCount, uint32 *bytesDecrypted, CSSM_DATA_PTR RemData, CSSM_PRIVILEGE Privilege) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS Privilege (input) The privilege to be applied during the cryptographic operation. See CSSM_DecryptData() for other parameters. DESCRIPTION This function is similar to CSSM_DecryptData(). It also accepts a USEE tag as a privilege request parameter. CSSM checks that either its privilege set or the application's privilege set (if the application is signed) includes the tag. If the tag is found and the service provider privilege set indicates that it is supported, the tag is forwarded to the service provider. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_BLOCK_SIZE_MISMATCH CSSMERR_CSP_OUTPUT_LENGTH_ERROR SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_DecryptData CSSM_EncryptDataInit CSSM_EncryptDataUpdate CSSM_EncryptDataFinal CSSM_EncryptDataP CSSM_EncryptDataInitP CSSM_DecryptP CSSM_DecryptDataInitP CSSM_QuerySize 3 DecryptDataUpdate NAME DecryptDataUpdate, CSSM_DecryptDataUpdate, CSP_DecryptDataUpdate - Continue the staged decryption process (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DecryptDataUpdate (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *CipherBufs, uint32 CipherBufCount, CSSM_DATA_PTR ClearBufs, uint32 ClearBufCount, uint32 *bytesDecrypted) SPI: CSSM_RETURN CSSMCSPI CSP_DecryptDataUpdate (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *CipherBufs, uint32 CipherBufCount, CSSM_DATA_PTR ClearBufs, uint32 ClearBufCount, uint32 *bytesDecrypted) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. CipherBufs (input) A pointer to a vector of CSSM_DATA structures that contain the data to be operated on. CipherBufCount (input) The number of CipherBufs. ClearBufs (output) A pointer to a vector of CSSM_DATA structures that contain the decrypted data resulting from the decryption operation. ClearBufCount (input) The number of ClearBufs. bytesDecrypted (output) A pointer to uint32 for the size of the decrypted data in bytes. SPI PARAMETER CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform calls to CSSM for the memory functions managed by CSSM. DESCRIPTION This function continues the staged decryption process over all data in the set of input buffers. There can be algorithm-specific and token-specific rules restricting the lengths of data in CSSM_DecryptUpdate() calls, but multiple input buffers are supported. The minimum number of buffers required to contain the resulting plain text is produced as output. Excess output buffer space is not remembered across staged decryption calls. Each staged call begins filling one or more new output buffers. The CSSM_QuerySize() (CSSM API), or CSP_QuerySize() (CSP SPI), function can be used to estimate the output buffer size required for each update call. NOTES FOR API The output is returned to the caller either by filling the caller- specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, preallocated output buffer, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value greater than zero and a non-NULL data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value equal to zero and a NULL data pointer field value. The application is always responsible for deallocating the memory when it is no longer needed. In-place decryption can be done by supplying the same input and output buffers. NOTES FOR SPI The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_QuerySize CSSM_DecryptData CSSM_DecryptDataInit CSSM_DecryptDataFinal Functions for the CSP SPI: CSP_QuerySize CSP_DecryptData CSP_DecryptDataInit CSP_DecryptDataFinal 3 DeregisterDispatchTable NAME DeregisterDispatchTable - Invalidate CSSM pointers to EMM (CDSA) SYNOPSIS # include (void) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS None. DESCRIPTION This EMM-defined function is invoked by CSSM once for each CSSM_ModuleDetach() operation issued against a service provider of the type managed by the EMM. CSSM uses this function to inform the EMM that the set of CSSM function pointers provided to the EMM when the session was attached are no longer valid. 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 Errors are described in the CDSA technical standard. See CDSA. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: RegisterDispatchTable 3 DeriveKey NAME DeriveKey, CSSM_DeriveKey, CSP_DeriveKey - Derive new symmetric key (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DeriveKey (CSSM_CC_HANDLE CCHandle, CSSM_DATA_PTR Param, uint32 KeyUsage, uint32 KeyAttr, const CSSM_DATA *KeyLabel, const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, CSSM_KEY_PTR DerivedKey) SPI: CSSM_RETURN CSSMCSPI CSP_DeriveKey (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context, CSSM_DATA_PTR Param, uint32 KeyUsage, uint32 KeyAttr, const CSSM_DATA *KeyLabel, const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, CSSM_KEY_PTR DerivedKey) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation. Param (input/output) This parameter varies depending on the derivation algorithm. Password based derivation algorithms use this parameter to return a cipher block chaining initialization vector. Concatenation algorithms use this parameter to get the second item to concatenate. KeyUsage (input) A bit mask indicating all permitted uses for the new derived key. KeyAttr (input) A bit mask defining other attribute values for the new derived key. KeyLabel (input/optional) Pointer to a byte string that will be used as the label for the derived key. CredAndAclEntry (input/optional) A structure containing one or more credentials authorized for creating a key and the prototype ACL entry that will control future use of the newly created key. The credentials and ACL entry prototype can be presented as immediate values or callback functions can be provided for use by the CSP to acquire the credentials and/or the subject of the ACL entry interactively. If the CSP provides public access for creating a key, then the credentials can be NULL. If the CSP defines a default initial ACL entry for the new key, then the ACL entry prototype can be empty. DerivedKey (output) A pointer to a CSSM_KEY structure that returns the derived key. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM. Context (input) Pointer to CSSM_CONTEXT structure that describes the attributes with this context. DESCRIPTION This function derives a new symmetric key using the context and/or information from the base key in the context. The CSP can require that the cryptographic context include access credentials for authentication and authorization checks when using a private key or a secret key. Authorization policy can restrict the set of callers who can create a new resource. In this case, the caller must present a set of access credentials for authorization. Upon successfully authenticating the credentials, the template that verified the presented samples identifies the ACL entry that will be used in the authorization computation. If the caller is authorized, the new resource is created. The caller must provide an initial ACL entry to be associated with the newly created resource. This entry is used to control future access to the new resource and (since the subject is deemed to be the "Owner") exercise control over its associated ACL. The caller can specify the following items for initializing an ACL entry: 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. 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. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS COMMENTS The KeyData field of the CSSM_KEY structure is allocated by the CSP. The application is required to free this memory using the CSSM_FreeKey() (CSSM API), or CSP_FreeKey() (CSP SPI) call, or with the memory functions registered for the CSPHandle. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_CSP_CreateDeriveKeyContext 3 DigestData NAME DigestData, CSSM_DigestData, CSP_DigestData - Compute message digest (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DigestData (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *DataBufs, uint32 DataBufCount, CSSM_DATA_PTR Digest) SPI: CSSM_RETURN CSSMCSPI CSP_DigestData (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context, const CSSM_DATA *DataBufs, uint32 DataBufCount, CSSM_DATA_PTR Digest) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. DataBufs (input) A pointer to a vector of CSSM_DATA structures that contain the data to be operated on. DataBufCount (input) The number of DataBufs. Digest (output) A pointer to the CSSM_DATA structure for the message digest. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM. Context (input) Pointer to CSSM_CONTEXT structure that describes the attributes with this context. DESCRIPTION This function computes a message digest for all data contained in the set of input buffers. NOTES FOR API The output is returned to the caller either by filling the caller- specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, preallocated output buffer, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value greater than zero and a non-NULL data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value equal to zero and a NULL data pointer field value. The application is always responsible for deallocating the memory when it is no longer needed. NOTES FOR SPI The output is returned to the caller as specifed in Buffer Management for Cryptographic Services. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_OUTPUT_LENGTH_ERROR SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DigestDataInit CSSM_DigestDataUpdate CSSM_DigestDataFinal CSSM_DigestDataClone Functions for the CSP SPI: CSP_DigestDataInit CSP_DigestDataUpdate CSP_DigestDataFinal CSP_DigestDataClone 3 DigestDataClone NAME DigestDataClone, CSSM_DigestDataClone, CSP_DigestDataClone - Clone a staged message digest (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DigestDataClone (CSSM_CC_HANDLE CCHandle, CSSM_CC_HANDLE *ClonednewCCHandle) SPI: CSSM_RETURN CSSMCSPI CSP_DigestDataClone (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, CSSM_CC_HANDLE ClonednewCCHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of a staged message digest operation. ClonednewCCHandle (output) The cloned digest context handle. The handle will be set to CSSM_INVALID_HANDLE if the function fails. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform calls to CSSM for the memory functions managed by CSSM. DESCRIPTION This function clones a given staged message digest context with its cryptographic attributes and intermediate result. NOTES When a digest context is cloned, a new context is created with data associated with the parent context. Changes made to the parent context after calling this function will not be reflected in the cloned context. The cloned context could be used with the CSSM_DigestDataUpdate() and CSSM_DigestDataFinal() functions. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DigestData CSSM_DigestDataInit CSSM_DigestDataUpdate CSSM_DigestDataFinal Functions for the CSP SPI: CSP_DigestData CSP_DigestDataInit CSP_DigestDataUpdate CSP_DigestDataFinal 3 DigestDataFinal NAME DigestDataFinal, CSSM_DigestDataFinal, CSP_DigestDataFinal - Finalize the staged message digest (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DigestDataFinal (CSSM_CC_HANDLE CCHandle, CSSM_DATA_PTR Digest) SPI: CSSM_RETURN CSSMCSPI CSP_DigestDataFinal (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, CSSM_DATA_PTR Digest) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. Digest (output) A pointer to the CSSM_DATA structure for the message digest. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM. DESCRIPTION This function finalizes the staged message digest function. NOTES FOR API The output is returned to the caller either by filling the caller- specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, preallocated output buffer, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value greater than zero and a non-NULL data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value equal to zero and a NULL data pointer field value. The application is always responsible for deallocating the memory when it is no longer needed. NOTES FOR SPI The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_OUTPUT_LENGTH_ERROR SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DigestData CSSM_DigestDataInit CSSM_DigestDataUpdate CSSM_DigestDataClone Functions for the CSP SPI: CSP_DigestData CSP_DigestDataInit CSP_DigestDataUpdate CSP_DigestDataClone 3 DigestDataInit NAME DigestDataInit, CSSM_DigestDataInit, CSP_DigestDataInit - Initialize the staged message digest (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DigestDataInit (CSSM_CC_HANDLE CCHandle) SPI: CSSM_RETURN CSSMCSPI CSP_DigestDataInit (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM. Context (input) Pointer to CSSM_CONTEXT structure that describes the attributes with this context. DESCRIPTION This function initializes the staged message digest 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DigestData CSSM_DigestDataUpdate CSSM_DigestDataClone CSSM_DigestDataFinal Functions for the CSP SPI: CSP_DigestData CSP_DigestDataUpdate CSP_DigestDataClone CSP_DigestDataFinal 3 DigestDataUpdate NAME DigestDataUpdate, CSSM_DigestDataUpdate - Continue the staged process of digesting (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_DigestDataUpdate (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *DataBufs, uint32 DataBufCount) SPI: CSSM_RETURN CSSMCSPI CSP_DigestDataUpdate (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *DataBufs, uint32 DataBufCount) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. DataBufs (input) A pointer to a vector of CSSM_DATA structures that contain the data to be operated on. DataBufCount (input) The number of DataBufs. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM. 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. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_DigestData CSSM_DigestDataInit CSSM_DigestDataClone CSSM_DigestDataFinal Functions for the CSP SPI: CSP_DigestData CSP_DigestDataInit CSP_DigestDataClone CSP_DigestDataFinal 3 EncryptData NAME EncryptData, CSSM_EncryptData, CSP_EncryptData - Encrypts all buffer data (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_EncryptData (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *ClearBufs, uint32 ClearBufCount, CSSM_DATA_PTR CipherBufs, uint32 CipherBufCount, uint32 *bytesEncrypted, CSSM_DATA_PTR RemData) SPI: CSSM_RETURN CSSMCSPI CSP_EncryptData (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context, const CSSM_DATA *ClearBufs, uint32 ClearBufCount, CSSM_DATA_PTR CipherBufs, uint32 CipherBufCount, uint32 *bytesEncrypted, CSSM_DATA_PTR RemData, CSSM_PRIVILEGE Privilege) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. ClearBufs (input) A pointer to a vector of CSSM_DATA structures that contain the data to be operated on. ClearBufCount (input) The number of ClearBufs. CipherBufs (output) A pointer to a vector of CSSM_DATA structures that contain the results of the operation on the data. CipherBufCount (input) The number of CipherBufs. bytesEncrypted (output) A pointer to uint32 for the size of the encrypted data in bytes. RemData (output) A pointer to the CSSM_DATA structure for the remaining cipher text if there is not enough buffer space available in the output data structures. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform calls to CSSM for the memory functions managed by CSSM. Context (input) Pointer to CSSM_CONTEXT structure that describes the attributes with this context. Privilege (input) The export privilege to be applied during the cryptographic operation. This parameter is forwarded to the CSP after CSSM verifies the caller and service provider privilege set includes the specified PRIVILEGE. 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. NOTES FOR API The output is returned to the caller either by filling the caller- specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, preallocated output buffer, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value greater than zero and a non-NULL data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value equal to zero and a NULL Data pointer field value. The application is always responsible for deallocating the memory when it is no longer needed. In-place encryption can be done by supplying the same input and output buffers. NOTES FOR SPI The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_BLOCK_SIZE_MISMATCH CSSMERR_CSP_OUTPUT_LENGTH_ERROR SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_QuerySize CSSM_DecryptData CSSM_EncryptDataInit CSSM_EncryptDataUpdate CSSM_EncryptDataFinal CSSM_EncryptDataP CSSM_EncryptDataInitP CSSM_DecryptP CSSM_DecryptDataInitP Functions for the CSP SPI: CSP_QuerySize CSP_DecryptData CSP_EncryptDataInit CSP_EncryptDataUpdate CSP_EncryptDataFinal 3 EncryptDataFinal NAME EncryptDataFinal, CSSM_EncryptDataFinal, CSP_EncryptDataFinal - Finalize staged encryption process (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_EncryptDataFinal (CSSM_CC_HANDLE CCHandle, CSSM_DATA_PTR RemData) SPI: CSSM_RETURN CSSMCSPI CSP_EncryptDataFinal (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, CSSM_DATA_PTR RemData) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. RemData (output) A pointer to the CSSM_DATA structure for the last encrypted block containing padded data, if necessary. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform calls to CSSM for the memory functions managed by CSSM. 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. NOTES FOR API The output is returned to the caller either by filling the caller- specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, preallocated output buffer, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value greater than zero and a non-NULL data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value equal to zero and a NULL data pointer field value. The application is always responsible for deallocating the memory when it is no longer needed. NOTES FOR SPI The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_BLOCK_SIZE_MISMATCH CSSMERR_CSP_OUTPUT_LENGTH_ERROR SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_QuerySize CSSM_DecryptData CSSM_EncryptDataInit CSSM_EncryptDataUpdate CSSM_EncryptDataFinal CSSM_EncryptDataP CSSM_EncryptDataInitP CSSM_DecryptP CSSM_DecryptDataInitP Functions for the CSP SPI: CSP_EncryptData CSP_EncryptDataInit CSP_EncryptDataUpdate 3 EncryptDataInit NAME EncryptDataInit, CSSM_EncryptDataInit, CSP_EncryptDataInit - Initialize the staged encrypt funciton (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_EncryptDataInit (CSSM_CC_HANDLE CCHandle) SPI: CSSM_RETURN CSSMCSPI CSP_EncryptDataInit (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context, CSSM_PRIVILEGE Privilege) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform calls to CSSM for the memory functions managed by CSSM. Context (input) Pointer to CSSM_CONTEXT structure that describes the attributes with this context. Privilege (input) The export privilege to be applied during the cryptographic operation. This parameter is forwarded to the CSP after CSSM verifies the caller and service provider privilege set includes the specified PRIVILEGE. DESCRIPTION This function initializes the staged encrypt function. There may be algorithm-specific and token-specific rules restricting the lengths of data following data update calls making use of these parameters. The CSP can require that the cryptographic context include access credentials for authentication and authorization checks when using a private key or a secret key. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_QuerySize CSSM_DecryptData CSSM_EncryptDataInit CSSM_EncryptDataUpdate CSSM_EncryptDataFinal CSSM_EncryptDataP CSSM_EncryptDataInitP CSSM_DecryptP CSSM_DecryptDataInitP Functions for the CSP SPI: CSP_QuerySize CSP_DecryptData CSP_EncryptDataInit CSP_EncryptDataUpdate CSP_EncryptDataFinal 3 EncryptDataInitP NAME EncryptDataInitP - Initialize the staged encrypt function with privilege (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_EncryptDataInitP (CSSM_CC_HANDLE CCHandle, CSSM_PRIVILEGE Privilege) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS Privilege (input) The privilege to be applied during the cryptographic operation. See CSSM_EncryptDataInit for other parameters. DESCRIPTION This function is similar to CSSM_EncryptDataInit(). It also accepts a USEE tag as a privilege request parameter. CSSM checks that either its privilege set or the application's privilege set (if the application is signed) includes the tag. If the tag is found and the service provider privilege set indicates that it is supported, the tag is forwarded to the service provider. For staged operations using privilege initialization functions CSSM_EncryptDataInitP(), the completion functions CSSM_EncryptDataUpdate() and CSSM_EncryptDataFinalize() are used. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_DecryptData CSSM_EncryptDataInit CSSM_EncryptDataUpdate CSSM_EncryptDataFinal CSSM_EncryptDataP CSSM_EncryptDataInitP CSSM_DecryptP CSSM_DecryptDataInitP CSSM_QuerySize 3 EncryptDataP NAME EncryptDataP - Encrypt data with privilege (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_EncryptDataP (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *ClearBufs, uint32 ClearBufCount, CSSM_DATA_PTR CipherBufs, uint32 CipherBufCount, uint32 *bytesEncrypted, CSSM_DATA_PTR RemData, CSSM_PRIVILEGE Privilege) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS Privilege (input) The privilege to be applied during the cryptographic operation. See CSSM_EncryptData for other parameters. DESCRIPTION This function is similar to CSSM_EncryptData(). It also accepts a USEE tag as a privilege request parameter. CSSM checks that either its own privilege set or the application's privilege set (if the application is signed) includes the tag. If the tag is found and the service provider privilege set indicates that it is supported, the tag is forwarded to the service provider. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_BLOCK_SIZE_MISMATCH CSSMERR_CSP_OUTPUT_LENGTH_ERROR SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_DecryptData CSSM_EncryptDataInit CSSM_EncryptDataUpdate CSSM_EncryptDataFinal CSSM_EncryptDataP CSSM_EncryptDataInitP CSSM_DecryptP CSSM_DecryptDataInitP CSSM_QuerySize 3 EncryptDataUpdate NAME EncryptDataUpdate, CSSM_EncryptDataUpdate, CSP_EncryptDataUpdate - Continue the staged encryption process (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_EncryptDataUpdate (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *ClearBufs, uint32 ClearBufCount, CSSM_DATA_PTR CipherBufs, uint32 CipherBufCount, uint32 *bytesEncrypted) SPI: CSSM_RETURN CSSMCSPI CSP_EncryptDataUpdate (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *ClearBufs, uint32 ClearBufCount, CSSM_DATA_PTR CipherBufs, uint32 CipherBufCount, uint32 *bytesEncrypted) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. ClearBufs (input) A pointer to a vector of CSSM_DATA structures that contain the data to be operated on. ClearBufCount (input) The number of ClearBufs. CipherBufs (output) A pointer to a vector of CSSM_DATA structures that contain the encrypted data resulting from the encryption operation. CipherBufCount (input) The number of CipherBufs. bytesEncrypted (output) A pointer to uint32 for the size of the encrypted data in bytes. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform calls to CSSM for the memory functions managed by CSSM. 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. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. NOTES FOR API The output is returned to the caller either by filling the caller- specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, preallocated output buffer, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value greater than zero and a non-NULL Data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value equal to zero and a NULL data pointer field value. The application is always responsible for deallocating the memory when it is no longer needed. In-place encryption can be done by supplying the same input and output buffers. NOTES FOR SPI The output is returned to the caller as specified in Buffer Management for Cryptographic Services. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_QuerySize CSSM_DecryptData CSSM_EncryptDataInit CSSM_EncryptDataUpdate CSSM_EncryptDataFinal CSSM_EncryptDataP CSSM_EncryptDataInitP CSSM_DecryptP CSSM_DecryptDataInitP Functions for the CSP SPI: CSP_QuerySize CSP_DecryptData CSP_EncryptDataInit CSP_EncryptDataFinal 3 EventNotifyManager NAME EventNotifyManager - Receive an event notification (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI EventNotifyManager (const CSSM_MANAGER_EVENT_NOTIFICATION *EventDescription) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS EventDescription A structure containing the following fields: DestinationModuleManagerType (input) The unique service mask identifying the destination module manager. SourceModuleManagerType (input) The unique service mask identifying the source module manager. Event (input) An identifier indicating the event that has or will take place. EventId (input/optional) A unique identifier associated with this event notification. It must be used in any reply notification that results from this event notification. EventData (input/optional) Arbitrary data (required or informational) for this event. DESCRIPTION This function receives an event notification from another module manager. The source manager is identified by its service mask. The specified event type is interpreted by the received and the appropriate actions must be taken in response. EventId and EventData are optional. The EventId is specified by the source module manager when a reply is expected. The destination module manager must use this identifier when replying to the event notification. The EventData is additional data or descriptive information provided to the destination manager. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSSM_MODULE_MANAGER_NOT_FOUND SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 FreeKey NAME FreeKey, CSSM_FreeKey, CSP_FreeKey - Clean up keys (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_FreeKey (CSSM_CSP_HANDLE CSPHandle, const CSSM_ACCESS_CREDENTIALS *AccessCred, CSSM_KEY_PTR KeyPtr, CSSM_BOOL Delete) SPI: CSSM_RETURN CSSMCSPI CSP_FreeKey (CSSM_CSP_HANDLE CSPHandle, const CSSM_ACCESS_CREDENTIALS *AccessCred, CSSM_KEY_PTR KeyPtr, CSSM_BOOL Delete) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CSPHandle (input) The handle that describes the module to perform this operation. AccessCred (input/optional) If the target key referenced by KeyPtr is protected and Delete has the value CSSM_TRUE, this parameter must contain the certificates and samples required to access the target key. The certificates must be presented as immediate values in the input structure. The samples can be immediate values, be obtained through a protected mechanism, or be obtained through a callback function. KeyPtr (input) The key whose associated keying material can be discarded at this time. Delete (input) If this value is CSSM_TRUE, the key data in the key structure will be removed and any internal storage related to that key will also be removed. In this case the key no longer exists in any form, unless previously wrapped out of the CSP by the application. If this value is CSSM_FALSE, then only the resources related to the key structure are released. The key may still be accessible by other means internally to the CSP. 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. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 GenerateAlgorithmParams NAME GenerateAlgorithmParams, CSSM_GenerateAlgorithmParams, CSP_GenerateAlgorithmParams - Generate algorithm parameters (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_GenerateAlgorithmParams (CSSM_CC_HANDLE CCHandle, uint32 ParamBits, CSSM_DATA_PTR Param) SPI: CSSM_RETURN CSSMCSPI CSP_GenerateAlgorithmParams (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context, uint32 ParamBits, CSSM_DATA_PTR Param, uint32 *NumberOfUpdatedAttributes, CSSM_CONTEXT_ATTRIBUTE_PTR *UpdatedAttributes) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. ParamBits (input) Used to generate parameters for the algorithm (for example, Diffie-Hellman). Param (output) Pointer to a CSSM_DATA structure used to provide information to the parameter generation process, or to receive information resulting from the generation process that is not required as a parameter to the algorithm. For instance, phase 2 of the KEA algorithm requires a private random value, rA, and a public version, Ra, to be generated. The private value, rA, is added to the context and the public value, Ra, is returned to the caller. In some cases, when both input and output is required, a data structure is passed to the algorithm. In this situation, Param->Data references the structure and Param->Length is set to the length of the structure. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM. Context (input) Pointer to CSSM_CONTEXT structure that describes the attributes with this context. Modifying this structure has no effect on the internal structure maintained by the CSSM. It is only a copy of the actual data. Changes to the context attributes must be returned using the UpdatedAttributes return parameter. NumberOfUpdatedAttributes (output) The number of CSSM_CONTEXT_ATTRIBUTE structures contained in the UpdatedAttributes array. If this value is zero, UpdatedAttributes should be set to NULL. UpdatedAttributes (output) An array of attributes that will be added to the context should be returned using this parameter. Memory for the attribute structures should be allocated using the CSSM_UPCALLS callbacks provided to the service provider module when CSSM_SPI_ModuleAttach() is called. DESCRIPTION This function generates algorithm parameters for the specified context. These parameters include Diffie-Hellman key agreement parameters and DSA key generation parameters. In most cases the algorithm parameters will be added directly to the cryptographic context (by returning an array of CSSM_CONTEXT_ATTRIBUTE structures), but an algorithm may return some data to the caller via the Param parameter. The generated parameters are added to the context as an attribute of type CSSM_ATTRIBUTE_ALG_PARAMS. Other attributes returned are added to the context, or replace existing values in the context. NOTES FOR API The output is returned to the caller either by filling the caller- specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, pre-allocated output buffer, the caller must provide an array of one or more CSSM_DATA structures each, containing a Length field value greater than zero and a non-NULL data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value equal to zero and a NULL data pointer field value. The application is always responsible for deallocating the memory when it is no longer needed. NOTES FOR SPI The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 GenerateKey NAME GenerateKey, CSSM_GenerateKey, CSP_GenerateKey - Generate a symmetric key (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_GenerateKey (CSSM_CC_HANDLE CCHandle, uint32 KeyUsage, uint32 KeyAttr, const CSSM_DATA *KeyLabel, const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, CSSM_KEY_PTR Key) SPI: CSSM_RETURN CSSMCSPI CSP_GenerateKey (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context, uint32 KeyUsage, uint32 KeyAttr, const CSSM_DATA *KeyLabel, const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, CSSM_KEY_PTR Key) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. KeyUsage (input) A bit mask indicating all permitted uses for the new key. KeyAttr (input) A bit mask defining attribute values for the new key. KeyLabel (input/optional) Pointer to a byte string that will be used as the label for the key. CredAndAclEntry (input/optional) A structure containing one or more credentials authorized for creating a key and the prototype ACL entry that will control future use of the newly created key. The credentials and ACL entry prototype can be presented as immediate values or callback functions can be provided for use by the CSP to acquire the credentials and/or the ACL entry interactively. If the CSP provides public access for creating a key, then the credentials can be NULL. If the CSP defines a default initial ACL entry for the new key, then the ACL entry prototype can be an empty list. Key (output) Pointer to CSSM_KEY structure used to hold the new key. The CSSM_KEY structure should be empty upon input to this function. The CSP will ignore any values residing in this structure at function invocation. Input values should be supplied in the cryptographic context, KeyUsage, KeyAttr, and KeyLabel input parameters. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform up-calls to CSSM for the memory functions managed by CSSM. Context (input) Pointer to CSSM_CONTEXT structure that describes the attributes with this context. Key (output) Pointer to CSSM_KEY structure used to obtain the key. Upon function invocation, any values in the CSSM_Key structure should be ignored. All input values should be supplied in the cryptographic Context, KeyUsage, KeyAttr, and KeyLabel input parameters. 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. NOTES The KeyData field of the CSSM_KEY structure is allocated by the CSP. The application is required to free this memory using the CSSM_FreeKey() (CSSM API), or CSP_FreeKey() (CSP SPI), function or with the memory functions registered for the CSPHandle. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_GenerateRandom CSSM_GenerateKeyPair Functions for the CSP SPI: CSP_GenerateRandom CSP_GenerateKeyPair 3 GenerateKeyP NAME GenerateKeyP - Generate a key with privilege (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_GenerateKeyP (CSSM_CC_HANDLE CCHandle, uint32 KeyUsage, uint32 KeyAttr, const CSSM_DATA *KeyLabel, const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, CSSM_KEY_PTR Key, CSSM_PRIVILEGE Privilege) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS Privilege (input) The privilege to be applied during the cryptographic operation. See CSSM_GenerateKey for other parameters. DESCRIPTION This function is similar to the CSSM_GenerateKey() function. It also accepts a USEE tag as a privilege request parameter. CSSM checks that either its own privilege set or the application's privilege set (if the application is signed) includes the tag. If the tag is found and the service provider privilege set indicates that it is supported, the tag is forwarded to the service provider. 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 Errors are described in the CDSA technical standard. See CDSA. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_GenerateKeyPairP CSSM_GenerateRandom 3 GenerateKeyPair NAME GenerateKeyPair, CSSM_GenerateKeyPair, CSP_GenerateKeyPair - Generate an asymmetric key pair (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_GenerateKeyPair (CSSM_CC_HANDLE CCHandle, uint32 PublicKeyUsage, uint32 PublicKeyAttr, const CSSM_DATA *PublicKeyLabel, CSSM_KEY_PTR PublicKey, uint32 PrivateKeyUsage, uint32 PrivateKeyAttr, const CSSM_DATA *PrivateKeyLabel, const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, CSSM_KEY_PTR PrivateKey) SPI: CSSM_RETURN CSSMCSPI CSP_GenerateKeyPair (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context, uint32 PublicKeyUsage, uint32 PublicKeyAttr, const CSSM_DATA *PublicKeyLabel, CSSM_KEY_PTR PublicKey, uint32 PrivateKeyUsage, uint32 PrivateKeyAttr const CSSM_DATA *PrivateKeyLabel, const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, CSSM_KEY_PTR PrivateKey, CSSM_PRIVILEGE Privilege) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. PublicKeyUsage (input) A bit mask indicating all permitted uses for the new public key. PublicKeyAttr (input) A bit mask defining attribute values for the new public key. PublicKeyLabel (input/optional) Pointer to a byte string that will be used as the label for the public key. PublicKey (output) Pointer to CSSM_KEY structure used to hold the new public key. The CSSM_KEY structure should be empty upon input to this function. The CSP will ignore any values residing in this structure at function invocation. Input values should be supplied in the cryptographic Context, PublicKeyUsage, PublicKeyAttr, and PublicKeyLabel input parameters. PrivateKeyUsage (input) A bit mask indicating all permitted uses for the new private key. PrivateKeyAttr (input) A bit mask defining attribute values for the new private key. PrivateKeyLabel (input/optional) Pointer to a byte string that will be used as the label for the private key. CredAndAclEntry (input/optional) A structure containing one or more credentials authorized for creating a key and the prototype ACL entry that will control future use of the newly created key. The credentials and ACL entry prototype can be presented as immediate values or callback functions can be provided for use by the CSP to acquire the credentials and/or the ACL entry interactively. If the CSP provides public access for creating a key, then the credentials can be NULL. If the CSP defines a default initial ACL entry for the new key, then the ACL entry prototype can be an empty list. PrivateKey (output) Pointer to CSSM_KEY structure used to obtain the private key. Upon function invocation, any values in the CSSM_Key structure should be ignored. All input values should be supplied in the cryptographic Context, PrivateKeyUsage, PrivateKeyAttr, and PrivateKeyLabel input parameters. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform 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. 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 AuthorizationTag. (This item applies only 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. NOTES The KeyData fields of the CSSM_KEY structures are allocated by the CSP. The application is required to free this memory using the CSSM_FreeKey() (CSSM API), or CSP_FreeKey() (CSP SPI), function or with the memory functions registered for the CSPHandle. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_GenerateKey CSSM_GenerateRandom Functions for the CSP SPI: CSP_GenerateKey CSP_GenerateRandom 3 GenerateKeyPairP NAME GenerateKeyPairP - Generate an asymmetric key pair with privilege (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_GenerateKeyPairP (CSSM_CC_HANDLE CCHandle, uint32 PublicKeyUsage, uint32 PublicKeyAttr, const CSSM_DATA *PublicKeyLabel, CSSM_KEY_PTR PublicKey, uint32 PrivateKeyUsage, uint32 PrivateKeyAttr, const CSSM_DATA *PrivateKeyLabel, const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, CSSM_KEY_PTR PrivateKey, CSSM_PRIVILEGE Privilege) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS Privilege (input) The privilege to be applied during the cryptographic operation. See CSSM_GenerateKeyPair. DESCRIPTION This function is similar to the CSSM_GenerateKeyPair() function. It also accepts a USEE tag as a privilege request parameter. CSSM checks that either its own privilege set or the application's privilege set (if the application is signed) includes the tag. If the tag is found and the service provider privilege set indicates that it is supported, the tag is forwarded to the service provider. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: CSSM_GenerateKeyPair 3 GenerateMac NAME GenerateMac, CSSM_GenerateMac, CSP_GenerateMac - Compute a message authentication code (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_GenerateMac (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *DataBufs, uint32 DataBufCount, CSSM_DATA_PTR Mac) SPI: CSSM_RETURN CSSMCSPI CSP_GenerateMac (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context, const CSSM_DATA *DataBufs, uint32 DataBufCount, CSSM_DATA_PTR Mac) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. DataBufs (input) A pointer to a vector of CSSM_DATA structures that contain the data to be operated on. DataBufCount (input) The number of DataBufs. Mac (output) A pointer to the CSSM_DATA structure for the Message Authentication Code. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform calls to CSSM for the memory functions managed by CSSM. Context (input) Pointer to CSSM_CONTEXT structure that describes the attributes with this context. DESCRIPTION This function computes a message authentication code for all data contained in the set of input buffers. NOTES ON API The output is returned to the caller either by filling the caller- specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, preallocated output buffer, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value greater than zero and a non-NULL data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value equal to zero and a NULL data pointer field value. The application is always responsible for deallocating the memory when it is no longer needed. NOTES ON SPI The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_OUTPUT_LENGTH_ERROR SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_GenerateMacInit CSSM_GenerateMacUpdate CSSM_GenerateMacFinal Functions for the CSP SPI: CSP_GenerateMacInit CSP_GenerateMacUpdate CSP_GenerateMacFinal 3 GenerateMacFinal NAME GenerateMacFinal, CSSM_GenerateMacFinal, CSP_GenerateMacFinal - Finalize the staged message authentication code (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_GenerateMacFinal (CSSM_CC_HANDLE CCHandle, CSSM_DATA_PTR Mac) SPI: CSSM_RETURN CSSMCSPI CSP_GenerateMacFinal (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, CSSM_DATA_PTR Mac) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. Mac (output) A pointer to the CSSM_DATA structure for the message authentication code. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform calls to CSSM for the memory functions managed by CSSM. DESCRIPTION This function finalizes the staged message authentication code function. NOTES ON API The output is returned to the caller either by filling the caller- specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, preallocated output buffer, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value greater than zero and a non-NULL data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value equal to zero and a NULL data pointer field value. The application is always responsible for deallocating the memory when it is no longer needed. NOTES ON SPI The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_OUTPUT_LENGTH_ERROR SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_GenerateMac CSSM_GenerateMacInit CSSM_GenerateMacUpdate Functions for the CSP SPI: CSP_GenerateMac CSP_GenerateMacInit CSP_GenerateMacUpdate 3 GenerateMacInit NAME GenerateMacInit, CSSM_GenerateMacInit, CSP_GenerateMacInit - Initialize the staged message authentication code (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_GenerateMacInit (CSSM_CC_HANDLE CCHandle) SPI: CSSM_RETURN CSSMCSPI CSP_GenerateMacInit (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform calls to CSSM for the memory functions managed by CSSM. Context (input) Pointer to CSSM_CONTEXT structure that describes the attributes with this context. DESCRIPTION This function initializes the staged message authentication code 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_GenerateMac CSSM_GenerateMacUpdate CSSM_GenerateMacFinal Functions for the CSP SPI: CSP_GenerateMac CSP_GenerateMacUpdate CSP_GenerateMacFinal 3 GenerateMacUpdate NAME GenerateMacUpdate, CSSM_GenerateMacUpdate, CSP_GenerateMacUpdate - Continue the staged process of computing a message authentication code (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_GenerateMacUpdate (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *DataBufs, uint32 DataBufCount) SPI: CSSM_RETURN CSSMCSPI CSP_GenerateMacUpdate (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *DataBufs, uint32 DataBufCount) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. DataBufs (input) A pointer to a vector of CSSM_DATA structures that contain the data to be operated on. DataBufCount (input) The number of DataBufs. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform calls to CSSM for the memory functions managed by CSSM. 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. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_GenerateMac CSSM_GenerateMacInit CSSM_GenerateMacFinal Functions for the CSP SPI: CSP_GenerateMac CSP_GenerateMacInit CSP_GenerateMacFinal 3 GenerateRandom NAME GenerateRandom, CSSM_GenerateRandom, CSP_GenerateRandom function - Generate random data (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_GenerateRandom (CSSM_CC_HANDLE CCHandle, CSSM_DATA_PTR RandomNumber) SPI: CSSM_RETURN CSSMCSPI CSP_GenerateRandom (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context, CSSM_DATA_PTR RandomNumber) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. RandomNumber (output) Pointer to CSSM_DATA structure used to obtain the random number and the size of the random number in bytes. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform calls to CSSM for the memory functions managed by CSSM. Context (input) Pointer to CSSM_CONTEXT structure that describes the attributes with this context. DESCRIPTION This function generates random data. NOTES ON API The output is returned to the caller either by filling the caller- specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, preallocated output buffer, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value greater than zero and a non-NULL data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value equal to zero and a NULL data pointer field value. The application is always responsible for deallocating the memory when it is no longer needed. NOTES ON SPI The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 GetOperationalStatistics NAME GetOperationalStatistics, CSSM_CSP_GetOperationalStatistics, CSP_GetOperationalStatistics - Get operational values of a subservice (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CSP_GetOperationalStatistics (CSSM_CSP_HANDLE CSPHandle, CSSM_CSP_OPERATIONAL_STATISTICS *Statistics) SPI: CSSM_RETURN CSSMCSPI CSSM_CSP_GetOperationalStatistics (CSSM_CSP_HANDLE CSPHandle, CSSM_CSP_OPERATIONAL_STATISTICS *Statistics) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CSPHandle (input) Handle of the cryptographic service provider that will perform the operation. Statistics (output) Structure containing the subservice's current 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. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 GetTimeValue NAME GetTimeValue, CSSM_GetTimeValue, CSP_GetTimeValue - Get a CSP time value (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_GetTimeValue (CSSM_CSP_HANDLE CSPHandle, CSSM_ALGORITHMS TimeAlgorithm, CSSM_DATA *TimeData) SPI: CSSM_RETURN CSSMCSPI CSP_GetTimeValue (CSSM_CSP_HANDLE CSPHandle, CSSM_ALGORITHMS TimeAlgorithm, kCSSM_DATA *TimeData) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CSPHandle (input) Handle of the cryptographic service provider that will perform the operation. TimeAlgorithm (input) A CSSM algorithm type that indicates the method for fetching the time. The following algorithm types are currently supported: CSSM_ALGID_UTC Returns a time value in the form YYYYMMDDhhmmss (4 characters for the year; 2 characters each for the month, the day, the hour, the minute, and the second). The time returned is GMT. CSSM_ALGID_RUNNING_COUNTER The current value of a running hardware counter that operates while the device is in operation. This value can be read from a processor counter provided by some platform architectures. TimeData (output) The time value of counter value returned in response to the request. 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. NOTES The output is returned to the caller either by filling the caller- specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, preallocated output buffer, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value greater than zero and a non-NULL data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value equal to zero and a NULL data pointer field value. The application is always responsible for deallocating the memory when it is no longer needed. Some tokens require authentication before returning a time value. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 HRS_FreeBIRHandle NAME CSSM_HRS_FreeBIRHandle, HRS_FreeBIRHandle - Free memory associated with BIR Handle SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_FreeBIRHandle( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_BIR_HANDLE Handle); SPI CSSM_RETURN CSSMHRI HRS_FreeBIRHandle( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_BIR_HANDLE Handle); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS ModuleHandle (input) The handle of the attached HRS service provider. Handle (input) The BIR Handle to be freed. DESCRIPTION Frees the memory and resources associated with the specified BIR Handle. The associated BIR is no longer referenceable through that handle. If necessary, the application must make the BIR presistent either in an HRS-managed database or an application-managed database before freeing the handle. RETURN VALUE A CSSM_RETURN value indicating success or specifying an error condition. The value CSSM_OK indicates success. All other values represent an error condition. ERRORS Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL 3 HRS_GetBIRFromHandle NAME CSSM_HRS_GetBIRFromHandle, HRS_GetBIRFromHandle SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_GetBIRFromHandle( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_BIR_HANDLE Handle, CSSM_HRS_BIR_PTR *BIR); SPI CSSM_RETURN CSSMHRI HRS_GetBIRFromHandle( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_BIR_HANDLE Handle, CSSM_HRS_BIR_PTR *BIR); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. Handle (input) The handle of the BIR to be retrieved. BIR (output) The retrieved BIR. DESCRIPTION Retrieves the BIR associated with a BIR handle. The handle is invalidated. The HRS service provider allocates the storage for both the retrieved BIR structure and its data members, using the application?s memory allocation callback 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL 3 HRS_GetHeaderFromHandle NAME CSSM_HRS_GetHeaderFromHandle, HRS_GetHeaderFromHandle SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_GetHeaderFromHandle( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_BIR_HANDLE Handle, CSSM_HRS_BIR_HEADER_PTR Header); SPI CSSM_RETURN CSSMHRI HRS_GetHeaderFromHandle( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_BIR_HANDLE Handle, CSSM_HRS_BIR_HEADER_PTR Header); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. Handle (input) The handle of the BIR whose header is to be retrieved. Header (output) The header of the specified BIR. DESCRIPTION Retrieves the BIR header identified by Handle. The BIR Handle is not freed by the HRS service provider. 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL 3 HRS_EnableEvents NAME CSSM_HRS_EnableEvents, HRS_EnableEvents SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_EnableEvents( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_MODULE_EVENT_MASK *Events); SPI CSSM_RETURN CSSMHRI HRS_EnableEvents( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_MODULE_EVENT_MASK *Events); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. Events (input) A pointer to a mask indicating which events to enable. DESCRIPTION This function enables the events (indicated by the Events mask) from the attached HRS service provider in the current process. All other events from this HRS service provider are disabled for this process. 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL 3 HRS_SetGUICallbacks NAME CSSM_HRS_SetGUICallbacks, HRS_SetGUICallbacks SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_SetGUICallbacks( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_GUI_STREAMING_CALLBACK GuiStreamingCallback, void *GuiStreamingCallbackCtx, CSSM_HRS_GUI_STATE_CALLBACK GuiStateCallback, void *GuiStateCallbackCtx); SPI CSSM_RETURN CSSMHRI HRS_SetGUICallbacks (CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_GUI_STREAMING_CALLBACK GuiStreamingCallback, void *GuiStreamingCallbackCtx, CSSM_HRS_GUI_STATE_CALLBACK GuiStateCallback, void *GuiStateCallbackCtx); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. GuiStreamingCallback (input) A pointer to an application callback to deal with the presentation of biometric streaming data. GuiStreamingCallbackCtx (input) A generic pointer to context information provided by the application that will be presented on the callback. GuiStateCallback (input) A pointer to an application callback to deal with GUI state changes. GuiStateCallbackCtx (input) A generic pointer to context information provided by the application that will be presented on the callback. DESCRIPTION This function allows the application to establish callbacks so that the application may control the "look-and-feel" of the biometric user interface. Note that not all HRS service providers provide streaming data. 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL 3 HRS_CancelGUICallbacks NAME CSSM_HRS_CancelGUICallbacks, HRS_CancelGUICallbacks SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_CancelGUICallbacks (CSSM_HRS_HANDLE ModuleHandle); SPI CSSM_RETURN CSSMHRI HRS_CancelGUICallbacks (CSSM_HRS_HANDLE ModuleHandle); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. DESCRIPTION This function cancels GUICallbacks if they have been set. A GUICallback should be canceled before the service provider is detached. 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL 3 HRS_SetStreamCallback NAME CSSM_HRS_SetStreamCallback, HRS_SetStreamCallback SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_SetStreamCallback (CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_STREAM_CALLBACK StreamCallback, void *StreamCallbackCtx); SPI CSSM_RETURN CSSMHRI HRS_SetStreamCallback (CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_STREAM_CALLBACK StreamCallback, void *StreamCallbackCtx); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. StreamCallback (input) A pointer to an application callback to deal with the client/server transmission of protocol data units between HRS service providers. StreamCallbackCtx (input) A generic pointer to context information provided by the application that will be presented on the callback. DESCRIPTION This function allows the application to establish a callback for client/server communication. The callback allows the HRS service provider to send a protocol message to its partner service provider, and to receive a protocol message in exchange. 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 Errors are described in the CDSA Technical Standard. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL 3 HRS_CancelStreamCallbacks NAME CSSM_HRS_CancelStreamCallbacks, HRS_CancelStreamCallbacks SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_CancelStreamCallbacks (CSSM_HRS_HANDLE ModuleHandle); SPI CSSM_RETURN CSSMHRI HRS_CancelStreamCallbacks (CSSM_HRS_HANDLE ModuleHandle); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. DESCRIPTION This function cancels the StreamCallback if it has been set. A StreamCallback should be canceled before the service provider is detached. 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL 3 HRS_StreamInputOutput NAME CSSM_HRS_StreamInputOutput, HRS_StreamInputOutput SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_StreamInputOutput( CSSM_HRS_HANDLE ModuleHandle, CSSM_DATA_PTR InMessage, CSSM_DATA_PTR OutMessage); SPI CSSM_RETURN CSSMHRI HRS_StreamInputOutput( CSSM_HRS_HANDLE ModuleHandle, CSSM_DATA_PTR InMessage, CSSM_DATA_PTR OutMessage); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. InMessage (input) InMessage contains a protocol data unit from the partner HRS service provider. OutMessage (output) OutMessage contains a protocol data unit to be sent back to the partner HRS service provider. If the parameter is NULL, there is no message to return. DESCRIPTION This function allows the application to pass a protocol data unit into the HRS service provider from the partner HRS service provider, and to obtain a response message to return to the partner. 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL 3 HRS_Capture NAME CSSM_HRS_Capture, HRS_Capture SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_Capture( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_BIR_PURPOSE Purpose, CSSM_HRS_BIR_HANDLE_PTR CapturedBIR, sint32 Timeout, CSSM_HRS_BIR_HANDLE_PTR AuditData); SPI CSSM_RETURN CSSMHRI HRS_Capture( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_BIR_PURPOSE Purpose, CSSM_HRS_BIR_HANDLE_PTR CapturedBIR, sint32 Timeout, CSSM_HRS_BIR_HANDLE_PTR AuditData); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. Purpose (input) A value indicating the purpose of the biometric data capture. CapturedBIR (output) A handle to a BIR containing captured data. This data is either an "intermediate" type BIR (which can only be used by either the Process or CreateTemplate functions, depending on the purpose), or a "processed" BIR (which can be used directly by VerifyMatch or IdentifyMatch, depending on the purpose). Timeout (input) An integer specifying the timeout value (in milliseconds) for the operation. If this timeout is reached, the function returns an error, and no results. This value can be any positive number. A -1 value means the service provider's default timeout value will be used. AuditData (output/optional) A handle to a BIR containing raw biometric data. This data may be used to provide human-identifiable data of the person at the device. If the pointer is NULL on input, no audit data is collected. Not all BSPs support the collection of audit data. A service provider may return a handle value of CSSM_HRS_UNSUPPORTED_BIR_HANDLE indicating not supported, or a value of CSSM_HRS_INVALID_BIR_HANDLE indicating no audit data is available. DESCRIPTION This function captures samples for the purpose specified, and returns either an "intermediate" type BIR (if the Process function needs to be called), or a "processed" BIR (if not). The Purpose is recorded in the header of the CapturedBIR. If AuditData is non-NULL, a BIR of type "raw" may be returned. The function returns handles to whatever data is collected, and all local operations can be completed through use of the handles. If the application needs to acquire the data either to store it in a database or to send it to a server, the application can retrieve the data with the HRS_GetBIRFromHandle() function. The application may request control of the GUI "look-and-feel" by providing a GUI callback pointer in HRS_SetGUICallbacks(). Capture serializes use of the device. If two or more applications are racing for the device, the losers will wait until the timeout expires. This serialization takes place in all functions that capture data. 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL CSSMERR_HRS_PURPOSE_NOT_SUPPORTED CSSMERR_HRS_TIMEOUT_EXPIRED CSSMERR_HRS_TOO_MANY_HANDLES CSSMERR_HRS_UNABLE_TO_CAPTURE 3 HRS_CreateTemplate NAME CSSM_HRS_CreateTemplate, HRS_CreateTemplate SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_CreateTemplate( CSSM_HRS_HANDLE ModuleHandle, const CSSM_HRS_INPUT_BIR *CapturedBIR, const CSSM_HRS_INPUT_BIR *StoredTemplate, CSSM_HRS_BIR_HANDLE_PTR NewTemplate, const CSSM_DATA *Payload); SPI CSSM_RETURN CSSMHRI HRS_CreateTemplate( CSSM_HRS_HANDLE ModuleHandle, const CSSM_HRS_INPUT_BIR *CapturedBIR, const CSSM_HRS_INPUT_BIR *StoredTemplate, CSSM_HRS_BIR_HANDLE_PTR NewTemplate, const CSSM_DATA *Payload); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. CapturedBIR (input) The captured BIR or its handle. StoredTemplate (input/optional) Optionally, the template to be adapted, or its key in a database, or its handle. NewTemplate (output) A handle to a newly created template that is derived from the CapturedBIR and (optionally) the StoredTemplate. Payload (input/optional) A pointer to data that will be wrapped inside the newly created template. This parameter is ignored, if NULL. DESCRIPTION This function takes a BIR containing raw biometric data for the purpose of creating a new enrollment template. A new BIR is constructed from the CapturedBIR, and (optionally) it may perform an adaptation based on an existing StoredTemplate. The old StoredTemplate remains unchanged. If the StoredTemplate contains a payload, the payload is not copied into the NewTemplate. If the NewTemplate needs a payload, then that Payload must be presented as an argument to the 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL CSSMERR_HRS_BIR_SIGNATURE_FAILURE CSSMERR_HRS_INCONSISTENT_PURPOSE CSSMERR_HRS_INVALID_BIR CSSMERR_HRS_PURPOSE_NOT_SUPPORTED CSSMERR_HRS_RECORD_NOT_FOUND CSSMERR_HRS_TOO_MANY_HANDLES CSSMERR_HRS_UNABLE_TO_WRAP_PAYLOAD 3 HRS_Process NAME CSSM_HRS_Process, HRS_Process SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_Process( CSSM_HRS_HANDLE ModuleHandle, const CSSM_HRS_INPUT_BIR *CapturedBIR, CSSM_HRS_BIR_HANDLE_PTR ProcessedBIR); SPI CSSM_RETURN CSSMHRI HRS_Process( CSSM_HRS_HANDLE ModuleHandle, const CSSM_HRS_INPUT_BIR *CapturedBIR, CSSM_HRS_BIR_HANDLE_PTR ProcessedBIR); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. CapturedBIR (input) The captured BIR or its handle. ProcessedBIR (output) A handle for the newly constructed "processed" BIR, NULL. DESCRIPTION This function processes the intermediate data captured via a call to HRS_Capture() for the purpose of either verification or identification. If the processing capability is in the attached service provider, a "processed" BIR is returned; otherwise, ProcessedBIR is set to 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL CSSMERR_HRS_BIR_SIGNATURE_FAILURE CSSMERR_HRS_INCONSISTENT_PURPOSE CSSMERR_HRS_INVALID_BIR CSSMERR_HRS_PURPOSE_NOT_SUPPORTED CSSMERR_HRS_RECORD_NOT_FOUND CSSMERR_HRS_TOO_MANY_HANDLES CSSMERR_HRS_UNABLE_TO_WRAP_PAYLOAD 3 HRS_VerifyMatch NAME CSSM_HRS_VerifyMatch, HRS_VerifyMatch SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_VerifyMatch( CSSM_HRS_HANDLE ModuleHandle, const CSSM_HRS_FAR *MaxFARRequested, const CSSM_HRS_FRR *MaxFRRRequested, const CSSM_BOOL *FARPrecedence, const CSSM_HRS_INPUT_BIR *ProcessedBIR, const CSSM_HRS_INPUT_BIR *StoredTemplate, CSSM_HRS_BIR_HANDLE *AdaptedBIR, CSSM_BOOL *Result, CSSM_HRS_FAR_PTR FARAchieved, CSSM_HRS_FRR_PTR FRRAchieved, CSSM_DATA_PTR *Payload); SPI CSSM_RETURN CSSMHRI HRS_VerifyMatch( CSSM_HRS_HANDLE ModuleHandle, const CSSM_HRS_FAR *MaxFARRequested, const CSSM_HRS_FRR *MaxFRRRequested, const CSSM_BOOL *FARPrecedence, const CSSM_HRS_INPUT_BIR *ProcessedBIR, const CSSM_HRS_INPUT_BIR *StoredTemplate, CSSM_HRS_BIR_HANDLE *AdaptedBIR, CSSM_BOOL *Result, CSSM_HRS_FAR_PTR FARAchieved, CSSM_HRS_FRR_PTR FRRAchieved, CSSM_DATA_PTR *Payload); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. MaxFARRequested (input) The requested FAR criterion for successful verification. MaxFRRRequested (input/optional) The requested FRR criterion for successful verification. A NULL pointer indicates that this criterion is not provided. FARPrecedence (input) If both criteria are provided, this parameter indicates which takes precedence: CSSM_TRUE for FAR, CSSM_FALSE for FRR. ProcessedBIR (input) The BIR to be verified, or its handle. StoredTemplate (input) The BIR to be verified against, or its key in a database, or its handle. AdaptedBIR (output/optional) A pointer to the handle of the adapted BIR. This parameter can be NULL if an Adapted BIR is not desired. Not all service providers support the adaptation of BIRs. The function may return a handle value of CSSM_HRS_UNSUPPORTED_BIR_HANDLE to indicate that adaptation is not supported, or a value of CSSM_HRS_INVALID_BIR_HANDLE to indicate that adaptation was not possible. Result (output) A pointer to a Boolean value indicating (CSSM_TRUE/CSSM_FALSE) whether the BIRs matched or not according to the specified criteria. FARAchieved (output) A pointer to an FAR value indicating the closeness of the match. FRRAchieved (output/optional) A pointer to an FRR value indicating the closeness of the match. Payload (output/optional) If the StoredTemplate contains a payload, it is returned in an allocated CSSM_DATA structure if the FARAchieved satisfies the policy of the service provider. DESCRIPTION This function performs a verification (1-to-1) match between two BIRs - the ProcessedBIR and the StoredTemplate. The ProcessedBIR is the "processed" BIR constructed specifically for this verification. The StoredTemplate was created at enrollment. The application must request a maximum FAR value for a successful match, and may also (optionally) request a maximum FRR for a successful match. If a maximum FRR value is provided, the application must also indicate (via the FARPrecedence parameter) which one takes precedence. The Boolean Result indicates whether verification was successful or not, and the FARAchieved is a FAR value indicating how closely the BIRs actually matched. The service provider may optionally return the corresponding FRR that was achieved, through the FRRAchieved return parameter. By setting the AdaptedBIR pointer to non-NULL, the application can request that a BIR be constructed by adapting the StoredTemplate using the ProcessedBIR. A new handle is returned to the AdaptedBIR. If the StoredTemplate contains a Payload, the Payload may be returned upon successful verification if the FARAchieved is sufficiently stringent. This is controlled by the policy of the service provider. If the match is successful, an attempt may be made to adapt the StoredTemplate with information taken from the ProcessedBIR. (Not all service providers perform adaptation.) The resulting AdaptedBIR should now be considered an optimal enrollment template, and be saved in the enrollment database. It is up to the application whether or not it uses or discards this data. It is important to note that adaptation may not occur in all cases. In the event of an adaptation, this function stores the handle to the new BIR in the memory pointed to by the AdaptedBIR parameter. 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 Errors are described in the CDSA Technical Standard. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL CSSMERR_HRS_ADAPTATION_NOT_SUPPORTED CSSMERR_HRS_BIR_NOT_FULLY_PROCESSED CSSMERR_HRS_BIR_SIGNATURE_FAILURE CSSMERR_HRS_INCONSISTENT_PURPOSE 3 HRS_IdentifyMatch NAME CSSM_HRS_IdentifyMatch, HRS_IdentifyMatch SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_IdentifyMatch( CSSM_HRS_HANDLE ModuleHandle, const CSSM_HRS_FAR *MaxFARRequested, const CSSM_HRS_FRR *MaxFRRRequested, const CSSM_BOOL *FARPrecedence, const CSSM_HRS_INPUT_BIR *ProcessedBIR, const CSSM_HRS_IDENTIFY_POPULATION *Population, CSSM_BOOL Binning, uint32 MaxNumberOfResults, uint32 *NumberOfResults, CSSM_HRS_CANDIDATE_ARRAY_PTR *Candidates, sint32 Timeout); SPI CSSM_RETURN CSSMHRI HRS_IdentifyMatch( CSSM_HRS_HANDLE ModuleHandle, const CSSM_HRS_FAR *MaxFARRequested, const CSSM_HRS_FRR *MaxFRRRequested, const CSSM_BOOL *FARPrecedence, const CSSM_HRS_INPUT_BIR *ProcessedBIR, const CSSM_HRS_IDENTIFY_POPULATION *Population, CSSM_BOOL Binning, uint32 MaxNumberOfResults, uint32 *NumberOfResults, CSSM_HRS_CANDIDATE_ARRAY_PTR *Candidates, sint32 Timeout); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. MaxFARRequested (input) The requested FAR criterion for successful verification. MaxFRRRequested (input/optional) The requested FRR criterion for successful verification. A NULL pointer indicates that this criterion is not provided. FARPrecedence (input) If both criteria are provided, this parameter indicates which takes precedence: CSSM_TRUE for FAR, CSSM_FALSE for FRR. ProcessedBIR (input) The BIR to be identified. Population (input) The population of BIRs against which the Identify match is performed. Binning (input) A Boolean indicating whether Binning is on or off. Binning is a search-optimization technique that the service provider may employ. It is based on searching the population according to the intrinsic characteristics of the biometric data. While it may improve the speed of the Match operation, it may also increase the probability of missing a candidate. MaxNumberOfResults (input) Specifies the maximum number of match candidates to be returned as a result of the 1:N match. A value of zero is a request for all candidates. NumberOfResults (output) Specifies the number of candidates returned in the Candidates array as a result of the 1:N match. Candidates (output) A pointer to an array of CSSM_HRS_CANDIDATE_PTRs corresponding to the BIRs identified as a result of the match process (that is, indices associated with BIRs found to exceed the match threshold). This list is in rank order, with the highest scoring record being first. If no matches are found, this pointer will be set to NULL. If the Population was presented in a database, the IDs are database IDs; if the set was presented in an in-memory array, the IDs are indexes into the array. Timeout (input) An integer specifying the timeout value (in milliseconds) for the operation. If this timeout is reached, the function returns an error, and no candidate list. This value can be any positive number. A -1 value means the service provider's default timeout value will be used. DESCRIPTION This function performs an identification (1-to-many) match between a ProcessedBIR and a set of stored BIRs. The ProcessedBIR is the "processed" BIR captured specifically for this identification. The population that the match takes place against can be presented in one of three ways: 1. In a database identified by an open database handle 2. Input in an array of BIRs 3. In the "default" database of the BSP (possibly stored in the biometric device) The application must request a maximum FAR value criterion for a successful match, and may also (optionally) request a maximum FRR criterion for a successful match. If a maximum FRR value is provided, the application must also indicate, via the FARPrecedence parameter, which criteria takes precedence. The FARAchieved and, optionally, the FRRAchieved are returned for each result in the Candidate array. NOTES Not all service providers support 1:N identification. Depending on the service provider and the location and size of the database to be searched, this operation can take a significant amount of time to perform The number of match candidates found by the service provider is dependent on the actual FAR used. 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL CSSMERR_HRS_BIR_NOT_FULLY_PROCESSED CSSMERR_HRS_BIR_SIGNATURE_FAILURE CSSMERR_HRS_FUNCTION_NOT_SUPPORTED CSSMERR_HRS_INCONSISTENT_PURPOSE CSSMERR_HRS_NO_INPUT_BIRS CSSMERR_HRS_RECORD_NOT_FOUND CSSMERR_HRS_TIMEOUT_EXPIRED 3 HRS_Enroll NAME CSSM_HRS_Enroll, HRS_Enroll SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_Enroll( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_BIR_PURPOSE Purpose, const CSSM_HRS_INPUT_BIR *StoredTemplate, CSSM_HRS_BIR_HANDLE_PTR NewTemplate, const CSSM_DATA *Payload, sint32 Timeout CSSM_HRS_BIR_HANDLE_PTR AuditData); SPI CSSM_RETURN CSSMHRI HRS_Enroll( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_BIR_PURPOSE Purpose, const CSSM_HRS_INPUT_BIR *StoredTemplate, CSSM_HRS_BIR_HANDLE_PTR NewTemplate, const CSSM_DATA *Payload, sint32 Timeout CSSM_HRS_BIR_HANDLE_PTR AuditData); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. Purpose (input) A value indicating the desired purpose of Enrollment. StoredTemplate (input/optional) Optionally, the BIR to be adapted, or its key in a database, or its handle. NewTemplate (output) A handle to a newly created template that is derived from the new raw samples and (optionally) the StoredTemplate. Payload (input/optional) A pointer to data that will be wrapped inside the newly created template. This parameter is ignored, if NULL. Timeout (input) An integer specifying the timeout value (in milliseconds) for the operation. If this timeout is reached, the function returns an error, and no results. This value can be any positive number. A -1 value means the BSP's default timeout value will be used. AuditData (output/optional) A handle to a BIR containing biometric audit data. This data may be used to provide human-identifiable data of the person at the device. If the pointer is NULL on input, no audit data is collected. Not all HRS service providers support the collection of audit data. An HRS service provider may return a handle value of CSSM_HRS_UNSUPPORTED_BIR_HANDLE to indicate AuditData is not supported, or a value of CSSM_HRS_INVALID_BIR_HANDLE to indicate that no audit data is available. DESCRIPTION This function captures biometric data from the attached device for the purpose of creating a ProcessedBIR for the purpose of enrollment. The Enroll function may be split between client and server if a streaming callback has been set. Either the client or the server can initiate the 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL CSSMERR_HRS_PURPOSE_NOT_SUPPORTED CSSMERR_HRS_RECORD_NOT_FOUND CSSMERR_HRS_TIMEOUT_EXPIRED CSSMERR_HRS_TOO_MANY_HANDLES CSSMERR_HRS_UNABLE_TO_CAPTURE CSSMERR_HRS_UNABLE_TO_WRAP_PAYLOAD 3 HRS_Verify NAME CSSM_HRS_Verify, HRS_Verify SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_Verify( CSSM_HRS_HANDLE ModuleHandle, const CSSM_HRS_FAR *MaxFARRequested, const CSSM_HRS_FRR *MaxFRRRequested, const CSSM_BOOL *FARPrecedence, const CSSM_HRS_INPUT_BIR *StoredTemplate, CSSM_HRS_BIR_HANDLE_PTR AdaptedBIR, CSSM_BOOL *Result, CSSM_HRS_FAR_PTR FARAchieved, CSSM_HRS_FRR_PTR FRRAchieved, CSSM_DATA_PTR *Payload, sint32 Timeout, CSSM_HRS_BIR_HANDLE_PTR AuditData); SPI CSSM_RETURN CSSMHRI HRS_Verify( CSSM_HRS_HANDLE ModuleHandle, const CSSM_HRS_FAR *MaxFARRequested, const CSSM_HRS_FRR *MaxFRRRequested, const CSSM_BOOL *FARPrecedence, const CSSM_HRS_INPUT_BIR *StoredTemplate, CSSM_HRS_BIR_HANDLE_PTR AdaptedBIR, CSSM_BOOL *Result, CSSM_HRS_FAR_PTR FARAchieved, CSSM_HRS_FRR_PTR FRRAchieved, CSSM_DATA_PTR *Payload, sint32 Timeout, CSSM_HRS_BIR_HANDLE_PTR AuditData); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. MaxFARRequested (input) The requested FAR criterion for successful verification. MaxFRRRequested (input/optional) The requested FRR criterion for successful verification. A NULL pointer indicates that this criterion is not provided. FARPrecedence (input) If both criteria are provided, this parameter indicates which takes precedence: CSSM_TRUE for FAR, CSSM_FALSE for FRR. StoredTemplate (input) The BIR to be verified against, or its key in a database, or its handle. AdaptedBIR (output/optional) A pointer to the handle of the adapted BIR. This parameter can be NULL if an adapted BIR is not desired. Not all HRS service providers support the adaptation of BIRs. The function may return a handle value of CSSM_HRS_UNSUPPORTED_BIR_HANDLE to indicate that adaptation is not supported, or a value of CSSM_HRS_INVALID_BIR_HANDLE to indicate that adaptation was not possible. Result (output) A pointer to a Boolean value indicating (CSSM_TRUE/CSSM_FALSE) whether the BIRs matched or not, according to the specified criteria. FARAchieved (output) A pointer to an FAR value indicating the closeness of the match. FRRAchieved (output/optional) A pointer to an FRR value indicating the closeness of the match. Payload (output/optional) If the StoredTemplate contains a payload, it is returned in an allocated CSSM_DATA structure if the FARAchieved satisfies the policy of the service provider. Timeout (input) An integer specifying the timeout value (in milliseconds) for the operation. If this timeout is reached, the function returns an error, and no results. This value can be any positive number. A -1 value means the service provider's default timeout value will be used. AuditData (output/optional) A handle to a BIR containing raw biometric data. This data may be used to provide human-identifiable data of the person at the device. If the pointer is NULL on input, no audit data is collected. Not all service providers support the collection of audit data. An HRS service provider may return a handle value of CSSM_HRS_UNSUPPORTED_BIR_HANDLE to indicate AuditData is not supported, or a value of CSSM_HRS_INVALID_BIR_HANDLE to indicate that no audit data is available. DESCRIPTION This function captures biometric data from the attached device, and compares it against the StoredTemplate. The application must request a maximum FAR value criterion for a successful match, and may also (optionally) request a maximum FRR criterion for a successful match. If a maximum FRR value is provided, the application must also indicate via the FARPrecedence parameter, which criteria takes precedence. The Boolean Result indicates whether verification was successful or not, and the FARAchieved is a FAR value indicating how closely the BIRs actually matched. The service provider may optionally return the corresponding FRR that was achieved through the FRRAchieved return parameter. If the StoredTemplate contains a payload, the Payload may be returned upon successful verification. Optionally, a new AdaptedBIR may be constructed. The Verify function may be split between client and server if a streaming callback has been set. Either the client or the server can initiate the operation. If the match is successful, an attempt may be made to adapt the StoredTemplate with information taken from the ProcessedBIR. (Not all service providers perform adaptation.) The resulting AdaptedBIR should now be considered an optimal enrollment, and be saved in the enrollment database. It is up to the application whether or not it uses or discards this data. It is important to note that adaptation may not occur in all cases. In the event of an adaptation, this function stores the handle to the new BIR in the memory pointed to by the AdaptedBIR parameter. 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL CSSMERR_HRS_BIR_SIGNATURE_FAILURE CSSMERR_HRS_INCONSISTENT_PURPOSE CSSMERR_HRS_RECORD_NOT_FOUND CSSMERR_HRS_TIMEOUT_EXPIRED CSSMERR_HRS_TOO_MANY_HANDLES CSSMERR_HRS_UNABLE_TO_CAPTURE 3 HRS_Identify NAME CSSM_HRS_Identify, HRS_Identify SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_Identify( CSSM_HRS_HANDLE ModuleHandle, const CSSM_HRS_FAR *MaxFARRequested, const CSSM_HRS_FRR *MaxFRRRequested, const CSSM_BOOL *FARPrecedence, const CSSM_HRS_IDENTIFY_POPULATION *Population, CSSM_BOOL Binning, uint32 MaxNumberOfResults, uint32 *NumberOfResults, CSSM_HRS_CANDIDATE_ARRAY_PTR *Candidates, sint32 Timeout, CSSM_HRS_BIR_HANDLE_PTR AuditData); SPI CSSM_RETURN CSSMHRI HRS_Identify( CSSM_HRS_HANDLE ModuleHandle, const CSSM_HRS_FAR *MaxFARRequested, const CSSM_HRS_FRR *MaxFRRRequested, const CSSM_BOOL *FARPrecedence, const CSSM_HRS_IDENTIFY_POPULATION *Population, CSSM_BOOL Binning, uint32 MaxNumberOfResults, uint32 *NumberOfResults, CSSM_HRS_CANDIDATE_ARRAY_PTR *Candidates, sint32 Timeout, CSSM_HRS_BIR_HANDLE_PTR AuditData); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. MaxFARRequested (input) The requested FAR criterion for successful identification. MaxFRRRequested (input/optional) The requested FRR criterion for successful identification. A NULL pointer indicates that this criterion is not provided. FARPrecedence (input) If both criteria are provided, this parameter indicates which takes precedence: CSSM_TRUE for FAR, CSSM_FALSE for FRR. Population (input) The population of Templates against which the Identify match is performed. Binning (input) A Boolean value indicating whether Binning is on or off. Binning is a search optimization technique that the BSP may employ. It is based on searching the population according to the intrinsic characteristics of the biometric data. While it may improve the speed of the Match operation, it may also increase the probability of missing a candidate. MaxNumberOfResults (input) Specifies the maximum number of match candidates to be returned as a result of the 1:N match. A value of zero is a request for all candidates. NumberOfResults (output) Specifies the number of candidates returned in the Candidates array as a result of the 1:N match. Candidates (output) A pointer to an array of CSSM_HRS_CANDIDATE_PTRs corresponding to the BIRs identified as a result of the match process (that is, indices associated with BIRs found to exceed the match threshold). This list is in rank order, with the highest scoring record being first. If no matches are found, this pointer will be set to NULL. If the Population was presented in a database, the IDs are database IDs; if the set was presented in an in-memory array, the IDs are indexes into the array. Timeout (input) An integer specifying the timeout value (in milliseconds) for the operation. If this timeout is reached, the function returns an error, and no results. This value can be any positive number. A -1 value means the service provider's default timeout value will be used. AuditData (output/optional) A handle to a BIR containing raw biometric data. This data may be used to provide human-identifiable data of the person at the device. If the pointer is NULL on input, no audit data is collected. Not all HRS service providers support the collection of audit data. A BSP may return a handle value of CSSM_HRS_UNSUPPORTED_BIR_HANDLE to indicate AuditData is not supported, or a value of CSSM_HRS_INVALID_BIR_HANDLE to indicate that no audit data is available. DESCRIPTION This function captures biometric data from the attached device, and compares it against the Population. The application must request a maximum FAR value criterion for a successful match, and may also (optionally) request a maximum FRR criterion for a successful match. If a maximum FRR value is provided, the application must also indicate via the FARPrecedence parameter, which criteria takes precedence. The function returns a number of candidates from the population that match according to the specified criteria, and the FARAchieved and, optionally, the FRRAchieved are returned for each result in the Candidate array. The Identify function may be split between client and server if a streaming callback has been set. Either the client or the server can initiate the operation. NOTES Not all service providers support 1:N identification. See your service provider's programming manual for more details. Depending on the service provider and the location and size of the database to be searched, this operation can take a significant amount of time to perform. Check your service provider's manual for recommended Timeout values. The number of match candidates found by the service provider is dependent on the actual FAR used. 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL CSSMERR_HRS_BIR_SIGNATURE_FAILURE CSSMERR_HRS_FUNCTION_NOT_SUPPORTED CSSMERR_HRS_INCONSISTENT_PURPOSE CSSMERR_HRS_NO_INPUT_BIRS CSSMERR_HRS_RECORD_NOT_FOUND CSSMERR_HRS_TIMEOUT_EXPIRED CSSMERR_HRS_TOO_MANY_HANDLES CSSMERR_HRS_UNABLE_TO_CAPTURE 3 HRS_Import NAME CSSM_HRS_Import, HRS_Import SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_Import( CSSM_HRS_HANDLE ModuleHandle, const CSSM_DATA *InputData, CSSM_HRS_BIR_BIOMETRIC_DATA_FORMAT InputFormat, CSSM_HRS_BIR_PURPOSE Purpose, CSSM_HRS_BIR_HANDLE_PTR ConstructedBIR); SPI CSSM_RETURN CSSMHRI HRS_Import( CSSM_HRS_HANDLE ModuleHandle, const CSSM_DATA *InputData, CSSM_HRS_BIR_BIOMETRIC_DATA_FORMAT InputFormat, CSSM_HRS_BIR_PURPOSE Purpose, CSSM_HRS_BIR_HANDLE_PTR ConstructedBIR); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. InputData (input) A pointer to image/stream data to import into a ProcessedBIR. The image/stream conforms to the standard identified by InputFormat. InputFormat (input) The format of the InputData. Purpose (input) A value indicating the Enroll purpose. ConstructedBIR (output) A handle to a BIR constructed from the imported biometric data. This BIR may be either an Intermediate or Processed BIR (as indicated in the header). DESCRIPTION This function imports non-realtime raw biometric data to construct a BIR for the purpose specified. InputData identifies the memory buffer containing the raw biometric data, while InputFormat identifies the form of the raw biometric data. The function returns a handle to the ConstructedBIR. If the application needs to acquire the BIR either to store it in a database or to send it to a server, the application can retrieve the data with the HRS_GetBIRFromHandle( ) function, or store it directly using HRS_DbStoreBIR(). 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL CSSMERR_HRS_FUNCTION_NOT_SUPPORTED CSSMERR_HRS_PURPOSE_NOT_SUPPORTED CSSMERR_HRS_TOO_MANY_HANDLES CSSMERR_HRS_UNABLE_TO_IMPORT CSSMERR_HRS_UNSUPPORTED_FORMAT 3 HRS_SetPowerMode NAME CSSM_HRS_SetPowerMode, HRS_SetPowerMode SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_SetPowerMode( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_POWER_MODE PowerMode); SPI CSSM_RETURN CSSMHRI HRS_SetPowerMode( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_POWER_MODE PowerMode); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. PowerMode (input) A 32-bit value indicting the power mode to set the device to. DESCRIPTION This function sets the device to the requested power mode if the device supports it. 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_HRS_FUNCTION_NOT_SUPPORTED 3 HRS_DbOpen ~~~ NAME CSSM_HRS_DbOpen, HRS_DbOpen SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_DbOpen( CSSM_HRS_HANDLE ModuleHandle, const uint8 *DbName, CSSM_HRS_DB_ACCESS_TYPE AccessRequest, CSSM_HRS_DB_HANDLE_PTR DbHandle, CSSM_HRS_DB_CURSOR_PTR Cursor); SPI CSSM_RETURN CSSMHRI HRS_DbOpen( CSSM_HRS_HANDLE ModuleHandle, const uint8 *DbName, CSSM_HRS_DB_ACCESS_TYPE AccessRequest, CSSM_HRS_DB_HANDLE_PTR DbHandle, CSSM_HRS_DB_CURSOR_PTR Cursor); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. DbName (input) A pointer to the null-terminated string containing the name of the database. AccessRequest (input) An indicator of the requested access mode for the database, such as read or write. DbHandle (output) The handle to the opened data store. The value will be set to CSSM_HRS_DB_INVALID_HANDLE if the function fails. Cursor (output) A handle that can be used to iterate through the database. DESCRIPTION This function opens the data store with the specified name under the specified access mode. A database Cursor is set to point to the first record in the database. Note that the default database (if any) is always open. 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL CSSMERR_HRS_DATABASE_DOES_NOT_EXIST CSSMERR_HRS_DATABASE_IS_LOCKED CSSMERR_HRS_INVALID_ACCESS_REQUEST CSSMERR_HRS_INVALID_DATABASE_NAME CSSMERR_HRS_UNABLE_TO_OPEN_DATABASE 3 HRS_DbClose NAME CSSM_HRS_DbClose, HRS_DbClose SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_DbClose( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_DB_HANDLE DbHandle); SPI CSSM_RETURN CSSMHRI HRS_DbClose( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_DB_HANDLE DbHandle); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. DbHandle (input) The DB handle for an open database managed by the service provider. This specifies the open database to be closed. DESCRIPTION This function closes an open database. All cursors currently set to the database are freed. The default database cannot be closed. 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL 3 HRS_DbCreate NAME CSSM_HRS_DbCreate, HRS_DbCreate SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_DbCreate( CSSM_HRS_HANDLE ModuleHandle, const uint8 *DbName, CSSM_HRS_DB_ACCESS_TYPE AccessRequest, CSSM_HRS_DB_HANDLE_PTR DbHandle); SPI CSSM_RETURN CSSMHRI HRS_DbCreate( CSSM_HRS_HANDLE ModuleHandle, const uint8 *DbName, CSSM_HRS_DB_ACCESS_TYPE AccessRequest, CSSM_HRS_DB_HANDLE_PTR DbHandle); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. DbName (input) A pointer to the null-terminated string containing the name of the new database. AccessRequest (input) An indicator of the requested access mode for the database, such as read or write. DbHandle (output) The handle to the newly created and open data store. The value will be set to CSSM_HRS_DB_INVALID_HANDLE if the function fails. DESCRIPTION This function creates and opens a new database. The name of the new database is specified by the input parameter DbName. The newly created database is opened under the specified access mode. 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL CSSMERR_HRS_DATABASE_ALREADY_EXISTS CSSMERR_HRS_INVALID_ACCESS_REQUEST CSSMERR_HRS_INVALID_DATABASE_NAME 3 HRS_DbDelete NAME CSSM_HRS_DbDelete, HRS_DbDelete SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_DbDelete( CSSM_HRS_HANDLE ModuleHandle, const uint8 *DbName); SPI CSSM_RETURN CSSMHRI HRS_DbDelete( CSSM_HRS_HANDLE ModuleHandle, const uint8 *DbName); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. DbName (input) A pointer to the null-terminated string containing the name of the database to be deleted. DESCRIPTION This function deletes all records from the specified database and removes all state information associated with that database. 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL CSSMERR_HRS_DATABASE_IS_OPEN CSSMERR_HRS_INVALID_DATABASE_NAME 3 HRS_DbSetCursor NAME CSSM_HRS_DbSetCursor, HRS_DbSetCursor SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_DbSetCursor( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_DB_HANDLE DbHandle, const CSSM_GUID *KeyValue, CSSM_HRS_DB_CURSOR_PTR Cursor); SPI CSSM_RETURN CSSMHRI HRS_DbSetCursor( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_DB_HANDLE DbHandle, const CSSM_GUID *KeyValue, CSSM_HRS_DB_CURSOR_PTR Cursor); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. DbHandle (input) A handle to the open database. KeyValue (input) The key into the database of the BIR to which the Cursor is to be set. Cursor (output) A handle that can be used to iterate through the database from the retrieved record. DESCRIPTION The Cursor is set to point to the record indicated by the KeyValue in the database identified by the DbHandle. A NULL value will set the cursor to the first record in the database. 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL CSSMERR_HRS_RECORD_NOT_FOUND 3 HRS_DbFreeCursor NAME CSSM_HRS_DbFreeCursor, HRS_DbFreeCursor SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_DbFreeCursor( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_DB_CURSOR_PTR Cursor); SPI CSSM_RETURN CSSMHRI HRS_DbFreeCursor( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_DB_CURSOR_PTR Cursor); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. Cursor (input) The database Cursor to be freed. DESCRIPTION Frees memory and resources associated with the specified Cursor. 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL CSSMERR_HRS_CURSOR_IS_INVALID 3 HRS_DbStoreBIR NAME NAME CSSM_HRS_DbStoreBIR, HRS_DbStoreBIR SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_DbStoreBIR( CSSM_HRS_HANDLE ModuleHandle, const CSSM_HRS_INPUT_BIR *BIRToStore, CSSM_HRS_DB_HANDLE DbHandle, CSSM_GUID_PTR Guid); SPI CSSM_RETURN CSSMHRI HRS_DbStoreBIR( CSSM_HRS_HANDLE ModuleHandle, const CSSM_HRS_INPUT_BIR *BIRToStore, CSSM_HRS_DB_HANDLE DbHandle, CSSM_GUID_PTR Guid); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. BIRToStore (input) The BIR to be stored in the open database (either the BIR, or its handle, or the index to it in another open database). DbHandle (input) The handle to the open database. Guid (output) A GUID that uniquely identifies the new BIR in the database. This GUID cannot be changed. To associate a different BIR with the user, it is necessary to delete the old one, store a new one in the database, and then replace the old GUID with the new one in the application account database. DESCRIPTION The BIR identified by the BIRToStore parameter is stored in the open database identified by the DbHandle parameter. If the BIRToStore is identified by a BIR Handle, the input BIR Handle is freed. If the BIRToStore is identified by a database key value, the BIR is copied to the open database. A new GUID is assigned to the new BIR in the database, and this GUID can be used as a key value to access the BIR later. 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL 3 HRS_DbGetBIR NAME CSSM_HRS_DbGetBIR, HRS_DbGetBIR SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_DbGetBIR( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_DB_HANDLE DbHandle, const CSSM_GUID *KeyValue, CSSM_HRS_BIR_HANDLE_PTR RetrievedBIR, CSSM_HRS_DB_CURSOR_PTR Cursor); SPI CSSM_RETURN CSSMHRI HRS_DbGetBIR( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_DB_HANDLE DbHandle, const CSSM_GUID *KeyValue, CSSM_HRS_BIR_HANDLE_PTR RetrievedBIR, CSSM_HRS_DB_CURSOR_PTR Cursor); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. DbHandle (input) The handle to the open database. KeyValue (input) The key into the database of the BIR to retrieve. RetrievedBIR (output) A handle to the retrieved BIR. Cursor (output) A handle that can be used to iterate through the database from the retrieved record. DESCRIPTION The BIR identified by the KeyValue parameter in the open database identified by the DbHandle parameter is retrieved. The BIR is copied into the service provider?s storage and a handle to it is returned. The Cursor is set to point to the next record, or the first record in the database if the retrieved BIR is the last. 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL CSSMERR_HRS_RECORD_NOT_FOUND 3 HRS_DbGetNextBIR NAME CSSM_HRS_DbGetNextBIR, HRS_DbGetNextBIR SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_DbGetNextBIR( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_DB_CURSOR_PTR Cursor, CSSM_HRS_BIR_HANDLE_PTR RetrievedBIR, CSSM_GUID_PTR Guid); SPI CSSM_RETURN CSSMHRI HRS_DbGetNextBIR( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_DB_CURSOR_PTR Cursor, CSSM_HRS_BIR_HANDLE_PTR RetrievedBIR, CSSM_GUID_PTR Guid); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. Cursor (input/output) A handle indicating which record to retrieve. RetrievedBIR (output) A handle to the retrieved BIR. Guid (output) The GUID that uniquely identifies the retrieved BIR in the database. DESCRIPTION The BIR identified by the Cursor parameter is retrieved. The BIR is copied into the service provider?s storage, a handle to it is returned, and a pointer to the GUID that uniquely identifies the BIR in the database is returned. The Cursor is updated to the next record in the database, or to the first when the end of the database is reached. 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL CSSMERR_HRS_CURSOR_IS_INVALID CSSMERR_HRS_END_OF_DATABASE 3 HRS_DbQueryBIR NAME CSSM_HRS_DbQueryBIR, HRS_DbQueryBIR SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_DbQueryBIR( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_DB_HANDLE DbHandle, const CSSM_HRS_INPUT_BIR *BIRToQuery, CSSM_GUID_PTR Guid); SPI CSSM_RETURN CSSMHRI HRS_DbQueryBIR( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_DB_HANDLE DbHandle, const CSSM_HRS_INPUT_BIR *BIRToQuery, CSSM_GUID_PTR Guid); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. DbHandle (input) The handle to the open database. BIRToQuery (input) The BIR to be queried in the open database (either the BIR, or its handle, or the key to it in another open database). Guid (output) The GUID that uniquely identifies the BIR in the database. DESCRIPTION If the BIR identified by the BIRToQuery parameter is in the open database identified by the DbHandle parameter, a pointer to its GUID is returned. Otherwise, CSSMERR_HRS_RECORD_NOT_FOUND is returned. 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL CSSMERR_HRS_RECORD_NOT_FOUND 3 HRS_DbDeleteBIR NAME CSSM_HRS_DbDeleteBIR, HRS_DbDeleteBIR SYNOPSIS #include API CSSM_RETURN CSSMAPI CSSM_HRS_DbDeleteBIR( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_DB_HANDLE DbHandle, const CSSM_GUID *KeyValue); SPI CSSM_RETURN CSSMHRI HRS_DbDeleteBIR( CSSM_HRS_HANDLE ModuleHandle, CSSM_HRS_DB_HANDLE DbHandle, const CSSM_GUID *KeyValue); LIBRARY HRS Extensible Module Manager (CDSA$INHRSEMM_SHR.EXE) PARAMETERS The parameter definitions are the same for the API and the SPI. ModuleHandle (input) The handle of the attached HRS service provider. DbHandle (input) The handle to the open database. KeyValue (input) The GUID of the BIR to be deleted. DESCRIPTION The BIR identified by the KeyValue parameter in the open database identified by the DbHandle parameter is deleted from the database. If there is a cursor set to the deleted BIR, then the cursor is moved to the next sequential BIR (or set to the start of the database if there are no more records). 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 Errors are described in the CDSA Technical Standard. See CDSA. CSSMERR_CSSM_NOT_INITIALIZED CSSMERR_CSSM_FUNCTION_FAILED CSSMERR_CSSM_FUNCTION_NOT_IMPLEMENTED CSSMERR_CSSM_FUNCTION_INTEGRITY_FAIL CSSMERR_HRS_END_OF_DATABASE CSSMERR_HRS_RECORD_NOT_FOUND 3 Initialize NAME Initialize - Verify module version (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI Initialize (uint32 VerMajor, uint32 VerMinor) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS VerMajor (input) The major version number of the CSSM that is invoking this module manager. VerMinor (input) The minor version number of the CSSM that is invoking this module manager. DESCRIPTION This function checks whether the current version of the module is compatible with the CSSM version specified as input and performs any module-manager-specific setup activities. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSSM_MODULE_MANAGER_INITIALIZE_FAIL SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: Terminate 3 MDS_Initialize NAME MDS_Initialize - Initiate service context with MDS (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI MDS_Initialize (const CSSM_GUID *pCallerGuid, const CSSM_DATA *pCallerManifest, const CSSM_MEMORY_FUNCS *pMemoryFunctions, MDS_FUNCS_PTR pDlFunctions, MDS_HANDLE *hMds) LIBRARY Module Directory Services library (CDSA$MDS300_SHR.EXE) PARAMETERS pCallerGuid (input/optional) The GUID of the module calling MDS. pCallerManifest (input/optional) The Manifest of the module calling MDS. pMemoryFunctions (input) The memory-management routines MDS uses to allocate query results on behalf of the caller. pDlFunctions (output) The function table containing MDS programming interfaces for database access. hMds (output) A new handle that can be used to interact with the MDS. The value will be set to CSSM_INVALID_HANDLE if the function fails. DESCRIPTION This function initiates a service context with MDS and returns an opaque handle corresponding to that context. The caller provides memory functions that MDS can use to manage memory in the caller's space on behalf of the caller. The caller also provides input/output table pDlFunctions to get access to MDS databases. If the caller is a CDSA service provider that will require write-access to an MDS database, (such as a module that supports dynamic insertion and removal events), then the caller can provide the caller's GUID as input parameter pCallerGuid. When provided as input, the GUID is associated with the MDS handle and is used during DbOpen processing. If write-access is requested during DbOpen, MDS uses the associated GUID to locate the service provider's signed manifest credentials in the DS Common relation. The service provider module and its credentials are verified to ensure that write-access is permitted on this database by this module. The installers will have to provide the pCallerManifest instead of pCallerGuid, as GUID cannot be used to locate an application unless it is installed. Only one of the two parameters pCallerGuid and pCallerManifest should be non NULL in an MDS_Initialize() call, otherwise an error will be returned. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_DL_INVALID_POINTER CSSMERR_DL_INTERNAL_ERROR CSSMERR_DL_MEMORY_ERROR CSSMERR_DL_FUNCTION_FAILED SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 MDS_Install NAME MDS_Install - Create the object directory database (CDSA) SYNOPSIS #include CSSM_RETURN CSSMAPI MDS_Install (MDS_HANDLE MdsHandle) LIBRARY Module Directory Services library (CDSA$MDS300_SHR.EXE) PARAMETERS MdsHandle (input) The MDS handle identifying an MDS context. DESCRIPTION This function creates the Object Directory database containing the Object relation, and the CDSA Directory database containing the set of CDSA-specific relations defined in this specification. The MdsHandle identifies an MDS context created by invoking MDS_Initialize(). The context contains information about the access rights of the caller. Write-access is required to perform this 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_DL_INVALID_DL_HANDLE CSSMERR_DL_DATASTORE_ALREADY_EXISTS CSSMERR_DL_INVALID_ACCESS_REQUEST CSSMERR_DL_INVALID_DB_LOCATION CSSMERR_DL_INVALID_DB_NAME CSSMERR_DL_INVALID_OPEN_PARAMETERS CSSMERR_DL_INVALID_RECORD_INDEX CSSMERR_DL_INVALID_RECORDTYPE CSSMERR_DL_INVALID_FIELD_NAME CSSMERR_DL_UNSUPPORTED_FIELD_FORMAT CSSMERR_DL_UNSUPPORTED_INDEX_INFO CSSMERR_DL_UNSUPPORTED_LOCALITY CSSMERR_DL_UNSUPPORTED_NUM_ATTRIBUTES CSSMERR_DL_UNSUPPORTED_NUM_INDEXES CSSMERR_DL_UNSUPPORTED_NUM_RECORDTYPES CSSMERR_DL_UNSUPPORTED_RECORDTYPE CSSMERR_DL_FIELD_SPECIFIED_MULTIPLE CSSMERR_DL_INCOMPATIBLE_FIELD_FORMAT CSSMERR_DL_INVALID_PARSING_MODULE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 MDS_Terminate NAME MDS_Terminate - Terminate the MDS service context (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI MDS_Terminate (MDS_HANDLE MdsHandle) LIBRARY Module Directory Services library (CDSA$MDS300_SHR.EXE) PARAMETERS MdsHandle (input) The MDS handle corresponding to the context being terminated. DESCRIPTION This function terminates the MDS service context identified by the opaque MdsHandle. The MDS handle is invalidated and MDS frees all internal resources associated with the context. RETURN 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_DL_INVALID_DL_HANDLE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 MDS_Uninstall NAME MDS_Uninstall - Delete the object directory database (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI MDS_Uninstall (MDS_HANDLE MdsHandle) LIBRARY Module Directory Services library (CDSA$MDS300_SHR.EXE) PARAMETERS MdsHandle (input) The MDS handle identifying a valid MDS context. DESCRIPTION This function deletes the Object Directory database containing the Object relation, and the CDSA Directory database containing the set of CDSA-specific relations defined in this specification. The MdsHandle identifies the MDS context created by invoking MDS_Initialize(). The context contains information about the access rights of the caller. Write-access is required to perform this 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_DL_INVALID_DL_HANDLE CSSMERR_DL_DATASTORE_IS_OPEN CSSMERR_DL_INVALID_DB_LOCATION CSSMERR_DL_INVALID_DB_NAME CSSMERR_DL_DATASTORE_DOESNOT_EXIST SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 ModuleManagerAuthenticate NAME ModuleManagerAuthenticate - Module manager authentication (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI ModuleManagerAuthenticate (CSSM_KEY_HIERARCHY KeyHierarchy, const CSSM_GUID *CssmGuid, const CSSM_GUID *AppGuid, CSSM_MANAGER_REGISTRATION_INFO_PTR FunctionTable) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS KeyHierarchy (input) The CSSM_KEY_HIERARCHY flag indicating which embedded key(s) CSSM should use when verifying the integrity of the module manager. CssmGuid (input) A CSSM_GUID value identifying the calling CSSM. The elective module manager can use this value to locate the signed manifest credentials for CSSM. AppGuid (input/optional) A CSSM_GUID value identifying the application who invoked the calling CSSM. The elective module manager can use this value to locate the signed manifest credentials for the application. FunctionTable (output) A set of function pointers for EMM-defined functions used by CSSM to communicate state changes related to module attach and module detach operations. DESCRIPTION This function should perform the elective module manager's half of the bilateral authentication procedure with CSSM. The CssmGuid is used to locate the CSSM's credentials to be verified. The credentials are a zipped, signed manifest. The KeyHierarchy indicates which public key should be used as the root when checking the integrity of the module manager. The AppGuid is used to locate the application's signed manifest credentials. The elective module manager must check the application's credentials to verify the application's authorization. If no privileges are requested, then the application is not required to provide a GUID nor a set of signed manifest credentials. Upon successful completion, the elective module manager returns its function table to the calling CSSM. The EMM function table contains the set of EMM entry points that CSSM uses to notify the module manager of significant events such as module attach and module detach requests issued by an application, and event notifications issued by other module managers. This function symbol must be exported by the elective module manager, so CSSM can invoke this function upon completion of the loading process. This function is the first module manager interface invoked by CSSM after loading and invoking the main entry point. In particular, the elective module manager's initialize function is invoked by CSSM after this function has successfully completed execution. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 ObtainPrivateKeyFromPublicKey NAME ObtainPrivateKeyFromPublicKey, CSSM_CSP_ObtainPrivateKeyFromPublicKey, CSP_ObtainPrivateKeyFromPublicKey - Convert public key to private key (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CSP_ObtainPrivateKeyFromPublicKey (CSSM_CSP_HANDLE CSPHandle const CSSM_KEY *PublicKey, CSSM_KEY_PTR PrivateKey) SPI: CSSM_RETURN CSSMCSPI CSP_ObtainPrivateKeyFromPublicKey (CSSM_CSP_HANDLE CSPHandle, const CSSM_KEY *PublicKey, CSSM_KEY_PTR PrivateKey) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) 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. DESCRIPTION Given a public key this function returns a reference to the private key. The private key and its associated passphrase can be used as an input to any function requiring a private key value. NOTES The KeyData field of the CSSM_KEY structure is allocated by the CSP. The application is required to free this memory using the CSSM_FreeKey() (CSSM API), or CSP_FreeKey() (CSP SPI), function or with the memory functions registered for the CSPHandle. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_PRIVATE_KEY_NOT_FOUND SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 PassThrough NAME PassThrough, CSSM_CSP_PassThrough, CSP_PassThrough - Extend crypto functionality (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_CSP_PassThrough (CSSM_CC_HANDLE CCHandle, uint32 PassThroughId, const void *InData, void **OutData) SPI: CSSM_RETURN CSSMCSPI CSP_PassThrough (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context, uint32 PassThroughId, const void *InData, void **OutData) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation. PassThroughId (input) An identifier specifying the custom function to be performed. InData (input) A pointer to a module, implementation-specific structure containing the input data. OutData (output) A pointer to a module, implementation-specific structure containing the output data. The service provider will allocate the memory for this structure. The application should free the memory for the structure. SPI PARAMETERS CSPHandle (input) Handle of the CSP supporting the PassThrough function. Context (input) Pointer to CSSM_CONTEXT structure that describes the attributes with this custom context structure. DESCRIPTION The CSSM_CSP_PassThrough() (CSSM API), or CSP_PassThrough() (CSP SPI), function is provided to allow CSP developers to extend the crypto functionality of the CSSM API. NOTES 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. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_INVALID_PASSTHROUGH_ID SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 QueryKeySizeInBits NAME QueryKeySizeInBits, CSSM_QueryKeySizeInBits, CSP_QueryKeySizeInBits - Get CSP logical and effective sizes (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_QueryKeySizeInBits (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_KEY *Key, CSSM_KEY_SIZE_PTR KeySize) SPI: CSSM_RETURN CSSMCSPI CSP_QueryKeySizeInBits (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context, const CSSM_KEY *Key, CSSM_KEY_SIZE_PTR KeySize) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CSPHandle (input/optional) The handle that describes the cryptographic service provider module used to perform this function. For the API, this parameter is ignored if a valid cryptographic context handle is specified. CCHandle (input/optional) A handle to a context that describes a cryptographic operation. The cryptographic context should contain a handle to the CSP that is being queried and the key about which key-size information is being requested. Key (input/optional) A pointer to a CSSM_KEY structure containing the key about which key-size information is being requested. This parameter is ignored if a valid cryptographic context handle is specified. KeySize (output) Pointer to a CSSM_KEY_SIZE data structure. The logical and effective sizes (in bits) for the key are returned in this structure. For the API, if no context handle is provided, only the CSSM_KEY_SIZE LogicalKeySizeInBits field is set. SPI PARAMETERS Context (input) Pointer to CSSM_CONTEXT structure that describes the attributes with this context. DESCRIPTION This function queries a Cryptographic Service Provider (CSP) for the logical and effective sizes of a specified key. The cryptographic service provider (handle) and the key can be specified either in the cryptographic context or as parameters to the function call. If a valid cryptographic context handle parameter is specified, the CSP handle and key parameters are ignored. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_QUERY_SIZE_UNKNOWN SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_GenerateRandom CSSM_GenerateKeyPair CSSM_GenerateKey Functions for the CSP SPI: CSP_GenerateRandom CSP_GenerateKeyPair CSP_GenerateKey 3 QuerySize NAME QuerySize, CSSM_QuerySize, CSP_QuerySize - Get size of the output data (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_QuerySize (CSSM_CC_HANDLE CCHandle, CSSM_BOOL Encrypt, uint32 QuerySizeCount, CSSM_QUERY_SIZE_DATA_PTR DataBlockSizes) SPI: CSSM_RETURN CSSMCSPI CSP_QuerySize (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context, CSSM_BOOL Encrypt, uint32 QuerySizeCount, CSSM_QUERY_SIZE_DATA_PTR DataBlockSizes) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle for an encryption and decryption context. Encrypt (input) A boolean indicating whether encryption is the operation for which the output data size should be calculated. If CSSM_TRUE, the operation is encryption. If CSSM_FALSE the operation is decryption. QuerySizeCount (input) The number of entries in the array of DataBlockSizes. DataBlockSizes (input/output) An array of data block input sizes and corresponding entries for the data block output sizes that are returned by this function. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform calls to CSSM for the memory functions managed by CSSM. Context (input) Pointer to CSSM_CONTEXT structure that describes the attributes with this context. DESCRIPTION This function queries for the size of the output data for a cryptographic operation. If the context is an encryption or decryption context type then the Encrypt parameter will determine which operation is being performed. If Encrypt is set to CSSM_TRUE then it is an encrypt operation, otherwise it is a decrypt operation. For all other context types the Encrypt parameter is ignored. This function can also be used to query the output size requirements for the intermediate steps of a staged cryptographic operation. There may be algorithm-specific and token-specific rules restricting the lengths of data following data update calls. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_QUERY_SIZE_UNKNOWN SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_EncryptData CSSM_EncryptDataUpdate CSSM_DecryptData CSSM_DecryptDataUpdate CSSM_SignData CSSM_VerifyData CSSM_DigestData CSSM_GenerateMac Functions for the CSP SPI: CSP_EncryptData CSP_EncryptDataUpdate CSP_DecryptData CSP_DecryptDataUpdate CSP_SignData CSP_VerifyData CSP_DigestData CSP_GenerateMac 3 RefreshFunctionTable NAME RefreshFunctionTable - Gets EMM-defined API function (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI RefreshFunctionTable (CSSM_FUNC_NAME_ADDR_PTR FuncNameAddrPtr, uint32 NumOfFuncNameAddr) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS FuncNameAddrPtr (input/output) A pointer to a table mapping function names to EMM-defined APIs. NumOfFuncNameAddr (input) The number of entries in the table referenced by FuncNameAddrPtr. DESCRIPTION CSSM invokes this function to obtain the EMM-defined API function. The table is returned to CSSM in FuncNameAddrPtr and CSSM returns the table to the application. The application uses this table to invoke the security services defined by the EMM's service category. CSSM must obtain and forward the API table to the application on behalf of the EMM because the application is not aware of the optional nature of the EMM. Applications use CSSM to obtain the API function table for basic module managers and elective module managers, providing a uniform application programming model. If the Elective Module Manager needs the service provider's SPI function table in order to initialize the API function table, the EMM can obtain the SPI function table by invoking the CSSM-provided service cssm_GetAttachFunctions(). The service module may implement only a subset of the defined functions and the EMM may wish to manage these functions in a particular manner through the API mapping. The elective module manager uses the SPI function table to dispatch application calls for service to attached modules. Multiple applications and multiple instances of a service module can be concurrently active. The single elective module manager is responsible for managing all of these concurrent sessions. After completing initialization of the API function table, the EMM returns the refreshed API table to CSSM. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. ERRORS Errors are described in the CDSA technical standard. See CDSA. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 RegisterDispatchTable NAME RegisterDispatchTable - Provide the EMM with CSSM function pointers (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI RegisterDispatchTable (CSSM_STATE_FUNCS_PTR CssmStateCallTable) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS CssmStateCallTable (input) A table of function pointers for the set of CSSM-defined functions the elective module manager can use to query and control the state of an attach-session between an application and a service provider managed by the module manager. DESCRIPTION This EMM-defined function is invoked by CSSM once for each CSSM_ModuleAttach(), operation requesting a service provider of the type managed by the EMM. CSSM uses this function to provide the EMM with a set of CSSM function pointers. The EMM invokes these functions at anytime during the life cycle of the attach-session to obtain information about the current state and to modify the current state of the attach session. When the attach-session is terminated, CSSM informs the module manager by invoking the EMM function DeregisterDispatchTable(). The corresponding set of CSSM state functions become invalid at that time. 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 Errors are described in the CDSA technical standard. See CDSA. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: DeregisterDispatchTable 3 RetrieveCounter NAME RetrieveCounter, CSSM_RetrieveCounter, CSP_RetrieveCounter - Get the value of a tamper resistant clock (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_RetrieveCounter (CSSM_CSP_HANDLE CSPHandle, CSSM_DATA_PTR Counter) SPI: CSSM_RETURN CSSMCSPI CSP_RetrieveCounter (CSSM_CSP_HANDLE CSPHandle, CSSM_DATA_PTR Counter) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) 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. DESCRIPTION This function returns the value of a tamper resistant clock/counter of the cryptographic device. NOTES ON SPI The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 RetrieveUniqueId NAME RetrieveUniqueId, CSSM_RetrieveUniqueId, CSP_RetrieveUniqueId - Get identifier (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_RetrieveUniqueId (CSSM_CSP_HANDLE CSPHandle, CSSM_DATA_PTR UniqueID) SPI: CSSM_RETURN CSSMCSPI CSP_RetrieveUniqueId (CSSM_CSP_HANDLE CSPHandle, CSSM_DATA_PTR UniqueID) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) 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. 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. NOTES ON SPI The output is returned to the caller as specified in Buffer Management for Cryptographic Services. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 SignData NAME SignData, CSSM_SignData, CSP_SignData - Sign all buffer data (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_SignData (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *DataBufs, uint32 DataBufCount, CSSM_ALGORITHMS DigestAlgorithm, CSSM_DATA_PTR Signature) SPI: CSSM_RETURN CSSMCSPI CSP_SignData (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context, const CSSM_DATA *DataBufs, uint32 DataBufCount, CSSM_ALGORITHMS DigestAlgorithm, CSSM_DATA_PTR Signature) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. DataBufs (input) A pointer to a vector of CSSM_DATA structures that contain the data to be signed. DataBufCount (input) The number of DataBufs to be signed. DigestAlgorithm (input) If signing just a digest, specifies the type of digest. In this case, the context should only specify the encryption algorithm. If not signing just a digest, it must be CSSM_ALGID_NONE. In this case, the context should specify the combination digest/encryption algorithm. Signature (output) A pointer to the CSSM_DATA structure for the signature. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM. Context (input) Pointer to CSSM_CONTEXT structure that describes the attributes with this context. DESCRIPTION This function signs all data contained in the set of input buffers using the private key specified in the context. The CSP can require that the cryptographic context include access credentials for authentication and authorization checks when using a private key or a secret key. Signing can include digesting the data and encrypting the digest or signing just the digest (already calculated by the application). If digesting the data and encrypting the digest, then the context should specify the combination digest/encryption algorithm (for example, CSSM_ALGID_MD5WithRSA). In this case, the DigestAlgorithm parameter must be set to CSSM_ALGID_NONE. If signing just the digest, then the context should specify just the encryption algorithm and the DigestAlgorithm parameter should specify the type of digest (for example, CSSM_ALGID_MD5). Also, DataBufCount must be 1. If the signing algorithm is not reversible or strictly limits the size of the signed data, then the algorithm can specify signing without digesting. In this case, the sign operation is performed on the input data and the size of the input data is restricted by the service provider. NOTES ON API The output is returned to the caller either by filling the caller- specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, preallocated output buffer, the caller must provide an array of one or more CSSM_DATA structures each, containing a Length field value greater than zero and a non-NULL data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value equal to zero and a NULL data pointer field value. The application is always responsible for deallocating the memory when it is no longer needed. NOTES ON SPI The output is returned to the caller as specifed in Buffer Management for Cryptographic Services. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_OUTPUT_LENGTH_ERROR CSSMERR_CSP_INVALID_DIGEST_ALGORITHM SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_VerifyData CSSM_SignDataInit CSSM_SignDataUpdate CSSM_SignDataFinal Functions for the CSP SPI: CSP_VerifyData CSP_SignDataInit CSP_SignDataUpdate CSP_SignDataFinal 3 SignDataFinal NAME SignDataFinal, CSSM_SignDataFinal, CSP_SignDataFinal - Complete the final stage of the sign data (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_SignDataFinal (CSSM_CC_HANDLE CCHandle, CSSM_DATA_PTR Signature) SPI: CSSM_RETURN CSSMCSPI CSP_SignDataFinal (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, CSSM_DATA_PTR Signature) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. Signature (output) A pointer to the CSSM_DATA structure for the signature. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM. DESCRIPTION This function completes the final stage of the sign data function. NOTES ON API The output is returned to the caller either by filling the caller- specified buffer or by using the application's declared memory allocation functions to allocate buffer space. To specify a specific, preallocated output buffer, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value greater than zero and a non-NULL data pointer field value. To specify automatic output buffer allocation by the CSP, the caller must provide an array of one or more CSSM_DATA structures, each containing a Length field value equal to zero and a NULL data pointer field value. The application is always responsible for deallocating the memory when it is no longer needed. NOTES ON SPI The output is returned to the caller as specifed in Buffer Management for Cryptographic Services. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_OUTPUT_LENGTH_ERROR SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_SignData CSSM_SignDataInit CSSM_SignDataUpdate Functions for the CSP SPI: CSP_SignData CSP_SignDataInit CSP_SignDataUpdate 3 SignDataInit NAME SignDataInit, CSSM_SignDataInit, CSP_SignDataInit - Initialize the staged sign data (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_SignDataInit (CSSM_CC_HANDLE CCHandle) SPI: CSSM_RETURN CSSMCSPI CSP_SignDataInit (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM. Context (input) Pointer to CSSM_CONTEXT structure that describes the attributes with this context. DESCRIPTION This function initializes the staged sign data function. For staged operations, a combination operation selecting both a digesting algorithm and a signing algorithm must be specified. The CSP can require that the cryptographic context include access credentials for authentication and authorization checks when using a private key or a secret key. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_SignData CSSM_SignDataUpdate CSSM_SignDataFinal Functions for the CSP SPI: CSP_SignData CSP_SignDataUpdate CSP_SignDataFinal 3 SignDataUpdate NAME SignDataUpdate, CSSM_SignDataUpdate, CSP_SignDataUpdate - Continue the staged signing process input buffer data (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_SignDataUpdate (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *DataBufs, uint32 DataBufCount) SPI: CSSM_RETURN CSSMCSPI CSP_SignDataUpdate (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *DataBufs, uint32 DataBufCount) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. DataBufs (input) A pointer to a vector of CSSM_DATA structures that contain the data to be operated on. DataBufCount (input) The number of DataBufs to be signed. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform calls to CSSM for the memory functions managed by CSSM. 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. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_SignData CSSM_SignDataInit CSSM_SignDataFinal Functions for the CSP SPI: CSP_SignData CSP_SignDataInit CSP_SignDataFinal 3 TP_ApplyCrlToDb NAME TP_ApplyCrlToDb, CSSM_TP_ApplyCrlToDb - Update persistent storage (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_TP_ApplyCrlToDb (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CSP_HANDLE CSPHandle, const CSSM_ENCODED_CRL *CrlToBeApplied, const CSSM_CERTGROUP *SignerCertGroup, const CSSM_TP_VERIFY_CONTEXT *ApplyCrlVerifyContext, CSSM_TP_VERIFY_CONTEXT_RESULT_PTR ApplyCrlVerifyResult) SPI: CSSM_RETURN CSSMTPI TP_ApplyCrlToDb (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CSP_HANDLE CSPHandle, const CSSM_ENCODED_CRL *CrlToBeApplied, const CSSM_CERTGROUP *SignerCertGroup, const CSSM_TP_VERIFY_CONTEXT *ApplyCrlVerifyContext, CSSM_TP_VERIFY_CONTEXT_RESULT_PTR ApplyCrlVerifyResult) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS TPHandle (input) The handle that describes the add-in trust policy module used to perform this function. CLHandle (input/optional) The handle that describes the add-in certificate library module that can be used to manipulate the CRL as it is applied to the data store and to manipulate the certificates effected by the CRL, if required. If no certificate library module is specified, the TP module uses an assumed CL module, if required. CSPHandle (input/optional) The handle referencing a Cryptographic Service Provider to be used to verify signatures on the CRL determining whether to trust the CRL and apply it to the data store. The TP module is responsible for creating the cryptographic context structures required to perform the verification operation. If no CSP is specified, the TP module uses an assumed CSP to perform these operations. If optional, the caller will set this value to 0. CrlToBeApplied (input) A pointer to a structure containing the encoded certificate revocation list to be applied to the data store. The CRL type and encoding are included in this structure. SignerCertGroup (input) A pointer to the CSSM_CERTGROUP structure containing one or more related certificates that partially or fully represent the signer of the certificate revocation list. The first certificate in the group is the target certificate representing the CRL signer. Use of subsequent certificates is specific to the trust domain. For example, in a hierarchical trust model subsequent members are intermediate certificates of a certificate chain. ApplyCrlVerifyContext (input/optional) A structure containing credentials, policy information, and contextual information to be used in the verification process. All of the input values in the context are optional. The service provider can define default values or can attempt to operate without input for all the other fields of this input structure. The operation can fail if a necessary input value is omitted and the service module can not define an appropriate default value. ApplyCrlVerifyResult (output/optional) A pointer to a structure containing information generated during the verification process. The information can include: Evidence (output/optional) NumberOfEvidences (output/optional) DESCRIPTION This function updates persistent storage to reflect entries in the certificate revocation list. The TP module determines whether the memory-resident CRL is trusted, and if it should be applied to one or more of the persistent databases. Side effects of this function can include saving a persistent copy of the CRL in a data store, or removing certificate records from a data store. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_TP_INVALID_CL_HANDLE CSSMERR_TP_INVALID_CSP_HANDLE CSSMERR_TP_INVALID_CRL_TYPE CSSMERR_TP_INVALID_CRL_ENCODING CSSMERR_TP_INVALID_CRL_POINTER CSSMERR_TP_INVALID_CRL CSSMERR_TP_INVALID_CERTGROUP_POINTER CSSMERR_TP_INVALID_CERTGROUP CSSMERR_TP_INVALID_CERTIFICATE CSSMERR_TP_INVALID_ACTION CSSMERR_TP_INVALID_ACTION_DATA CSSMERR_TP_VERIFY_ACTION_FAILED CSSMERR_TP_INVALID_CRLGROUP_POINTER CSSMERR_TP_INVALID_CRLGROUP CSSMERR_TP_INVALID_CRL_AUTHORITY CSSMERR_TP_INVALID_CALLERAUTH_CONTEXT_POINTER CSSMERR_TP_INVALID_POLICY_IDENTIFIERS CSSMERR_TP_INVALID_TIMESTRING CSSMERR_TP_INVALID_STOP_ON_POLICY CSSMERR_TP_INVALID_CALLBACK CSSMERR_TP_INVALID_ANCHOR_CERT CSSMERR_TP_CERTGROUP_INCOMPLETE CSSMERR_TP_INVALID_DL_HANDLE CSSMERR_TP_INVALID_DB_HANDLE CSSMERR_TP_INVALID_DB_LIST_POINTER CSSMERR_TP_INVALID_DB_LIST CSSMERR_TP_AUTHENTICATION_FAILED CSSMERR_TP_INSUFFICIENT_CREDENTIALS CSSMERR_TP_NOT_TRUSTED CSSMERR_TP_CERT_REVOKED CSSMERR_TP_CERT_SUSPENDED CSSMERR_TP_CERT_EXPIRED CSSMERR_TP_CERT_NOT_VALID_YET CSSMERR_TP_INVALID_CERT_AUTHORITY CSSMERR_TP_INVALID_SIGNATURE CSSMERR_TP_INVALID_NAME CSSMERR_TP_CERTIFICATE_CANT_OPERATE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CrlGetFirstItem CSSM_CL_CrlGetNextItem CSSM_DL_CertRevoke Functions for the TP SPI: CL_CrlGetFirstItem CL_CrlGetNextItem DL_CertRevoke 3 TP_CertCreateTemplate NAME TP_CertCreateTemplate, CSSM_TP_CertCreateTemplate - Allocate and initialize template memory (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_TP_CertCreateTemplate (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, uint32 NumberOfFields, const CSSM_FIELD *CertFields, CSSM_DATA_PTR CertTemplate) SPI: CSSM_RETURN CSSMTPI TP_CertCreateTemplate (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, uint32 NumberOfFields, const CSSM_FIELD *CertFields, CSSM_DATA_PTR CertTemplate) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS TPHandle (input) The handle that describes the add-in trust policy module used to perform this function. CLHandle (input) The handle that describes the certificate library module used to perform this function. NumberOfFields (input) The number of certificate field values specified in the CertFields. CertFields (input) A pointer to an array of OID/value pairs that identifies the field values to initialize a new certificate. CertTemplate (output) A pointer to a CSSM_DATA structure that will contain the unsigned certificate template as a result of this function. DESCRIPTION This function allocates and initializes memory for an encoded certificate template output in CertTemplate->Data. The template values are specified by the input OID/value pairs contained in CertFields. The initialization process includes encoding all certificate field values according to the certificate type and certificate template encoding supported by the trust policy library module. The CertTemplate output is an unsigned certificate template in the format supported by the TP. The memory for CertTemplate->Data is allocated by the service provider using the calling application's memory management routines. The application must deallocate the memory. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_TP_INVALID_CL_HANDLE CSSMERR_TP_INVALID_FIELD_POINTER CSSMERR_TP_UNKNOWN_TAG CSSMERR_TP_INVALID_NUMBER_OF_FIELDS SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_TP_CertGetAllTemplateFields CSSM_TP_CertSign Functions for the TP SPI: TP_CertGetAllTemplateFields TP_CertSign 3 TP_CertGetAllTemplateFields NAME TP_CertGetAllTemplateFields, CSSM_TP_CertGetAllTemplateFields - Get CertTemplate field values (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_TP_CertGetAllTemplateFields (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, const CSSM_DATA *CertTemplate, uint32 *NumberOfFields, CSSM_FIELD_PTR *CertFields) SPI: CSSM_RETURN CSSMTPI TP_CertGetAllTemplateFields (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, const CSSM_DATA *CertTemplate, uint32 *NumberOfFields, CSSM_FIELD_PTR *CertFields) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS TPHandle (input) The handle that describes the add-in trust policy module used to perform this function. CLHandle (input) The handle that describes the certificate library module used to perform this function. CertTemplate (input) A pointer to the CSSM_DATA structure containing the packed, encoded certificate template. NumberOfFields (output) The length of the output array of fields. CertFields (output) A pointer to an array of CSSM_FIELD structures which contains the OIDs and values of the fields of the input certificate template. DESCRIPTION This function extracts and returns all field values from CertTemplate. The CertTemplate parameter is an unsigned certificate template in the format supported by the TP. Fields are returned as a set of OID-value pairs. The OID identifies the TP certificate template field and the data format of the value extracted from that field. The Trust Policy module defines and uses a preferred data format for returning field values from this function. Memory for the CertFields output is allocated by the service provider using the calling application's memory management routines. The application must deallocate the memory, by calling CSSM_CL_FreeFields() (CSSM API), or CL_FreeFields() (TP SPI). 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_TP_INVALID_CL_HANDLE CSSMERR_TP_INVALID_FIELD_POINTER CSSMERR_TP_UNKNOWN_FORMAT SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_TP_CertCreateTemplate CSSM_TP_CertSign Functions for the TP SPI: TP_CertCreateTemplate TP_CertSign 3 TP_CertGroupConstruct NAME TP_CertGroupConstruct, CSSM_TP_CertGroupConstruct - Construct credential (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_TP_CertGroupConstruct (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CSP_HANDLE CSPHandle, const CSSM_DL_DB_LIST *DBList, const void *ConstructParams, const CSSM_CERTGROUP *CertGroupFrag, CSSM_CERTGROUP_PTR *CertGroup) SPI: CSSM_RETURN CSSMTPI TP_CertGroupConstruct (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CSP_HANDLE CSPHandle, const CSSM_DL_DB_LIST *DBList, const void *ConstructParams, const CSSM_CERTGROUP *CertGroupFrag, CSSM_CERTGROUP_PTR *CertGroup) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS TPHandle (input) The handle to the trust policy module to perform this operation. CLHandle (input/optional) The handle to the certificate library module that can be used to manipulate and parse values in stored in the certgroup certificates. If no certificate library module is specified, the TP module uses an assumed CL module. CSPHandle (input./optional) A handle specifying the Cryptographic Service Provider to be used to verify certificates as the certificate group is constructed. If the a CSP handle is not specified, the trust policy module can assume a default CSP. If the module cannot assume a default, or the default CSP is not available on the local system, an error occurs. DBList (input) A list of handle pairs specifying a data storage library module and a data store, identifying certificate databases containing certificates (and possibly other security objects) that are managed by that module. certificates (and possibly other security objects). The data stores should be searched to complete construction of a semantically-related certificate group. ConstructParams (input/optional) A pointer to data that can be used by the add-in trust policy module in constructing the CertGroup. The semantics of this parameter are defined by the trust policy and the credential model supported by that policy. The input parameter can consist of a set of values, each guiding some aspect of the construction process. Parameter values can: · Limit the certificates that are added to the constructed set. · Identify other sources of certificates for inclusion in the constructed set. CertGroupFrag (input) A list of certificates that form a possibly incomplete set of certificates. The first certificate in the group represents the target certificate for which a group of semantically related certificates will be assembled. Subsequent intermediate certificates can be supplied by the caller. They need not be in any particular order. CertGroup (output) A pointer to a complete certificate group based on the original subset of certificates and the certificate data stores. The CSSM_CERTGROUP and its sub-structure is allocated by the service provider and must be deallocated by the application. DESCRIPTION This function builds a collection of certificates that together make up a meaningful credential for a given trust domain. For example, in a hierarchical trust domain, a certificate group is a chain of certificates from an end entity to a top level certification authority. The constructed certificate group format (such as ordering) is implementation specific. However, the subject or end-entity is always the first certificate in the group. A partially constructed certificate group is specified in CertGroupFrag. The first certificate is interpreted to be the subject or end-entity certificate. Subsequent certificates in the CertGroupFrag structure may be used during the construction of a certificate group in conjunction with certificates found in the data stores specified in DBList. The trust policy defines the certificates that will be included in the resulting set. The output set is a sequence of certificates ordered by the relationship among them. The result set can be augmented by adding semantically-related certificates obtained by searching the certificate data stores specified in DBList. The data stores are searched in order of appearance in DBList. If the TP supports a hierarchical model of certificates, the function output is an uninterrupted, ordered chain of certificates based on the first certificate as the leaf of the certificate chain. If the certificate is multiply-signed, then the ordered chain will follow the first signing certificate. The function should also detect cross- certificate pairs and should include both certificates without duplicating either certificate. Extraneous certificates in the CertGroupFrag fragment or contained in the DBList data stores are ignored. The certificate group returned by this function can be used as input to the function CSSM_TP_CertGroupVerify() (CSSM API), or TP_CertGroupVerify() (TP SPI). The constructed certificate group can be consistent locally or globally. Consistency can be limited to the local system if locally- defined points of trust are inserted into the group. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_TP_INVALID_CL_HANDLE CSSMERR_TP_INVALID_CSP_HANDLE CSSMERR_TP_INVALID_DL_HANDLE CSSMERR_TP_INVALID_DB_HANDLE CSSMERR_TP_INVALID_DB_LIST_POINTER CSSMERR_TP_INVALID_DB_LIST CSSMERR_TP_INVALID_CERTGROUP_POINTER CSSMERR_TP_INVALID_CERTGROUP CSSMERR_TP_INVALID_CERTIFICATE CSSMERR_TP_CERTGROUP_INCOMPLETE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_TP_CertGroupPrune CSSM_TP_CertGroupVerify Functions for the TP SPI: TP_CertGroupPrune TP_CertGroupVerify 3 TP_CertGroupPrune NAME TP_CertGroupPrune, CSSM_TP_CertGroupPrune - Remove locally issued anchor certificates (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_TP_CertGroupPrune (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, const CSSM_DL_DB_LIST *DBList, const CSSM_CERTGROUP *OrderedCertGroup, CSSM_CERTGROUP_PTR *PrunedCertGroup) SPI: CSSM_RETURN CSSMTPI TP_CertGroupPrune (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, const CSSM_DL_DB_LIST *DBList, const CSSM_CERTGROUP *OrderedCertGroup, CSSM_CERTGROUP_PTR *PrunedCertGroup) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS TPHandle (input) The handle to the trust policy module to perform this operation. CLHandle (input/optional) The handle to the certificate library module that can be used to manipulate and parse the certgroup certificates and the certificates in the specified data stores. If no certificate library module is specified, the TP module uses an assumed CL module. DBList (input) A list of handle pairs specifying a data storage library module and a data store, identifying certificate databases containing certificates (and possibly other security objects) that are managed by that module. The data stores are searched for anchor certificates restricted to have local scope. These certificates are candidates for removal from the subject certificate group. OrderedCertGroup (input) The initial complete set of semantically-related certificates - for example, the result of a CSSM_TP_CertGroupConstruct() (CSSM API), or TP_CertGroupConstruct() (TP SPI), call - from which certificates will be selectively removed. PrunedCertGroup (output) A pointer to a certificate group containing those certificates which are verifiable credentials outside of the local system. The CSSM_CERTGROUP and its substructure is allocated by the service provider and must be deallocated by the application. DESCRIPTION This function removes any locally issued anchor certificates from a constructed certificate group. The prune operation can remove those certificates that have been signed by any local certificate authority, as it is possible that these certificates will not be meaningful on other systems. This operation can also remove additional certificates that can be added to the certificate group again using the CSSM_TP_CertGroupConstruct() (CSSM API), or TP_CertGroupConstruct() (TP SPI), operation. The pruned certificate group should be suitable for export to external hosts/entities, which can in turn reconstruct and verify the certificate group. The DBList parameter specifies a set of data stores containing certificates that should be pruned from the group. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_TP_INVALID_CL_HANDLE CSSMERR_TP_INVALID_DL_HANDLE CSSMERR_TP_INVALID_DB_HANDLE CSSMERR_TP_INVALID_DB_LIST_POINTER CSSMERR_TP_INVALID_DB_LIST CSSMERR_TP_INVALID_CERTGROUP_POINTER CSSMERR_TP_INVALID_CERTGROUP CSSMERR_TP_INVALID_CERTIFICATE CSSMERR_TP_CERTGROUP_INCOMPLETE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_TP_CertGroupConstruct CSSM_TP_CertGroupVerify Functions for the TP SPI: TP_CertGroupConstruct TP_CertGroupVerify 3 TP_CertGroupToTupleGroup NAME TP_CertGroupToTupleGroup, CSSM_TP_CertGroupToTupleGroup - Create a set of authorization tuples (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_TP_CertGroupToTupleGroup (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, const CSSM_CERTGROUP *CertGroup, CSSM_TUPLEGROUP_PTR *TupleGroup) SPI: CSSM_RETURN CSSMTPI TP_CertGroupToTupleGroup (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, const CSSM_CERTGROUP *CertGroup, CSSM_TUPLEGROUP_PTR *TupleGroup) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS TPHandle (input) The handle that describes the trust policy service module used to perform this function. CLHandle (input/optional) The handle that describes the certificate library module that can be used to scan the certificate fields for values. If no certificate library module is specified, the TP module uses an assumed CL module. CertGroup (input) A group of certificates in the native certificate format supported by the Trust Policy module. The certificates carry authorizations for one or more certificate subjects. TupleGroup (output) A pointer to a structure containing references to one or more tuples resulting from the translation process. Storage for structure and the tuples is allocated by the service provider and must be deallocated by the application. DESCRIPTION This function creates a set of authorization tuples based on a set of input certificates. The certificates must be of the type managed by the Trust Policy module. The trust policy module may require that the input certificates be successfully verified before being translated to tuples. It is assumed that the certificates carry authorizations. The trust policy service provider interprets the certificate authorization fields and generates one or more tuples corresponding to those authorizations. The certificates of the type managed by the Trust Policy module. The resulting tuples can be input to an authorization evaluation function, such as CSSM_AC_AuthCompute() (CSSM API), or AC_AuthCompute() (AC SPI), which determines whether a particular action is authorized under a basic set of authorization assumptions. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_TP_INVALID_CL_HANDLE CSSMERR_TP_INVALID_CERTGROUP_POINTER CSSMERR_TP_INVALID_CERTGROUP SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_TP_TupleGroupToCertGroup CSSM_AC_AuthCompute Functions for the TP SPI: TP_TupleGroupToCertGroup AC_AuthCompute 3 TP_CertGroupVerify NAME TP_CertGroupVerify, CSSM_TP_CertGroupVerify - Determine if a certificate is trusted (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_TP_CertGroupVerify (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CSP_HANDLE CSPHandle, const CSSM_CERTGROUP *CertGroupToBeVerified, const CSSM_TP_VERIFY_CONTEXT *VerifyContext, CSSM_TP_VERIFY_CONTEXT_RESULT_PTR VerifyContextResult) SPI: CSSM_RETURN CSSMTPI TP_CertGroupVerify (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CSP_HANDLE CSPHandle, const CSSM_CERTGROUP *CertGroupToBeVerified, const CSSM_TP_VERIFY_CONTEXT *VerifyContext, CSSM_TP_VERIFY_CONTEXT_RESULT_PTR VerifyContextResult) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS TPHandle (input) The handle that describes the add-in trust policy module used to perform this function. CLHandle (input/optional) The handle that describes the add-in certificate library module that can be used to manipulate the subject certificate and anchor certificates. If no certificate library module is specified, the TP module uses an assumed CL module, if required. CSPHandle (input/optional) The handle that describes the add-in cryptographic service provider module that can be used to perform the cryptographic operations required to carry out the verification. If no CSP handle is specified, the TP module allocates a suitable CSP. CertGroupToBeVerified (input) A group of one or more certificates to be verified. The first certificate in the group is the primary target certificate for verification. Use of the subsequent certificates during the verification process is specific to the trust domain. VerifyContext (input/optional) A structure containing credentials, policy information, and contextual information to be used in the verification process. All of the input values in the context are optional except Action. The service provider can define default values or can attempt to operate without input for all the other fields of this input structure. The operation can fail if a necessary input value is omitted and the service module can not define an appropriate default value. VerifyContextResult (output/optional) A pointer to a structure containing information generated during the verification process. The information can include: Evidence (output/optional) NumberOfEvidences (output/optional) DESCRIPTION This function determines whether the certificate is trusted. The actions performed by this function differ based on the trust policy domain. The factors include practices, procedures and policies defined by the certificate issuer. Typically certificate verification involves the verification of multiple certificates. The first certificate in the group is the target of the verification process. The other certificates in the group are used in the verification process to connect the target certificate with one or more anchors of trust. The supporting certificates can be contained in the provided certificate group or can be stored in the data stores specified in the VerifyContext DBList. This allows the trust policy module to construct a certificate group and perform verification in one operation. The data stores specified by DBList can also contain certificate revocation lists used in the verification process. It is also possible to provide a data store of anchor certificates. Typically the points of Trust are few in number and are embedded in the caller or in the TPM during software manufacturing or at runtime The caller can select to be notified incrementally as each certificate is verified. The CallbackWithVerifiedCert parameter (in the VerifyContext) can specify a caller function to be invoked at the end of each certificate verification, returning the verified certificate for use by the caller. Anchor certificates are a list of implicitly trusted certificates. These include root certificates, cross certified certificates, and locally defined sources of trust. These certificates form the basis to determine trust in the subject certificate. A policy identifier can specify an additional set of conditions that must be satisfied by the subject certificate in order to meet the trust criteria. The name space for policy identifiers is defined by the application domains to which the policy applies. This is outside of CSSM. A list of policy identifiers can be specified and the stopping condition for evaluating that set of conditions. The evaluation and verification process can produce a list of evidence. The evidence can be selected values from the certificates examined in the verification process, entire certificates from the process or other pertinent information that forms an audit trail of the verification process. This evidence is returned to the caller after all steps in the verification process have been completed. If verification succeeds, the trust policy module may carry out the action on the specified data or may return approval for the action requiring the caller to perform the action. The caller must consult TP module documentation outside of this specification to determine all module-specific side effects of this 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_TP_INVALID_CL_HANDLE CSSMERR_TP_INVALID_CSP_HANDLE CSSMERR_TP_INVALID_CERTGROUP_POINTER CSSMERR_TP_INVALID_CERTGROUP CSSMERR_TP_INVALID_CERTIFICATE CSSMERR_TP_INVALID_ACTION CSSMERR_TP_INVALID_ACTION_DATA CSSMERR_TP_VERIFY_ACTION_FAILED CSSMERR_TP_INVALID_CRLGROUP_POINTER CSSMERR_TP_INVALID_CRLGROUP CSSMERR_TP_INVALID_CRL_AUTHORITY CSSMERR_TP_INVALID_CALLERAUTH_CONTEXT_POINTER CSSMERR_TP_INVALID_POLICY_IDENTIFIERS CSSMERR_TP_INVALID_TIMESTRING CSSMERR_TP_INVALID_STOP_ON_POLICY CSSMERR_TP_INVALID_CALLBACK CSSMERR_TP_INVALID_ANCHOR_CERT CSSMERR_TP_CERTGROUP_INCOMPLETE CSSMERR_TP_INVALID_DL_HANDLE CSSMERR_TP_INVALID_DB_HANDLE CSSMERR_TP_INVALID_DB_LIST_POINTER CSSMERR_TP_INVALID_DB_LIST CSSMERR_TP_AUTHENTICATION_FAILED CSSMERR_TP_INSUFFICIENT_CREDENTIALS CSSMERR_TP_NOT_TRUSTED CSSMERR_TP_CERT_REVOKED CSSMERR_TP_CERT_SUSPENDED CSSMERR_TP_CERT_EXPIRED CSSMERR_TP_CERT_NOT_VALID_YET CSSMERR_TP_INVALID_CERT_AUTHORITY CSSMERR_TP_INVALID_SIGNATURE CSSMERR_TP_INVALID_NAME SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 TP_CertReclaimAbort NAME TP_CertReclaimAbort, CSSM_TP_CertReclaimAbort - Terminate the process of reclaiming certificates (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_TP_CertReclaimAbort (CSSM_TP_HANDLE TPHandle, CSSM_LONG_HANDLE KeyCacheHandle) SPI: CSSM_RETURN CSSMTPI TP_CertReclaimAbort (CSSM_TP_HANDLE TPHandle, CSSM_LONG_HANDLE KeyCacheHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS TPHandle (input) The handle that describes the service provider module used to perform this function. KeyCacheHandle (input) An opaque handle that identifies the cache of protected private keys reclaimed from a certificate authority for potentially recovery on the local system. DESCRIPTION This function terminates the iterative process of reclaiming certificates and recovering their associated private keys from a protected key cache. This function must be called even if all private keys are recovered from the cache. This function destroys all intermediate state and secret information used during the reclamation process. At completion of this function, the cache handle is invalid. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_TP_INVALID_KEYCACHE_HANDLE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_TP_CertReclaimKey Functions for the TP SPI: TP_CertReclaimKey 3 TP_CertReclaimKey NAME TP_CertReclaimKey, CSSM_TP_CertReclaimKey - Get private key associated with a certificate (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_TP_CertReclaimKey (CSSM_TP_HANDLE TPHandle, const CSSM_CERTGROUP *CertGroup, uint32 CertIndex, CSSM_LONG_HANDLE KeyCacheHandle, CSSM_CSP_HANDLE CSPHandle, const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry) SPI: CSSM_RETURN CSSMTPI TP_CertReclaimKey (CSSM_TP_HANDLE TPHandle, const CSSM_CERTGROUP *CertGroup, uint32 CertIndex, CSSM_LONG_HANDLE KeyCacheHandle, CSSM_CSP_HANDLE CSPHandle, const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS TPHandle (input) The handle that describes the service provider module used to perform this operation. CertGroup (input) A pointer to a structure containing a reference to a group of certificates and the number of certificates contained in that group. The certificate group contains all certificates that are candidates for reclamation. CertIndex (input) An index value that identifies the certificate whose associated private key is to be recovered and stored in the local CSP. This index value I references the I-th certificate in CertGroup. KeyCacheHandle (input) A reference handle that uniquely identifies the cache of protected private keys associated with the reclaimed certificates contained in CertGroup. The structure of the cache is opaque to the caller. CSPHandle (input) The handle that describes the CSP module where the private key is to be stored. Optionally, the CA service provider can use this CSP to perform additional cryptographic operations or may use another default CSP for that purpose. 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. DESCRIPTION This function recovers the private key associated with a certificate and securely stores that key in the specified cryptographic service provider. The key and its associated certificate are among a set of certificates and private keys reclaimed from a certificate authority. The particular private key to be recovered to the local system is identified by its associated certificate. The certificate is identified by its CertIndex position within the CertGroup. The reclamation process associates the private key with the public key contained in the certificate, and securely stores the private key in the specified cryptographic service provider. The CSP can require that the caller provide access credentials authorizing inserting a new key into the CSP through an UnwrapKey operation. The caller should also provide an initial Access Control List (ACL) entry for the newly inserted key. The ACL entry is used to control future use of the recovered private key. These inputs are provided in CredAndAclEntry. When all required private keys have been reclaimed, the key cache can be discarded using the function CSSM_TP_CertReclaimAbort() (CSSM API), or TP_CertReclaimAbort() (TP SPI). The caller must free the CertGroup when it is no longer needed. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_TP_INVALID_CERTGROUP_POINTER CSSMERR_TP_INVALID_CERTGROUP CSSMERR_TP_INVALID_CERTIFICATE CSSMERR_TP_INVALID_INDEX CSSMERR_TP_INVALID_KEYCACHE_HANDLE CSSMERR_TP_INVALID_CSP_HANDLE CSSMERR_TP_AUTHENTICATION_FAILED CSSMERR_TP_INSUFFICIENT_CREDENTIALS SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_TP_RetrieveCredResult CSSM_TP_Cert_ReclaimAbort Functions for the TP SPI: TP_RetrieveCredResult TP_Cert_ReclaimAbort 3 TP_CertRemoveFromCrlTemplate NAME TP_CertRemoveFromCrlTemplate, CSSM_TP_CertRemoveFromCrlTemplate - Determine if the revoking certificate group can remove the subject certificate group from the CRL template (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_TP_CertRemoveFromCrlTemplate (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CSP_HANDLE CSPHandle, const CSSM_DATA *OldCrlTemplate, const CSSM_CERTGROUP *CertGroupToBeRemoved, const CSSM_CERTGROUP *RevokerCertGroup, const CSSM_TP_VERIFY_CONTEXT *RevokerVerifyContext, CSSM_TP_VERIFY_CONTEXT_RESULT_PTR RevokerVerifyResult, CSSM_DATA_PTR NewCrlTemplate) SPI: CSSM_RETURN CSSMTPI TP_CertRemoveFromCrlTemplate (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CSP_HANDLE CSPHandle, const CSSM_DATA *OldCrlTemplate, const CSSM_CERTGROUP *CertGroupToBeRemoved, const CSSM_CERTGROUP *RevokerCertGroup, const CSSM_TP_VERIFY_CONTEXT *RevokerVerifyContext, CSSM_TP_VERIFY_CONTEXT_RESULT_PTR RevokerVerifyResult, CSSM_DATA_PTR NewCrlTemplate) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS TPHandle (input) The handle that describes the add-in trust policy module used to perform this function. CLHandle (input/optional) The handle that describes the add-in certificate library module used to perform this function. CSPHandle (input/optional) The handle that describes the add-in cryptographic service provider module used to perform this function. OldCrlTemplate (input/optional) A pointer to the CSSM_DATA structure containing an existing certificate revocation list. If this input is NULL, a new list is created or the operation fails. CertGroupToBeRemoved (input) A group of one or more certificates to be removed from the the CRL template. RevokerCertGroup (input) A group of one or more certificates that partially or fully represent the revoking entity for this operation. The first certificate in the group is the target certificate representing the revoker. The use of subsequent certificates is specific to the trust domain. RevokerVerifyContext (input) A structure containing policy elements useful in verifying certificates and their use with respect to a security policy. Optional elements in the verify context left unspecified will cause the internal default values to be used. Default values are specified in the TP module vendor release documents. This context is used to verify the revoker certificate group. RevokerVerifyResult (output/optional) A pointer to a structure containing information generated during the verification process. The information can include: Evidence (output/optional) NumberOfEvidences (output/optional) NewCrlTemplate (output) A pointer to the CSSM_DATA structure containing the updated certificate revocation list. If the pointer is NULL, an error has occurred. DESCRIPTION The TP module determines whether the revoking certificate group can remove the subject certificate group from the CRL template. The revoker certificate group is first authenticated and its applicability to perform this operation is determined. Once the trust is established, the TP removes the certificates from the CRL template. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_TP_INVALID_CL_HANDLE CSSMERR_TP_INVALID_CSP_HANDLE CSSMERR_TP_INVALID_CRL_POINTER CSSMERR_TP_INVALID_CRL CSSMERR_TP_UNKNOWN_FORMAT CSSMERR_TP_CRL_ALREADY_SIGNED CSSMERR_TP_INVALID_CERTGROUP_POINTER CSSMERR_TP_INVALID_CERTGROUP CSSMERR_TP_INVALID_CERTIFICATE CSSMERR_TP_INVALID_ACTION CSSMERR_TP_INVALID_ACTION_DATA CSSMERR_TP_VERIFY_ACTION_FAILED CSSMERR_TP_INVALID_CRLGROUP_POINTER CSSMERR_TP_INVALID_CRLGROUP CSSMERR_TP_INVALID_CRL_AUTHORITY CSSMERR_TP_INVALID_CALLERAUTH_CONTEXT_POINTER CSSMERR_TP_INVALID_POLICY_IDENTIFIERS CSSMERR_TP_INVALID_TIMESTRING CSSMERR_TP_INVALID_STOP_ON_POLICY CSSMERR_TP_INVALID_CALLBACK CSSMERR_TP_INVALID_ANCHOR_CERT CSSMERR_TP_CERTGROUP_INCOMPLETE CSSMERR_TP_INVALID_DL_HANDLE CSSMERR_TP_INVALID_DB_HANDLE CSSMERR_TP_INVALID_DB_LIST_POINTER CSSMERR_TP_INVALID_DB_LIST CSSMERR_TP_AUTHENTICATION_FAILED CSSMERR_TP_INSUFFICIENT_CREDENTIALS CSSMERR_TP_NOT_TRUSTED CSSMERR_TP_CERT_REVOKED CSSMERR_TP_CERT_SUSPENDED CSSMERR_TP_CERT_EXPIRED CSSMERR_TP_CERT_NOT_VALID_YET CSSMERR_TP_INVALID_CERT_AUTHORITY CSSMERR_TP_INVALID_SIGNATURE CSSMERR_TP_INVALID_NAME CSSMERR_TP_CERTIFICATE_CANT_OPERATE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CrlAddCert Functions for the TP SPI: CL_CrlAddCert 3 TP_CertRevoke NAME TP_CertRevoke, CSSM_TP_CertRevoke - Determine if the revoking certificate group can revoke the subject certificate group (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_TP_CertRevoke (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CSP_HANDLE CSPHandle, const CSSM_DATA *OldCrlTemplate, const CSSM_CERTGROUP *CertGroupToBeRevoked, const CSSM_CERTGROUP *RevokerCertGroup, const CSSM_TP_VERIFY_CONTEXT *RevokerVerifyContext, CSSM_TP_VERIFY_CONTEXT_RESULT_PTR RevokerVerifyResult, CSSM_TP_CERTCHANGE_REASON Reason, CSSM_DATA_PTR NewCrlTemplate) SPI: CSSM_RETURN CSSMTPI TP_CertRevoke (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CSP_HANDLE CSPHandle, const CSSM_DATA *OldCrlTemplate, const CSSM_CERTGROUP *CertGroupToBeRevoked, const CSSM_CERTGROUP *RevokerCertGroup, const CSSM_TP_VERIFY_CONTEXT *RevokerVerifyContext, CSSM_TP_VERIFY_CONTEXT_RESULT_PTR RevokerVerifyResult, CSSM_TP_CERTCHANGE_REASON Reason, CSSM_DATA_PTR NewCrlTemplate) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS TPHandle (input) The handle that describes the add-in trust policy module used to perform this function. CLHandle (input/optional) The handle that describes the add-in certificate library module used to perform this function. CSPHandle (input/optional) The handle that describes the add-in cryptographic service provider module used to perform this function. OldCrlTemplate (input/optional) A pointer to the CSSM_DATA structure containing an existing certificate revocation list. If this input is NULL, a new list is created or the operation fails. CertGroupToBeRevoked (input) A group of one or more certificates that partially or fully represent the certificate to be revoked by this operation. The first certificate in the group is the target certificate. The use of subsequent certificates is specific to the trust domain. For example, in a hierarchical trust model subsequent members are intermediate certificates of a certificate chain. RevokerCertGroup (input) A group of one or more certificates that partially or fully represent the revoking entity for this operation. The first certificate in the group is the target certificate representing the revoker. The use of subsequent certificates is specific to the trust domain. RevokerVerifyContext (input) A structure containing policy elements useful in verifying certificates and their use with respect to a security policy. Optional elements in the verify context left unspecified will cause the internal default values to be used. Default values are specified in the TP module vendor release documents. This context is used to verify the revoker certificate group. RevokerVerifyResult (output/optional) A pointer to a structure containing information generated during the verification process. The information can include: Evidence (output/optional) NumberOfEvidences (output/optional) Reason (input/optional) The reason for revoking the subject certificate. NewCrlTemplate (output/optional) A pointer to the CSSM_DATA structure containing the updated certificate revocation list. If the pointer is NULL, an error has occurred. DESCRIPTION The TP module determines whether the revoking certificate group can revoke the subject certificate group. The revoker certificate group is first authenticated and its applicability to perform this operation is determined. Once the trust is established, the TP revokes the subject certificate by adding it to the certificate revocation list. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_TP_INVALID_CL_HANDLE CSSMERR_TP_INVALID_CSP_HANDLE CSSMERR_TP_INVALID_CRL_POINTER CSSMERR_TP_INVALID_CRL CSSMERR_TP_UNKNOWN_FORMAT CSSMERR_TP_CRL_ALREADY_SIGNED CSSMERR_TP_INVALID_CERTGROUP_POINTER CSSMERR_TP_INVALID_CERTGROUP CSSMERR_TP_INVALID_CERTIFICATE CSSMERR_TP_INVALID_ACTION CSSMERR_TP_INVALID_ACTION_DATA CSSMERR_TP_VERIFY_ACTION_FAILED CSSMERR_TP_INVALID_CRLGROUP_POINTER CSSMERR_TP_INVALID_CRLGROUP CSSMERR_TP_INVALID_CRL_AUTHORITY CSSMERR_TP_INVALID_CALLERAUTH_CONTEXT_POINTER CSSMERR_TP_INVALID_POLICY_IDENTIFIERS CSSMERR_TP_INVALID_TIMESTRING CSSMERR_TP_INVALID_STOP_ON_POLICY CSSMERR_TP_INVALID_CALLBACK CSSMERR_TP_INVALID_ANCHOR_CERT CSSMERR_TP_CERTGROUP_INCOMPLETE CSSMERR_TP_INVALID_DL_HANDLE CSSMERR_TP_INVALID_DB_HANDLE CSSMERR_TP_INVALID_DB_LIST_POINTER CSSMERR_TP_INVALID_DB_LIST CSSMERR_TP_AUTHENTICATION_FAILED CSSMERR_TP_INSUFFICIENT_CREDENTIALS CSSMERR_TP_NOT_TRUSTED CSSMERR_TP_CERT_REVOKED CSSMERR_TP_CERT_SUSPENDED CSSMERR_TP_CERT_EXPIRED CSSMERR_TP_CERT_NOT_VALID_YET CSSMERR_TP_INVALID_CERT_AUTHORITY CSSMERR_TP_INVALID_SIGNATURE CSSMERR_TP_INVALID_NAME CSSMERR_TP_CERTIFICATE_CANT_OPERATE CSSMERR_TP_INVALID_REASON SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CrlAddCert Functions for the TP SPI: CL_CrlAddCert 3 TP_CertSign NAME TP_CertSign, CSSM_TP_CertSign - Determine if signer certificate is trusted (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_TP_CertSign (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *CertTemplateToBeSigned, const CSSM_CERTGROUP *SignerCertGroup, const CSSM_TP_VERIFY_CONTEXT *SignerVerifyContext, CSSM_TP_VERIFY_CONTEXT_RESULT_PTR SignerVerifyResult, CSSM_DATA_PTR SignedCert) SPI: CSSM_RETURN CSSMTPI TP_CertSign (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *CertTemplateToBeSigned, const CSSM_CERTGROUP *SignerCertGroup, const CSSM_TP_VERIFY_CONTEXT *SignerVerifyContext, CSSM_TP_VERIFY_CONTEXT_RESULT_PTR SignerVerifyResult, CSSM_DATA_PTR SignedCert) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS TPHandle (input) The handle that describes the add-in trust policy module used to perform this function. CLHandle (input/optional) The handle that describes the add-in certificate library module used to perform this function. CCHandle (input/optional) The handle that describes the cryptographic context for signing the certificate. This context also identifies the cryptographic service provider to be used to perform the signing operation. If this handle is not provided by the caller, the trust policy module can assume a default signing algorithm and a default CSP. If the trust policy module does not assume defaults or the default CSP is not available on the local system, an error occurs. CertTemplateToBeSigned (input) A pointer to a structure containing a certificte template to be signed. The CRL type and encoded are included in this structure. SignerCertGroup (input) A group of one or more certificates that partially or fully represent the signer for this operation. The first certificate in the group is the target certificate representing the signer. Use of subsequent certificates is specific to the trust domain. For example, in a hierarchical trust model subsequent members are intermediate certificates of a certificate chain. SignerVerifyContext (input/optional) A structure containing credentials, policy information, and contextual information to be used in the verification process. All of the input values in the context are optional. The service provider can define default values or can attempt to operate without input for all the other fields of this input structure. The operation can fail if a necessary input value is omitted and the service module can not define an appropriate default value. SignerVerifyResult (output/optional) A pointer to a structure containing information generated during the verification process. The information can include: Evidence (output/optional) NumberOfEvidences (output/optional) SignedCert (output) A pointer to the CSSM_DATA structure containing the signed certificate. The SignedCert->Data is allocated by the service provider and must be deallocated by the application. DESCRIPTION The TP module decides whether the signer certificate is trusted to sign the CertTemplateToBeSigned. The signer certificate group is first authenticated and its applicability to perform this operation is determined. Once the trust is established, this operation signs the entire certificate. The caller must provide a credential that permits the caller to use the private key for this signing operation. The credential can be provided in the cryptographic context CCHandle. If CCHandle is NULL, the credentials in the SignerVerifyContext specify the credential value. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_TP_INVALID_CL_HANDLE CSSMERR_TP_INVALID_CONTEXT_HANDLE CSSMERR_TP_INVALID_CERTGROUP_POINTER CSSMERR_TP_INVALID_CERTGROUP CSSMERR_TP_INVALID_CERTIFICATE CSSMERR_TP_UNKNOWN_FORMAT CSSMERR_TP_INVALID_ACTION CSSMERR_TP_INVALID_ACTION_DATA CSSMERR_TP_VERIFY_ACTION_FAILED CSSMERR_TP_INVALID_CRLGROUP_POINTER CSSMERR_TP_INVALID_CRLGROUP CSSMERR_TP_INVALID_CRL_AUTHORITY CSSMERR_TP_INVALID_CALLERAUTH_CONTEXT_POINTER CSSMERR_TP_INVALID_POLICY_IDENTIFIERS CSSMERR_TP_INVALID_TIMESTRING CSSMERR_TP_INVALID_STOP_ON_POLICY CSSMERR_TP_INVALID_CALLBACK CSSMERR_TP_INVALID_ANCHOR_CERT CSSMERR_TP_CERTGROUP_INCOMPLETE CSSMERR_TP_INVALID_DL_HANDLE CSSMERR_TP_INVALID_DB_HANDLE CSSMERR_TP_INVALID_DB_LIST_POINTER CSSMERR_TP_INVALID_DB_LIST CSSMERR_TP_AUTHENTICATION_FAILED CSSMERR_TP_INSUFFICIENT_CREDENTIALS CSSMERR_TP_NOT_TRUSTED CSSMERR_TP_CERT_REVOKED CSSMERR_TP_CERT_SUSPENDED CSSMERR_TP_CERT_EXPIRED CSSMERR_TP_CERT_NOT_VALID_YET CSSMERR_TP_INVALID_CERT_AUTHORITY CSSMERR_TP_INVALID_SIGNATURE CSSMERR_TP_INVALID_NAME CSSMERR_TP_CERTIFICATE_CANT_OPERATE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_TP_CertCreateTemplate CSSM_TP_CrlSign Functions for the TP SPI: TP_CertCreateTemplate TP_CrlSign 3 TP_ConfirmCredResult NAME TP_ConfirmCredResult, CSSM_TP_ConfirmCredResult - Confirm credentials (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_TP_ConfirmCredResult (CSSM_TP_HANDLE TPHandle, const CSSM_DATA *ReferenceIdentifier, const CSSM_TP_CALLERAUTH_CONTEXT *CallerAuthCredentials, const CSSM_TP_CONFIRM_RESPONSE *Responses, const CSSM_TP_AUTHORITY_ID *PreferredAuthority) SPI: CSSM_RETURN CSSMTPI TP_ConfirmCredResult (CSSM_TP_HANDLE TPHandle, const CSSM_DATA *ReferenceIdentifier, const CSSM_TP_CALLERAUTH_CONTEXT *CallerAuthCredentials, const CSSM_TP_CONFIRM_RESPONSE *Responses, const CSSM_TP_AUTHORITY_ID *PreferredAuthority) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS TPHandle (input) The handle that describes the certification authority module used to perform this function. ReferenceIdentifier (input) A reference identifier that uniquely identifies execution of the call sequence CSSM_TP_SubmitCredRequest() and CSSM_TP_RetrieveCredResult() (or the equivalent TP SPI call pair) to submit a set of requests and to retrieve the results of those requests. CallerAuthCredentials (input/optional) This structure contains a set of caller authentication credentials. The authentication information can be a passphrase, a PIN, a completed registration form, a certificate, or a template of user-specific data. The required set of credentials is defined by the service provider module and recorded in a record in the MDS Primary relation. Multiple credentials can be required. If the local service provider module does not require credentials from a caller, then the Credentials field of this verification context structure can be NULL. The structure optionally contains additional credentials that can be used to support the authentication process. Authentication credentials required by the authority should be included in the RequestInput. The local TP module can forward information from the CallerAuthCredentials to the authority, as appropriate, but is not required to do so. Responses (input) An ordered vector of acknowledges indicating the caller's acceptance or rejection of results. The vector contains one acknowledgement per result returned by CSSM_TP_RetrieveCredResult() (CSSM API), or TP_RetrieveCredResult() (TP SPI). PreferredAuthority (input/optional) The identifier which uniquely describes the Authority to receive the acknowledgements. The structure can include: · An identity certificate for the authority · The location of the authority DESCRIPTION This function submits a vector of acknowledgements to a Certificate Authority for a set of requests and corresponding results identified by ReferenceIdentifier. The caller must execute the call sequence CSSM_TP_SubmitCredRequest() and CSSM_TP_RetrieveCredResult()(or the equivalent TP SPI calls) to submit a set of requests and to retrieve the results of those requests. Some Certificate Authority services accessed through the request and retrieve functions require confirmation. The function CSSM_TP_RetrieveCredResult() (CSSM API), or TP_RetrieveCredResult() (TP SPI), returns a value indicating whether the caller must invoke CSSM_TP_ConfirmCredResult(), (CSSM API), or TP_ConfirmCredResult() (TP SPI), to successfully complete the service. The Responses vector accepts or rejects each result independently. If the caller rejects a returned result, the action taken by the authority depends on the requested type of service. The ReferenceIdentifier also identifies the authority process state associated with the function pair CSSM_TP_SubmitCredRequest() and CSSM_TP_RetrieveCredResult() (or the equivalent TP SPI calls). The PreferredAuthority information can be used to further identify the authority to receive the acknowledgement. After successful execution of this function, the value of the ReferenceIdentifier is undefined and should not be used in subsequent operations in the current module attach session. This function fails if ReferenceIdentifier is invalid or the Authority process can not be located. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_TP_INVALID_IDENTIFIER_POINTER CSSMERR_TP_INVALID_IDENTIFIER CSSMERR_TP_INVALID_CALLERAUTH_CONTEXT_POINTER CSSMERR_TP_INVALID_POLICY_IDENTIFIERS CSSMERR_TP_INVALID_TIMESTRING CSSMERR_TP_INVALID_STOP_ON_POLICY CSSMERR_TP_INVALID_CALLBACK CSSMERR_TP_INVALID_ANCHOR_CERT CSSMERR_TP_CERTGROUP_INCOMPLETE CSSMERR_TP_INVALID_DL_HANDLE CSSMERR_TP_INVALID_DB_HANDLE CSSMERR_TP_INVALID_DB_LIST_POINTER CSSMERR_TP_INVALID_DB_LIST CSSMERR_TP_AUTHENTICATION_FAILED CSSMERR_TP_INSUFFICIENT_CREDENTIALS CSSMERR_TP_NOT_TRUSTED CSSMERR_TP_CERT_REVOKED CSSMERR_TP_CERT_SUSPENDED CSSMERR_TP_CERT_EXPIRED CSSMERR_TP_CERT_NOT_VALID_YET CSSMERR_TP_INVALID_CERT_AUTHORITY CSSMERR_TP_INVALID_SIGNATURE CSSMERR_TP_INVALID_NAME CSSMERR_TP_INVALID_RESPONSE_VECTOR CSSMERR_TP_INVALID_AUTHORITY CSSMERR_TP_NO_DEFAULT_AUTHORITY CSSMERR_TP_UNSUPPORTED_ADDR_TYPE CSSMERR_TP_INVALID_NETWORK_ADDR SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_TP_SubmitCredRequest CSSM_TP_RetrieveCredResult CSSM_TP_ReceiveConfirmation Functions for the TP SPI: TP_SubmitCredRequest TP_RetrieveCredResult TP_ReceiveConfirmation 3 TP_CrlCreateTemplate NAME TP_CrlCreateTemplate, CSSM_TP_CrlCreateTemplate - Create an unsigned memory-resident CRL template (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_TP_CrlCreateTemplate (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, uint32 NumberOfFields, const CSSM_FIELD *CrlFields, CSSM_DATA_PTR NewCrlTemplate) SPI: CSSM_RETURN CSSMTPI TP_CrlCreateTemplate (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, uint32 NumberOfFields, const CSSM_FIELD *CrlFields, CSSM_DATA_PTR NewCrlTemplate) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS TPHandle (input) The handle that describes the add-in trust policy module used to perform this function. CLHandle (input/optional) The handle that describes the add-in certificate library module used to perform this function. NumberOfFields (input) The number of OID/value pairs specified in the CrlFields input parameter. CrlFields (input) Any array of field OID/value pairs containing the values to initialize the CRL attribute fields NewCrlTemplate (output) A pointer to the CSSM_DATA structure containing the new CRL. The NewCrl->Data is allocated by the service provider and must be deallocated by the application. DESCRIPTION This function creates an unsigned, memory-resident CRL template. Fields in the CRL are initialized based on the descriptive data specified by the OID/value input pairs in CrlFields and the local domain policy of the TP. The specified OID/value pairs can initialize all or a subset of the general attribute fields in the new CRL, though the module developer may specify a set of fields that must be or cannot be set using this operation. The NewCrlTemplate output is an unsigned CRL template in the format supported by the TP. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_TP_INVALID_CL_HANDLE CSSMERR_TP_INVALID_FIELD_POINTER CSSMERR_TP_UNKNOWN_TAG CSSMERR_TP_INVALID_NUMBER_OF_FIELDS SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_TP_CrlSignWithKey CSSM_TP_CrlSignWithCert Functions for the TP SPI: TP_CrlSignWithKey TP_CrlSignWithCert 3 TP_CrlSign NAME TP_CrlSign, CSSM_TP_CrlSign - Determine if signer certificate is trusted (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_TP_CrlSign (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_ENCODED_CRL *CrlToBeSigned, const CSSM_CERTGROUP *SignerCertGroup, const CSSM_TP_VERIFY_CONTEXT *SignerVerifyContext, CSSM_TP_VERIFY_CONTEXT_RESULT_PTR SignerVerifyResult, CSSM_DATA_PTR SignedCrl) SPI: CSSM_RETURN CSSMTPI TP_CrlSign (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_ENCODED_CRL *CrlToBeSigned, const CSSM_CERTGROUP *SignerCertGroup, const CSSM_TP_VERIFY_CONTEXT *SignerVerifyContext, CSSM_TP_VERIFY_CONTEXT_RESULT_PTR SignerVerifyResult, CSSM_DATA_PTR SignedCrl) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS TPHandle (input) The handle that describes the add-in trust policy module used to perform this function. CLHandle (input/optional) The handle that describes the add-in certificate library module that can be used to manipulate the certificates to be verified. If no certificate library module is specified, the TP module uses an assumed CL module, if required. CCHandle (input/optional) The handle that describes the cryptographic context for signing the CRL. This context also identifies the cryptographic service provider to be used to perform the signing operation. If this handle is not provided by the caller, the trust policy module can assume a default signing algorithm and a default CSP. If the trust policy module does not assume defaults or the default CSP is not available on the local system an error occurs. CrlToBeSigned (input) A pointer to the CSSM_DATA structure containing a certificate revocation list to be signed. SignerCertGroup (input) A pointer to the CSSM_CERTGROUP structure containing one or more related certificates that partially or fully represent the signer of the certificate revocation list. The first certificate in the group is the target certificate representing the CRL signer. Use of subsequent certificates is specific to the trust domain. For example, in a hierarchical trust model subsequent members are intermediate certificates of a certificate chain. SignerVerifyContext (input/optional) A structure containing credentials, policy information, and contextual information to be used in the verification process. All of the input values in the context are optional. The service provider can define default values or can attempt to operate without input for all the other fields of this input structure. The operation can fail if a necessary input value is omitted and the service module can not define an appropriate default value. SignerVerifyResult (output/optional) A pointer to a structure containing information generation during the verification process. The information can include: Evidence (output/optional) NumberOfEvidences (output/optional) SignedCrl (output) A pointer to the CSSM_DATA structure containing the signed certificate revocation list. The SignedCrl->Data is allocated by the service provider and must be deallocated by the application. DESCRIPTION The TP module decides whether the signer certificate is trusted to sign the entire certificate revocation list. The signer certificate group is first authenticated and its applicability to perform this operation is determined. Once the trust is established, this operation signs the entire certificate revocation list. Individual records within the certificate revocation list were signed when they were added to the list. The caller must provide a credential that permits the caller to use the private key for this signing operation. The credential can be provided in the cryptographic context CCHandle. If CCHandle is NULL, the credentials in the SignerVerifyContext specify the credential value. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_TP_INVALID_CL_HANDLE CSSMERR_TP_INVALID_CONTEXT_HANDLE CSSMERR_TP_INVALID_CRL_TYPE CSSMERR_TP_INVALID_CRL_ENCODING CSSMERR_TP_INVALID_CRL_POINTER CSSMERR_TP_INVALID_CRL CSSMERR_TP_INVALID_CERTGROUP_POINTER CSSMERR_TP_INVALID_CERTGROUP CSSMERR_TP_INVALID_CERTIFICATE CSSMERR_TP_INVALID_ACTION CSSMERR_TP_INVALID_ACTION_DATA CSSMERR_TP_VERIFY_ACTION_FAILED CSSMERR_TP_INVALID_CRLGROUP_POINTER CSSMERR_TP_INVALID_CRLGROUP CSSMERR_TP_INVALID_CRL_AUTHORITY CSSMERR_TP_INVALID_CALLERAUTH_CONTEXT_POINTER CSSMERR_TP_INVALID_POLICY_IDENTIFIERS CSSMERR_TP_INVALID_TIMESTRING CSSMERR_TP_INVALID_STOP_ON_POLICY CSSMERR_TP_INVALID_CALLBACK CSSMERR_TP_INVALID_ANCHOR_CERT CSSMERR_TP_CERTGROUP_INCOMPLETE CSSMERR_TP_INVALID_DL_HANDLE CSSMERR_TP_INVALID_DB_HANDLE CSSMERR_TP_INVALID_DB_LIST_POINTER CSSMERR_TP_INVALID_DB_LIST CSSMERR_TP_AUTHENTICATION_FAILED CSSMERR_TP_INSUFFICIENT_CREDENTIALS CSSMERR_TP_NOT_TRUSTED CSSMERR_TP_CERT_REVOKED CSSMERR_TP_CERT_SUSPENDED CSSMERR_TP_CERT_EXPIRED CSSMERR_TP_CERT_NOT_VALID_YET CSSMERR_TP_INVALID_CERT_AUTHORITY CSSMERR_TP_INVALID_SIGNATURE CSSMERR_TP_INVALID_NAME CSSMERR_TP_CERTIFICATE_CANT_OPERATE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CrlSign Functions for the TP SPI: CL_CrlSign 3 TP_CrlVerify NAME TP_CrlVerify, CSSM_TP_CrlVerify - Verify integrity of the certificate revocation list (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_TP_CrlVerify (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CSP_HANDLE CSPHandle, const CSSM_ENCODED_CRL *CrlToBeVerified, const CSSM_CERTGROUP *SignerCertGroup, const CSSM_TP_VERIFY_CONTEXT *VerifyContext, CSSM_TP_VERIFY_CONTEXT_RESULT_PTR RevokerVerifyResult) SPI: CSSM_RETURN CSSMTPI TP_CrlVerify (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CSP_HANDLE CSPHandle, const CSSM_ENCODED_CRL *CrlToBeVerified, const CSSM_CERTGROUP *SignerCertGroup, const CSSM_TP_VERIFY_CONTEXT *VerifyContext, CSSM_TP_VERIFY_CONTEXT_RESULT_PTR RevokerVerifyResult) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS TPHandle (input) The handle that describes the add-in trust policy module used to perform this function. CLHandle (input/optional) The handle that describes the add-in certificate library module that can be used to manipulate the certificates to be verified. If no certificate library module is specified, the TP module uses an assumed CL module, if required. CSPHandle (input/optional) The handle referencing a Cryptographic Service Provider to be used to verify signatures on the signer's certificate and on the CRL. The TP module is responsible for creating the cryptographic context structure required to perform the verification operation. If no CSP is specified, the TP module uses an assumed CSP to perform the operations. CrlToBeVerified (input) A pointer to the CSSM_DATA structure containing a signed certificate revocation list to be verified. The CRL type and encoding are included in this structure. SignerCertGroup (input) A pointer to the CSSM_CERTGROUP structure containing one or more related certificates that paretially or fully represent the signer of the certificate revocation list. The first certificate in the group is the target certificate representing the CRL signer. Use of subsequent certificates is specific to the trust domain. For example, in a hierarchical trust model subsequent members are intermediate certificates of a certificate chain - the caller can specify additional points of trust represented by anchor certificates in the VerifyContext. The trust policy module can use these additional points of trust in the verification process. VerifyContext (input/optional) A structure containing credentials, policy information, and contextual information to be used in the verification process. All of the input values in the context are optional. The service provider can define default values or can attempt to operate without input for all the other fields of this input structure. The operation can fail if a necessary input value is omitted and the service module can not define an appropriate default value RevokerVerifyResult (output/optional) A pointer to a structure containing information generation during the verification process. The information can include: Evidence (output/optional) NumberOfEvidences (output/optional) DESCRIPTION This function verifies the integrity of the certificate revocation list and determines whether it is trusted. The conditions for trust are part of the trust policy module. It can include conditions such as validity of the signer's certificate, verification of the signature on the CRL, the identity of the signer, the identity of the sender of the CRL, date the CRL was issued, the effective dates on the CRL, and so on. The caller can specify additional points of trust represented by anchor certificates in the VerifyContext. The trust policy module can use these additional points of trust in the verification process. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_TP_INVALID_CL_HANDLE CSSMERR_TP_INVALID_CSP_HANDLE CSSMERR_TP_INVALID_CRL_TYPE CSSMERR_TP_INVALID_CRL_ENCODING CSSMERR_TP_INVALID_CRL_POINTER CSSMERR_TP_INVALID_CRL CSSMERR_TP_INVALID_CERTGROUP_POINTER CSSMERR_TP_INVALID_CERTGROUP CSSMERR_TP_INVALID_CERTIFICATE CSSMERR_TP_INVALID_ACTION CSSMERR_TP_INVALID_ACTION_DATA CSSMERR_TP_VERIFY_ACTION_FAILED CSSMERR_TP_INVALID_CRLGROUP_POINTER CSSMERR_TP_INVALID_CRLGROUP CSSMERR_TP_INVALID_CRL_AUTHORITY CSSMERR_TP_INVALID_CALLERAUTH_CONTEXT_POINTER CSSMERR_TP_INVALID_POLICY_IDENTIFIERS CSSMERR_TP_INVALID_TIMESTRING CSSMERR_TP_INVALID_STOP_ON_POLICY CSSMERR_TP_INVALID_CALLBACK CSSMERR_TP_INVALID_ANCHOR_CERT CSSMERR_TP_CERTGROUP_INCOMPLETE CSSMERR_TP_INVALID_DL_HANDLE CSSMERR_TP_INVALID_DB_HANDLE CSSMERR_TP_INVALID_DB_LIST_POINTER CSSMERR_TP_INVALID_DB_LIST CSSMERR_TP_AUTHENTICATION_FAILED CSSMERR_TP_INSUFFICIENT_CREDENTIALS CSSMERR_TP_NOT_TRUSTED CSSMERR_TP_CERT_REVOKED CSSMERR_TP_CERT_SUSPENDED CSSMERR_TP_CERT_EXPIRED CSSMERR_TP_CERT_NOT_VALID_YET CSSMERR_TP_INVALID_CERT_AUTHORITY CSSMERR_TP_INVALID_SIGNATURE CSSMERR_TP_INVALID_NAME CSSMERR_TP_CERTIFICATE_CANT_OPERATE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_CL_CrlVerify Functions for the TP SPI: CL_CrlVerify 3 TP_FormRequest NAME TP_FormRequest, CSSM_TP_FormRequest - Get form from authority (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_TP_FormRequest (CSSM_TP_HANDLE TPHandle, const CSSM_TP_AUTHORITY_ID *PreferredAuthority, CSSM_TP_FORM_TYPE FormType, CSSM_DATA_PTR BlankForm) SPI: CSSM_RETURN CSSMTPI TP_FormRequest (CSSM_TP_HANDLE TPHandle, const CSSM_TP_AUTHORITY_ID *PreferredAuthority, CSSM_TP_FORM_TYPE FormType, CSSM_DATA_PTR BlankForm) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS TPHandle (input) The handle that describes the certification authority module used to perform this function. PreferredAuthority (input/optional) A CSSM_TP_AUTHORITY_ID structure containing either a certificate that identifies the Authority process, or a network address directly or indirectly identifying the location of the authority. If the input is NULL, the module can assume a default authority location. If a default authority can not be assumed, the request can not be initiated and the operation fails. FormType (input) Indicates the type of form being requested. BlankForm (output) A CSSM_DATA structure containing the requested form. The caller must have knowledge of the structure of the form based on FormType. DESCRIPTION This function returns a blank form of type FormType from an Authority. If the PreferredAuthority list is NULL, the CA module can use a default authority name and location based on FormType. The CA module must incorporate knowledge of the interface protocol for communicating with the authority. ERRORS Errors are described in the CDSA technical standard. See CDSA. CSSMERR_TP_INVALID_AUTHORITY CSSMERR_TP_NO_DEFAULT_AUTHORITY CSSMERR_TP_UNSUPPORTED_ADDR_TYPE CSSMERR_TP_INVALID_NETWORK_ADDR CSSMERR_TP_INVALID_FORM_TYPE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_TP_FormSubmit Functions for the TP SPI: TP_FormSubmit 3 TP_FormSubmit NAME TP_FormSubmit, CSSM_TP_FormSubmit - Submit form to ClearanceAuthority (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_TP_FormSubmit (CSSM_TP_HANDLE TPHandle, CSSM_TP_FORM_TYPE FormType, const CSSM_DATA *Form, const CSSM_TP_AUTHORITY_ID *ClearanceAuthority, const CSSM_TP_AUTHORITY_ID *RepresentedAuthority, CSSM_ACCESS_CREDENTIALS_PTR Credentials) SPI: CSSM_RETURN CSSMTPI TP_FormSubmit (CSSM_TP_HANDLE TPHandle, CSSM_TP_FORM_TYPE FormType, const CSSM_DATA *Form, const CSSM_TP_AUTHORITY_ID *ClearanceAuthority, const CSSM_TP_AUTHORITY_ID *RepresentedAuthority, CSSM_ACCESS_CREDENTIALS_PTR Credentials) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS TPHandle (input) A handle for the service provider module that will perform the operation. FormType (input) Indicates the type of form being submitted. Form (input) A pointer to the CSSM_DATA structure containing the completed form to be submitted to the ClearanceAuthority. ClearanceAuthority (input/optional) A CSSM_TP_AUTHORITY_ID structure containing either a certificate that identifies the clearance authority process, or a network address directly or indirectly identifying the location of the authority. If the input is NULL, the service provider module can assume a default authority based on the FormType and contents of Form. If a default authority can not be assumed, the request can not be initiated and the operation fails. RepresentedAuthority (input/optional) A CSSM_TP_AUTHORITY_ID structure containing either a certificate that identifies the authority represented by the ClearanceAuthority, or a network address directly or indirectly identifying the location of the authority. If the input is NULL, the service provider module can assume a default authority based on the FormType and contents of Form. If a default authority can not be assumed, the request can not be initiated and the operation fails. Credentials (output/optional) A pointer to a structure containing one or more credentials issued in response to the contents of the Form. If the output is NULL, either no credentials were returned or an error occurred. DESCRIPTION The completed Form is submitted to a ClearanceAuthority, who is acting on behalf of a RepresentedAuthority. Typically the submitted form is requesting an authorization credential required as input to future service requests to the RepresentedAuthority. If the form is honored by the ClearanceAuthority, then a set of one or more Credentials is returned to the requester. These credential can be used as the input credential in future service requests submitted to the RepresentedAuthority. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_TP_INVALID_FORM_TYPE CSSMERR_TP_INVALID_AUTHORITY CSSMERR_TP_NO_DEFAULT_AUTHORITY CSSMERR_TP_UNSUPPORTED_ADDR_TYPE CSSMERR_TP_INVALID_NETWORK_ADDR CSSMERR_TP_AUTHENTICATION_FAILED CSSMERR_TP_INSUFFICIENT_CREDENTIALS CSSMERR_TP_REJECTED_FORM SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_TP_FormRequest Functions for the TP SPI: TP_FormRequest 3 TP_PassThrough NAME TP_PassThrough, CSSM_TP_PassThrough - Extend trust policy functionality SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_TP_PassThrough (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DL_DB_LIST *DBList, uint32 PassThroughId, const void *InputParams, void **OutputParams) SPI: CSSM_RETURN CSSMTPI TP_PassThrough (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DL_DB_LIST *DBList, uint32 PassThroughId, const void *InputParams, void **OutputParams) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS TPHandle (input) The handle that describes the add-in trust policy module used to perform this function. CLHandle (input/optional) The handle that describes the add-in certificate library module that can be used to manipulate the subject certificate and anchor certificates. If no certificate library module is specified, the TP module uses an assumed CL module, if required. CCHandle (input/optional) The handle that describes the context of the cryptographic operation. If the module-specific operation does not perform any cryptographic operations, a cryptographic context is not required DBList (input/optional) A list of handle pairs specifying a data storage library module and a data store, identifying certificate databases containing certificates (and possibly other security objects) that may be used by the pass-through function. If no DL and DB handle pairs are specified, the TP module can use an assumed DL module and an assumed data store for this operation. PassThroughId (input) An identifier assigned by a TP module to indicate the exported function to be performed. InputParams (input/optional) A pointer to a module, implementation-specific structure containing parameters to be interpreted in a function-specific manner by the requested TP module. OutputParams (output/optional) A pointer to a module, implementation-specific structure containing the output data. The service provider allocates the memory for substructures. The application must free the memory for the substructures. DESCRIPTION This function allows applications to call trust policy module- specific operations that have been exported. Such operations may include queries or services specific to the domain represented by the TP module. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_TP_INVALID_CL_HANDLE CSSMERR_TP_INVALID_CONTEXT_HANDLE CSSMERR_TP_INVALID_DL_HANDLE CSSMERR_TP_INVALID_DB_HANDLE CSSMERR_TP_INVALID_DB_LIST_POINTER CSSMERR_TP_INVALID_DB_LIST CSSMERR_TP_INVALID_PASSTHROUGH_ID SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 TP_ReceiveConfirmation NAME TP_ReceiveConfirmation, CSSM_TP_ReceiveConfirmation - Poll for confirmation (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_TP_ReceiveConfirmation (CSSM_TP_HANDLE TPHandle, const CSSM_DATA *ReferenceIdentifier, CSSM_TP_CONFIRM_RESPONSE_PTR *Responses, sint32 *ElapsedTime) SPI: CSSM_RETURN CSSMTPI TP_ReceiveConfirmation (CSSM_TP_HANDLE TPHandle, const CSSM_DATA *ReferenceIdentifier, CSSM_TP_CONFIRM_RESPONSE_PTR *Responses, sint32 *ElapsedTime) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS TPHandle (input) The handle that describes the certification authority module used to perform this function. ReferenceIdentifier (input) A reference identifier that uniquely identifies a set of service requests and the results created in response to those requests. Responses (output) An ordered vector of acknowledges indicating the caller's acceptance or rejection of results. The vector contains one acknowledgement per result created by the certificate authority. ElapsedTime (output) If the confirmation has not been received, this output value is the number of seconds elapsed since the certificate authority created the results or CSSM_ELAPSED_TIME_UNKNOWN. If the confirmation has been received, this output value is CSSM_ELAPSED_TIME_COMPLETE. DESCRIPTION A certificate authority uses this function to poll for confirmation from a requester who has been served by the authority. A requester sends a confirmation to the authority by successfully invoking the function CSSM_TP_ConfirmCredResult() (CSSM API), or TP_ConfirmCredResult() (TP SPI). The ReferenceIdentifier uniquely identifies the service request and corresponding results for which confirmation is expected. This reference identifier need not be identical to the reference identifier used by the requester, but a one-to-one mapping between the two name spaces must be well-defined. Responses is an ordered vector of acknowledgements indicating, for each returned result, whether the result was accepted or rejected by the original requester for whom the service was performed. If a result is rejected by the receiver, then the authority process must undo the service if a reverse operation is possible and available. If a fatal error occurs, this function returns an error code, indicating that the function call can never be completed. If confirmation has not been received, the function return value is CSSM_OK and the ElapsedTime is returned to the caller of this function. The time represents elapsed seconds since the service results were produced by the authority process. Note that there can be a difference between the time the authority process produces the results and the time the results are actually received by the requester. Elapsed time is relative and should increase with consecutive calls using the same ReferenceIdentifier. If the TP module has no knowledge of the elapsed time, the value CSSM_ELAPSED_TIME_UNKNOWN must be returned. If the service requester has confirmed receipt of the service results, this function returns CSSM_OK and ElapsedTime is CSSM_ELAPSED_TIME_COMPLETE. This function can be invoked repeatedly until the confirmation is received or until the caller decides the acknowledgement may be lost and chooses to undo the results of the original service request. This function fails if the ReferenceIdentifier is invalid or does not match any requested service for which confirmation is expected. RETURN VALUE A CSSM return value combined with elapsed time to indicate one of three results: _______________________________________________________________________ Complete Function Function Return RetrieveOutput EstimatedTime Result Value _______________________________________________________________________ Confirmation CSSM_OK CSSM_ELAPSED_TIME_COMPLETE Received Confirmation not CSSM_OK CSSM_ELAPSED_TIME_UNKNOWN received, but or expected in the future Fatal Error, (!CSSM_OK) NA Confirmation is not expected _______________________________________________________________________ For a return value of (!CSSM_OK) the return value is an error code. ERRORS Errors are described in the CDSA technical standard. See CDSA. CSSMERR_TP_INVALID_IDENTIFIER_POINTER CSSMERR_TP_INVALID_IDENTIFIER SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_TP_ConfirmCredResult Functions for the TP SPI: CSSM_TP_ConfirmCredResult 3 TP_SubmitCredRequest NAME TP_SubmitCredRequest, CSSM_TP_SubmitCredRequest - Submit credential request (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_TP_SubmitCredRequest (CSSM_TP_HANDLE TPHandle, const CSSM_TP_AUTHORITY_ID *PreferredAuthority, CSSM_TP_AUTHORITY_REQUEST_TYPE RequestType, const CSSM_TP_REQUEST_SET *RequestInput, const CSSM_TP_CALLERAUTH_CONTEXT *CallerAuthContext, sint32 *EstimatedTime, CSSM_DATA_PTR ReferenceIdentifier) SPI: CSSM_RETURN CSSMTPI TP_SubmitCredRequest (CSSM_TP_HANDLE TPHandle, const CSSM_TP_AUTHORITY_ID *PreferredAuthority, CSSM_TP_AUTHORITY_REQUEST_TYPE RequestType, const CSSM_TP_REQUEST_SET *RequestInput, const CSSM_TP_CALLERAUTH_CONTEXT *CallerAuthContext, sint32 *EstimatedTime, CSSM_DATA_PTR ReferenceIdentifier) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS TPHandle (input) The handle that describes the certification authority module used to perform this function. PreferredAuthority (input/optional) The identifier which uniquely describes the Certificate Service Authority to submit the request to. RequestType (input) The identifier of the type of request to submit. RequestInput (input) A pointer to the input parameters to be submitted to the authority who will perform the requested service. CallerAuthContext (input/optional) This structure contains a set of caller authentication credentials. The authentication information can be a passphrase, a PIN, a completed registration form, a certificate, or a template of user-specific data. The required set of credentials is defined by the service provider module and recorded in the MDS Primary relation. Multiple credentials can be required. If the local service provider module does not require credentials from a caller, then the CallerCredentials field of this verification context structure can be NULL. The structure optionally contains additional credentials that can be used to support the authentication process. Authentication credentials required by the authority should be included in the RequestInput. The local service provider module can forward this credential information to the authority, as appropriate, but is not required to do so. EstimatedTime (output) The number of estimated seconds before the service results are ready to be retrieved. A (default) value of zero indicates that the results can be retrieved immediately via the corresponding CSSM_TP_RetrieveCredResult() (CSSM API), or TP_RetrieveCredResult() (TP SPI), function call. When the local service provider module or the authority cannot estimate the time required to perform the requested service, the output value for estimated time is CSSM_ESTIMATED_TIME_UNKNOWN. ReferenceIdentifier (output) A reference identifier, which uniquely identifies this specific request. The handle persists across application executions and becomes undefined when all local processing of the request has completed. Local processing is completed in one of two ways: · For certificate services that do not require explicit confirmation by the requester, the reference identifier is invalidated when the corresponding CSSM_TP_RetrieveCredResult() (CSSM API), or TP_RetrieveCredResult() (TP SPI), function completes (by returning valid results or by failure, which blocks returned results) · For certificate services that require explicit confirmation by the requester, the reference identifier is invalidated by successfully invoking the function CSSM_TP_ConfirmCredResu() (CSSM API), or CSSM_TP_ConfirmCredResult() (TP SPI). DESCRIPTION If the caller is successfully authenticated, then this function submits a request to the Authority identified by PreferredAuthority. The authority service can be local or remote. If the Authority is not specified, then the TP module can assume a default authority based on the RequestType and the CallerAuthContext. RequestType indicates the type of Authority request and RequestInput specifies the input parameters needed by the authority to perform the request. The request is submitted to the authority only if the TP module can successfully authenticate the caller. The CallerAuthContext presents the caller's credentials and a list of one or more policies under which the caller should be authenticated. Caller credentials can be presented in several forms: · Memory-resident credential values, directly referenced by the structure · Data bases containing credentials · Callback functions that can be invoked to obtain credentials from an active entity The local service provider must select and forward the credentials required by the Authority. The caller must provide all necessary credentials through the CallerAuthContext parameter. If the caller can not be authenticated by the local service provider, the function fails and the request is not submitted to the selected authority. This function returns a ReferenceIdentifier and an EstimatedTime (specified in seconds). ReferenceIdentifier is an ID for the submitted request. EstimatedTime defines the expected time to process the request. This time may be substantial when the request requires offline authentication procedures by the Authority process. In contrast, the estimated time can be zero, meaning the result can be obtained immediately using CSSM_TP_RetrieveCredResult() (CSSM API), or TP_RetrieveCredResult() (TP SPI). After the specified time has elapsed, the caller must use the function CSSM_TP_RetrieveCredResult() (CSSMAPI), or TP_RetrieveCredResult() (TP SPI), with the reference identifier, to obtain the result of 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_TP_INVALID_AUTHORITY CSSMERR_TP_NO_DEFAULT_AUTHORITY CSSMERR_TP_UNSUPPORTED_ADDR_TYPE CSSMERR_TP_INVALID_NETWORK_ADDR CSSMERR_TP_UNSUPPORTED_SERVICE CSSMERR_TP_INVALID_REQUEST_INPUTS CSSMERR_TP_INVALID_CALLERAUTH_CONTEXT_POINTER CSSMERR_TP_INVALID_POLICY_IDENTIFIERS CSSMERR_TP_INVALID_TIMESTRING CSSMERR_TP_INVALID_STOP_ON_POLICY CSSMERR_TP_INVALID_CALLBACK CSSMERR_TP_INVALID_ANCHOR_CERT CSSMERR_TP_CERTGROUP_INCOMPLETE CSSMERR_TP_INVALID_DL_HANDLE CSSMERR_TP_INVALID_DB_HANDLE CSSMERR_TP_INVALID_DB_LIST_POINTER CSSMERR_TP_INVALID_DB_LIST CSSMERR_TP_AUTHENTICATION_FAILED CSSMERR_TP_INSUFFICIENT_CREDENTIALS CSSMERR_TP_NOT_TRUSTED CSSMERR_TP_CERT_REVOKED CSSMERR_TP_CERT_SUSPENDED CSSMERR_TP_CERT_EXPIRED CSSMERR_TP_CERT_NOT_VALID_YET CSSMERR_TP_INVALID_CERT_AUTHORITY CSSMERR_TP_INVALID_SIGNATURE CSSMERR_TP_INVALID_NAME SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_TP_RetrieveCredResult Functions for the TP SPI: TP_RetrieveCredResult 3 TP_TupleGroupToCertGroup NAME TP_TupleGroupToCertGroup, CSSM_TP_TupleGroupToCertGroup - Create a set of certificate templates (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_TP_TupleGroupToCertGroup (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, const CSSM_TUPLEGROUP *TupleGroup, CSSM_CERTGROUP_PTR *CertTemplates) SPI: CSSM_RETURN CSSMTPI TP_TupleGroupToCertGroup (CSSM_TP_HANDLE TPHandle, CSSM_CL_HANDLE CLHandle, const CSSM_TUPLEGROUP *TupleGroup, CSSM_CERTGROUP_PTR *CertTemplates) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) DESCRIPTION This function creates a set of certificate templates based on a set of input tuples. The tuples describe a set of authorizations for one or more subjects. The trust policy service provider maps these authorizations to appropriate template values for one or more certificates of the type managed by the Trust Policy module. The resulting certificate templates can be input to a certificate creation function, such as CSSM_CL_CertSign(), (CSSM API), or CL_CertSign(), (TP SPI). The signed certificates created by these functions should carry the authorizations described in the input tuples. PARAMETERS TPHandle (input) The handle that describes the trust policy service module used to perform this function. CLHandle (input/optional) The handle that describes the certificate library module that can be used to assist in the creation of field values. If no certificate library module is specified, the TP module uses an assumed CL module, if required. TupleGroup (input) A pointer to a group of CSSM_TUPLE describing authorizations for one or more subjects. CertTemplates (output) A pointer to a structure containing references to one or more certificate templates resulting from the translation process. Storage for the structure and certificate templates is allocated by the service provider and must be deallocated by the application. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_TP_INVALID_CL_HANDLE CSSMERR_TP_INVALID_TUPLEGROUP_POINTER CSSMERR_TP_INVALID_TUPLEGROUP CSSMERR_TP_INVALID_TUPLE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics For the CSSM API: CSSM_TP_CertGroupToTupleGroup CSSM_AC_AuthCompute For the TP SPI: TP_CertGroupToTupleGroup AC_AuthCompute 3 Terminate NAME Terminate - Clean up module-manager-specific activities (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI Terminate (void) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS None. DESCRIPTION This function performs any module-manager-specific cleanup activities in preparation for unloading of the elective module manager. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSSM_EMM_AUTHENTICATE_FAILED. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions: Initialize 3 UnwrapKey NAME UnwrapKey, CSSM_UnwrapKey, CSP_UnwrapKey - Unwrap the wrapped key (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_UnwrapKey (CSSM_CC_HANDLE CCHandle, const CSSM_KEY *PublicKey, const CSSM_WRAP_KEY *WrappedKey, uint32 KeyUsage, uint32 KeyAttr, const CSSM_DATA *KeyLabel, const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, CSSM_KEY_PTR UnwrappedKey, CSSM_DATA_PTR DescriptiveData) SPI: CSSM_RETURN CSSMCSPI CSP_UnwrapKey (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context, const CSSM_KEY *PublicKey, const CSSM_WRAP_KEY *WrappedKey, uint32 KeyUsage, uint32 KeyAttr, const CSSM_DATA *KeyLabel, const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, CSSM_KEY_PTR UnwrappedKey, CSSM_DATA_PTR DescriptiveData, CSSM_PRIVILEGE Privilege) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation. PublicKey (input/optional) The public key corresponding to the private key being unwrapped. If a symmetric key is being unwrapped, then this parameter must be NULL. WrappedKey (input) A pointer to the wrapped key. The wrapped key may be a symmetric key or the private key of a public/private key pair. The unwrapping method is specified as meta data within the wrapped key and is not specified outside of the wrapped key. KeyUsage (input) A bit mask indicating all permitted uses for the unwrapped key. If no value is specified, the CSP defines the usage mask for the unwrapped key. KeyAttr (input) A bit mask defining other attribute values to be associated with the unwrapped key. KeyLabel (input/optional) Pointer to a byte string that will be used as the label for the unwrapped key. CredAndAclEntry (input/optional) A structure containing one or more credentials authorized for creating a key and the prototype ACL entry that will control future use of the newly created key. The credentials and ACL entry prototype can be presented as immediate values or callback functions can be provided for use by the CSP to acquire the credentials and/or the ACL entry interactively. If the CSP provides public access for creating a key, then the credentials can be NULL. If the CSP defines a default initial ACL entry for the new key, then the ACL entry prototype can be an empty list. UnwrappedKey (output) A pointer to a CSSM_KEY structure that returns the unwrapped key. DescriptiveData (output) A pointer to a CSSM_DATA structure that returns any additional descriptive data that was associated with the key during the wrapping operation. It is assumed that the caller incorporated knowledge of the structure of this data. If no additional data is associated with the imported key, this output value is NULL. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM. CCHandle (input) The handle that describes the context of this cryptographic operation. Context (input) Pointer to CSSM_CONTEXT structure that describes the attributes with this context. Privilege (input) The export privilege to be applied during the cryptographic operation. This parameter is forwarded to the CSP after CSSM verifies the caller and service provider privilege set includes the specified PRIVILEGE. DESCRIPTION This function unwraps the wrapped key using the context. The wrapped key can be a symmetric key or a private key. If the unwrapping algorithm is a symmetric algorithm, then a symmetric context must be provided. If the unwrapping algorithm is an asymmetric algorithm, then an asymmetric context must be provided. If the key is a private key, then an asymmetric context must be provide describing the unwrapping algorithm. The CSP can require the caller to provide credentials authorizing the caller to store the unwrapped key within the CSP. The CSP can also require that the caller provide an initial ACL entry to control future access to the newly stored key. These credentials and the initial ACL entry value are provided in CredAndAclEntry parameter. If the unwrapping algorithm is CSSM_ALGID_NONE and the wrapped key is actually a raw key (as indicated by its key attributes), then the key is imported into the CSP. Support for a CSSM_ALGID_NONE unwrapping algorithm is at the option of the CSP. The unwrapped key is restored to its original pre-wrap state based on the key attributes recorded by the wrapped key during the wrap operation. These attributes must not be modified by the caller. Authorization policy can restrict the set of callers who can create a new resource. In this case, the caller must present a set of access credentials for authorization. Upon successfully authenticating the credentials, the template that verified the presented samples identifies the ACL entry that will be used in the authorization computation. If the caller is authorized, the new resource is created. The caller must provide an initial ACL entry to be associated with the newly created resource. This entry is used to control future access to the new resource and (since the subject is deemed to be the "Owner") exercise control over its associated ACL. The caller can specify the following items for initializing an ACL entry: 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. NOTES The KeyData field of the CSSM_KEY structure is allocated by the CSP. The application is required to free this memory using the CSSM_FreeKey() (CSSM API), or CSP_FreeKey() (CSP SPI), function or with the memory functions registered for the CSPHandle. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS CSSMERR_CSP_PUBLIC_KEY_INCONSISTENT CSSMERR_CSP_PRIVATE_KEY_ALREADY_EXIST SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_WrapKey Functions for the CSP SPI: CSP_WrapKey 3 UnwrapKeyP NAME UnwrapKeyP - Unwrap the wrapped keys with privilege (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_UnwrapKeyP (CSSM_CC_HANDLE CCHandle, const CSSM_KEY *PublicKey, const CSSM_WRAP_KEY *WrappedKey, uint32 KeyUsage, uint32 KeyAttr, const CSSM_DATA *KeyLabel, const CSSM_RESOURCE_CONTROL_CONTEXT *CredAndAclEntry, CSSM_KEY_PTR UnwrappedKey, CSSM_DATA_PTR DescriptiveData, CSSM_PRIVILEGE Privilege) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS Privilege (input) The privilege to be applied during the cryptographic operation. See CSSM_UnwrapKey. DESCRIPTION This function is similar to CSSM_UnwrapKey(). It also accepts a USEE tag as a privilege request parameter. CSSM checks that either its own privilege set or the Application's privilege set (if the Application is signed) includes the tag. If the tag is found and the service provider privilege set indicates that it is supported, the tag is forwarded to the service provider. NOTES 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() function or with the memory functions registered for the CSPHandle. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_KEY_LABEL_ALREADY_EXISTS CSSMERR_CSP_PUBLIC_KEY_INCONSISTENT CSSMERR_CSP_PRIVATE_KEY_ALREADY_EXIST SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 VerifyData NAME VerifyData, CSSM_VerifyData, CSP_VerifyData - Verify input buffer data (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_VerifyData (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *DataBufs, uint32 DataBufCount, CSSM_ALGORITHMS DigestAlgorithm, const CSSM_DATA *Signature) SPI: CSSM_RETURN CSSMCSPI CSP_VerifyData (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context, const CSSM_DATA *DataBufs, uint32 DataBufCount, CSSM_ALGORITHMS DigestAlgorithm, const CSSM_DATA *Signature) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. DataBufs (input) A pointer to a vector of CSSM_DATA structures that contain the data to be operated on. DataBufCount (input) The number of DataBufs to be verified. DigestAlgorithm (input) If verifying just a digest, specifies the type of digest. In this case, the context should only specify the encryption algorithm. If not verifying just a digest, it must be CSSM_ALGID_NONE. In this case, the context should specify the combination digest/encryption algorithm. Signature (input) A pointer to a CSSM_DATA structure which contains the signature and the size of the signature. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM. Context (input) Pointer to CSSM_CONTEXT structure that describes the attributes with this context. 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. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_INPUT_LENGTH_ERROR CSSMERR_CSP_VERIFY_FAILED CSSMERR_CSP_INVALID_SIGNATURE CSSMERR_CSP_INVALID_DIGEST_ALGORITHM SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_SignData CSSM_VerifyDataInit CSSM_VerifyDataUpdate CSSM_VerifyDataFinal Functions for the CSP SPI: CSP_SignData CSP_VerifyDataInit CSP_VerifyDataUpdate CSP_VerifyDataFinal 3 VerifyDataFinal NAME VerifyDataFinal, CSSM_VerifyDataFinal, CSP_VerifyDataFinal - Finalize the staged verify data (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_VerifyDataFinal (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *Signature) SPI: CSSM_BOOL CSSMCSPI CSP_VerifyDataFinal (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *Signature) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. Signature (input) A pointer to a CSSM_DATA structure which contains the starting address for the signature to verify against and the length of the signature in bytes. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM. DESCRIPTION This function finalizes the staged verify data 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_INPUT_LENGTH_ERROR CSSMERR_CSP_VERIFY_FAILED CSSMERR_CSP_INVALID_SIGNATURE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_VerifyData CSSM_VerifyDataInit CSSM_VerifyDataUpdate Functions for the CSP SPI: CSP_VerifyData CSP_VerifyDataInit CSP_VerifyDataUpdate 3 VerifyDataInit NAME VerifyDataInit, CSSM_VerifyDataInit, CSP_VerifyDataInit - Initialize the staged verify data (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_VerifyDataInit (CSSM_CC_HANDLE CCHandle) SPI: CSSM_RETURN CSSMCSPI CSP_VerifyDataInit (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform up calls to CSSM for the memory functions managed by CSSM. Context (input) Pointer to CSSM_CONTEXT structure that describes the attributes with this context. 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. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_VerifyDataUpdate CSSM_VerifyDataFinal CSSM_VerifyData Functions for the CSP SPI: CSP_VerifyDataUpdate CSP_VerifyDataFinal CSP_VerifyData 3 VerifyDataUpdate NAME VerifyDataUpdate, CSSM_VerifyDataUpdate, CSP_VerifyDataUpdate - Continue the staged verification (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_VerifyDataUpdate (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *DataBufs, uint32 DataBufCount) SPI: CSSM_RETURN CSSMCSPI CSP_VerifyDataUpdate (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *DataBufs, uint32 DataBufCount) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. DataBufs (input) A pointer to a vector of CSSM_DATA structures that contain the data to be operated on. DataBufCount (input) The number of DataBufs to be verified. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform calls to CSSM for the memory functions managed by CSSM. 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. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_VerifyData CSSM_VerifyDataInit CSSM_VerifyDataFinal Functions for the CSP SPI: CSP_VerifyData CSP_VerifyDataInit CSP_VerifyDataFinal 3 VerifyDevice NAME VerifyDevice, CSSM_VerifyDevice, CSP_VerifyDevice - Cause the cryptographic module to perform a self verification and integrity check (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_VerifyDevice (CSSM_CSP_HANDLE CSPHandle, const CSSM_DATA *DeviceCert) SPI: CSSM_RETURN CSSMCSPI CSP_VerifyDevice (CSSM_CSP_HANDLE CSPHandle, const CSSM_DATA *DeviceCert) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) 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. DESCRIPTION This function triggers the cryptographic module to perform self verification and integrity checking. 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_DEVICE_VERIFY_FAILED SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 VerifyMac NAME VerifyMac, CSSM_VerifyMac, CSP_VerifyMac - Verify the message authentication code (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_VerifyMac (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *DataBufs, uint32 DataBufCount, const CSSM_DATA *Mac) SPI: CSSM_RETURN CSSMCSPI CSP_VerifyMac (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context, const CSSM_DATA *DataBufs, uint32 DataBufCount, const CSSM_DATA *Mac) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. DataBufs (input) A pointer to a vector of CSSM_DATA structures that contain the data to be operated on. DataBufCount (input) The number of DataBufs. Mac (input) A pointer to the CSSM_DATA structure containing the MAC to verify. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform calls to CSSM for the memory functions managed by CSSM. Context (input) Pointer to CSSM_CONTEXT structure that describes the attributes with this context. DESCRIPTION This function verifies the message authentication code over all data contained in the set of input buffers based on the input 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_INPUT_LENGTH_ERROR CSSMERR_CSP_VERIFY_FAILED CSSMERR_CSP_INVALID_SIGNATURE SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_VerifyMacInit CSSM_VerifyMacUpdate CSSM_VerifyMacFinal Functions for the CSP SPI: CSP_VerifyMacInit CSP_VerifyMacUpdate CSP_VerifyMacFinal 3 VerifyMacFinal NAME VerifyMacFinal, CSSM_VerifyMacFinal, CSP_VerifyMacFinal - Finalize the staged message authentication code (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_VerifyMacFinal (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *Mac) SPI: CSSM_RETURN CSSMCSPI CSP_VerifyMacFinal (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *Mac) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. Mac (input) A pointer to the CSSM_DATA structure containing the MAC to verify. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform calls to CSSM for the memory functions managed by CSSM. DESCRIPTION This function finalizes the staged message authentication code verification 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 Errors are described in the CDSA technical standard. See CDSA. CSSMERR_CSP_INPUT_LENGTH_ERROR CSSMERR_CSP_VERIFY_FAILED CSSMERR_CSP_INVALID_SIGNATURE COMMENTS FOR SPI The output is returned to the caller as specified in Buffer Management for Cryptographic Services. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_VerifyMac CSSM_VerifyMacInit CSSM_VerifyMacUpdate Functions for the CSP SPI: CSP_VerifyMac CSP_VerifyMacInit CSP_VerifyMacUpdate 3 VerifyMacInit NAME VerifyMacInit, CSSM_VerifyMacInit, CSP_VerifyMacInit - Initialize the staged message authentication code (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_VerifyMacInit (CSSM_CC_HANDLE CCHandle) SPI: CSSM_RETURN CSSMCSPI CSP_VerifyMacInit (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform calls to CSSM for the memory functions managed by CSSM. Context (input) Pointer to CSSM_CONTEXT structure that describes the attributes with this context. DESCRIPTION This function initializes the staged message authentication code verification 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_VerifyMac CSSM_VerifyMacUpdate CSSM_VerifyMacFinal Functions for the CSP SPI: CSP_VerifyMac CSP_VerifyMacUpdate CSP_VerifyMacFinal 3 VerifyMacUpdate NAME VerifyMacUpdate, CSSM_VerifyMacUpdate, CSP_VerifyMacUpdate - Continue the staged process of verifying the message authentication code (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_VerifyMacUpdate (CSSM_CC_HANDLE CCHandle, const CSSM_DATA *DataBufs, uint32 DataBufCount) SPI: CSSM_RETURN CSSMCSPI CSP_VerifyMacUpdate (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_DATA *DataBufs, uint32 DataBufCount) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle that describes the context of this cryptographic operation used to link to the CSP-managed information. DataBufs (input) A pointer to a vector of CSSM_DATA structures that contain the data to be operated on. DataBufCount (input) The number of DataBufs. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform calls to CSSM for the memory functions managed by CSSM. 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. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_VerifyMac CSSM_VerifyMacInit CSSM_VerifyMacFinal Functions for the CSP SPI: CSP_VerifyMac CSP_VerifyMacInit CSP_VerifyMacFinal 3 WrapKey NAME WrapKey, CSSM_WrapKey, CSP_WrapKey - Wrap a key using the context (CDSA) SYNOPSIS # include API: CSSM_RETURN CSSMAPI CSSM_WrapKey (CSSM_CC_HANDLE CCHandle, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_KEY *Key, const CSSM_DATA *DescriptiveData, CSSM_WRAP_KEY_PTR WrappedKey) SPI: CSSM_RETURN CSSMCSPI CSP_WrapKey (CSSM_CSP_HANDLE CSPHandle, CSSM_CC_HANDLE CCHandle, const CSSM_CONTEXT *Context, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_KEY *Key, const CSSM_DATA *DescriptiveData, CSSM_WRAP_KEY_PTR WrappedKey, CSSM_PRIVILEGE Privilege) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) API PARAMETERS CCHandle (input) The handle to the context that describes this cryptographic operation. AccessCred (input) A pointer to the set of one or more credentials required to access the private or secret key to be exported from the CSP. The credentials structure can contain an immediate value for the credential, such as a passphrase, or the caller can specify a callback function the CSP can use to obtain one or more credentials. Key (input) A pointer to the key to be wrapped. DescriptiveData (input/optional) A pointer to a CSSM_DATA structure containing additional descriptive data to be associated and included with the key during the wrapping operation. The caller and the wrapping algorithm incorporate knowledge of the structure of the descriptive data. If the wrapping algorithm does not accept additional descriptive data, then this parameter must be NULL. If the wrapping algorithm accepts descriptive data, the corresponding unwrapping algorithm can be used to extract the descriptive data and the key. WrappedKey (output) A pointer to a CSSM_WRAP_KEY structure that returns the wrapped key. SPI PARAMETERS CSPHandle (input) The handle that describes the add-in cryptographic service provider module used to perform up-calls to CSSM for the memory functions managed by CSSM. Context (input) Pointer to CSSM_CONTEXT structure that describes the attributes with this context. Privilege (input) The export privilege to be applied during the cryptographic operation. This parameter is forwarded to the CSP after CSSM verifies the caller and service provider privilege set includes the specified PRIVILEGE. DESCRIPTION This function wraps the supplied key using the context. It allows a key to be exported from a CSP. Four types of wrapping exist: 1. Wrap a symmetric key with a symmetric key. 2. Wrap a symmetric key with an asymmetric public key. 3. Wrap an asymmetric private key with a symmetric key. 4. Wrap an asymmetric private key with an asymmetric public key. For types 1 and 3, a symmetric context should be provided. For types 2 and 4, an asymmetric context is provided. If there is a CSSM_ATTRIBUTE_WRAPPED_KEY_FORMAT argument in the context represented by the CCHandle, the value of the attribute specifies the format of the wrapped key. If this argument is not present, the symmetric key is wrapped according to CMS for types 1 and 3, and according to PKCS8 for types 2 and 4. If the wrapping algorithm in the context is CSSM_ALGID_NONE, then the key is returned in raw format, if permitted and supported by the CSP (in this case the CSSM_ATTRIBUTE_WRAPPED_KEY_FORMAT attribute is ignored). All significant key attributes are incorporated into the KeyHeader of the returned WrappedKey, such that the state of the key can be fully restored by the unwrap process. The CSP can require that the cryptographic context includes access credentials for authentication and authorization checks when using the secret or private key. NOTES The KeyData field of the CSSM_KEY structure is allocated by the CSP. The application is required to free this memory using the CSSM_FreeKey() (CSSM API), or CSP_FreeKey() (CSP SPI) function, or with the memory functions registered for the CSPHandle. 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 Errors are described in the CDSA technical standard. See CDSA. None specific to this call. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics Functions for the CSSM API: CSSM_UnwrapKey Functions for the CSP SPI: CSP_UnwrapKey 3 WrapKeyP NAME WrapKeyP - Wrap a key with privilege (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI CSSM_WrapKeyP (CSSM_CC_HANDLE CCHandle, const CSSM_ACCESS_CREDENTIALS *AccessCred, const CSSM_KEY *Key, const CSSM_DATA *DescriptiveData, CSSM_WRAP_KEY_PTR WrappedKey, CSSM_PRIVILEGE Privilege) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS Privilege (input) The privilege to be applied during the cryptographic operation. See CSSM_WrapKey. DESCRIPTION This function is similar to CSSM_WrapKey(). It also accepts a USEE tag as a privilege request parameter. CSSM checks that either its own privilege set or the application's privilege set (if the application is signed) includes the tag. If the tag is found, and the service provider privilege set indicates that it is supported, the tag is forwarded to the service provider. NOTES 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() functon, or with the memory functions registered for the CSPHandle. 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 Errors are described in the CDSA technical standard. See CDSA. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 cssm_CcToHandle NAME cssm_CcToHandle - Get the module attach handle (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI cssm_CcToHandle (CSSM_CC_HANDLE Cc, CSSM_MODULE_HANDLE_PTR ModuleHandle) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS Cc (input) A handle identifying a cryptographic context. ModuleHandle (output) A service provider's module attach handle. This value will be set to CSSM_INVALID_HANDLE if the function fails. DESCRIPTION This function returns the module attach handle identifying the service module that is managing the specified cryptographic context. The entry point to this function is provided to a service module in a table of upcall functions passed to the service provider during module attach processing. If the PVC checking for service providers is on, the service provider has to introduce itself before calling 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 Errors are described in the CDSA technical standard. See CDSA. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 cssm_DeregisterManagerServices NAME cssm_DeregisterManagerServices - Deregister manager services SYNOPSIS # include void CSSMAPI cssm_DeregisterManagerServices (const CSSM_GUID *Guid); PARAMETERS GUID (input) A pointer to the CSSM_GUID structure containing the global unique identifier for this module. DESCRIPTION This function is used by an elective module manager to deregister its function table with CSSM core services prior to termination. This function is invoked by an elective module manager only when exiting due to an error condition detected by the EMM. This allows CSSM to clean up any state information associated with the exiting EMM. 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 Errors are described in the CDSA technical standard. See CDSA. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 cssm_GetAppMemoryFunctions NAME cssm_GetAppMemoryFunctions - Get service functions (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI cssm_GetAppMemoryFunctions (CSSM_MODULE_HANDLE hAddIn, CSSM_UPCALLS_PTR UpcallTable) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS hAddIn (input) The handle identifying the attach-session whose memory management function table is returned by this function. UpcallTable (output) The table containing sets of service functions among them a set of four memory management functions provided by the application that initiated the attach-session identified by hAddIn. DESCRIPTION This function gets a function table containing sets of service functions. Among these service functions are four application- provided memory management functions. The elective module manager can use these functions to manage memory on behalf of the application. The returned function table is specific to the attach- session identified by the module handle. RETURN VALUE A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition. ERRORS Errors are described in the CDSA technical standard. See CDSA. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 cssm_GetAttachFunctions NAME cssm_GetAttachFunctions - Get SPI function table (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI cssm_GetAttachFunctions (CSSM_MODULE_HANDLE hAddIn, CSSM_SERVICE_MASK AddinType, void **SPFunctions, CSSM_GUID_PTR Guid) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS hAddIn (input) The handle identifying the attach-session whose function table is to be returned by this function. AddinType (input) A CSSM_SERVICE_MASK value identifying the type of service module whose function table is to be returned by this function. SPFunctions (output) A pointer to the service module function table, which CSSM acquired from the service module during module-attach processing. The module manager should use this table to forward application invocation of the elective APIs to their corresponding SPIs. The memory pointed to by the function pointers should not be freed by the EMM. Guid (output) A CSSM_GUID value identifying the service module whose function table is to be returned by this function. DESCRIPTION This function returns an SPI function table for the service module identified by the module handle. The module must be of the type specified by the service mask. The SPFunctions parameter contains the returned function table. The elective module manager must use this function table to forward an application's call to the elective APIs to their corresponding SPIs represented in the function table. The returned Guid identifies the service module. It can be used to locate credentials and other information about the service module. This function sets a lock on the SP functions table. The CSSM service function cssm_ReleaseAttachFunctions() must be used to release the lock. 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 Errors are described in the CDSA technical standard. See CDSA. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 cssm_GetModuleInfo NAME cssm_GetModuleInfo - Get the module handle state information SYNOPSIS # include CSSM_RETURN CSSMAPI cssm_GetModuleInfo (CSSM_MODULE_HANDLE Module, CSSM_GUID_PTR Guid, CSSM_VERSION_PTR Version, uint32 *SubServiceId, CSSM_SERVICE_TYPE *SubServiceType, CSSM_ATTACH_FLAGS *AttachFlags, CSSM_KEY_HIERARCHY *KeyHierarchy, CSSM_API_MEMORY_FUNCS_PTR AttachedMemFuncs, CSSM_FUNC_NAME_ADDR_PTR FunctionTable, uint32 NumFunctionTable); PARAMETERS Module (input) The handle to a service provider module. GUID (input) A pointer to the CSSM_GUID structure containing the global unique identifier for this module. Version (output) The version number set on ModuleAttach. SubServiceId (output) The slot number of the reader to which the module is attached. SubServiceType (output) A CSSM_SERVICE_TYPE value identifying the class of security service AttachFlags (output) This parameter provides the caller with session specific information asso- ciated with the module handle. KeyHierarchy (output) The key hierarchy supplied when the module was attached. AttachedMemFuncs (output) The memory functions supplied when the module was attached. FunctionTable (input/output optional) A table of function-name and API function-pointer pairs. The caller provides the name of the functions as input. The corresponding API function pointers are returned on output. The function table allows dynamic linking of CDSA interfaces, including interfaces to Elective Module Managers, which are transparently loaded by CSSM during the CSSM_ModuleAttach() function. The caller of this function should allocate the memory for the number of slots required. NumFunctionTable (input) The number of entries in the FunctionTable parameter. If no FunctionTable is provided, this value must be zero. DESCRIPTION This function returns the state information associated with the module handle. The information returned by this function is that set by the call to the CSSM_ModuleAttach() function. The entry point to this function is provided to a service module in a table of upcall functions passed to the service provider during module attach processing. If the PVC checking for service providers is on, the service provider has to introduce itself before calling 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 Errors are described in the CDSA technical standard. See CDSA. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 cssm_IsFuncCallValid NAME cssm_IsFuncCallValid - Check secure linkage (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI cssm_IsFuncCallValid (CSSM_MODULE_HANDLE hAddin, CSSM_PROC_ADDR SrcAddress, /* application */, CSSM_PROC_ADDR DestAddress, CSSM_PRIVILEGE InPriv, CSSM_PRIVILEGE *OutPriv, CSSM_BITMASK Hints, CSSM_BOOL * IsOK) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS hAddIn (input) The handle identifying the attach-session whose caller and callee scope is being tested by this function. SrcAddress (input/optional) An address to be tested for containment within the application that requested and created the attach-session identified by the module handle. DestAddress (input/optional) An address within a service module. The destination address must be valid for the service provider associated with the attach-session identified by the module handle. InPriv (input) The privilege value to be checked. Privilege checks apply to both SrcAddress and DestAddress. OutPriv (output) If non-NULL, the global privilege will be checked and returned in OutPriv. Hints (input) A flag providing search hints. IsOK (output) CSSM_TRUE if success, CSSM_FALSE if fail. DESCRIPTION This function checks secure linkage between an application and a service module. Based on address scope of the application and the service module associated with the attach handle, CSSM determines whether the SrcAddress is within an associated application and DestAddress is within the associated service module. The scope of the application and the service module is determined by their respective signed manifest credentials, which attest to the integrity of each entity. This function uses the input privilege value InPriv to compare against the privilege range associated with the ranges for SrcAddress and DestAddres. The privilege check is performed when the InPriv privilege value is non-NULL. If the EMM wants the global privilege value to be checked, InPriv is zero and OutPriv is non-NULL. CSSM will return the privilege value in OutPriv. If integrity only checks are to be performed, InPriv is zero and OutPriv is NULL. Another parameter called Hints is used to help CSSM efficiently perform the integrity and privilege verification operations. Hints helps CSSM know where to look to find the desired state information. In the regular case, CSSM will look for SrcAddress in the CallerList and DestAddress in the AttachList. For callback functions, the SrcAddress and DestAddress are likely to be in AttachList. 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 Errors are described in the CDSA technical standard. See CDSA. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 3 cssm_ReleaseAttachFunctions NAME cssm_ReleaseAttachFunctions - Release lock on the SP function table (CDSA) SYNOPSIS # include CSSM_RETURN CSSMAPI cssm_ReleaseAttachFunctions (CSSM_MODULE_HANDLE hAddIn) LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS hAddIn (input) The handle identifying the attach-session whose function table is to be released by this function. DESCRIPTION This function releases the lock on the SP function table for the service module identified by the module handle. The SPI function table was obtained by the elective module manager through the cssm_GetAttachFunctions() 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 Errors are described in the CDSA technical standard. See CDSA. SEE ALSO Books Intel CDSA Application Developer's Guide (see CDSA) Other Help Topics 2 CDSA$CERTGEN.EXE The certgen utility allows the user to create digital certificates in the form runfilename.cer. Private keys will be placed in [.CDSA.PKD]csp-name.PRI under the login directory of the current process. This program generally is called by CDSA_SYSDIR:[SIGN]CDSA$GEN_CERTS.COM. SYNOPSIS certgen [runfilename] OPTIONS runfilename This optional parameter specifies the name of the run file that contains the parameters that certgen needs to create a certificate. If no run file is specified, the default run file is certgen.run in the current directory. A certgen run file contains the following items, as appropriate - each on a separate line: certtype location certtype can be one of the following: -s Indicates a self-signed certificate. -i Indicates a certificate signed by another certificate. -v Indicates that the created certificate takes its subject and public key from a certificate issued by another vendor. You cannot use this option to create a self-signed certificate. location indicates where the issuer certificate is read from if -i or -v is specified. filename If certtype is -s or -i, filename indicates the location of the XML template that contains the Subject Name that must go into this certificate. If certtype is -v, filename indicates the location of the Vendor Certificate. algorithm Indicates the algorithm used to generate the key pair associated with the certificate being created. Algorithm can be either DSA or RSA. The specified algorithm must be supported by one of the Cryptographic Service Providers available in the local implementation of CDSA. This parameter is not valid if -v is specified for certtype. keysize Specifies the logical key size (in bits) of the key pair being generated. Typical examples are 128, 256, 512, 1024, and so on. The specified key size must be supported by one of the Cryptographic Service Providers available in the local implementation of CDSA. This parameter is not valid if -v is specified for certtype. cspguid The globally unique identifier of the Cryptographic Service Provider that is being used. certfile The output file into which the created certificate is to be written. subject_password The password used to protect a key pair if one is being generated. This parameter is not valid if -v is specified for certtype. issuer_password The password used to unlock the private key required to sign the generated certificate. This parameter is not valid if -s is specified for certtype. validity_period The validity period for the certificate. This parameter contains a start and end date for the validity period in the form YYMMDDHHMMSS YYMMDDHHMMSS. The validity period cannot extend beyond the year 2049. If validity_period is not specified, the validity period for the certificate lasts for exactly one year. 3 EXAMPLE $ certgen intmods.run The following is an example of a run file (intmods.run) that creates a certificate named intmods.cer, which is signed by intmanf.cer and generates a 1024-bit DSA key pair. -i intmanf.cer intmods.xml dsa 1024 {67ef50d0-fe74-11d2-a8e6-0090271d266f} intmods.cer intmods intmanf 001013000000 101013000000 2 CDSA$ISSUER.EXE The issuer utility is used to create a set of functions that are embedded into CSSM, or are used by EISL. A CDSA application developer needs to create only the EISL_RetrieveSelfCheckKey function. The other functions noted here are applicable only for CDSA vendors (in this case, HP). This program generally is called by CDSA_SYSDIR:[SIGN]CDSA$GEN_CERTS.COM. SYNOPSIS issuer option certfile codefile functionname OPTIONS option A code that defines the function to be created. Specify one of the following values: -i Creates a function that returns an issuer name from the certificate. -s Creates a function that returns a signer name from the certificate. -k Creates a function that returns a trusted public key. NOTE: A CDSA application developer who is creating the EISL_RetrieveSelfCheckKey function should specify -k. The other codes are used only by CDSA vendors who are building CDSA itself rather than a CDSA application or service provider module. certfile A text file that contains the name of the certificate to be used. codefile The file to which the generated function is written. functionname Name of the function to be generated. One of the following: * cssm_GetIntegrityRootKeys (cssm_GetExportRootKeys for export) * cssm_GetIntegrityRootNames (cssm_GetExportRootNames for export) * EISL_RetrieveSelfCheckKey NOTE: CDSA application developers need to create only the EISL_RetrieveSelfCheckKey function (the last item in the following list). The full set of functions is listed here to provide a complete overview of the issuer utility. The other functions are applicable only for CDSA vendors. Those who want to learn more about certificate chains can refer to the Intel CDSA Manifest Signing Tools User's Guide. 3 EXAMPLE The following example extracts the public key from the certificate intmods.cer and creates a function named EISL_RetrieveSelfCheckKey() in the file modselfkey.h. $ create intmodscertfile. intmods.cer $! $ issuer -k intmodscertfile. modselfkey.h "EISL_RetrieveSelfCheckKey" 2 CDSA$MDS_INSTALL.EXE The mds_install utility is used to install or uninstall the Module Directory Services database used by CDSA. This program generally is called by SYS$STARTUP:CDSA$INITIALIZE.COM. SYNOPSIS mds_install [ [-s source] [-d dbdest] ] | [-u] OPTIONS NOTE: OpenVMS users can specify only the -u option (or no option). However, the other options are described here for completeness for users who are accustomed to seeing them on another platform. -s source Specifies the MDS Dll source location (not used by OpenVMS). -d dbdest Specifies the destination file specification for the MDS database to be created. This parameter is currently hardcoded on OpenVMS, and should not be changed. -u Specifies that the operation is an uninstall of MDS, rather than an install. This parameter cannot be used with the -s and -d parameters. 3 EXAMPLE The following command creates an empty CDSA MDS database. (If it is run against an already existing database, it does nothing.) mds_install 2 CDSA$MOD_INSTALL.EXE The mod_install utility is used to add information about CDSA modules into the Module Directory Services database. This program generally is called by SYS$STARTUP:CDSA$INITIALIZE.COM. SYNOPSIS mod_install [-f] option [-s file] [-d path] OPTIONS -f Specifies not to warn about unsigned or corrupt modules. option Specifies the action to be taken by the mod_install utility: -i Install the module. -u Uninstall the module. -r Refresh the installation information. -s file Specifies the full file specification (in UNIX directory format) of the source file to be installed. -d path Specifies the destination path (in UNIX directory format) of the source file to be installed. 3 EXAMPLE The following example installs the add-in module stubcsp300_shr.exe in the CDSA MDS database. The logical definition in the first command is necessary because the shareable image is not in SYS$LIBRARY and it will be invoked as part of the installation process. $ define stubcsp300_shr "cdsa_tempdir:[addin]stubcsp300_shr.exe" $ mod_install -i -s /cdsa_tempdir/addin - _$ /stubcsp300_shr.exe -d /cdsa_tempdir/addin 2 CDSA$OUTPUT_ERROR.EXE Note that this utility is defined as cdsa_error by CDSA$SYMBOLS.COM. The cdsa_error utility converts a CDSA numeric error code into its corresponding text strings. The text is output to SYS$OUTPUT. SYNOPSIS cdsa_error base_flag error_code OPTIONS base_flag The mathematical base in which the error code is represented: -d Specifies that the value of error_code is decimal (base 10). -o Specifies that the value of error_code is octal (base 8). -h Specifies that the value of error_code is hexadecimal (base 16). If you specify something other than these options, you will get an error message that lists the correct options. (See Example 2.) error_code The error code stated in the numerical base specified by the base-flag parameter. 3 EXAMPLES 1. $ cdsa_error -h 3135 Error: CSSMERR_DL_STALE_UNIQUE_RECORD The record returned has been changed by someone and is stale 2. $ cdsa_error -? dka300:[sys0.syscommon.][sysexe]cdsa$output_error.exe;1: illegal option -- ? cdsa$output_error -d|o|h options: -d : Error code is a decimal number -o : Error code is an octal number -h : Error code is a hexadecimal number 2 CDSA$SIGN.EXE Note that this utility is defined as cdsa_sign by CDSA$SYMBOLS.COM. The cdsa_sign utility takes a service provider product, application, or CSSM binary, plus the manufacturer certificates generated using certgen, and creates a manifest file. Manifest files have a file extension of .ESW. This utility can be used for Integrity signing and for Export signing. The options for each function are totally different, so they are described here in separate sections. Integrity signing for a module must always be done before Export signing. 3 Integrity_Signing Integrity signing is optional for applications and mandatory for plug-in modules. SYNOPSIS cdsa_sign module_name subdirectory type signer_cert password cert_chain module_guid access_tag pvcapi_tag pvcspi_tag priv_tag OPTIONS module_ name The name of the module being signed. subdirectory The subdirectory (in UNIX directory format) containing the module being signed. type The module type, which can be one of the following: A - Service provider module C - CSSM D - Application sharable image E - Elective Module Manager G - Generic image X - Application executable signer_cert The name of the certificate being used to sign the module. password The password for the private key of the certificate being used to sign the module. cert_chain A text file identifying the Integrity certificates to be embedded. This file has the following form: number cert1 cert2 . . . where number is the number of certificates being embedded, and cert1 and cert2 are the names of certificates to be embedded; for example: 2 introot.cer intmanf.cer module_guid The string version of the globally unique identifier of the module being signed (as installed in MDS). access_tag For installer modules, this is the base-64 encoded, unsigned, 32-bit value (in big-endian) of the access type defined for CDSA_DB_ACCESS_TYPE. For modules other than installers, specify "XX" for this parameter. pvcapi_tag Specifies whether pointer validation checking is to be done on the application program interface boundaries. The values for the CDSA_PVC_API tag are as follows: "EXEMPT" Specifies an application manifest, where the program can set the PVC flag in cssm_Init. "OFF" Specifies a CSSM manifest, where the PVC flag is not applicable. "XX" Specifies that the CDSA_PVC_API tag is not in the manifest. pvcspi_tag Specifies whether pointer validation checking is to be done on the service provider interface boundaries. The values for the CDSA_PVC_SPI tag are as follows: "EXEMPT" Specifies a service provider manifest, where the program can set the PVC flag in cssm_Init. "OFF" Specifies a CSSM manifest, where the PVC flag is not applicable. "XX" Specifies that the CDSA_PVC_SPI tag is not in the manifest. priv_tag The CDSA_PRIV tag in the manifest. Currently, no CDSA_PRIV tag values are defined, so specify "XX" to indicate that this tag is not in the manifest. 3 Integrity_Signing_Example The following is an example of the cdsa_sign command for Integrity signing: $ define cdsa_sign "/cdsa_tempdir/addin" $ set default cdsa_sysdir:[sign] $ cdsa_sign stubcsp300_shr cdsa_sign A intmods.cer - _$ intmods intchain. {79BDE0F0-4541-11d3-A8F3-0090271D266F} - _$ "XX" "EXEMPT" "XX" "XX" The first command defines the logical cdsa_sign (which is used internally by the code) in UNIX directory format as the directory where the executable to be signed can be found. * stubcsp300_shr is the name of the module being signed. * cdsa_sign is the logical pointing to the directory containing the module. * A indicates that stubcsp300_shr is a service provider module. * intmods.cer is the name of the certificate being used to sign the module. * intmods is the password for the private key of the certificate (intmods.cer) being used to sign the module. * intchain. is the name of the text file containing the names of the certificates in the Integrity chain. * {79BDE0F0-4541-11d3-A8F3-0090271D266F} is the GUID of the service provider module. * "XX" is the access tag, which indicates that this is not an installer module. * "EXEMPT" is the CDSA_PVC_API tag specifying that this is an application manifest. * "XX" specifies that the CDSA_PVC_SPI tag is not in the manifest. * "XX" specifies that the CDSA_PRIV tag is not in the manifest. 3 Export_Signing Export signing is optional. Before you can do Export signing for a module, you must already have done Integrity signing and a manifest must exist. For more information about Export signing, refer to the Intel CDSA Manifest Signing Tools User's Guide. SYNOPSIS cdsa_sign manifest_path signer_cert password cert_chain usee_tag priv_tag pvcapi_tag pvcspi_tag OPTIONS manifest_path The path (in UNIX directory format) to the manifest created in the Integrity signing phase. signer_cert The name of the certificate being used to sign the module. password The password for the private key of the certificate being used to sign the module. cert_chain A text file identifying the Export certificates to be embedded. This file has the following form: number cert1 cert2 . . . where number is the number of certificates being embedded, and cert1 and cert2 are the names of certificates to be embedded; for example: 2 introot.cer intmanf.cer usee_tag The base-64 encoded value of the CSSM_USEE_TAG value. This value must be enclosed within double quotation marks. priv_tag The CDSA_PRIV tag in the manifest. Currently, no CDSA_PRIV tag values are defined, so specify "XX" to indicate that this tag is not in the manifest. pvcapi_tag The CDSA_PVC_API tag for application and CSSM manifests. The values are: "EXEMPT" Specifies an application manifest. "OFF" Specifies a CSSM manifest. "XX" Specifies that the CDSA_PVC_API tag is not in the manifest. pvcspi_tag The CDSA_PVC_SPI tag for application and CSSM manifests. The values are: "EXEMPT" Specifies an application manifest. "OFF" Specifies a CSSM manifest. "XX" Specifies that the CDSA_PVC_SPI tag is not in the manifest. 3 Export_Signing_Example The following is an example of the cdsa_sign command for Export signing: $ cdsa_sign /cdsa_tempdir/des2/des2.esw exapps.cer secret exchain. - _$ "AAAAAQ==" "XX" "EXEMPT" "XX" In this example: * /cdsa_tempdir/des2/des2.esw is the path (in UNIX format) to the manifest created during Integrity signing. * exapps.cer is the name of the certificate being used to sign the module. * secret is the password for the private key of the certificate being used to sign the module. * exchain. is the name of the text file identifying the Export certificate chain to be embedded in the signature. * "AAAAAQ==" is the base-64 encoded value of the CDSA_USEE_DOMESTIC tag. * "XX" specifies that the CDSA_PRIV tag is not in the manifest. * "EXEMPT" is the CDSA_PVC_API tag specifying that this is an application manifest. * "XX" specifies that the CDSA_PVC_SPI tag is not in the manifest. 2 CDSA$X5092XML.EXE The x5092xml utility reads an X509 certificate file, extracts the subject name, and writes the name as XML to an XML file. This tool is useful for producing example template files that can be modified. SYNOPSIS x5092xml infile outfile OPTIONS infile The name of the X509 certificate file from which the subject name is being extracted. outfile The name of the XML file to which the name is to be written. 3 EXAMPLE x5092xml introot.cer introot.xml 2 CDSA$VALIDATE.EXE The CDSA$VALIDATE program allows the user to check the validity of a manifest against the file that it was created from. It performs the same functionality as programmatically calling CDSA_FileValidate, but from a stand-alone program. SYNOPSIS $ CDSA$VALIDATE filename OPTIONS filename The full file specification of the file for which the manifest was created. Currently, the filename must be a Windows style path in order to be compatible with CDSA. The name of the manifest that is the digital signature of 'filename' is calculated from the target filename. The manifest has a file extension of "*._ESW" where is the extension of the target file. EXAMPLE $ @sys$manager:cdsa$symbols $ validate /user1/mydirectory/foobar.pcsi RETURNS CDSA$VALIDATE will return SS$_NORMAL for success and 0 if the validation fails, or an error occurs. 2 CDSA_FileValidate NAME CDSA_FileValidate - Validate a manifest file against its target file SYNOPSIS #include int CDSA_FileValidate( char *target_file, CSSM_RETURN *CDSA_Ret_Status ); LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS target_file (input) The full filespec of the file to be validated. CDSA_Ret_Status (output) A CDSA status code. If non-zero, the status may be decoded using the routine Decode_CDSA_Error. DESCRIPTION This routine validates a target file using the associated manifest file. It is the callable equivalent of CDSA$VALIDATE.EXE. RETURN VALUE VMS_Success or VMS_Failure ERRORS Errors are described in the CDSA technical standard. See CDSA. CSSM_OK CSSM_ERRCODE_SELF_CHECK_FAILED CSSMERR_SD_NO_TARGETFILE CSSMERR_SD_NO_MANIFESTFILE CSSM_ERRCODE_MEMORY_ERROR CSSMERR_SD_MANIFESTFILE_OPEN_FAILED CSSMERR_SD_MANIFESTFILE_READ_FAILED CSSMERR_SD_TARGETFILE_STRING_NOT_FOUND CSSMERR_SD_TARGETFILE_TERMINATOR_NOT_FOUND 2 Decode_CDSA_Error NAME Decode_CDSA_Error - Turn a CDSA error code into the corresponding message SYNOPSIS #include void Decode_CDSA_Error( CSSM_RETURN Error_Code, char *Error_Label_String, char *Error_String); LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS Error_Code (input) The numeric error code return by CDSA routines. Error_Label_String (output) The string representing the error code itself. Error_String (output) The string describing the error. DESCRIPTION This routine converts a numeric CDSA error code into two strings. Error_Label_String is a string representing the error that can be used in error-checking code. Error_String is a description of the error. RETURN VALUE None ERRORS None 2 Print_CDSA_Error NAME Print_CDSA_Error - Output the CDSA error strings to SYS$OUTPUT SYNOPSIS #include void Print_CDSA_Error( CSSM_RETURN Error_Code); LIBRARY Common Security Services Manager library (CDSA$INCSSM300_SHR.EXE) PARAMETERS Error_Code (input) The numeric error code return by CDSA routines. DESCRIPTION This routine outputs the strings returned by Decode_CDSA_Error to SYS$OUTPUT. It provides a simple way report CDSA errors from a user program. RETURN VALUE None ERRORS None 2 Human Recognition Service (HRS) CDSA/HRS (Common Data Security Architecture/Human Recognition Service) is a CSSM (Common Security Services Manager) EMM (Elective Module Manager). It is intended to provide a high-level generic authentication model, suited to use for any form of human authentication. Particular emphasis has been made in the design on its suitability for authentication using biometric technology. It covers the basic functions of Enrollment, Verification, and Identification, and includes a database interface to allow a biometric service provider (BSP) to manage the identification population for optimum performance. It also provides primitives which allow the application to manage the capture of samples on a client, and the Enrollment, Verification, and Identification, on a server. The HRS is designed for use by both application developers and biometric technology developers. To make the integration of the technology as straightforward and simple as possible (thus enhancing its commercial viability), the approach taken is to hide or encapsulate to the extent possible the complexities of the biometric technology. This approach also serves to extend the generality of the interface to address a larger set of potential biometric technologies and applications. 2 CDSA_V2_New_Features New Features in CDSA V2.2 - Full support for Secure Delivery, a mechanism used to produce and validate digital signatures for PCSI kits to be installed on OpenVMS. - Version 0.9.7E of the OpenSSL crypto routines. New features in CDSA V2.1 - The ability to use CDSA$SIGN.EXE to create manifests for generic files, rather than just executable files. - CDSA$VALIDATE.EXE, which allows checking a generic manifest against the file for which it was created. Also available is the new routine CDSA_FileValidate, which can be called programmatically to perform the same function. - Version 0.9.7D of the OpenSSL crypto routines. New features in CDSA V2.0 - The tools to let application developers create certificates and sign their applications and optionally participate in bilateral authentication with CSSM. - The tools to allow developers to create new plug-in modules written for an existing category of service, and to have the modules participate in bilateral authentication with CSSM. - The tools to allow developers to create new categories of service and write plug-in modules to the new interface (and participate in bilateral authentication with CSSM). - New example programs to demonstrate the steps for writing and signing applications and plugin modules. - Version 0.9.6G of the OpenSSL crypto routines.