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