CryptCATAdminAcquireContext2 function (mscat.h)

The CryptCATAdminAcquireContext2 function acquires a handle to a catalog administrator context for a given hash algorithm and hash policy.

You can use this handle in subsequent calls to the following functions:

• CryptCATAdminAddCatalog
• CryptCATAdminEnumCatalogFromHash
• CryptCATAdminRemoveCatalog

This function has no associated import library. You must use the LoadLibrary and GetProcAddress functions to dynamically link to Wintrust.dll.

Syntax

BOOL CryptCATAdminAcquireContext2(
  [out]          HCATADMIN               *phCatAdmin,
  [in, optional] const GUID              *pgSubsystem,
  [in, optional] PCWSTR                  pwszHashAlgorithm,
  [in, optional] PCCERT_STRONG_SIGN_PARA pStrongHashPolicy,
                 DWORD                   dwFlags
);

Parameters

[out] phCatAdmin

A pointer to the catalog administrator context handle that is assigned by this function. When you have finished using the handle, close it by calling the CryptCATAdminReleaseContext function.

[in, optional] pgSubsystem

A pointer to the GUID that identifies the subsystem. DRIVER_ACTION_VERIFY represents the subsystem for operating system components and third party drivers. This is the subsystem used by most implementations.

[in, optional] pwszHashAlgorithm

Optional null-terminated Unicode string that specifies the name of the hash algorithm to use when calculating and verifying hashes. This value can be NULL. If it is NULL, the default hashing algorithm may be chosen, depending on the value you set for the pStrongHashPolicy parameter. The default algorithm in Windows 8 is SHA1. The default may change in future Windows versions. For more information, see Remarks.

[in, optional] pStrongHashPolicy

Pointer to a CERT_STRONG_SIGN_PARA structure that contains the parameters used to check for strong signatures. The function chooses the lowest common hashing algorithm that satisfies the specified policy and the algorithm specified by the pwszHashAlgorithm parameter or the system default algorithm (if no algorithm is specified).

dwFlags

Reserved. This value must be zero.

Return value

If the function succeeds, the return value is nonzero (TRUE).

If the function fails, the return value is zero (FALSE). For extended error information, call GetLastError.

The following table lists the error codes most commonly returned by the GetLastError function.

Return code	Description
ERROR_INVALID_PARAMETER	The phCatAdmin parameter cannot be NULL. The dwFlags parameter must be zero (0).
ERROR_NOT_ENOUGH_MEMORY	There was insufficient memory to create a new catalog administrator object.
NTE_BAD_ALGID	The hash algorithm specified by the pwszHashAlgorithm parameter cannot be found.

Remarks

This function enables you to choose, or chooses for you, the hash algorithm to be used in functions that require the catalog administrator context. Although you can set the name of the hashing algorithm, we recommend that you let the function determine the algorithm. Doing so protects your application from hard coding algorithms that may become untrusted in the future.

Requirements

Requirement	Value
Minimum supported client	Windows 8 [desktop apps only]
Minimum supported server	Windows Server 2012 [desktop apps only]
Target Platform	Windows
Header	mscat.h
Library	Wintrust.lib
DLL	Wintrust.dll

See also

CryptCATAdminAddCatalog

CryptCATAdminReleaseContext

CryptCATAdminRemoveCatalog