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

Module Directory Services APIs

The Module Directory Service API leverages a large subset of the CDSA Data Storage Library API to support query, update and schema management operations. Because MDS is a separate system from CDSA, MDS defines a small set of context management functions. The user must invoke these functions to create and destroy service contexts with MDS.

MDS Context APIs

The man-page definitions for Key Recovery Module Management Operations are presented in this section. Previous section.

NAME

MDS_Initialize

SYNOPSIS


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)

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.

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.

RETURN VALUE

A CSSM_RETURN value indicating success or specifying a particular error condition. The value CSSM_OK indicates success. All other values represent an error condition.

ERRORS

This API returns CSSM Data Storage Library error codes from the function CSSM_DL_DbCreate(). These error codes are listed below. See also the Error Codes and Error Values section in the Data Storage Library Services API.

CSSMERR_DL_INVALID_POINTER

CSSMERR_DL_INTERNAL_ERROR

CSSMERR_DL_MEMORY_ERROR

CSSMERR_DL_FUNCTION_FAILED

Previous section.

NAME

MDS_Terminate

SYNOPSIS


CSSM_RETURN CSSMAPI MDS_Terminate
    (MDS_HANDLE MdsHandle)

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.

PARAMETERS

MdsHandle (input)

The MDS handle corresponding to the context being terminated.

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

This API returns CSSM Data Storage Library error codes from the function CSSM_DL_DbCreate(). These error codes are listed below. See also the Error Codes and Error Values section in the Data Storage Library Services API.

CSSMERR_DL_INVALID_DL_HANDLE

MDS Installation APIs

The man-page definitions for MDS Installation functions are presented in this section. Previous section.

NAME

MDS_Install

SYNOPSIS


CSSM_RETURN CSSMAPI MDS_Install
    (MDS_HANDLE MdsHandle)

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.

PARAMETERS

MdsHandle (input)

The MDS handle identifying an MDS 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

This API returns CSSM Data Storage Library error codes from the function CSSM_DL_DbCreate(). These error codes are listed below. See also the Error Codes and Error Values section in the Data Storage Library Services API

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

Previous section.

NAME

MDS_Uninstall

SYNOPSIS


CSSM_RETURN CSSMAPI MDS_Uninstall
    (MDS_HANDLE MdsHandle)

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.

PARAMETERS

MdsHandle (input)

The MDS handle identifying a valid MDS 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

This API returns CSSM Data Storage Library error codes from the function CSSM_DL_DbDelete(). These error codes are listed below. See also the Error Codes and Error Values section in the Data Storage Library Services API

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

MDS Database Service APIs

MDS uses a large subset of the CDSA Data Storage Library APIs to support query, update, and schema management operations. The MDS supported functions are defined by the function table MDS_FUNCS. The service performed by each of these functions is the same as the service defined for the corresponding Data Storage Library operations.

For the definitions of these operations, refer to the relevant chapters on Data Storage Library Services API, in this Technical Standard.

Write-Access to MDS Databases

Updating MDS Schema

The MDS schema may require updating after initial installation. Conditions requiring updates are:

MDS specification change
EMM service provider installation
CDSA versioning and migration
Proprietary schema extensions.

Schema can be updated using CreateRelation and DestroyRelation. Schema update operations require special privilege and exclusive access to database files. The mechanisms for enforcing privileged access include:

Privileged application
File permissions
Administrative passphrase.

Exclusive access to database schema requires opening the MDS database with access rights defined by CSSM_DB_ACCESS_PRIVILEGED.

Updating MDS Databases

MDS records may be inserted, modified or deleted using MDS interfaces. The MDS service must be opened with write permissions CSSM_DB_ACCESS_WRITE for update operations to succeed. Read permission is needed CSSM_DB_ACCESS_READ for query operations to succeed.

Additional privileges may be needed to open a database with CSSM_DB_ACCESS_WRITE. Privileges may be acquired, and privileged access enforced, by file permissions and manifest based cross-check.

Installation programs and CDSA service providers that support dynamic insert/remove events are the primary software modules that need to update records in MDS databases. MDS requires that these callers provide signed manifest credentials authorizing write access to MDS databases. The signed manifest must contain an MDS access mask authorizing write access for the caller.

An installer provides its signed manifest credential as an explicit input parameter to the MDS_Initialize() function. When a signed manifest is provided, MDS proceeds as follows:

Verifies the integrity and authenticity of the signed manifest
Verifies the integrity of the caller's executable code
If both verifications succeed, extracts the access control information provided in the signed manifest, and associates it with an MDS handle returned by the function.

CDSA service providers that support insert/remove events need write access to MDS databases. The signed manifest of a CDSA service provider or any CDSA application is stored in the MDS database during installation of the service provider or application. The service provider's record is identified by the provider's GUID. Similarly application's record is identified by the application's GUID. When the service provider or application calls the MDS_Initialize() function, the GUID is passed as an input and signed manifest parameter of MDS_Initialize() should be NULL. When a GUID is provided, MDS proceeds as follows:

Uses the GUID to retrieve the service provider's signed manifest from the MDS database
Extracts the access control information provided in the signed manifest, and associates it with an MDS handle returned by the function.

The integrity and authenticity of the service provider has already been checked when the service provider was loaded into the CDSA environment.

When MDS databases are opened, an access control mask can be applied to the access type requested database open operation.

Manifest Attributes for MDS Access Control Privileges

Signed Manifests, as defined elsewhere in this specification, contain a set of name-value pairs, called attributes. Access privileges are granted to a module by adding an appropriate attribute to the module's signed manifest. The tag name for this attribute is CDSA_ACCESS_TAG

The value associated with the tag name sets the access permission granted to the module. Valid values are those access flag values defined by the CDSA Data Storage Library service definition of CSSM_DB_ACCESS_TYPE.

CDSA_DB_ACCESS_TYPE is a base64 encodeed, unsigned 32-bit integer in big-endian ordering.

Contents

Next section

Index