1 – AC AuthCompute
AC_AuthCompute - Compute authorization (CDSA)
SYNOPSIS
# include <cssm.h>
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
1.1 – ACHandle
(input)
The handle that describes the authorization computation module
used to perform this function.
1.2 – 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.
1.3 – 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.
1.4 – NumberOfRequestors
(input)
The number of entries in the Requestors array.
1.5 – 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.
1.6 – 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 <date1>)(not-after <date2 >)). Note that
each element is a two-element sublist. The <date> 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 (<date>).
1.7 – 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 <req>). The valid
values for <req> 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.
1.8 – 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.
2 – AC PassThrough
NAME
AC_PassThrough,
CSSM_AC_PassThrough - Call exported module-specific operations (CDSA)
SYNOPSIS
# include <cssm.h>
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)
2.1 – ACHandle
(input)
The handle that describes the authorization computation module
used to perform this function.
2.2 – 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.
2.3 – 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.
2.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.
2.5 – 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.
2.6 – PassThroughId
(input)
An identifier assigned by the AC module to indicate the exported
function to perform.
2.7 – 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.
2.8 – 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 <cssm.h>
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
4 – CL CertAbortQuery
NAME
CL_CertAbortQuery,
CSSM_CL_CertAbortQuery function - Terminate a results handle (CDSA)
SYNOPSIS
# include <cssm.h>
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
5 – CL CertCache
NAME
CL_CertCache,
CSSM_CL_CertCache - Cache a copy of a certificate (CDSA)
SYNOPSIS
# include <cssm.h>
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
6 – CL CertCreateTemplate
NAME
CL_CertCreateTemplate,
CSSM_CL_CertCreateTemplate - Allocate and initialize
memory for a certificate template (CDSA)
SYNOPSIS
# include <cssm.h>
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
7 – CL CertDescribeFormat
NAME
CL_CertDescribeFormat,
CSSM_CL_CertDescribeFormat - Return a list of the CSSM_OID values (CDSA)
SYNOPSIS
# include <cssm.h>
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
8 – CL CertGetAllFields
NAME
CL_CertGetAllFields,
CSSM_CL_CertGetAllFields - Return a list of input certificate values
(CDSA)
SYNOPSIS
# include <cssm.h>
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
9 – CL CertGetAllTemplateFields
NAME
CL_CertGetAllTemplateFields,
CSSM_CL_CertGetAllTemplateFields - Extract and return values stored
in CertTemplate (CDSA)
SYNOPSIS
# include <cssm.h>
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
10 – CL CertGetFirstCachedFieldValue
NAME
CL_CertGetFirstCachedFieldValue,
CSSM_CL_CertGetFirstCachedFieldValue - Return values from the cached
certificate (CDSA)
SYNOPSIS
# include <cssm.h>
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
11 – CL CertGetFirstFieldValue
NAME
CL_CertGetFirstFieldValue,
CSSM_CL_CertGetFirstFieldValue - Return the value of the certificate
field (CDSA)
SYNOPSIS
# include <cssm.h>
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
12 – CL CertGetKeyInfo
NAME
CL_CertGetKeyInfo,
CSSM_CL_CertGetKeyInfo - Return the public key and integral
information (CDSA)
SYNOPSIS
# include <cssm.h>
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
13 – CL CertGetNextCachedFieldValue
NAME
CL_CertGetNextCachedFieldValue,
CSSM_CL_CertGetNextCachedFieldValue - Return the value of a certificate
field (CDSA)
SYNOPSIS
# include <cssm.h>
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
14 – CL CertGetNextFieldValue
NAME
CL_CertGetNextFieldValue,
CSSM_CL_CertGetNextFieldValue - Return the value of a certificate
field (CDSA)
SYNOPSIS
# include <cssm.h>
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
15 – CL CertGroupFromVerifiedBundle
NAME
CL_CertGroupFromVerifiedBundle,
CSSM_CL_CertGroupFromVerifiedBundle - Verify the signature of a
bundle (CDSA)
SYNOPSIS
# include <cssm.h>
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
16 – CL CertGroupToSignedBundle
NAME
CL_CertGroupToSignedBundle,
CSSM_CL_CertGroupToSignedBundle - Convert a certificate group to a
certificate bundle (CDSA)
SYNOPSIS
# include <cssm.h>
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
17 – CL CertSign
NAME
CL_CertSign,
CSSM_CL_CertSign - Sign a certificate (CDSA)
SYNOPSIS
# include <cssm.h>
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
18 – CL CertVerify
NAME
CL_CertVerify,
CSSM_CL_CertVerify - Verify a signed certificate (CDSA)
SYNOPSIS
# include <cssm.h>
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
19 – CL CertVerifyWithKey
NAME
CL_CertVerifyWithKey,
CSSM_CL_CertVerifyWithKey - Verify with a key (CDSA)
SYNOPSIS
# include <cssm.h>
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
20 – CL CrlAbortCache
NAME
CL_CrlAbortCache,
CSSM_CL_CrlAbortCache - Terminate a CRL cache handle (CDSA)
SYNOPSIS
# include <cssm.h>
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
21 – CL CrlAbortQuery
NAME
CL_CrlAbortQuery,
CSSM_CL_CrlAbortQuery - Terminate a query (CDSA)
SYNOPSIS
# include <cssm.h>
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
22 – CL CrlAddCert
NAME
CL_CrlAddCert,
CSSM_CL_CrlAddCert - Revoke an input certificate (CDSA)
SYNOPSIS
# include <cssm.h>
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
23 – CL CrlCache
NAME
CL_CrlCache,
CSSM_CL_CrlCache - Cache a copy of a certificate revocation
list (CDSA)
SYNOPSIS
# include <cssm.h>
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
24 – CL CrlCreateTemplate
NAME
CL_CrlCreateTemplate,
CSSM_CL_CrlCreateTemplate - Create an unsigned, memory-resident
CRL (CDSA)
SYNOPSIS
# include <cssm.h>
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
25 – CL CrlDescribeFormat
NAME
CL_CrlDescribeFormat,
CSSM_CL_CrlDescribeFormat - Return a list of the CSSM_OID values (CDSA)
SYNOPSIS
# include <cssm.h>
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)
26 – CL CrlGetAllCachedRecordFields
NAME
CL_CrlGetAllCachedRecordFields,
CSSM_CL_CrlGetAllCachedRecordFields - Return field values from a CRL
record (CDSA)
SYNOPSIS
# include <cssm.h>
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
27 – CL CrlGetAllFields
NAME
CL_CrlGetAllFields,
CSSM_CL_CrlGetAllFields - Get the field values from the CRL (CDSA)
SYNOPSIS
# include <cssm.h>
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
28 – CL CrlGetFirstCachedFieldValue
NAME
CL_CrlGetFirstCachedFieldValue,
CSSM_CL_CrlGetFirstCachedFieldValue - Get field values from the cached
CRL (CDSA)
SYNOPSIS
# include <cssm.h>
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
29 – CL CrlGetFirstFieldValue
NAME
CL_CrlGetFirstFieldValue,
CSSM_CL_CrlGetFirstFieldValue - Get the value of the first CRL
field (CDSA)
SYNOPSIS
# include <cssm.h>
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
30 – CL CrlGetNextCachedFieldValue
NAME
CL_CrlGetNextCachedFieldValue,
CSSM_CL_CrlGetNextCachedFieldValue - Get the value of the next cached
CRL field (CDSA)
SYNOPSIS
# include <cssm.h>
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
31 – CL CrlGetNextFieldValue
NAME
CL_CrlGetNextFieldValue,
CSSM_CL_CrlGetNextFieldValue - Get the value of the next CRL
field (CDSA)
SYNOPSIS
# include <cssm.h>
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
32 – CL CrlRemoveCert
NAME
CL_CrlRemoveCert,
CSSM_CL_CrlRemoveCert - Reinstate a certificate (CDSA)
SYNOPSIS
# include <cssm.h>
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
33 – CL CrlSetFields
NAME
CL_CrlSetFields,
CSSM_CL_CrlSetFields - Set new field values (CDSA)
SYNOPSIS
# include <cssm.h>
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
34 – CL CrlSign
NAME
CL_CrlSign,
CSSM_CL_CrlSign - Sign a CRL (CDSA)
SYNOPSIS
# include <cssm.h>
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
35 – CL CrlVerify
NAME
CL_CrlVerify,
CSSM_CL_CrlVerify - Verify a signed CRL has not been altered (CDSA)
SYNOPSIS
# include <cssm.h>
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
36 – CL CrlVerifyWithKey
NAME
CL_CrlVerifyWithKey,
CSSM_CL_CrlVerifyWithKey - Verify a CRL with a specific key (CDSA)
SYNOPSIS
# include <cssm.h>
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
37 – CL FreeFieldValue
NAME
CL_FreeFieldValue,
CSSM_CL_FreeFieldValue - Free field data (CDSA)
SYNOPSIS
# include <cssm.h>
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)
38 – CL FreeFields
NAME
CL_FreeFields,
CSSM_CL_FreeFields - Free fields (CDSA)
SYNOPSIS
# include <cssm.h>
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)
39 – CL IsCertInCachedCrl
NAME
CL_IsCertInCachedCrl,
CSSM_CL_IsCertInCachedCrl - Search cached CRL for a record (CDSA)
SYNOPSIS
# include <cssm.h>
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
40 – CL IsCertInCrl
NAME
CL_IsCertInCrl,
CSSM_CL_IsCertInCrl - Search CRL for a certificate record (CDSA)
SYNOPSIS
# include <cssm.h>
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)
41 – CL PassThrough
NAME
CL_PassThrough,
CSSM_CL_PassThrough - Extend certificate library functionality (CDSA)
SYNOPSIS
# include <cssm.h>
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)
42 – CSP EventNotify
NAME
CSP_EventNotify - Notify service module of a context event (CDSA)
SYNOPSIS
# include <cssm.h>
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
43 – CSSM CSP ChangeLoginAcl
NAME
CSSM_CSP_ChangeLoginAcl - Edit a stored CSP ACL login session (CDSA)
SYNOPSIS
# include <cssm.h>
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
44 – CSSM CSP ChangeLoginOwner
NAME
CSSM_CSP_ChangeLoginOwner - Define a new login owner (CDSA)
SYNOPSIS
# include <cssm.h>
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
45 – CSSM CSP CreateAsymmetricContext
NAME
CSSM_CSP_CreateAsymmetricContext - Create an asymmetric encryption
cryptographic context (CDSA)
SYNOPSIS
# include <cssm.h>
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
46 – CSSM CSP CreateDeriveKeyContext
NAME
CSSM_CSP_CreateDeriveKeyContext - Create a cryptographic context to
derive a symmetric key (CDSA)
SYNOPSIS
# include <cssm.h>
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
47 – CSSM CSP CreateDigestContext
NAME
CSSM_CSP_CreateDigestContext - Create a digest cryptographic
context (CDSA)
SYNOPSIS
# include <cssm.h>
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
48 – CSSM CSP CreateKeyGenContext
NAME
CSSM_CSP_CreateKeyGenContext - Create a key generation cryptographic
context (CDSA)
SYNOPSIS
# include <cssm.h>
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
49 – CSSM CSP CreateMacContext
NAME
CSSM_CSP_CreateMacContext - Create a message authentication code
cryptographic context (CDSA)
SYNOPSIS
# include <cssm.h>
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
50 – CSSM CSP CreatePassThroughContext
NAME
CSSM_CSP_CreatePassThroughContext - Create a custom cryptographic
context (CDSA)
SYNOPSIS
# include <cssm.h>
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
51 – CSSM CSP CreateRandomGenContext
NAME
CSSM_CSP_CreateRandomGenContext - Create a random number generation
cryptographic context (CDSA)
SYNOPSIS
# include <cssm.h>
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
52 – CSSM CSP CreateSignatureContext
NAME
CSSM_CSP_CreateSignatureContext - Create a signature cryptographic
context (CDSA)
SYNOPSIS
# include <cssm.h>
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
53 – CSSM CSP CreateSymmetricContext
NAME
CSSM_CSP_CreateSymmetricContext - Create a symmetric encryption
cryptographic context (CDSA)
SYNOPSIS
# include <cssm.h>
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
54 – CSSM CSP GetLoginAcl
NAME
CSSM_CSP_GetLoginAcl - Get description of CSP ACL entries (CDSA)
SYNOPSIS
# include <cssm.h>
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
55 – CSSM CSP GetLoginOwner
NAME
CSSM_CSP_GetLoginOwner - Get login owner data (CDSA)
SYNOPSIS
# include <cssm.h>
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
56 – CSSM CSP Login
NAME
CSSM_CSP_Login - Log user in to the CSP (CDSA)
SYNOPSIS
# include <cssm.h>
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
57 – CSSM CSP Logout
NAME
CSSM_CSP_Logout - Terminate the login session (CDSA)
SYNOPSIS
# include <cssm.h>
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
58 – CSSM ChangeKeyAcl
NAME
CSSM_ChangeKeyAcl - Edit a stored ACL associated with the target
key (CDSA)
SYNOPSIS
# include <cssm.h>
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
59 – CSSM ChangeKeyOwner
NAME
CSSM_ChangeKeyOwner - Change the owner of a key (CDSA)
SYNOPSIS
# include <cssm.h>
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
60 – CSSM DeleteContext
NAME
CSSM_DeleteContext - Free the context structure (CDSA)
SYNOPSIS
# include <cssm.h>
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
61 – CSSM DeleteContextAttributes
NAME
CSSM_DeleteContextAttributes - Delete internal data (CDSA)
SYNOPSIS
# include <cssm.h>
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
62 – CSSM FreeContext
NAME
CSSM_FreeContext - Free memory associated with the context
structure (CDSA)
SYNOPSIS
# include <cssm.h>
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
63 – CSSM GetAPIMemoryFunctions
NAME
CSSM_GetAPIMemoryFunctions - Retrieve the memory function table
associated with the security service
module
SYNOPSIS
# include <cssm.h>
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)
64 – CSSM GetContext
NAME
CSSM_GetContext - Get context information (CDSA)
SYNOPSIS
# include <cssm.h>
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
65 – CSSM GetContextAttribute
NAME
CSSM_GetContextAttribute - Get context attribute (CDSA)
SYNOPSIS
# include <cssm.h>
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
66 – CSSM GetKeyAcl
NAME
CSSM_GetKeyAcl - Get ACL entries by key (CDSA)
SYNOPSIS
# include <cssm.h>
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
67 – CSSM GetKeyOwner
NAME
CSSM_GetKeyOwner - Get data describing key owner (CDSA)
SYNOPSIS
# include <cssm.h>
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
68 – CSSM GetModuleGUIDFromHandle
NAME
CSSM_GetModuleGUIDFromHandle - Get GUID of the attached module (CDSA)
SYNOPSIS
# include <cssm.h>
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
69 – CSSM GetPrivilege
NAME
CSSM_GetPrivilege - Get CSSM privilege value (CDSA)
SYNOPSIS
# include <cssm.h>
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
70 – CSSM GetSubserviceUIDFromHandle
NAME
CSSM_GetSubserviceUIDFromHandle - Complete a subservice unique
identifier structure (CDSA)
SYNOPSIS
# include <cssm.h>
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
71 – CSSM Init
NAME
CSSM_Init - Initialize CSSM (CDSA)
SYNOPSIS
# include <cssm.h>
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=<n/a> 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=<n/a> CDSA_PVC_API=<n/a> API checks: on (1)
CDSA_PVC_API=OFF CDSA_PVC_API=<n/a> 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=<n/a> 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=<n/a> CDSA_PVC_SPI=<n/a> SPI checks: on (2)
CDSA_PVC_SPI=OFF CDSA_PVC_SPI=<n/a> 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)
72 – CSSM Introduce
NAME
CSSM_Introduce - Identify an executable module (CDSA)
SYNOPSIS
# include <cssm.h>
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)
73 – CSSM ListAttachedModuleManagers
NAME
CSSM_ListAttachedModuleManagers - Get a list of GUIDs for the
attached module manager(CDSA)
SYNOPSIS
# include <cssm.h>
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)
74 – CSSM ModuleAttach
NAME
CSSM_ModuleAttach - Attach and verify a service provider
module (CDSA)
SYNOPSIS
# include <cssm.h>
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
75 – CSSM ModuleDetach
NAME
CSSM_ModuleDetach - Detach application from service provider
module (CDSA)
SYNOPSIS
# include <cssm.h>
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
76 – CSSM ModuleLoad
NAME
CSSM_ModuleLoad - Initialize the security service module (CDSA)
SYNOPSIS
# include <cssm.h>
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)
77 – CSSM ModuleUnload
NAME
CSSM_ModuleUnload - Deregister event notification callbacks (CDSA)
SYNOPSIS
# include <cssm.h>
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)
78 – CSSM SPI ModuleAttach
NAME
CSSM_SPI_ModuleAttach - Attach a service provider module(CDSA)
SYNOPSIS
# include <cssm.h>
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
79 – CSSM SPI ModuleDetach
NAME
CSSM_SPI_ModuleDetach - Notify service module of a context
event (CDSA)
SYNOPSIS
# include <cssm.h>
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
80 – CSSM SPI ModuleLoad
NAME
CSSM_SPI_ModuleLoad - Initialize process between CSSM and the add-in
service module (CDSA)
SYNOPSIS
# include <cssm.h>
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
81 – CSSM SPI ModuleUnload
NAME
CSSM_SPI_ModuleUnload - Disable events and deregister CSSM event
notification (CDSA)
SYNOPSIS
# include <cssm.h>
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
82 – CSSM SetContext
NAME
CSSM_SetContext - Replace all context information (CDSA)
SYNOPSIS
# include <cssm.h>
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
83 – CSSM SetPrivilege
NAME
CSSM_SetPrivilege - Store privilege value in CSSM framework (CDSA)
SYNOPSIS
# include <cssm.h>
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
84 – CSSM TP RetrieveCredResult
NAME
CSSM_TP_RetrieveCredResult - Return the results of the credentials
request (CDSA)
SYNOPSIS
# include <cssm.h>
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 <estimated seconds>
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
85 – CSSM Terminate
NAME
CSSM_Terminate - Terminate the use of CSSM (CDSA)
SYNOPSIS
# include <cssm.h>
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
86 – CSSM Unintroduce
NAME
CSSM_Unintroduce - Remove module (CDSA)
SYNOPSIS
# include <cssm.h>
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)
87 – CSSM UpdateContextAttributes
NAME
CSSM_UpdateContextAttributes - Update context attribute values (CDSA)
SYNOPSIS
# include <cssm.h>
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
88 – DL Authenticate
NAME
DL_Authenticate, CSSM_DL_Authenticate - Provide authentication
credentials (CDSA)
SYNOPSIS
# include <cssm.h>
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
89 – DL ChangeDbAcl
NAME
DL_ChangeDbAcl, CSSM_DL_ChangeDbAcl - Edit stored ACL (CDSA)
SYNOPSIS
# include <cssm.h>
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
90 – DL ChangeDbOwner
NAME
DL_ChangeDbOwner, CSSM_DL_ChangeDbOwner - Define a new data base
owner (CDSA)
SYNOPSIS
# include <cssm.h>
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
91 – DL CreateRelation
NAME
DL_CreateRelation, CSSM_DL_CreateRelation - Create a new persistent
relation (CDSA)
SYNOPSIS
# include <cssm.h>
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
92 – DL DataAbortQuery
NAME
DL_DataAbortQuery, CSSM_DL_DataAbortQuery - Terminate DL_DataGetFirst
query (CDSA)
SYNOPSIS
# include <cssm.h>
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
93 – DL DataDelete
NAME
DL_DataDelete, CSSM_DL_DataDelete - Remove data record (CDSA)
SYNOPSIS
# include <cssm.h>
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
94 – DL DataGetFirst
NAME
DL_DataGetFirst, CSSM_DL_DataGetFirst - Get first data record (CDSA)
SYNOPSIS
# include <cssm.h>
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
95 – DL DataGetFromUniqueRecordId
NAME
DL_DataGetFromUniqueRecordId,
CSSM_DL_DataGetFromUniqueRecordId - Get data record (CDSA)
SYNOPSIS
# include <cssm.h>
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
96 – DL DataGetNext
NAME
DL_DataGetNext, CSSM_DL_DataGetNext - Get next data record (CDSA)
SYNOPSIS
# include <cssm.h>
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
97 – DL DataInsert
NAME
DL_DataInsert, CSSM_DL_DataInsert - Create new persistent data
record (CDSA)
SYNOPSIS
# include <cssm.h>
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
98 – DL DataModify
NAME
DL_DataModify, CSSM_DL_DataModify - Modify persistent data
record (CDSA)
SYNOPSIS
# include <cssm.h>
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
99 – DL DbClose
NAME
DL_DbClose, CSSM_DL_DbClose - Close open data store (CDSA)
SYNOPSIS
# include <cssm.h>
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
100 – DL DbCreate
NAME
DL_DbCreate, CSSM_DL_DbCreate - Create and open new data
store (CDSA)
SYNOPSIS
# include <cssm.h>
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
101 – DL DbDelete
NAME
DL_DbDelete, CSSM_DL_DbDelete - Delete all records (CDSA)
SYNOPSIS
# include <cssm.h>
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
102 – DL DbOpen
NAME
DL_DbOpen, CSSM_DL_DbOpen - Open a data store (CDSA)
SYNOPSIS
# include <cssm.h>
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
103 – DL DestroyRelation
NAME
DL_DestroyRelation, CSSM_DL_DestroyRelation - Destroy an existing
relation (CDSA)
SYNOPSIS
# include <cssm.h>
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
104 – DL FreeNameList
NAME
DL_FreeNameList, CSSM_DL_FreeNameList - Free the list of the logical
data store names (CDSA)
SYNOPSIS
# include <cssm.h>
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
105 – DL FreeUniqueRecord
NAME
DL_FreeUniqueRecord, CSSM_DL_FreeUniqueRecord - Free data store
memory (CDSA)
SYNOPSIS
# include <cssm.h>
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
106 – DL GetDbAcl
NAME
DL_GetDbAcl, CSSM_DL_GetDbAcl - Get ACL description (CDSA)
SYNOPSIS
# include <cssm.h>
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
107 – DL GetDbNameFromHandle
NAME
DL_GetDbNameFromHandle,
CSSM_DL_GetDbNameFromHandle - Get data source name (CDSA)
SYNOPSIS
# include <cssm.h>
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
108 – DL GetDbNames
NAME
DL_GetDbNames, CSSM_DL_GetDbNames - Get list of logical data store
names (CDSA)
SYNOPSIS
# include <cssm.h>
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
109 – DL GetDbOwner
NAME
DL_GetDbOwner, CSSM_DL_GetDbOwner - Get data base owner (CDSA)
SYNOPSIS
# include <cssm.h>
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
110 – DL PassThrough
NAME
DL_PassThrough, CSSM_DL_PassThrough - Extend data storage module
functionality (CDSA)
SYNOPSIS
# include <cssm.h>
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
111 – DecryptData
NAME
DecryptData,
CSSM_DecryptData,
CSP_DecryptData - Decrypt buffer data (CDSA)
SYNOPSIS
# include <cssm.h>
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
112 – DecryptDataFinal
NAME
DecryptDataFinal,
CSSM_DecryptDataFinal,
CSP_DecryptDataFinal - Finalize staged decryption process (CDSA)
SYNOPSIS
# include <cssm.h>
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
113 – DecryptDataInit
NAME
DecryptDataInit,
CSSM_DecryptDataInit,
CSP_DecryptDataInit - Initialize the staged decrypt function(CDSA)
SYNOPSIS
# include <cssm.h>
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
114 – DecryptDataInitP
NAME
DecryptDataInitP - Intialize the staged decrypt function with
privilege (CDSA)
SYNOPSIS
# include <cssm.h>
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
115 – DecryptDataP
NAME
DecryptDataP - Decrypt data with privilege (CDSA)
SYNOPSIS
# include <cssm.h>
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
116 – DecryptDataUpdate
NAME
DecryptDataUpdate,
CSSM_DecryptDataUpdate,
CSP_DecryptDataUpdate - Continue the staged decryption process (CDSA)
SYNOPSIS
# include <cssm.h>
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
117 – DeregisterDispatchTable
NAME
DeregisterDispatchTable - Invalidate CSSM pointers to EMM (CDSA)
SYNOPSIS
# include <cssm.h>
(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
118 – DeriveKey
NAME
DeriveKey,
CSSM_DeriveKey,
CSP_DeriveKey - Derive new symmetric key (CDSA)
SYNOPSIS
# include <cssm.h>
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
119 – DigestData
NAME
DigestData,
CSSM_DigestData,
CSP_DigestData - Compute message digest (CDSA)
SYNOPSIS
# include <cssm.h>
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
120 – DigestDataClone
NAME
DigestDataClone,
CSSM_DigestDataClone,
CSP_DigestDataClone - Clone a staged message digest (CDSA)
SYNOPSIS
# include <cssm.h>
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
121 – DigestDataFinal
NAME
DigestDataFinal,
CSSM_DigestDataFinal,
CSP_DigestDataFinal - Finalize the staged message digest (CDSA)
SYNOPSIS
# include <cssm.h>
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
122 – DigestDataInit
NAME
DigestDataInit,
CSSM_DigestDataInit,
CSP_DigestDataInit - Initialize the staged message digest (CDSA)
SYNOPSIS
# include <cssm.h>
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
123 – DigestDataUpdate
NAME
DigestDataUpdate,
CSSM_DigestDataUpdate - Continue the staged process of digesting (CDSA)
SYNOPSIS
# include <cssm.h>
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
124 – EncryptData
NAME
EncryptData,
CSSM_EncryptData,
CSP_EncryptData - Encrypts all buffer data (CDSA)
SYNOPSIS
# include <cssm.h>
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
125 – EncryptDataFinal
NAME
EncryptDataFinal,
CSSM_EncryptDataFinal,
CSP_EncryptDataFinal - Finalize staged encryption process (CDSA)
SYNOPSIS
# include <cssm.h>
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
126 – EncryptDataInit
NAME
EncryptDataInit,
CSSM_EncryptDataInit,
CSP_EncryptDataInit - Initialize the staged encrypt funciton (CDSA)
SYNOPSIS
# include <cssm.h>
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
127 – EncryptDataInitP
NAME
EncryptDataInitP - Initialize the staged encrypt function with
privilege (CDSA)
SYNOPSIS
# include <cssm.h>
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
128 – EncryptDataP
NAME
EncryptDataP - Encrypt data with privilege (CDSA)
SYNOPSIS
# include <cssm.h>
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
129 – EncryptDataUpdate
NAME
EncryptDataUpdate,
CSSM_EncryptDataUpdate,
CSP_EncryptDataUpdate - Continue the staged encryption process (CDSA)
SYNOPSIS
# include <cssm.h>
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
130 – EventNotifyManager
NAME
EventNotifyManager - Receive an event notification (CDSA)
SYNOPSIS
# include <cssm.h>
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
131 – FreeKey
NAME
FreeKey, CSSM_FreeKey, CSP_FreeKey - Clean up keys (CDSA)
SYNOPSIS
# include <cssm.h>
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
132 – GenerateAlgorithmParams
NAME
GenerateAlgorithmParams,
CSSM_GenerateAlgorithmParams,
CSP_GenerateAlgorithmParams - Generate algorithm parameters (CDSA)
SYNOPSIS
# include <cssm.h>
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
133 – GenerateKey
NAME
GenerateKey,
CSSM_GenerateKey,
CSP_GenerateKey - Generate a symmetric key (CDSA)
SYNOPSIS
# include <cssm.h>
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
134 – GenerateKeyP
NAME
GenerateKeyP - Generate a key with privilege (CDSA)
SYNOPSIS
# include <cssm.h>
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
135 – GenerateKeyPair
NAME
GenerateKeyPair,
CSSM_GenerateKeyPair,
CSP_GenerateKeyPair - Generate an asymmetric key pair (CDSA)
SYNOPSIS
# include <cssm.h>
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
136 – GenerateKeyPairP
NAME
GenerateKeyPairP - Generate an asymmetric key pair with
privilege (CDSA)
SYNOPSIS
# include <cssm.h>
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
137 – GenerateMac
NAME
GenerateMac,
CSSM_GenerateMac,
CSP_GenerateMac - Compute a message authentication code (CDSA)
SYNOPSIS
# include <cssm.h>
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
138 – GenerateMacFinal
NAME
GenerateMacFinal,
CSSM_GenerateMacFinal,
CSP_GenerateMacFinal - Finalize the staged message authentication
code (CDSA)
SYNOPSIS
# include <cssm.h>
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
139 – GenerateMacInit
NAME
GenerateMacInit,
CSSM_GenerateMacInit,
CSP_GenerateMacInit - Initialize the staged message
authentication code (CDSA)
SYNOPSIS
# include <cssm.h>
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
140 – GenerateMacUpdate
NAME
GenerateMacUpdate,
CSSM_GenerateMacUpdate,
CSP_GenerateMacUpdate - Continue the staged process of computing
a message authentication code (CDSA)
SYNOPSIS
# include <cssm.h>
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
141 – GenerateRandom
NAME
GenerateRandom,
CSSM_GenerateRandom,
CSP_GenerateRandom function - Generate random data (CDSA)
SYNOPSIS
# include <cssm.h>
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
142 – GetOperationalStatistics
NAME
GetOperationalStatistics,
CSSM_CSP_GetOperationalStatistics,
CSP_GetOperationalStatistics - Get operational values of a
subservice (CDSA)
SYNOPSIS
# include <cssm.h>
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
143 – GetTimeValue
NAME
GetTimeValue,
CSSM_GetTimeValue,
CSP_GetTimeValue - Get a CSP time value (CDSA)
SYNOPSIS
# include <cssm.h>
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
144 – HRS FreeBIRHandle
NAME
CSSM_HRS_FreeBIRHandle, HRS_FreeBIRHandle - Free memory associated
with BIR Handle
SYNOPSIS
#include <hrs.h>
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
145 – HRS GetBIRFromHandle
NAME
CSSM_HRS_GetBIRFromHandle, HRS_GetBIRFromHandle
SYNOPSIS
#include <hrs.h>
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
146 – HRS GetHeaderFromHandle
NAME
CSSM_HRS_GetHeaderFromHandle, HRS_GetHeaderFromHandle
SYNOPSIS
#include <hrs.h>
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
147 – HRS EnableEvents
NAME
CSSM_HRS_EnableEvents, HRS_EnableEvents
SYNOPSIS
#include <hrs.h>
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
148 – HRS SetGUICallbacks
NAME
CSSM_HRS_SetGUICallbacks, HRS_SetGUICallbacks
SYNOPSIS
#include <hrs.h>
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
149 – HRS CancelGUICallbacks
NAME
CSSM_HRS_CancelGUICallbacks, HRS_CancelGUICallbacks
SYNOPSIS
#include <hrs.h>
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
150 – HRS SetStreamCallback
NAME
CSSM_HRS_SetStreamCallback, HRS_SetStreamCallback
SYNOPSIS
#include <hrs.h>
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
151 – HRS CancelStreamCallbacks
NAME
CSSM_HRS_CancelStreamCallbacks, HRS_CancelStreamCallbacks
SYNOPSIS
#include <hrs.h>
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
152 – HRS StreamInputOutput
NAME
CSSM_HRS_StreamInputOutput, HRS_StreamInputOutput
SYNOPSIS
#include <hrs.h>
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
153 – HRS Capture
NAME
CSSM_HRS_Capture, HRS_Capture
SYNOPSIS
#include <hrs.h>
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
154 – HRS CreateTemplate
NAME
CSSM_HRS_CreateTemplate, HRS_CreateTemplate
SYNOPSIS
#include <hrs.h>
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
155 – HRS Process
NAME
CSSM_HRS_Process, HRS_Process
SYNOPSIS
#include <hrs.h>
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
156 – HRS VerifyMatch
NAME
CSSM_HRS_VerifyMatch, HRS_VerifyMatch
SYNOPSIS
#include <hrs.h>
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
157 – HRS IdentifyMatch
NAME
CSSM_HRS_IdentifyMatch, HRS_IdentifyMatch
SYNOPSIS
#include <hrs.h>
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
158 – HRS Enroll
NAME
CSSM_HRS_Enroll, HRS_Enroll
SYNOPSIS
#include <hrs.h>
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
159 – HRS Verify
NAME
CSSM_HRS_Verify, HRS_Verify
SYNOPSIS
#include <hrs.h>
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
160 – HRS Identify
NAME
CSSM_HRS_Identify, HRS_Identify
SYNOPSIS
#include <hrs.h>
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
161 – HRS Import
NAME
CSSM_HRS_Import, HRS_Import
SYNOPSIS
#include <hrs.h>
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
162 – HRS SetPowerMode
NAME
CSSM_HRS_SetPowerMode, HRS_SetPowerMode
SYNOPSIS
#include <hrs.h>
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
163 – HRS DbOpen
~~~
NAME
CSSM_HRS_DbOpen, HRS_DbOpen
SYNOPSIS
#include <hrs.h>
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
164 – HRS DbClose
NAME
CSSM_HRS_DbClose, HRS_DbClose
SYNOPSIS
#include <hrs.h>
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
165 – HRS DbCreate
NAME
CSSM_HRS_DbCreate, HRS_DbCreate
SYNOPSIS
#include <hrs.h>
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
166 – HRS DbDelete
NAME
CSSM_HRS_DbDelete, HRS_DbDelete
SYNOPSIS
#include <hrs.h>
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
167 – HRS DbSetCursor
NAME
CSSM_HRS_DbSetCursor, HRS_DbSetCursor
SYNOPSIS
#include <hrs.h>
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
168 – HRS DbFreeCursor
NAME
CSSM_HRS_DbFreeCursor, HRS_DbFreeCursor
SYNOPSIS
#include <hrs.h>
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
169 – HRS DbStoreBIR NAME
NAME
CSSM_HRS_DbStoreBIR, HRS_DbStoreBIR
SYNOPSIS
#include <hrs.h>
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
170 – HRS DbGetBIR
NAME
CSSM_HRS_DbGetBIR, HRS_DbGetBIR
SYNOPSIS
#include <hrs.h>
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
171 – HRS DbGetNextBIR
NAME
CSSM_HRS_DbGetNextBIR, HRS_DbGetNextBIR
SYNOPSIS
#include <hrs.h>
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
172 – HRS DbQueryBIR
NAME
CSSM_HRS_DbQueryBIR, HRS_DbQueryBIR
SYNOPSIS
#include <hrs.h>
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
173 – HRS DbDeleteBIR
NAME
CSSM_HRS_DbDeleteBIR, HRS_DbDeleteBIR
SYNOPSIS
#include <hrs.h>
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
174 – Initialize
NAME
Initialize - Verify module version (CDSA)
SYNOPSIS
# include <cssm.h>
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
175 – MDS Initialize
NAME
MDS_Initialize - Initiate service context with MDS (CDSA)
SYNOPSIS
# include <mds.h>
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
176 – MDS Install
NAME
MDS_Install - Create the object directory database (CDSA)
SYNOPSIS
#include <mds.h>
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
177 – MDS Terminate
NAME
MDS_Terminate - Terminate the MDS service context (CDSA)
SYNOPSIS
# include <mds.h>
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
178 – MDS Uninstall
NAME
MDS_Uninstall - Delete the object directory database (CDSA)
SYNOPSIS
# include <mds.h>
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
179 – ModuleManagerAuthenticate
NAME
ModuleManagerAuthenticate - Module manager authentication (CDSA)
SYNOPSIS
# include <mds.h>
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
180 – ObtainPrivateKeyFromPublicKey
NAME
ObtainPrivateKeyFromPublicKey,
CSSM_CSP_ObtainPrivateKeyFromPublicKey,
CSP_ObtainPrivateKeyFromPublicKey - Convert public key to private
key (CDSA)
SYNOPSIS
# include <cssm.h>
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
181 – PassThrough
NAME
PassThrough,
CSSM_CSP_PassThrough,
CSP_PassThrough - Extend crypto functionality (CDSA)
SYNOPSIS
# include <cssm.h>
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
182 – QueryKeySizeInBits
NAME
QueryKeySizeInBits,
CSSM_QueryKeySizeInBits,
CSP_QueryKeySizeInBits - Get CSP logical and effective sizes (CDSA)
SYNOPSIS
# include <cssm.h>
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
183 – QuerySize
NAME
QuerySize,
CSSM_QuerySize,
CSP_QuerySize - Get size of the output data (CDSA)
SYNOPSIS
# include <cssm.h>
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
184 – RefreshFunctionTable
NAME
RefreshFunctionTable - Gets EMM-defined API function (CDSA)
SYNOPSIS
# include <cssm.h>
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
185 – RegisterDispatchTable
NAME
RegisterDispatchTable - Provide the EMM with CSSM function
pointers (CDSA)
SYNOPSIS
# include <cssm.h>
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
186 – RetrieveCounter
NAME
RetrieveCounter,
CSSM_RetrieveCounter,
CSP_RetrieveCounter - Get the value of a tamper resistant clock (CDSA)
SYNOPSIS
# include <cssm.h>
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
187 – RetrieveUniqueId
NAME
RetrieveUniqueId,
CSSM_RetrieveUniqueId,
CSP_RetrieveUniqueId - Get identifier (CDSA)
SYNOPSIS
# include <cssm.h>
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
188 – SignData
NAME
SignData,
CSSM_SignData,
CSP_SignData - Sign all buffer data (CDSA)
SYNOPSIS
# include <cssm.h>
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
189 – SignDataFinal
NAME
SignDataFinal,
CSSM_SignDataFinal,
CSP_SignDataFinal - Complete the final stage of the sign data (CDSA)
SYNOPSIS
# include <cssm.h>
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
190 – SignDataInit
NAME
SignDataInit,
CSSM_SignDataInit,
CSP_SignDataInit - Initialize the staged sign data (CDSA)
SYNOPSIS
# include <cssm.h>
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
191 – SignDataUpdate
NAME
SignDataUpdate,
CSSM_SignDataUpdate,
CSP_SignDataUpdate - Continue the staged signing process input
buffer data (CDSA)
SYNOPSIS
# include <cssm.h>
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
192 – TP ApplyCrlToDb
NAME
TP_ApplyCrlToDb,
CSSM_TP_ApplyCrlToDb - Update persistent storage (CDSA)
SYNOPSIS
# include <cssm.h>
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
193 – TP CertCreateTemplate
NAME
TP_CertCreateTemplate,
CSSM_TP_CertCreateTemplate - Allocate and initialize template
memory (CDSA)
SYNOPSIS
# include <cssm.h>
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
194 – TP CertGetAllTemplateFields
NAME
TP_CertGetAllTemplateFields,
CSSM_TP_CertGetAllTemplateFields - Get CertTemplate field values (CDSA)
SYNOPSIS
# include <cssm.h>
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
195 – TP CertGroupConstruct
NAME
TP_CertGroupConstruct,
CSSM_TP_CertGroupConstruct - Construct credential (CDSA)
SYNOPSIS
# include <cssm.h>
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
196 – TP CertGroupPrune
NAME
TP_CertGroupPrune,
CSSM_TP_CertGroupPrune - Remove locally issued anchor
certificates (CDSA)
SYNOPSIS
# include <cssm.h>
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
197 – TP CertGroupToTupleGroup
NAME
TP_CertGroupToTupleGroup,
CSSM_TP_CertGroupToTupleGroup - Create a set of authorization
tuples (CDSA)
SYNOPSIS
# include <cssm.h>
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
198 – TP CertGroupVerify
NAME
TP_CertGroupVerify,
CSSM_TP_CertGroupVerify - Determine if a certificate is trusted (CDSA)
SYNOPSIS
# include <cssm.h>
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
199 – TP CertReclaimAbort
NAME
TP_CertReclaimAbort,
CSSM_TP_CertReclaimAbort - Terminate the process of reclaiming
certificates (CDSA)
SYNOPSIS
# include <cssm.h>
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
200 – TP CertReclaimKey
NAME
TP_CertReclaimKey,
CSSM_TP_CertReclaimKey - Get private key associated with a
certificate (CDSA)
SYNOPSIS
# include <cssm.h>
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
201 – 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 <cssm.h>
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
202 – TP CertRevoke
NAME
TP_CertRevoke,
CSSM_TP_CertRevoke - Determine if the revoking certificate
group can revoke the subject certificate
group (CDSA)
SYNOPSIS
# include <cssm.h>
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
203 – TP CertSign
NAME
TP_CertSign,
CSSM_TP_CertSign - Determine if signer certificate is trusted (CDSA)
SYNOPSIS
# include <cssm.h>
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
204 – TP ConfirmCredResult
NAME
TP_ConfirmCredResult,
CSSM_TP_ConfirmCredResult - Confirm credentials (CDSA)
SYNOPSIS
# include <cssm.h>
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
205 – TP CrlCreateTemplate
NAME
TP_CrlCreateTemplate,
CSSM_TP_CrlCreateTemplate - Create an unsigned memory-resident CRL
template (CDSA)
SYNOPSIS
# include <cssm.h>
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
206 – TP CrlSign
NAME
TP_CrlSign,
CSSM_TP_CrlSign - Determine if signer certificate is trusted (CDSA)
SYNOPSIS
# include <cssm.h>
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
207 – TP CrlVerify
NAME
TP_CrlVerify,
CSSM_TP_CrlVerify - Verify integrity of the certificate
revocation list (CDSA)
SYNOPSIS
# include <cssm.h>
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
208 – TP FormRequest
NAME
TP_FormRequest,
CSSM_TP_FormRequest - Get form from authority (CDSA)
SYNOPSIS
# include <cssm.h>
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
209 – TP FormSubmit
NAME
TP_FormSubmit,
CSSM_TP_FormSubmit - Submit form to ClearanceAuthority (CDSA)
SYNOPSIS
# include <cssm.h>
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
210 – TP PassThrough
NAME
TP_PassThrough,
CSSM_TP_PassThrough - Extend trust policy functionality
SYNOPSIS
# include <cssm.h>
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
211 – TP ReceiveConfirmation
NAME
TP_ReceiveConfirmation,
CSSM_TP_ReceiveConfirmation - Poll for confirmation (CDSA)
SYNOPSIS
# include <cssm.h>
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 <elapsed seconds>
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
212 – TP SubmitCredRequest
NAME
TP_SubmitCredRequest,
CSSM_TP_SubmitCredRequest - Submit credential request (CDSA)
SYNOPSIS
# include <cssm.h>
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
213 – TP TupleGroupToCertGroup
NAME
TP_TupleGroupToCertGroup,
CSSM_TP_TupleGroupToCertGroup - Create a set of certificate
templates (CDSA)
SYNOPSIS
# include <cssm.h>
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
214 – Terminate
NAME
Terminate - Clean up module-manager-specific activities (CDSA)
SYNOPSIS
# include <cssm.h>
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
215 – UnwrapKey
NAME
UnwrapKey,
CSSM_UnwrapKey,
CSP_UnwrapKey - Unwrap the wrapped key (CDSA)
SYNOPSIS
# include <cssm.h>
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
216 – UnwrapKeyP
NAME
UnwrapKeyP - Unwrap the wrapped keys with privilege (CDSA)
SYNOPSIS
# include <cssm.h>
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
217 – VerifyData
NAME
VerifyData,
CSSM_VerifyData,
CSP_VerifyData - Verify input buffer data (CDSA)
SYNOPSIS
# include <cssm.h>
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
218 – VerifyDataFinal
NAME
VerifyDataFinal,
CSSM_VerifyDataFinal,
CSP_VerifyDataFinal - Finalize the staged verify data (CDSA)
SYNOPSIS
# include <cssm.h>
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
219 – VerifyDataInit
NAME
VerifyDataInit,
CSSM_VerifyDataInit,
CSP_VerifyDataInit - Initialize the staged verify data (CDSA)
SYNOPSIS
# include <cssm.h>
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
220 – VerifyDataUpdate
NAME
VerifyDataUpdate,
CSSM_VerifyDataUpdate,
CSP_VerifyDataUpdate - Continue the staged verification (CDSA)
SYNOPSIS
# include <cssm.h>
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
221 – VerifyDevice
NAME
VerifyDevice,
CSSM_VerifyDevice,
CSP_VerifyDevice - Cause the cryptographic module to perform a
self verification and integrity check (CDSA)
SYNOPSIS
# include <cssm.h>
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
222 – VerifyMac
NAME
VerifyMac,
CSSM_VerifyMac,
CSP_VerifyMac - Verify the message authentication code (CDSA)
SYNOPSIS
# include <cssm.h>
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
223 – VerifyMacFinal
NAME
VerifyMacFinal,
CSSM_VerifyMacFinal,
CSP_VerifyMacFinal - Finalize the staged message authentication
code (CDSA)
SYNOPSIS
# include <cssm.h>
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
224 – VerifyMacInit
NAME
VerifyMacInit,
CSSM_VerifyMacInit,
CSP_VerifyMacInit - Initialize the staged message authentication
code (CDSA)
SYNOPSIS
# include <cssm.h>
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
225 – VerifyMacUpdate
NAME
VerifyMacUpdate,
CSSM_VerifyMacUpdate,
CSP_VerifyMacUpdate - Continue the staged process of verifying
the message authentication code (CDSA)
SYNOPSIS
# include <cssm.h>
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
226 – WrapKey
NAME
WrapKey,
CSSM_WrapKey,
CSP_WrapKey - Wrap a key using the context (CDSA)
SYNOPSIS
# include <cssm.h>
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
227 – WrapKeyP
NAME
WrapKeyP - Wrap a key with privilege (CDSA)
SYNOPSIS
# include <cssm.h>
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
228 – cssm CcToHandle
NAME
cssm_CcToHandle - Get the module attach handle (CDSA)
SYNOPSIS
# include <cssm.h>
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
229 – cssm DeregisterManagerServices
NAME
cssm_DeregisterManagerServices - Deregister manager services
SYNOPSIS
# include <cssm.h>
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
230 – cssm GetAppMemoryFunctions
NAME
cssm_GetAppMemoryFunctions - Get service functions (CDSA)
SYNOPSIS
# include <cssm.h>
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
231 – cssm GetAttachFunctions
NAME
cssm_GetAttachFunctions - Get SPI function table (CDSA)
SYNOPSIS
# include <cssm.h>
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
232 – cssm GetModuleInfo
NAME
cssm_GetModuleInfo - Get the module handle state information
SYNOPSIS
# include <cssm.h>
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
233 – cssm IsFuncCallValid
NAME
cssm_IsFuncCallValid - Check secure linkage (CDSA)
SYNOPSIS
# include <cssm.h>
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
234 – cssm ReleaseAttachFunctions
NAME
cssm_ReleaseAttachFunctions - Release lock on the SP function
table (CDSA)
SYNOPSIS
# include <cssm.h>
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