CertSelectCertificateChains-Funktion (wincrypt.h)

Artikel
08/27/2023

Die CertSelectCertificateChains-Funktion ruft Zertifikatketten auf Der Grundlage der angegebenen Auswahlkriterien ab.

Syntax

BOOL CertSelectCertificateChains(
  [in, optional] LPCGUID                  pSelectionContext,
  [in]           DWORD                    dwFlags,
  [in, optional] PCCERT_SELECT_CHAIN_PARA pChainParameters,
  [in]           DWORD                    cCriteria,
  [in, optional] PCCERT_SELECT_CRITERIA   rgpCriteria,
  [in]           HCERTSTORE               hStore,
  [out]          PDWORD                   pcSelection,
  [out]          PCCERT_CHAIN_CONTEXT     **pprgpSelection
);

Parameter

[in, optional] pSelectionContext

Ein Zeiger auf die GUID des Zertifikatauswahlszenarios, das für diesen Aufruf verwendet werden soll.

[in] dwFlags

Flags zum Steuern des Zertifikatauswahlprozesses. Dieser Parameter kann eine Kombination aus null oder mehr der folgenden Flags sein:

Wert	Bedeutung
CERT_SELECT_ALLOW_EXPIRED	Wählen Sie abgelaufene Zertifikate aus, die die Auswahlkriterien erfüllen. Standardmäßig werden abgelaufene Zertifikate von der Auswahl abgelehnt.
CERT_SELECT_TRUSTED_ROOT	Wählen Sie Zertifikate aus, für die das Fehlerbit in der Zertifikatkettenvertrauensstellung status nicht auf CERT_TRUST_IS_UNTRUSTED_ROOT, CERT_TRUST_IS_PARTIAL_CHAIN oder CERT_TRUST_IS_NOT_TIME_VALID festgelegt ist. Darüber hinaus werden Zertifikate mit einem der folgenden ungültigen Einschränkungsfehler nicht ausgewählt: CERT_TRUST_INVALID_POLICY_CONSTRAINTS CERT_TRUST_INVALID_BASIC_CONSTRAINTS CERT_TRUST_INVALID_NAME_CONSTRAINTS
CERT_SELECT_DISALLOW_SELFSIGNED	Wählen Sie Zertifikate aus, die nicht selbst ausgestellt und selbstsigniert sind.
CERT_SELECT_HAS_PRIVATE_KEY	Wählen Sie Zertifikate aus, deren Wert für die CERT_KEY_PROV_INFO_PROP_ID-Eigenschaft des Zertifikats festgelegt ist.
CERT_SELECT_HAS_KEY_FOR_SIGNATURE	Wählen Sie Zertifikate aus, für die der Wert des dwKeySpec-Members der CERT_KEY_PROV_INFO_PROP_ID-Eigenschaft auf AT_SIGNATURE festgelegt ist. Wenn diese Funktion als Teil einer CNG-aktivierten Anwendung aufgerufen wird und das dwKeySpec-Element der CERT_KEY_PROV_INFO_PROP_ID-Eigenschaft auf -1 festgelegt ist, wählen Sie Zertifikate aus, für die der Wert der NCRYPT_KEY_USAGE_PROPERTY-Eigenschaft des zugeordneten privaten Schlüssels den NCRYPT_ALLOW_SIGNING_FLAG festgelegt hat.
CERT_SELECT_HAS_KEY_FOR_KEY_EXCHANGE	Wählen Sie Zertifikate aus, für die der Wert des dwKeySpec-Members der CERT_KEY_PROV_INFO_PROP_ID-Eigenschaft auf AT_KEYEXCHANGE festgelegt ist. Wenn diese Funktion als Teil einer CNG-fähigen Anwendung aufgerufen wird und das dwKeySpec-Element der CERT_KEY_PROV_INFO_PROP_ID-Eigenschaft auf -1 festgelegt ist, wählen Sie Zertifikate aus, für die entweder NCRYPT_ALLOW_DECRYPT_FLAG oder NCRYPT_ALLOW_KEY_AGREEMENT_FLAG festgelegt ist.
CERT_SELECT_HARDWARE_ONLY	Wählen Sie Zertifikate aus, für die der Wert der PP_IMPTYPE Eigenschaft des zugeordneten Anbieters für private Schlüssel auf CRYPT_IMPL_HARDWARE oder CRYPT_IMPL_REMOVABLE festgelegt ist. (Für CNG-Anbieter MUSS NCRYPT_IMPL_TYPE_PROPERTY-Eigenschaftswert entweder über den NCRYPT_IMPL_HARDWARE_FLAG oder NCRYPT_IMPL_REMOVABLE_FLAG Bitsatz verfügen). Wenn diese Funktion als Teil einer CNG-fähigen Anwendung aufgerufen wird, wählen Sie Zertifikate aus, für die die NCRYPT_IMPL_TYPE_PROPERTY-Eigenschaft auf NCRYPT_IMPL_HARDWARE_FLAG oder NCRYPT_IMPL_REMOVABLE_FLAG festgelegt ist.
CERT_SELECT_ALLOW_DUPLICATES	Lassen Sie die Auswahl von Zertifikaten zu, für die der Antragsteller und der Antragsteller-Alt-Name die gleichen Informationen enthalten und der Wert der Zertifikatvorlagenerweiterung gleichwertig ist. Wenn Zertifikate diesen Kriterien entsprechen, wird standardmäßig nur das neueste Zertifikat ausgewählt.

[in, optional] pChainParameters

Ein Zeiger auf eine CERT_SELECT_CHAIN_PARA Struktur, um Parameter für die Kettenerstellung anzugeben. Bei NULL werden Standardparameter verwendet.

Das pChainPara-Element der CERT_SELECT_CHAIN_PARA-Struktur verweist auf eine CERT_CHAIN_PARA-Struktur , die zum Aktivieren einer starken Signatur verwendet werden kann.

[in] cCriteria

Die Anzahl der Elemente im Array, auf die das rgpCriteria-Array verweist.

[in, optional] rgpCriteria

Ein Zeiger auf ein Array von CERT_SELECT_CRITERIA Strukturen, die die Auswahlkriterien definieren. Wenn dieser Parameter auf NULL festgelegt ist, muss der Wert des cCriteria-Parameters 0 sein.

[in] hStore

Das Handle für einen Speicher, aus dem die Zertifikate ausgewählt werden sollen.

[out] pcSelection

Ein Zeiger auf einen DWORD-Wert , um die Anzahl der Elemente im Array zu empfangen, auf die der pprgpSelection-Parameter verweist.

[out] pprgpSelection

Ein Zeiger auf einen Zeiger auf eine Position, an der ein Array mit CERT_CHAIN_CONTEXT Struktur empfangen wird. Die CertSelectCertificateChains-Funktion gibt nur Zertifikatketten zurück, die allen Auswahlkriterien entsprechen. Die Einträge im Array werden nach Qualität sortiert, d.h. die Kette mit der höchsten Qualität ist der erste Eintrag.

Der Speicher für das Array wird von der Funktion CertSelectCertificateChains zugewiesen. Um den zugewiesenen Arbeitsspeicher freizugeben, müssen Sie zunächst jeden einzelnen Kettenkontext im Array freigeben, indem Sie die CertFreeCertificateChain-Funktion aufrufen. Anschließend müssen Sie den Arbeitsspeicher freigeben, indem Sie die CertFreeCertificateChainList-Funktion aufrufen.

Rückgabewert

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

Wenn die Funktion fehlschlägt, gibt sie null (FALSE) zurück. Rufen Sie die GetLastError-Funktion auf, um erweiterte Fehlerinformationen zu erhalten.

Hinweis Wenn die Auswahl keine Ergebnisse liefert, gibt die CertSelectCertificateChains-FunktionTRUE zurück, aber der Wert, auf den vom pcSelection-Parameter verwiesen wird, ist auf 0 festgelegt.

Hinweise

Auswahlkriterien können entweder über den dwFlags-Parameter , über den rgpCriteria-Parameter oder über beide Parameter angegeben werden. Wenn keine Auswahlkriterien angegeben werden, ist die Funktion erfolgreich und gibt Zertifikatketten für alle Zertifikate in dem durch den hStore-Parameter angegebenen Speicher zurück.

Ausgewählte Zertifikatketten werden basierend auf der folgenden Einstellungslogik sortiert:

Bevorzugen Sie Zertifikate, die smart Karte-Zertifikate sind, gegenüber Zertifikaten, die nicht auf smart-Karte basieren.
Bevorzugen Sie Zertifikate, die einen längeren Gültigkeitszeitraum haben (das Ablaufdatum ist später).)
Wenn mehrere Zertifikate dasselbe Ablaufdatum haben, bevorzugen Sie Zertifikate, die kürzlich ausgestellt wurden.
Wenn ein Gleichstand vorhanden ist, bevorzugen Sie kürzere Ketten.

Bestimmte Auswahlkriterien erfordern, dass eine Zertifikatkette erstellt wird, bevor Sie diese Kriterien für die Verwendung auswählen können. Wenn die zum Erstellen der Kette erforderlichen Zwischenzertifikate nicht lokal verfügbar sind, wird ein Netzwerkabruf für die Ausstellerzertifikate durchgeführt. Dieser Netzwerkabruf wird ausgeführt, wenn das CERT_SELECT_TRUSTED_ROOT-Flag festgelegt ist oder für die folgenden Kriterien gilt:

CERT_SELECT_BY_ISSUER_NAME
CERT_SELECT_BY_ISSUER_ATTR
CERT_SELECT_BY_POLICY_OID

Führen Sie die folgenden Aktionen aus, um die Überprüfung einer starken Signatur zu aktivieren:

Erstellen Sie eine CERT_STRONG_SIGN_PARA-Struktur , geben Sie die erforderlichen Parameter für starke Signatur an, und legen Sie einen Zeiger auf die Struktur im pStrongSignPara-Element einer CERT_CHAIN_PARA-Struktur fest.
Legen Sie einen Zeiger auf die CERT_CHAIN_PARA-Struktur im pChainPara-Member einer CERT_SELECT_CHAIN_PARA-Struktur fest.
Legen Sie einen Zeiger auf die CERT_SELECT_CHAIN_PARA-Struktur im pChainParameters-Parameter dieser Funktion (CertSelectCertificateChains) fest.

Wenn Sie die Überprüfung der starken Signatur aktivieren, wird jede Zertifikatkette, die einen CERT_TRUST_IS_NOT_SIGNATURE_VALID Fehler im Feld dwErrorStatus der CERT_TRUST_STATUS-Struktur zurückgibt, übersprungen. (Der pprgpSelection-Parameter verweist auf eine CERT_CHAIN_CONTEXT Struktur, die wiederum auf die CERT_TRUST_STATUS-Struktur verweist.) Der wert CERT_TRUST_HAS_WEAK_SIGNATURE wird auch für eine schwache Signatur festgelegt.

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows 7 [Desktop-Apps \| UWP-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2008 R2 [Desktop-Apps \| UWP-Apps]
Zielplattform	Windows
Kopfzeile	wincrypt.h
Bibliothek	Crypt32.lib
DLL	Crypt32.dll

Weitere Informationen

CertGetCertificateContextProperty

CertSetCertificateContextProperty

Freigeben über