CertGetCertificateChain-Funktion (wincrypt.h)
Die CertGetCertificateChain-Funktion erstellt einen Zertifikatkettenkontext ab einem Endzertifikat und wird ggf. zu einem vertrauenswürdigen Stammzertifikat zurückkehren.
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 hChainEngineNULL ist, wird das Standardkettenmodul HCCE_CURRENT_USER verwendet. Dieser Parameter kann auf HCCE_LOCAL_MACHINE festgelegt werden.
[in] pCertContext
Ein Zeiger auf das CERT_CONTEXT des Endzertifikats, das Zertifikat, für das eine Kette erstellt wird. Dieser Zertifikatkontext wird das Nullindexelement in der ersten einfachen Kette sein.
[in, optional] pTime
Ein Zeiger auf eine FILETIME-Variable , die die Uhrzeit angibt, für die die Kette überprüft werden soll. Beachten Sie, dass sich die Uhrzeit nicht auf die Vertrauensliste, die Sperrung oder die Überprüfung des Stammspeichers 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 Zustand des Stammspeichers und nicht auf dem Zustand des Stammspeichers, der von diesem Parameter übergeben wird. Für den Widerruf muss eine Zertifikatsperrliste (CRL) selbst gültig sein. Der Wert dieses Parameters wird verwendet, um zu ermitteln, ob ein Zertifikat, das in einer CRL aufgeführt ist, widerrufen wurde.
[in] hAdditionalStore
Ein Handle zu jedem zusätzlichen Speicher, um nach unterstützenden Zertifikaten und Zertifikatvertrauenswürdigen Listen (CTLs) zu suchen. Dieser Parameter kann NULL sein, wenn kein zusätzlicher Speicher durchsucht werden soll.
[in] pChainPara
Ein Zeiger auf eine CERT_CHAIN_PARA Struktur, die Kettenbauparameter enthält.
[in] dwFlags
Kennzeichnen von Werten, die eine spezielle Verarbeitung angeben. Dieser Parameter kann eine Kombination aus einer oder mehreren der folgenden Flags sein.
| Wert | Bedeutung |
|---|---|
|
Wenn dieses Flag festgelegt ist, wird das Endzertifikat zwischengespeichert, was den Chain-Building-Prozess beschleunigen kann. Standardmäßig ist das Endzertifikat nicht zwischengespeichert, und es muss jedes Mal überprüft werden, wenn eine Kette für sie erstellt wird. |
|
Sperrprüfung greift nur auf zwischengespeicherte URLs zu. |
|
Dieses Flag wird intern während der Chain-Erstellung für ein OcSP-Zertifikat ( Online-Zertifikatstatusprotokoll ) verwendet, um cyclische Sperrprüfungen zu verhindern. Wenn die OCSP-Antwort während des Chain Building von einem unabhängigen OCSP-Signer signiert wird, gibt es neben dem ursprünglichen Chain Build eine zweite Kette, die für das OCSP-Signerzertifikat selbst erstellt wurde. Dieses Flag wird während dieses zweiten Chain Build verwendet, um ein rekursives unabhängiges OCSP-Signerzertifikat zu verhindern. Wenn das Signerzertifikat die szOID_PKIX_OCSP_NOCHECK Erweiterung enthält, wird die Sperrprüfung für das Blattzeichenzertifikat übersprungen. Sowohl OCSP- als auch CRL-Überprüfung sind zulässig.
Windows Server 2003 und Windows XP: Dieser Wert wird nicht unterstützt. |
|
Verwendet nur zwischengespeicherte URLs beim Erstellen einer Zertifikatkette. Das Internet und Intranet werden nicht nach URL-basierten Objekten gesucht.
Hinweis Diese Kennzeichnung gilt nicht für die Sperrüberprüfung. Legen Sie CERT_CHAIN_REVOCATION_CHECK_CACHE_ONLY fest, dass nur zwischengespeicherte URLs für die Sperrüberprüfung verwendet werden. |
|
Aus Leistungsgründen betrachtet der zweite Pass des Kettenbaus nur potenzielle Kettenpfade, die qualität größer oder gleich der höchsten Qualität sind, die während des ersten Passs bestimmt wurden. Der erste Pass berücksichtigt nur gültige Signatur, vollständige Kette und vertrauenswürdige Wurzeln, um die Kettequalität zu berechnen. Dieses Flag kann festgelegt werden, um diese Optimierung zu deaktivieren und alle potenziellen Kettenpfade während des zweiten Pass zu berücksichtigen. |
|
Dieses Flag wird nicht unterstützt. Zertifikate im "My"-Speicher werden niemals als Peer-Vertrauensstellung betrachtet. |
|
End-Entitätszertifikate im Speicher "TrustedPeople" sind vertrauenswürdig, ohne eine Kette zu erstellen. 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. |
|
Wenn Sie dieses Kennzeichen festlegen, wird angegeben, dass sich der Anrufer bei schwachen Signaturüberprüfungen anmelden möchte.
Dieses Flag steht im Rollupupdate für jedes Betriebssystem ab Windows 7 und Windows Server 2008 R2 zur Verfügung. |
|
Die Standardeinstellung besteht darin, nur den höchsten Qualitätskettenpfad zurückzugeben. Wenn Sie dieses Flag festlegen, werden die niedrigeren Qualitätsketten zurückgegeben. Diese werden in den Feldern "cLowerQualityChainContext " und "rgpLowerQualityChainContext " des Kettenkontexts zurückgegeben. |
|
Durch Festlegen dieses Flags wird die automatische Aktualisierung von Wurzeln von Drittanbietern aus dem Windows Update Webserver verhindert. |
|
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 über alle Widerrufs-URL-Abrufe darstellt.
Wenn Sie CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT festlegen, aber keinen dwUrlRetrievalTimeout-Wert angeben, wird das maximale kumulative Timeout standardmäßig auf 20 Sekunden festgelegt. Jede getestete URL wird nach der Hälfte des verbleibenden kumulativen Guthabens zeitoutiert. Das heißt, die erste URL wird nach 10 Sekunden, dem zweiten nach 5 Sekunden, dem dritten nach 2,5 Sekunden und so weiter, bis eine URL erfolgreich ist, 20 Sekunden übergeben wurde, oder es gibt keine weiteren URLs zum Testen. Wenn Sie CERT_CHAIN_REVOCATION_ACCUMULATIVE_TIMEOUT nicht festlegen, wird jeder Widerrufs-URL in der Kette einem maximalen Timeout zugewiesen, der dem in dwUrlRetrievalTimeout angegebenen Wert entspricht. Wenn Sie keinen Wert für das dwUrlRetrievalTimeout-Element angeben, wird jeder Sperr-URL einem maximalen Standardtimeout von 15 Sekunden zugewiesen. Wenn keine URL erfolgreich ist, beträgt der maximale kumulative Timeoutwert 15 Sekunden, die durch die Anzahl der URLs in der Kette multipliziert werden. Sie können die Standardwerte mithilfe von Gruppenrichtlinie festlegen. |
|
Wenn dieses Flag festgelegt ist, wird pTime als Zeitstempelzeit verwendet, um zu ermitteln, ob das Endzertifikat zeit gültig war. Die aktuelle Zeit kann auch verwendet werden, um festzustellen, 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. |
|
Durch Das Festlegen dieses Flags wird der Abruf von Authority Information Access (AIA) explizit deaktiviert. |
Sie können auch die folgenden Sperrzeichen festlegen, aber nur ein Flag aus dieser Gruppe kann gleichzeitig festgelegt werden.
[in] pvReserved
Dieser Parameter ist reserviert und muss NULL sein.
[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, gibt sie null (FALSE) zurück. Rufen Sie getLastError für erweiterte Fehlerinformationen auf.
Hinweise
Wenn eine Anwendung eine Zertifikatkette anfordert, befindet sich die zurückgegebene Struktur in Form einer CERT_CHAIN_CONTEXT. Dieser Kontext enthält ein Array von CERT_SIMPLE_CHAIN Strukturen, in dem 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, zusammenfassungsbasierte Vertrauensinformationen über die 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 Sichere Signaturüberprüfung für diese Funktion aktivieren, indem Sie das pStrongSignPara-Element der CERT_CHAIN_PARA Struktur festlegen, auf die der pChainPara-Parameter verweist.
- Wenn ein Zertifikat ohne starke Signatur in der Kette gefunden wird, werden die CERT_TRUST_HAS_WEAK_SIGNATURE und CERT_TRUST_IS_NOT_SIGNATURE_VALID Fehler im DwErrorStatus-Feld 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 zu ermitteln, ob die Mindestanforderungen für die Länge öffentlicher Schlüssel für eine starke Signatur erfüllt sind. Wenn die Bedingung nicht erfüllt ist, werden die CERT_TRUST_HAS_WEAK_SIGNATURE und CERT_TRUST_IS_NOT_SIGNATURE_VALID Fehler 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 CERT_TRUST_IS_OFFLINE_REVOCATION und CERT_TRUST_REVOCATION_STATUS_UNKNOWN Fehler werden im dwErrorStatus-Feld der CERT_TRUST_STATUS Struktur festgelegt. Außerdem wird das dwRevocationResult-Element 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 |