This call establishes the identity of the file that contains the enterprise key recovery policy function. It allows the use of a passphrase for access control to the update of the enterprise policy module. The first time this function is invoked, the old passphrase should be "default" in the Param field of the CSSM_CRYPTO_DATA_PTR. A passphrase can be established at this time for subsequent access control to this function by entering it in the NewPassphrase parameter. If the passphrase is to be changed, both the old and new passphrases have to be supplied.

The policy function module is operating system platform-specific (for Win95 and NT, it may be a Dynamic Link Library (DLL); for UNIX-based platforms, it may be a separate executable that gets launched by the OCSF). 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 this interface:

CSSM_BOOL EnterpriseRecoveryPolicy (CSSM_CONTEXT_PTR CryptoContext);

The CSSM_BOOL return value of this policy function will determine whether enterprise-based key recovery is mandated for the given cryptographic operation. CSSM_TRUE means that key recovery enablement is required for the given Context, and CSSM_FALSE means it is not.

CSSM_RETURN CSSMAPI CSSM_KR_SetEnterpriseRecoveryPolicy
               (char * RecoveryPolicyFileName,
               const CSSM_CRYPTO_DATA_PTR OldPassPhrase,
               const CSSSM_CRYPTO_DATA_PTR NewPassphrase) 

Input

RecoveryPolicyFileName

A pointer to a character string that specifies the filename of the module that contains the enterprise key recovery policy function. The filename may be a fully qualified pathname or a partial pathname.

OldPassPhrase

The passphrase used to control access to this operation. This should be "default" when this function is invoked for the first time.

NewPassPhrase

The value of the passphrase to be established for subsequent access to this function. It should be identical to the OldPassPhrase if the passphrase does not need to be updated.

A CSSM return value. This function returns CSSM_OK if successful, and returns CSSM_FAIL if an error has occurred. Use CSSM_GetError to determine the error code.