ICertRequest::GetCertificate-Methode (certcli.h)

Artikel
02/23/2024

Die GetCertificate-Methode gibt das Zertifikat zurück, das für die Anforderung als X.509-Zertifikat ausgestellt wurde, oder optional in eine PKCS#7-Nachricht ( Public Key Cryptography Standards ) verpackt, die die vollständige Zertifikatkette für den Certificate Services-Server enthält.

Syntax

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

Parameter

[in] Flags

Ein Flag für das Format und die Angabe, ob die vollständige Zertifikatkette enthalten ist.

Das Format des zurückgegebenen Zertifikats kann eines der folgenden Flags sein.

Wert	Bedeutung
CR_OUT_BASE64HEADER	BASE64-Format mit Anfang/Ende
CR_OUT_BASE64	BASE64-Format ohne Anfang/Ende
CR_OUT_BINARY	Binärformat

Die folgenden Flags können mit dem Formatflag kombiniert werden.

Wert	Bedeutung
CR_OUT_CHAIN	Schließen Sie die vollständige Zertifikatkette in PKCS #7 ein. Wenn dieses Flag nicht angegeben ist, wird nur das angeforderte Zertifikat im X.509-Format zurückgegeben.
CR_OUT_CRLS	Schließen Sie Zertifikatsperrlisten (Certificate Revocation Lists , CRLs) in PKCS #7 ein.

Um beispielsweise ein binäres Zertifikat mit vollständiger Zertifikatkette in C++ abzurufen, würden Sie Folgendes schreiben.

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

[out] pstrCertificate

Ein Zeiger auf den BSTR , der das Zertifikat im angegebenen Format enthält.

Erstellen Sie bei Verwendung dieser Methode eine Variable vom Typ BSTR , legen Sie die Variable gleich NULL fest, und übergeben Sie dann die Adresse dieser Variablen als pstrCertificate. Wenn Sie das Zertifikat verwendet haben, auf das von pstrCertificate verwiesen wird, geben Sie es frei, indem Sie die SysFreeString-Funktion aufrufen.

Rückgabewert

Wenn die Methode *pstrCertificate auf den BSTR festlegt, der das Zertifikat für die Anforderung enthält, gibt die Methode S_OK zurück.

Wenn die Methode fehlschlägt, gibt sie einen HRESULT-Wert zurück, der den Fehler angibt. Eine Liste allgemeiner Fehlercodes finden Sie unter Allgemeine HRESULT-Werte.

Hinweise

Eine Anwendung ruft diese Methode auf, um das zertifikat abzurufen, das mithilfe eines früheren Aufrufs von ICertRequest3::Submit oder ICertRequest3::RetrievePending ausgestellt wurde.

Beispiele

Das folgende Beispiel zeigt das Abrufen eines Zertifikats.

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

}

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	certcli.h (include Certsrv.h)
Bibliothek	Certidl.lib
DLL	Certcli.dll

Weitere Informationen

Freigeben über