ICertAdmin::RevokeCertificate-Methode (certadm.h)

Artikel
08/22/2023

Die RevokeCertificate-Methode widerruft ein Zertifikat entweder an einem angegebenen Datum oder sofort. Diese Methode wurde zuerst in der ICertAdmin-Schnittstelle definiert.

Ein widerrufenes Zertifikat wird in einer nachfolgenden Zertifikatsperrliste (Certificate Revocation Lists , CRLs) angezeigt, sofern das Sperrdatum zum Zeitpunkt der Veröffentlichung der Zertifikatsperrliste gültig ist.

Syntax

HRESULT RevokeCertificate(
  [in] const BSTR strConfig,
  [in] const BSTR strSerialNumber,
  [in] LONG       Reason,
  [in] DATE       Date
);

Parameter

[in] strConfig

Stellt eine gültige Konfigurationszeichenfolge für den Zertifizierungsstellenserver im Format COMPUTERNAME\CANAME dar, wobei COMPUTERNAME der Netzwerkname des Zertifikatdiensteservers und CANAME der allgemeine Name der Zertifizierungsstelle ist, wie er während der Einrichtung der Zertifikatdienste eingegeben wurde. Informationen zum Namen der Konfigurationszeichenfolge finden Sie unter ICertConfig.

WichtigRevokeCertificate löscht den internen Cache nicht, wenn die Konfigurationszeichenfolge geändert wird. Wenn Sie die Konfigurationszeichenfolge für die Zertifizierungsstelle ändern, müssen Sie ein neues ICertAdmin-Objekt instanziieren und diese Methode erneut mit der neuen Konfigurationszeichenfolge aufrufen.

[in] strSerialNumber

Gibt eine Seriennummer an, die das zu widerrufende Zertifikat identifiziert. Die Zeichenfolge muss die Seriennummer als gerade Zahl von Hexadezimalstellen angeben. Bei Bedarf kann der Zahl eine Null vorangestellt werden, um eine gerade Anzahl von Ziffern zu erzeugen. Es darf jedoch nicht mehr als eine führende Null verwendet werden.

[in] Reason

Gibt den Grund für den Widerruf an. Die folgenden Werte (definiert in Wincrypt.h) sind unterstützte Ursachencodes.

CRL_REASON_UNSPECIFIED (0)

CRL_REASON_KEY_COMPROMISE (1)

CRL_REASON_CA_COMPROMISE (2)

CRL_REASON_AFFILIATION_CHANGED (3)

CRL_REASON_SUPERSEDED (4)

CRL_REASON_CESSATION_OF_OPERATION (5)

CRL_REASON_CERTIFICATE_HOLD (6)

Sie können ein zertifikat widerrufen, das mit dem CRL_REASON_CERTIFICATE_HOLD Sperrgrundcode widerrufen wurde, indem Sie RevokeCertificate mit MAXDWORD als Reason-Wert aufrufen. Wenn ein Zertifikat mit einem anderen Grundcode als CRL_REASON_CERTIFICATE_HOLD widerrufen wurde, kann es nicht wiederhergestellt werden.

[in] Date

Gibt das Datum in koordinierter Weltzeit (Greenwich Mean Time) an, an dem der Widerruf wirksam wird. Der Wert 0 gibt die aktuelle koordinierte Weltzeit an, wodurch ein Zertifikat sofort widerrufen wird. Der Wert von Date wird in der Spalte Effektives Sperrdatum des widerrufenen Zertifikats (im MMC-Snap-In Zertifizierungsstelle) angezeigt.

Rückgabewert

VB

Wenn die Methode erfolgreich ist, 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

Diese Methode kann für dasselbe Zertifikat mehrmals aufgerufen werden, sodass Sie das effektive Sperrdatum und den Sperrgrund ändern können.

Wenn ein aktuell widerrufenes Zertifikat CRL_REASON_CERTIFICATE_HOLD als Grundcode aufweist, können Sie das Zertifikat erneut festlegen, indem Sie RevokeCertificate mit MAXDWORD (definiert in Winnt.h) als Wert für den Grundcode (den Reason-Parameter ) aufrufen. Nach der erneuten Verwendung wird das Zertifikat in zukünftigen ZERTIFIKATsperrlisten nicht mehr angezeigt.

Verwaltungsaufgaben verwenden DCOM. Code, der diese Schnittstellenmethode aufruft, wie in einer früheren Version von Certadm.h definiert, wird auf Windows-basierten Servern ausgeführt, solange der Client und der Server dasselbe Windows-Betriebssystem ausführen.

Beispiele

    BSTR bstrCA = NULL;
    BSTR bstrSerial = NULL;  // certificate serial number
    long nReason;
    DATE RevokeDate;         // revocation date
    SYSTEMTIME st;

    bstrSerial = SysAllocString(L"<SERIALNUMBERHERE>");
    bstrCA = SysAllocString(L"<COMPUTERNAMEHERE>\\<CANAMEHERE>");
    if (NULL == bstrCA || NULL == bstrSerial)
    {
        printf("Memory allocation failed\n");
        goto error;
    }
    
    nReason = CRL_REASON_AFFILIATION_CHANGED;  // Defined
	                                      // in Wincrypt.h

    //  Specify when the cert should be revoked.
    //  Note: To revoke immediately, set RevokeDate to zero.
    //  This example sets the revoke date to noon on 1/1/2001.
    //  Zero out values first (avoids setting minutes, seconds,
    //  and so on).
    memset(&st, 0, sizeof(SYSTEMTIME));
    st.wYear = 2001;
    st.wMonth = 1;     // Jan
    st.wDay = 1;       // 1st day of month
    st.wHour = 12;     // Noon

    //  Place the date in the required format.
    if (!SystemTimeToVariantTime(&st, &RevokeDate))
    {
        printf("Unable to convert time.\n");
        goto error;
    }

    //  Revoke the certificate.
    //  pCertAdmin is a previously instantiated ICertAdmin object.
    hr = pCertAdmin->RevokeCertificate( bstrCA,
                                        bstrSerial,
                                        nReason,
                                        RevokeDate );
    if (FAILED(hr))
    {
        printf("Failed RevokeCertificate. [%x]\n", hr);
        goto error;
    }
    else
        printf("Certificate %ws revoked.\n", bstrSerial );

    //  Done processing.

error:

    //  Free resources.
    if (bstrSerial)
        SysFreeString( bstrSerial );
    if (bstrCA)
        SysFreeString( bstrCA );

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Nicht unterstützt
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	certadm.h (include Certsrv.h)
Bibliothek	Certidl.lib
DLL	Certadm.dll

Weitere Informationen

Freigeben über