Expand Minimize

CertGetEnhancedKeyUsage function

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

Syntax


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

Parameters

pCertContext [in]

A pointer to a CERT_CONTEXT certificate context.

dwFlags [in]

Indicates whether the function will report on extensions of a certificate, its extended properties, or both. If set to zero, the function returns the valid uses of a certificate based on both the EKU extension and the EKU extended property value of the certificate.

To return only the EKU extension or EKU property value, set the following flags.

ValueMeaning
CERT_FIND_EXT_ONLY_ENHKEY_USAGE_FLAG

Get only the extension.

CERT_FIND_PROP_ONLY_ENHKEY_USAGE_FLAG

Get only the extended property value.

 

pUsage [out]

A pointer to a CERT_ENHKEY_USAGE structure (CERT_ENHKEY_USAGE is an alternate typedef name for the CTL_USAGE structure) that receives the valid uses of the certificate.

This parameter can be NULL to set the size of the key usage for memory allocation purposes. For more information, see Retrieving Data of Unknown Length.

pcbUsage [in, out]

A pointer to a DWORD that specifies the size, in bytes, of the structure pointed to by pUsage. When the function returns, the DWORD contains the size, in bytes, of the structure.

Return value

If the function succeeds, the function returns nonzero (TRUE).

If the function fails, it returns zero (FALSE).

Remarks

If a certificate has an EKU extension, that extension lists object identifiers (OIDs) for valid uses of that certificate. In a Microsoft environment, a certificate might also have EKU extended properties that specify valid uses for the certificate.

  • If a certificate has neither an EKU extension nor EKU extended properties, it is assumed to be valid for all uses.
  • If it has either an EKU extension or EKU extended 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 extended properties, it is valid only for the uses that are on both lists.

If dwFlags 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 extended 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 GetLastError can be used to determine whether the certificate is good for all uses or for none. 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

Minimum supported client

Windows XP [desktop apps only]

Minimum supported server

Windows Server 2003 [desktop apps only]

Header

Wincrypt.h

Library

Crypt32.lib

DLL

Crypt32.dll

See also

Enhanced Key Usage Functions
CertSetEnhancedKeyUsage

 

 

Community Additions

ADD
Show:
© 2014 Microsoft