Share via

CertGetIssuerCertificateFromStore

  • Article

This function retrieves the certificate context from the certificate store for the first or next issuer of the specified subject certificate. The new certificate chain verification functions are recommended instead of the use of this function.

PCCERT_CONTEXT WINAPI CertGetIssuerCertificateFromStore(
HCERTSTORE hCertStore,
PCCERT_CONTEXT pSubjectContext,
PCCERT_CONTEXT pPrevIssuerContext,
DWORD *pdwFlags
);

Parameters

  • hCertStore
    [in] Handle of a certificate store.

  • pSubjectContext
    [in] Pointer to a CERT_CONTEXT structure containing the subject information. This parameter can be obtained from any certificate store or can be created by the calling application using the CertCreateCertificateContext function.

  • pPrevIssuerContext
    [in/optional] Pointer to a CERT_CONTEXT structure containing the issuer information. An issuer can have multiple certificates, especially when a validity period is about to change. This parameter must be NULL on the call to get the first issuer certificate. To get the next certificate for the issuer, set the pPrevIssuerContext parameter to the CERT_CONTEXT structure returned by the previous call.

    A pPrevIssuerContext parameter that is not NULL is always freed by the CertGetIssuerCertificateFromStore function by using the CertFreeCertificateContext function, even for an error.

  • pdwFlags
    [in/out]The following flags enable verification checks on the returned certificate. They can be combined using a bitwise OR operation to enable multiple verifications.

    Value Description
    CERT_STORE_NO_CRL_FLAG Indicates no matching CRL was found.
    CERT_STORE_NO_ISSUER_FLAG Indicates no issuer certificate was found.
    CERT_STORE_SIGNATURE_FLAG Uses the public key in the issuer's certificate to verify the signature on the subject certificate.
    CERT_STORE_TIME_VALIDITY_FLAG Gets the current time and verifies that it is within the subject certificate's validity period.

    If a verification check of an enabled type succeeds, its flag is set to zero. If it fails, its flag remains set upon return.

    If CERT_STORE_SIGNATURE_FLAG is set, CERT_STORE_NO_ISSUER_FLAG is set if the function does not find an issuer certificate in the store. For more details, see the Remarks section later in this topic.

    In the case of a verification check failure, a pointer to the issuer's CERT_CONTEXT structure is still returned and the GetLastError function is not updated.

Return Values

If the function succeeds, the return value is a pointer to a read-only issuer CERT_CONTEXT structure.

If the function fails and the first or next issuer certificate is not found, the return value is NULL.

Only the last returned CERT_CONTEXT structure must be freed by calling the CertFreeCertificateContext function. When the returned CERT_CONTEXT structure from one call to the function is supplied as the pPrevIssuerContext parameter on a subsequent call, the context is freed as part of the action of the function.

For extended error information, call the GetLastError function. The following table lists some possible error codes.

Error value Description
CRYPT_E_NOT_FOUND No issuer was found for the subject certificate.
CRYPT_E_SELF_SIGNED The issuer certificate is the same as the subject certificate. It is a self-signed root certificate.
E_INVALIDARG The handle in the hCertStore parameter is not the same as that of the certificate context pointed to by the pPrevIssuerContext parameter, or an unsupported flag was set in the pdwFlags parameter.

Remarks

The CertDuplicateCertificateContext function can be called to make a duplicate of the issuer certificate.

The hexadecimal values for the dwFlags parameter can be combined using a bitwise OR operation to enable multiple verifications. For example, to enable both signature and time validity, the value 0x00000003 is passed in the dwFlags parameter on input. In this case, if CERT_STORE_SIGNATURE_FLAG verification succeeds but CERT_STORE_TIME_VALIDITY_FLAG verification fails, the dwFlags parameter returns as 0x00000002 on output.

The desktop platform supports the following pdwFlags, but Windows CE does not:

CERT_STORE_REVOCATION_FLAG

Requirements

Runs on Versions Defined in Include Link to
Windows CE OS 3.0 or later Wincrypt.h   Crypt32.lib

Note   This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.

See Also

CertCreateCertificateContext, CertFreeCertificateContext, CertDuplicateCertificateContext, CERT_CONTEXT

 Last updated on Tuesday, July 13, 2004

© 1992-2000 Microsoft Corporation. All rights reserved.