NAME

CSSM_KR_SetEnterpriseRecoveryPolicy

SYNOPSIS

CSSM_RETURN CSSMAPI CSSM_KR_SetEnterpriseRecoveryPolicy
    (const CSSM_DATA_PTR RecoveryPolicyFileName,
    const CSSM_CRYPTO_DATA_PTR OldPassPhrase)
    const CSSM_CRYPTO_DATA_PTR NewPassPhrase)

DESCRIPTION

This call establishes the identity of the file that contains the enterprise key recovery policy function. The first time this function is invoked, the old passphrase is established for access control purposes. Subsequent invocations of this function will require the original passphrase to be supplied in order to update the filename of the policy function. Optionally the passphrase can be changed from the oldpassphrase to the newpassphrase on subsequent invocations.

The policy function module is operating system platform specific (for Windows 95 and Windows NT, it may be a DLL, for UNIX platforms, it may be a separate executable which gets launched by the KRMM. It is expected that the policy function file will be protected using the available protection mechanisms of the operating system platform. The policy function is expected to conform to the following interface:

boolean EnterpriseRecoveryPolicy(CSSM_CONTEXT CryptoContext);

The Boolean return value of this policy function will determine whether enterprise-based key recovery is mandated for the given cryptographic operation.

PARAMETERS

RecoveryPolicyFileName (input)

A pointer to a CSSM_DATA structure that contains the file name of the module that contains the enterprise key recovery policy function. The filename may be a fully qualified pathname or a partial pathname.

OldPassPhrase (input)

The current, active passphrase that controls access to this operation.

NewPassPhrase (input/optional)

A new passphrase that becomes the current, active passphrase after the execution of this function. It must be used to control access to future invocations of this operation.

RETURN VALUES

A CSSM return value. This function returns CSSM_OK if successful and returns an error code if an error has occurred.

ERRORS

CSSM_KR_INVALID_FILENAME

Invalid policy file name.

CSSM_MEMORY_ERROR

Memory error.