ICertRequest ::GetCertificate, méthode (certcli.h)

Article
02/23/2024

La méthode GetCertificate retourne le certificat émis pour la demande sous la forme d’un certificat X.509 ou éventuellement empaqueté dans un message PKCS ( Public Key Cryptography Standards ) #7 qui contient la chaîne de certificats complète pour le serveur des services de certificats.

Syntaxe

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

Paramètres

[in] Flags

Indicateur pour le format et indique si la chaîne de certificats complète est incluse.

Le format du certificat retourné peut être l’un des indicateurs suivants.

Valeur	Signification
CR_OUT_BASE64HEADER	Format BASE64 avec début/fin
CR_OUT_BASE64	Format BASE64 sans début/fin
CR_OUT_BINARY	Format binaire

Les indicateurs suivants peuvent être combinés avec l’indicateur de format.

Valeur	Signification
CR_OUT_CHAIN	Incluez la chaîne de certificats complète dans PKCS #7. Si cet indicateur n’est pas spécifié, seul le certificat demandé, au format X.509 , est retourné.
CR_OUT_CRLS	Incluez des listes de révocation de certificats (CRL) dans le PKCS #7.

Par exemple, pour récupérer un certificat binaire avec une chaîne de certificats complète en C++, vous devez écrire ce qui suit.

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

[out] pstrCertificate

Pointeur vers le BSTR qui contient le certificat, au format spécifié.

Lorsque vous utilisez cette méthode, créez une variable de type BSTR , définissez la variable sur NULL, puis transmettez l’adresse de cette variable en tant que pstrCertificate. Lorsque vous avez terminé d’utiliser le certificat pointé vers pstrCertificate, libérez-le en appelant la fonction SysFreeString .

Valeur retournée

Si la méthode définit *pstrCertificate sur le BSTR qui contient le certificat pour la demande, la méthode retourne S_OK.

Si la méthode échoue, elle retourne une valeur HRESULT qui indique l’erreur. Pour obtenir la liste des codes d’erreur courants, consultez Valeurs HRESULT courantes.

Remarques

Une application appelle cette méthode pour récupérer le certificat émis par le biais d’un appel antérieur à ICertRequest3 ::Submit ou ICertRequest3 ::RetrievePending.

Exemples

L’exemple suivant illustre la récupération d’un certificat.

#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;

}

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge	Windows Server 2003 [applications de bureau uniquement]
Plateforme cible	Windows
En-tête	certcli.h (include Certsrv.h)
Bibliothèque	Certidl.lib
DLL	Certcli.dll