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:
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 |
|---|---|
|
The phCatAdmin parameter cannot be NULL.
The dwFlags parameter must be zero (0). |
|
There was insufficient memory to create a new catalog administrator object. |
|
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 |