CryptInstallDefaultContext

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function installs a previously acquired HCRYPTPROV context to be used as a default context. The values of two input parameters, wDefaultType and pvDefaultPara, specify where the default context is used.

Syntax

BOOL WINAPI CryptInstallDefaultContext(
  HCRYPTPROV hCryptProv,
  DWORD dwDefaultType,
  const void* pvDefaultPara,
  DWORD dwFlags,
  void* pvReserved,
  HCRYPTDEFAULTCONTEXT* phDefaultContext
);

Parameters

• hCryptProv
  [in] HCRYPTPROV handle to be used as the default context. This handle must have already been created using the CryptAcquireContext function.

• dwDefaultType
  [in] Specifies the use of the default provider handle. The following table shows the possible values for this parameter.

  Value	Description
  CRYPT_DEFAULT_CONTEXT_CERT_SIGN_OID	Installs a default HCRYPTPROV handle used to verify a certificate signature. pvDefaultPara points to the szOID value of the certificate signature algorithm; for example, szOID_OIWSEC_md5RSA. If pvDefaultPara is NULL, the HCRYPTPROV handle is used to verify all certificate signatures. The pvDefaultPara parameter cannot be NULL when CRYPT_DEFAULT_CONTEXT_PROCESS_FLAG is set.
  CRYPT_DEFAULT_CONTEXT_MULTI_CERT_SIGN_OID	Same as CRYPT_DEFAULT_CONTEXT_CERT_SIGN_OID. However, the default HCRYPT2PROV structure is to be used for multiple signature szOID values. The pvDefaultPara parameter points to a CRYPT_DEFAULT_CONTEXT_MULTI_OID_PARA structure containing an array of szOID pointers.

• pvDefaultPara
  [in] Pointer to the szOID value of the certificate signature algorithm or to an array of szOID values defined in the CRYPT_DEFAULT_CONTEXT_MULTI_OID_PARA structure. It can be NULL if the dwDefaultType parameter is CRYPT_DEFAULT_CONTEXT_CERT_SIGN_OID and the default HCRYPTPROV value is used to verify all certificate signatures.

• dwFlags
  [in] Specifies the way that the provider is freed. The following table shows possible values for this parameter.

  Value	Description
  CRYPT_DEFAULT_CONTEXT_AUTO_RELEASE_FLAG	The hCryptProv value is freed automatically when the process ends. The hCryptProv value is not freed by a call to the CryptUninstallDefaultContext function if the function is called before process or thread exit.
  CRYPT_DEFAULT_CONTEXT_PROCESS_FLAG	The hCryptProv value is applicable to all threads in the process. This is the default flag.

• pvReserved
  [in] Reserved for future use.

• phDefaultContext
  [out] Pointer to the handle of the new default context.

Return Value

If the function succeeds, the return value is nonzero, or TRUE, and the phDefaultContext parameter is updated with the handle to be passed to the CryptUninstallDefaultContext function.

If the function fails, the return value is zero, or FALSE.

For extended error information, call the GetLastError function.

Remarks

By default, the installed HCRYPTPROV value is only applicable to the current thread. Set CRYPT_DEFAULT_CONTEXT_PROCESS_FLAG to allow the HCRYPTPROV value to be used by all threads in the current process.

The installed HCRYPTPROV values are stack-ordered, thus the last installed HCRYPTPROV value is checked first. All thread-installed HCRYPTPROV values are checked before any process HCRYPTPROV values.

The installed HCRYPTPROV value remains available for default usage until the CryptUninstallDefaultContext function is called or the thread or process exits.

If CRYPT_DEFAULT_CONTEXT_AUTO_RELEASE_FLAG is set, then the HCRYPTPROV value is freed by the CryptReleaseContext function at thread or process exit. The provider is not re-freed if the CryptUninstallDefaultContext function was previously called.

Requirements

See Also

Reference

HCRYPTPROV
CryptAcquireContext
CryptReleaseContext
CryptUninstallDefaultContext