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 |
---|---|
|
BASE64 format with begin/end |
|
BASE64 format without begin/end |
|
Binary format |
The following flags can be combined with the format flag.
Value | Meaning |
---|---|
|
Include complete certificate chain in the PKCS #7.
If this flag is not specified, only the requested certificate, in X.509 format, is returned. |
|
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 |