CertGetCertificateChain-Funktion (wincrypt.h)

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.

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

[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

Siehe auch

CERT_CHAIN_PARA

CertDuplicateCertificateChain

CertFreeCertificateChain

von Zertifikatkettenüberprüfungsfunktionen