NAME

CSSM_RequestCssmExemption

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_RequestCssmExemption
    (CSSM_EXEMPTION_MASK ExemptionRequests,
    const char *AppFileName,
    const char *AppPathName,
    const void * Reserved)         

DESCRIPTION

This function authenticates the application and verifies whether it is authorized to receive the requested CSSM exemptions. Authentication is based on successful verification of the application's signed manifest credentials. Implied authorization can require credential verification based on specific roots of trust.

The exemption mask defines the requested exemptions. The application file name and application pathname specify the location of the application's credentials.

Applications may invoke this function multiple times. Each successful verification replaces the previously granted exemptions. Exemptions are not inherited by spawned processes or spawned threads.

CSSM and CSSM elective module managers are the authorization entities that define the roots of trust for authenticating applications and granting exemptions from built-in checks. The set of trusted roots can grow during execution. This makes an application's request for exemption dependent on execution order. If an application performs all module attach operations before calling CSSM_RequestCssmExemption, then all points of trust/authorization that could be effected by that request are known and the request can be accurately processed. If an application's authentication (and implied authorization) is dependent on roots of trust that are not yet known, then the application cannot be authenticated and the request for exemption will be denied.

PARAMETERS

ExemptionRequest (input)

A bitmask of all exemptions being requested by the caller.

AppFileName (input)

The name of the file that implements the application (containing its main entry point). This file name is used to locate the application's credentials for purposes of application authentication by CSSM.

AppPathName (input)

The path to the file that implements the application (containing its main entry point). This path name is used to locate the application's credentials for purposes of application authentication by CSSM.

Reserved (input/optional)

A reserved input.

RETURN VALUE

A CSSM_OK return value signifies the verification operation was successful and the exemption has been granted. When CSSM_FAIL is returned, an error has occurred. Use CSSM_GetError to obtain the error code.

ERRORS

CSSM_INVALID_CREDENTIALS

Malformed or missing credentials.

CSSM_NOT_AUTHORIZED

Credentials do not verify for requested exemptions.