CertGetCertificateChain-Funktion (wincrypt.h)
Die CertGetCertificateChain-Funktion erstellt einen Zertifikatkettenkontext, der von einem Endzertifikat beginnt und nach Möglichkeit zu einem vertrauenswürdigen Stammzertifikat zurückkehrt.
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 der zu verwendenden Ketten-Engine (Namespace und Cache). Wenn hChainEngineNULL ist, wird die Standardketten-Engine HCCE_CURRENT_USER verwendet. Dieser Parameter kann auf HCCE_LOCAL_MACHINE festgelegt 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 , der die Zeit angibt, für die die Kette überprüft werden soll. Beachten Sie, dass sich die Uhrzeit nicht auf die Vertrauensliste, die Sperrung oder die Stammspeicherüberprüfung auswirkt. Die aktuelle Systemzeit wird verwendet, wenn NULL an diesen Parameter übergeben wird. Die Vertrauensstellung, dass ein bestimmtes Zertifikat ein vertrauenswürdiger Stamm ist, basiert auf dem aktuellen Zustand des Stammspeichers und nicht auf dem Zustand des Stammspeichers zu einem zeitpunkt, der von diesem Parameter übergeben wurde. Für die Sperrung muss eine Zertifikatsperrliste (Certificate Revocation List , CRL) selbst zum aktuellen Zeitpunkt gültig sein. Der Wert dieses Parameters wird verwendet, um zu bestimmen, ob ein in einer Zertifikatsperrliste aufgeführtes Zertifikat widerrufen wurde.
[in] hAdditionalStore
Ein Handle für jeden zusätzlichen Speicher zum Suchen nach unterstützenden Zertifikaten und Zertifikatvertrauenslisten (Certificate Trust Lists , CTLs). Dieser Parameter kann NULL sein, wenn kein zusätzlicher Speicher durchsucht werden soll.
[in] pChainPara
Ein Zeiger auf eine CERT_CHAIN_PARA-Struktur , die Parameter zum Erstellen von Ketten enthält.
[in] dwFlags
Flagwerte, die auf eine spezielle Verarbeitung hinweisen. Dieser Parameter kann eine Kombination aus mindestens einem der folgenden Flags sein.
| Wert | Bedeutung |
|---|---|
|
Wenn dieses Flag festgelegt ist, wird das Endzertifikat zwischengespeichert, was den Prozess zur Erstellung der Kette beschleunigen kann. Standardmäßig wird das Endzertifikat nicht zwischengespeichert, und es muss jedes Mal überprüft werden, wenn eine Kette dafür erstellt wird. |
|
Die Sperrüberprüfung greift nur auf zwischengespeicherte URLs zu. |
|
Dieses Flag wird intern während der Kettenerstellung für ein OCSP-Signaturzertifikat (Onlinezertifikat status Protokoll) verwendet, um zyklische Sperrprüfungen zu verhindern. Wenn die OCSP-Antwort während der Kettenerstellung von einem unabhängigen OCSP-Signaturgeber signiert wird, gibt es zusätzlich zum ursprünglichen Kettenbuild eine zweite Kette, die für das OCSP-Signerzertifikat selbst erstellt wurde. Dieses Flag wird während dieses zweiten Kettenbuilds verwendet, um ein rekursives unabhängiges OCSP-Signerzertifikat zu verhindern. Wenn das Signaturzertifikat die szOID_PKIX_OCSP_NOCHECK-Erweiterung enthält, wird die Sperrprüfung für das Zertifikat des Blattzeichners übersprungen. Sowohl DIE OCSP- als auch die CRL-Überprüfung sind zulässig.
Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt. |
|
Verwendet beim Erstellen einer Zertifikatkette nur zwischengespeicherte URLs. Internet und Intranet werden nicht nach URL-basierten Objekten gesucht.
Hinweis Dieses Flag gilt nicht für die Sperrüberprüfung. Legen Sie CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY so fest, dass nur zwischengespeicherte URLs für die Sperrüberprüfung verwendet werden. |
|
Aus Leistungsgründen berücksichtigt der zweite Durchgang des Kettenaufbaus nur potenzielle Kettenpfade, deren Qualität größer oder gleich der höchsten Qualität ist, 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 Flag kann festgelegt werden, um diese Optimierung zu deaktivieren und alle potenziellen Kettenpfade während des zweiten Durchlaufs zu berücksichtigen. |
|
Dieses Flag wird nicht unterstützt. Zertifikate im "Mein"-Speicher werden nie als Peervertrauen betrachtet. |
|
Endentitätszertifikate im "TrustedPeople"-Speicher werden vertrauenswürdig, ohne dass eine Kettenerstellung durchgeführt 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 Windows XP : Dieses Flag wird nicht unterstützt. |
|
Das Festlegen dieses Flags gibt an, dass der Aufrufer schwache Signaturprüfungen aktivieren möchte.
Dieses Flag ist im Rollupupdate für jedes Betriebssystem ab Windows 7 und Windows Server 2008 R2 verfügbar. |
|
Standardmäßig wird nur der Kettenpfad der höchsten Qualität zurückgegeben. Durch Festlegen dieses Flags werden die Ketten mit niedrigerer Qualität zurückgegeben. Diese werden in den Feldern cLowerQualityChainContext und rgpLowerQualityChainContext des Kettenkontexts zurückgegeben. |
|
Das Festlegen dieses Flags verhindert die automatische Aktualisierung von Stammstammen von Drittanbietern aus dem Windows Update Webserver. |
|
Wenn Sie CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT festlegen und auch einen Wert für das dwUrlRetrievalTimeout-Element 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 das maximale kumulative Timeout standardmäßig auf 20 Sekunden festgelegt. Für jede getestete URL wird ein Timeout ausgeführt, nachdem die Hälfte des verbleibenden kumulierten Saldos abgelaufen ist. Das heißt, die erste URL ist nach 10 Sekunden timeout, die zweite nach 5 Sekunden, die dritte nach 2,5 Sekunden usw., bis eine URL erfolgreich ist, 20 Sekunden vergangen sind oder keine weiteren URLs mehr zu testen sind. Wenn Sie nicht CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT festlegen, wird jeder Sperr-URL in der Kette ein maximales Timeout zugewiesen, das dem in dwUrlRetrievalTimeout angegebenen Wert entspricht. Wenn Sie keinen Wert für das dwUrlRetrievalTimeout-Element angeben, wird jeder Sperr-URL ein maximales Standardtimeout von 15 Sekunden zugewiesen. Wenn keine URL erfolgreich ist, beträgt der maximale kumulative Timeoutwert 15 Sekunden multipliziert mit der Anzahl der URLs in der Kette. Sie können die Standardwerte mit Gruppenrichtlinie festlegen. |
|
Wenn dieses Flag festgelegt ist, wird pTime als Zeitstempelzeit verwendet, um zu bestimmen, ob das Endzertifikat zeit gültig war. Die aktuelle Zeit kann auch verwendet werden, um zu bestimmen, ob das Endzertifikat zeit gültig bleibt. Alle anderen Zertifizierungsstellen und Stammzertifikate in der Kette werden mithilfe der aktuellen Zeit und nicht mit pTime überprüft. |
|
Durch das explizite Festlegen dieses Flags werden AIA-Abrufe (Authority Information Access) deaktiviert. |
Sie können auch die folgenden Sperrflags festlegen, aber es kann jeweils nur ein Flag aus dieser Gruppe festgelegt werden.
[in] pvReserved
Dieser Parameter ist reserviert und muss NULL sein.
[out] ppChainContext
Die Adresse eines Zeigers auf den erstellten Kettenkontext. Wenn Sie die Verwendung des Kettenkontexts abgeschlossen haben, geben Sie die Kette frei, indem Sie die CertFreeCertificateChain-Funktion aufrufen.
Rückgabewert
Wenn die Funktion erfolgreich ist, gibt die Funktion ungleich null (TRUE) zurück.
Wenn die Funktion fehlschlägt, gibt sie null (FALSE) zurück. Rufen Sie GetLastError auf, um erweiterte Fehlerinformationen zu erhalten.
Hinweise
Wenn eine Anwendung eine Zertifikatkette anfordert, wird die zurückgegebene Struktur in Form einer CERT_CHAIN_CONTEXT. Dieser Kontext enthält ein Array von CERT_SIMPLE_CHAIN Strukturen, bei 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 der starken Signatur:
- Sie können die starke Signaturüberprüfung für diese Funktion aktivieren, indem Sie den pStrongSignPara-Member der CERT_CHAIN_PARA Struktur festlegen, auf die der pChainPara-Parameter verweist.
- 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 des öffentlichen Schlüssels 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 die der pChainPara-Parameter verweist.
- 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 Fehler CERT_TRUST_IS_OFFLINE_REVOCATION und CERT_TRUST_REVOCATION_STATUS_UNKNOWN werden im Feld dwErrorStatus der CERT_TRUST_STATUS-Struktur festgelegt. Außerdem wird der dwRevocationResult-Member der CERT_REVOCATION_INFO-Struktur auf NTE_BAD_ALGID festgelegt.
Beispiele
Ein Beispiel, das diese Funktion verwendet, finden Sie unter Beispiel-C-Programm: Erstellen einer Zertifikatkette.
Anforderungen
| Unterstützte Mindestversion (Client) | Windows XP [Desktop-Apps | UWP-Apps] |
| Unterstützte Mindestversion (Server) | Windows Server 2003 [Desktop-Apps | UWP-Apps] |
| Zielplattform | Windows |
| Kopfzeile | wincrypt.h |
| Bibliothek | Crypt32.lib |
| DLL | Crypt32.dll |
Weitere Informationen
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für