ICertRequest::GetCertificate method (certcli.h)

The GetCertificate method returns the certificate issued for the request as an X.509 certificate, or optionally packaged in a Public Key Cryptography Standards (PKCS) #7 message that contains the complete certificate chain for the Certificate Services server.

Syntax

HRESULT GetCertificate(
  [in]  LONG Flags,
  [out] BSTR *pstrCertificate
);

Parameters

[in] Flags

A flag for the format and whether the complete certificate chain is included.

The format of the returned certificate can be one of the following flags.

Value Meaning
CR_OUT_BASE64HEADER
BASE64 format with begin/end
CR_OUT_BASE64
BASE64 format without begin/end
CR_OUT_BINARY
Binary format
 

The following flags can be combined with the format flag.

Value Meaning
CR_OUT_CHAIN
Include complete certificate chain in the PKCS #7.

If this flag is not specified, only the requested certificate, in X.509 format, is returned.

CR_OUT_CRLS
Include certificate revocation lists (CRLs) in the PKCS #7.
 

For example, to retrieve a binary certificate with complete certificate chain in C++ you would write the following.

hResult = pCertReq->GetCACertificate(FALSE, bstrConfig,
     CR_OUT_BINARY | CR_OUT_CHAIN, &bstrCert);

[out] pstrCertificate

A pointer to the BSTR that contains the certificate, in the specified format.

When using this method, create a variable of BSTR type, set the variable equal to NULL, and then pass the address of this variable as pstrCertificate. When you have finished using the certificate pointed to by pstrCertificate, free it by calling the SysFreeString function.

Return value

If the method sets *pstrCertificate to the BSTR that contains the certificate for the request, the method returns S_OK.

If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see Common HRESULT Values.

Remarks

An application would call this method to retrieve the certificate issued by means of an earlier call to ICertRequest3::Submit or ICertRequest3::RetrievePending.

Examples

The following example shows retrieving a certificate.

#include <windows.h>
#include <stdio.h>
#include <Certcli.h>

HRESULT main()
{
    //  Pointer to interface object.
    ICertRequest * pCertRequest = NULL;

    //  Variable for COMPUTER\CANAME.
    BSTR         bstrCA = NULL;

    //  Variable for CA Certificate.
    BSTR         bstrCACert = NULL;

    HRESULT     hr;

    //  Initialize COM.
    hr = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);

    //  Check status.
    if (FAILED(hr))
    {
        printf("Failed CoInitializeEx [%x]\n", hr);
        goto error;
    }

    //  Instantiate the CertConfig object.
    hr = CoCreateInstance(CLSID_CCertRequest,
                          NULL,
                          CLSCTX_INPROC_SERVER,
                          IID_ICertRequest,
                          (void **)&pCertRequest);
    if (FAILED(hr))
    {
        printf("Failed CoCreateInstance pCertRequest [%x]\n", hr);
        goto error;
    }

    //  Note use of two backslashes (\\) in C++ 
    //  to produce one backslash (\).
    bstrCA = SysAllocString(L"server01\\myCAName");
    
    //  Retrieve the CA certificate.
    hr = pCertRequest->GetCACertificate(FALSE,
                                        bstrCA,
                                        CR_OUT_BASE64,
                                        &bstrCACert);
    if (FAILED(hr))
    {
        printf("Failed GetCACertificate [%x]\n", hr);
        goto error;
    }
    else
    {
        //  Use CA Certificate as needed.
    }

    //  Done processing.

error:

    //  Free BSTR values.
    if (NULL != bstrCA)
        SysFreeString(bstrCA);

    if (NULL != bstrCACert)
        SysFreeString(bstrCACert);

    //  Clean up object resources.
    if (NULL != pCertRequest)
        pCertRequest->Release();

    //  Free COM resources.
    CoUninitialize();

    return hr;

}

Requirements

Requirement Value
Minimum supported client Windows XP [desktop apps only]
Minimum supported server Windows Server 2003 [desktop apps only]
Target Platform Windows
Header certcli.h (include Certsrv.h)
Library Certidl.lib
DLL Certcli.dll

See also

CCertRequest

ICertRequest

ICertRequest2

ICertRequest3