Freigeben über

CertGetCertificateChain-Funktion (wincrypt.h)

  • Artikel

Die CertGetCertificateChain--Funktion erstellt einen Zertifikatkettenkontext beginnend mit einem Endzertifikat und geht nach Möglichkeit zu einem vertrauenswürdigen Stammzertifikatzurück.

Syntax

BOOL CertGetCertificateChain(
  [in, optional] HCERTCHAINENGINE     hChainEngine,
  [in]           PCCERT_CONTEXT       pCertContext,
  [in, optional] LPFILETIME           pTime,
  [in]           HCERTSTORE           hAdditionalStore,
  [in]           PCERT_CHAIN_PARA     pChainPara,
  [in]           DWORD                dwFlags,
  [in]           LPVOID               pvReserved,
  [out]          PCCERT_CHAIN_CONTEXT *ppChainContext
);

Parameter

[in, optional] hChainEngine

Ein Handle des zu verwendenden Kettenmoduls (Namespace und Cache). Wenn hChainEngineNULList, wird das Standardkettenmodul HCCE_CURRENT_USERverwendet. Dieser Parameter kann auf HCCE_LOCAL_MACHINEfestgelegt werden.

[in] pCertContext

Ein Zeiger auf die CERT_CONTEXT des Endzertifikats, das Zertifikat, für das eine Kette erstellt wird. Dieser Zertifikatkontext ist das Nullindexelement in der ersten einfachen Kette.

[in, optional] pTime

Ein Zeiger auf eine FILETIME Variable, die die Zeit angibt, für die die Kette überprüft werden soll. Beachten Sie, dass sich die Uhrzeit nicht auf die Überprüfung von Vertrauenslisten, Sperrung oder Stammspeicher auswirkt. Die aktuelle Systemzeit wird verwendet, wenn NULL- an diesen Parameter übergeben wird. Das Vertrauen in ein bestimmtes Zertifikat, das ein vertrauenswürdiger Stamm ist, basiert auf dem aktuellen Status des Stammspeichers und nicht auf dem Zustand des Stammspeichers, der von diesem Parameter übergeben wird. Zur Sperrung muss eine Zertifikatsperrliste (CRL) selbst gültig sein. Der Wert dieses Parameters wird verwendet, um zu bestimmen, ob ein in einer CRL aufgeführtes Zertifikat widerrufen wurde.

[in] hAdditionalStore

Ein Handle für alle zusätzlichen Speicher zum Suchen nach unterstützenden Zertifikaten und Zertifikatvertrauenslisten (CTLs). Dieser Parameter kann NULL werden, wenn kein zusätzlicher Speicher durchsucht werden soll.

[in] pChainPara

Ein Zeiger auf eine CERT_CHAIN_PARA Struktur, die Kettenaufbauparameter enthält.

[in] dwFlags

Kennzeichnen sie Werte, die eine spezielle Verarbeitung angeben. Dieser Parameter kann eine Kombination aus einer oder mehreren der folgenden Flags sein.

Wert Bedeutung
CERT_CHAIN_CACHE_END_CERT
0x00000001		 Wenn dieses Kennzeichen festgelegt ist, wird das Endzertifikat zwischengespeichert, wodurch der Prozess zum Erstellen von Ketten beschleunigt werden kann. Standardmäßig wird das Endzertifikat nicht zwischengespeichert, und es muss jedes Mal überprüft werden, wenn eine Kette dafür erstellt wird.
CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY
0x80000000		 Sperrüberprüfung greift nur auf zwischengespeicherte URLs zu. Dadurch würde verhindert, dass Netzwerkabrufe von CRLs oder OCSP für die End- oder Zertifizierungsstellenzertifikate abgerufen werden. CACHE_ONLY hängt von einem Freund auf dem Computer ab, um die CRL oder OCSP bereits aus dem Netzwerk abgerufen zu haben.
CERT_CHAIN_REVOCATION_CHECK_OCSP_CERT
0x04000000		 Dieses Kennzeichen wird intern während des Kettenaufbaus für ein Online-Zertifikatstatusprotokoll (OCSP)-Signierzertifikat verwendet, um zyklische Sperrprüfungen zu verhindern. Wenn die OCSP-Antwort während der Kettenerstellung von einem unabhängigen OCSP-Signierer signiert wird, gibt es zusätzlich zum ursprünglichen Kettenbuild eine zweite Kette, die für das OCSP-Signiererzertifikat selbst erstellt wurde. Dieses Kennzeichen wird während dieses zweiten Kettenbuilds verwendet, um ein rekursives unabhängiges OCSP-Signierzertifikat zu verhindern. Wenn das Signierzertifikat die szOID_PKIX_OCSP_NOCHECK Erweiterung enthält, wird die Sperrüberprüfung für das Blatt signiererzertifikat übersprungen. Sowohl OCSP- als auch CRL-Überprüfung sind zulässig.

Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt.
CERT_CHAIN_CACHE_ONLY_URL_RETRIEVAL
0x00000004		 Verwendet nur zwischengespeicherte URLs beim Erstellen einer Zertifikatkette. Das Internet und das Intranet werden nicht nach URL-basierten Objekten gesucht, z. B. CTL-Cabs, Wurzeln von Drittanbietern und AIA-Ausstellern. Die meisten Wurzeln sollten in einer crypt32.dll Ressource sein. Wenn dies nicht der Fall ist, ist dieser Abruf erforderlich, um einen Kettenaufbaufehler zu verhindern. Diese Cabs und Wurzeln werden auf Hochleistungs-Microsoft CDN-Servern gehostet.

Hinweis: Dieses Kennzeichen gilt nicht für die Sperrüberprüfung. Legen Sie CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY fest, um nur zwischengespeicherte URLs für die Sperrüberprüfung zu verwenden. Normalerweise werden CTL-Cabs bereits über den cryptsvc-Dienst vorab abgerufen.
CERT_CHAIN_DISABLE_PASS1_QUALITY_FILTERING0x00000040 Aus Leistungsgründen betrachtet der zweite Durchgang des Kettenbaus nur potenzielle Kettenpfade, die qualität größer oder gleich der höchsten Qualität sind, die während des ersten Durchgangs ermittelt wurde. Der erste Durchlauf berücksichtigt nur gültige Signatur, vollständige Kette und vertrauenswürdige Wurzeln, um die Kettenqualität zu berechnen. Dieses Kennzeichen kann festgelegt werden, um diese Optimierung zu deaktivieren und alle potenziellen Kettenpfade während des zweiten Durchlaufs zu berücksichtigen.
CERT_CHAIN_DISABLE_MY_PEER_TRUST
0x00000800		 Dieses Kennzeichen wird nicht unterstützt. Zertifikate im Speicher "Mein" werden niemals als Peer-Vertrauensstellung betrachtet.
CERT_CHAIN_ENABLE_PEER_TRUST
0x00000400		 Enden von Entitätszertifikaten im Speicher "TrustedPeople" sind vertrauenswürdig, ohne dass eine Kette erstellt wird. Diese Funktion legt die CERT_TRUST_IS_PARTIAL_CHAIN oder CERT_TRUST_IS_UNTRUSTED_ROOTdwErrorStatus Memberbits des ppChainContext--Parameters nicht fest.

Windows Server 2003 und Windows XP: Dieses Flag wird nicht unterstützt.
CERT_CHAIN_OPT_IN_WEAK_SIGNATURE
0x00010000		 Wenn Sie dieses Kennzeichen festlegen, wird angegeben, dass der Aufrufer schwache Signaturüberprüfungen durchführen möchte.

Dieses Kennzeichen ist im Rollupupdate für jedes Betriebssystem ab Windows 7 und Windows Server 2008 R2 verfügbar.
CERT_CHAIN_RETURN_LOWER_QUALITY_CONTEXTS
0x00000080		 Der Standardwert besteht darin, nur den höchsten Qualitätskettenpfad zurückzugeben. Wenn Sie dieses Kennzeichen festlegen, werden die niedrigeren Qualitätsketten zurückgegeben. Diese werden in den cLowerQualityChainContext- und rgpLowerQualityChainContext- Feldern des Kettenkontexts zurückgegeben.
CERT_CHAIN_DISABLE_AUTH_ROOT_AUTO_UPDATE
0x00000100		 Durch Festlegen dieses Flags wird die automatische Aktualisierung von Stammstämmen von Drittanbietern vom Windows Update-Webserver verhindert.
CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT
0x08000000		 Wenn Sie CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT festlegen und auch einen Wert für den dwUrlRetrievalTimeout Member der CERT_CHAIN_PARA Struktur angeben, stellt der Wert, den Sie in dwUrlRetrievalTimeout- angeben, das kumulative Timeout für alle Abrufe von Sperr-URL dar.

Wenn Sie CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT festlegen, aber keinen dwUrlRetrievalTimeout- Wert angeben, wird standardmäßig das maximale kumulierte Timeout auf 20 Sekunden festgelegt. Jedes getestete URL-Timeout nach der Hälfte des verbleibenden kumulierten Saldos wurde überschritten. Das heißt, die erste URL ist nach 10 Sekunden, die zweite nach 5 Sekunden, der dritte nach 2,5 Sekunden usw., bis eine URL erfolgreich ist, 20 Sekunden vergangen ist oder es keine weiteren ZU testden URLs gibt.

Wenn Sie CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUTnicht festlegen, wird jeder Sperr-URL in der Kette ein maximales Timeout zugewiesen, das dem in dwUrlRetrievalTimeoutangegebenen Wert entspricht. Wenn Sie keinen Wert für das dwUrlRetrievalTimeout Member angeben, wird jeder Sperr-URL ein maximales Standardtimeout von 15 Sekunden zugewiesen. Wenn keine URL erfolgreich ist, beträgt der maximale kumulierte Timeoutwert 15 Sekunden, multipliziert mit der Anzahl der URLs in der Kette.

Sie können die Standardwerte mithilfe von Gruppenrichtlinien festlegen.
CERT_CHAIN_TIMESTAMP_TIME
0x00000200		 Wenn dieses Kennzeichen festgelegt ist, wird pTime- als Zeitstempelzeit verwendet, um zu bestimmen, ob das Endzertifikat zeit gültig war. Die aktuelle Uhrzeit kann auch verwendet werden, um zu bestimmen, ob das Endzertifikat gültig bleibt. Alle anderen Zertifizierungsstelle (CA) und Stammzertifikate in der Kette werden mithilfe der aktuellen Uhrzeit überprüft und nicht pTime-.
CERT_CHAIN_DISABLE_AIA
0x00002000		 Durch das Festlegen dieses Flags werden die Abrufe von Autoritätsinformationen (Authority Information Access, AIA) explizit deaktiviert. Manchmal sind TLS-Server falsch konfiguriert und enthalten nicht die richtigen Zertifizierungsstellenzertifikate im Handshake.

Sie können auch die folgenden Sperrkennzeichnungen festlegen, aber es kann jeweils nur ein Flag aus dieser Gruppe festgelegt werden.

Wert Bedeutung
CERT_CHAIN_REVOCATION_CHECK_END_CERT
0x10000000		 Die Sperrüberprüfung erfolgt auf dem Endzertifikat und nur auf dem Endzertifikat.
CERT_CHAIN_REVOCATION_CHECK_CHAIN
0x20000000		 Die Sperrüberprüfung erfolgt auf allen Zertifikaten in jeder Kette.
CERT_CHAIN_REVOCATION_CHECK_CHAIN_EXCLUDE_ROOT
0x40000000		 Die Sperrüberprüfung erfolgt auf allen Zertifikaten in allen Ketten mit Ausnahme des Stammzertifikats.

[in] pvReserved

Dieser Parameter ist reserviert und muss NULLwerden.

[out] ppChainContext

Die Adresse eines Zeigers auf den erstellten Kettenkontext. Wenn Sie den Kettenkontext verwendet haben, lassen Sie die Kette los, indem Sie die CertFreeCertificateChain--Funktion aufrufen.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt die Funktion nonzero (TRUE) zurück.

Wenn die Funktion fehlschlägt, wird null (FALSE) zurückgegeben. Rufen Sie für erweiterte Fehlerinformationen GetLastError-auf.

Bemerkungen

Wenn eine Anwendung eine Zertifikatkette anfordert, befindet sich die zurückgegebene Struktur in Form eines CERT_CHAIN_CONTEXT. Dieser Kontext enthält ein Array von CERT_SIMPLE_CHAIN Strukturen, in denen jede einfache Kette von einem Endzertifikat zu einem selbstsignierten Zertifikat wechselt. Der Kettenkontext verbindet einfache Ketten über Vertrauenslisten. Jede einfache Kette enthält die Kette von Zertifikaten, Zusammenfassende Vertrauensinformationen zur Kette und Vertrauensinformationen zu jedem Zertifikatelement in der Kette.

Die folgenden Hinweise gelten für die Überprüfung sicherer Signaturen:

  • Sie können die Überprüfung der starken Signatur für diese Funktion aktivieren, indem Sie das pStrongSignPara- Element der CERT_CHAIN_PARA Struktur festlegen, auf die durch den pChainPara-Parameter verwiesen wird.
  • Wenn in der Kette ein Zertifikat ohne starke Signatur gefunden wird, werden die Fehler CERT_TRUST_HAS_WEAK_SIGNATURE und CERT_TRUST_IS_NOT_SIGNATURE_VALID im feld dwErrorStatus der CERT_TRUST_STATUS Struktur festgelegt. Der ppChainContext Parameter verweist auf eine CERT_CHAIN_CONTEXT Struktur, die wiederum auf die CERT_TRUST_STATUS Struktur verweist.
  • Wenn die Kette stark signiert ist, wird der öffentliche Schlüssel im Endzertifikat überprüft, um festzustellen, ob er die Mindestanforderungen für die Länge öffentlicher Schlüssel für eine starke Signatur erfüllt. Wenn die Bedingung nicht erfüllt ist, werden die Fehler CERT_TRUST_HAS_WEAK_SIGNATURE und CERT_TRUST_IS_NOT_SIGNATURE_VALID im feld dwErrorStatus der CERT_TRUST_STATUS Struktur festgelegt. Um die Überprüfung der Schlüssellänge zu deaktivieren, legen Sie den CERT_CHAIN_STRONG_SIGN_DISABLE_END_CHECK_FLAG Wert im dwStrongSignFlags Element der CERT_CHAIN_PARA Struktur fest, auf das durch den pChainPara-Parameter verwiesen wird.
  • Wenn die CERT_STRONG_SIGN_ENABLE_CRL_CHECK oder CERT_STRONG_SIGN_ENABLE_OCSP_CHECK Flags in der CERT_STRONG_SIGN_SERIALIZED_INFO Struktur festgelegt sind und eine CRL- oder OCSP-Antwort ohne starke Signatur gefunden wird, wird die CRL- oder OCSP-Antwort als offline behandelt. Das heißt, die CERT_TRUST_IS_OFFLINE_REVOCATION und CERT_TRUST_REVOCATION_STATUS_UNKNOWN Fehler werden im feld dwErrorStatus der CERT_TRUST_STATUS Struktur festgelegt. Außerdem wird das dwRevocationResult Member der CERT_REVOCATION_INFO Struktur auf NTE_BAD_ALGIDfestgelegt.

Die folgenden Empfehlungen gelten für alle Windows-Anwendungen, die diese APIs aufrufen, um ein TLS-Serverauthentifizierungszertifikat zu überprüfen:

  • Aktivieren Sie nur die Sperrüberprüfung für das Endzertifikat.
    • Legen Sie CERT_CHAIN_REVOCATION_CHECK_END_CERT Flag fest.
    • Die meisten Zertifizierungsstellenzertifikate verfügen über CRL mit einer Gültigkeitsdauer von 1 bis 6 Monaten.
      • Da heruntergeladene CRLs zwischengespeichert werden, ist diese Gültigkeit zu lang, um viel Wert zu haben.
    • Wenn eine Zertifizierungsstelle kompromittiert wird, werden die Zertifikate auch der Windows-CTL hinzugefügt.
    • Die empfohlene Methode für TLS-Server besteht darin, OCSP-Heftung für Endzertifikate zu unterstützen.
      • In diesem Fall sind keine Netzwerkabrufe erforderlich, es sei denn, die geheftet OCSP-Antwort ist abgelaufen.
  • Aktivieren Sie Netzwerkabrufe für CRLs, OCSP, AIA-Aussteller und Windows-Plattform-CTL-Cabs und Stammstamm von Drittanbietern.
    • Wenn die oben CERT_CHAIN_REVOCATION_CHECK_END_CERT festgelegt ist, ist dies der Standardwert.
    • Legen Sie keines der folgenden Flags fest, um Netzwerkabrufe zu verhindern. Weitere Informationen zu diesen Flags finden Sie in der obigen tabelle dwFlags:
      • CERT_CHAIN_CACHE_ONLY_URL_RETRIEVAL
      • CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY
      • CERT_CHAIN_DISABLE_AIA
  • Aktivieren Sie akkumulatives Timeout für CRL- und OCSP-Netzwerkabrufe.
    • Legen Sie das CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT Flag fest, das an CertGetCertificateChainübergeben wird.
    • Bietet eine obere Grenze für die Gesamtzeit, die für CRL- und OCSP-Netzwerkabrufe zulässig ist.
  • Verringern Sie die maximal zulässige Zeit für jeden Netzwerkabruf von 15 bis 10 Sekunden.
    • Legen Sie das feld dwUrlRetrievalTimeout im CERT_CHAIN_PARA an CertGetCertificateChain auf 10 * 1000 Millisekunden übergeben.
    • Dadurch wird auch das akkumulative Timeout von 20 auf 10 Sekunden reduziert.
      • Nur OCSP-Antworten sollten für Endzertifikate heruntergeladen werden. 5 Sekunden sollten für diesen Download ausreichen.
  • Offlinesperrfehler ignorieren.
    • Legen Sie CERT_CHAIN_POLICY_IGNORE_ALL_REV_UNKNOWN_FLAGS in der CERT_CHAIN_POLICY_PARA an CertVerifyCertificateChainPolicy(CERT_CHAIN_POLICY_SSL)übergeben.
    • Der Netzwerkabruf von OCSP und CRL ist der beste Versuch. Die meisten Netzwerkabrufe sollten einige Sekunden erfolgreich sein, aber es ist nicht 100% garantiert.
  • Cache-Zertifikatüberprüfungsinformationen.
    • Legen Sie die CERT_CHAIN_CACHE_END_CERTfest.
      • Ermöglicht das Zwischenspeichern von Informationen zu Endzertifikaten zusätzlich zu Zwischenzertifikaten.
    • Es ist üblich, mehrere TLS-Verbindungen mit demselben Server herzustellen.

Beispiele

Ein Beispiel, das diese Funktion verwendet, finden Sie unter Beispiel C-Programm: Erstellen einer Zertifikatkette.

Anforderungen

Anforderung Wert
mindestens unterstützte Client- Windows XP [Desktop-Apps | UWP-Apps]
mindestens unterstützte Server- Windows Server 2003 [Desktop-Apps | UWP-Apps]
Zielplattform- Fenster
Header- wincrypt.h
Library Crypt32.lib
DLL- Crypt32.dll

Siehe auch

CERT_CHAIN_PARA

CertDuplicateCertificateChain

CertFreeCertificateChain

von Zertifikatkettenüberprüfungsfunktionen