CertGetEnhancedKeyUsage

A version of this page is also available for

Windows Embedded CE 6.0 R3

4/8/2010

This function returns information from the extended key usage (EKU) extension or the EKU property of a certificate. EKUs indicate valid uses of the certificate.

Syntax

BOOL WINAPI CertGetEnhancedKeyUsage(
  PCCERT_CONTEXT pCertContext,
  DWORD dwFlags,
  PCERT_ENHKEY_USAGE pUsage,
  DWORD* pcbUsage
);

Parameters

• pCertContext
  [in] Pointer to a CERT_CONTEXT structure certificate context.

• dwFlags
  [in] Specifies whether the function reports on a certificate's extensions, its extended properties, or both. If the value of this parameter is set to zero, the function returns the valid uses of a certificate based on both the certificate's EKU extension and its EKU property value.

  The following table shows the flags that can be set to return only the EKU extension or EKU property value.

  Value	Description
  CERT_FIND_EXT_ONLY_ENHKEY_USAGE_FLAG	Gets only the extension.
  CERT_FIND_PROP_ONLY_ENHKEY_USAGE_FLAG	Gets only the extended property value.

• pUsage
  [out] Pointer to receive a CERT_ENHKEY_USAGE structure indicating the valid uses of the certificate.

  This parameter can be NULL to set the size of the key usage for memory allocation purposes.

• pcbUsage
  [in, out] On input, pointer to a DWORD that specifies the size, in bytes, of the structure pointed to by the pUsage parameter. On output, the DWORD contains the size in bytes of the structure.

Return Value

If the function succeeds, the return value is nonzero, or TRUE.

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

For extended error information, call the GetLastError function.

Remarks

If a certificate has an EKU extension, that extension lists OIDs for valid uses of that certificate. In a Microsoft environment, a certificate might also have EKU properties specifying valid uses for the certificate.

• If a certificate has neither an EKU extension nor EKU properties, it is assumed to be valid for all uses.
• If a certificate has either an EKU extension or EKU properties but not both, it is valid only for the uses indicated in the extension or extended properties that it has.
• If a certificate has both an EKU extension and EKU properties, it is valid only for the uses that are on both lists.

If the dwFlags parameter is set to zero, the cUsageIdentifier member of the CERT_ENHKEY_USAGE structure is set to the number of valid uses of the certificate determined by the value of both the EKU extension and the EKU property value.

If the cUsageIdentifier member is zero, the certificate might be valid for all uses or the certificate might have no valid uses. The return from a call to the GetLastError function can be used to determine whether the certificate is good for all uses or for no uses. If GetLastError returns CRYPT_E_NOT_FOUND, the certificate is good for all uses. If it returns zero, the certificate has no valid uses.

Requirements

See Also

Reference

CertSetEnhancedKeyUsage
CERT_CONTEXT
CTL_USAGE