Función CertSelectCertificateChains (wincrypt.h)

La función CertSelectCertificateChains recupera cadenas de certificados en función de los criterios de selección especificados.

Sintaxis

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
);

Parámetros

[in, optional] pSelectionContext

Puntero al GUID del escenario de selección de certificados que se va a usar para esta llamada.

[in] dwFlags

Marcas para controlar el proceso de selección de certificados. Este parámetro puede ser una combinación de cero o más de las marcas siguientes:

Valor	Significado
CERT_SELECT_ALLOW_EXPIRED	Seleccione certificados expirados que cumplan los criterios de selección. De forma predeterminada, los certificados expirados se rechazan de la selección.
CERT_SELECT_TRUSTED_ROOT	Seleccione certificados en los que el bit de error del estado de confianza de la cadena de certificados no esté establecido en CERT_TRUST_IS_UNTRUSTED_ROOT, CERT_TRUST_IS_PARTIAL_CHAIN o CERT_TRUST_IS_NOT_TIME_VALID. Además, no se seleccionan los certificados que tienen uno de los siguientes errores de restricción no válidos: CERT_TRUST_INVALID_POLICY_CONSTRAINTS CERT_TRUST_INVALID_BASIC_CONSTRAINTS CERT_TRUST_INVALID_NAME_CONSTRAINTS
CERT_SELECT_DISALLOW_SELFSIGNED	Seleccione los certificados que no se emiten automáticamente y autofirmados.
CERT_SELECT_HAS_PRIVATE_KEY	Seleccione certificados que tengan un valor establecido para la propiedad CERT_KEY_PROV_INFO_PROP_ID del certificado.
CERT_SELECT_HAS_KEY_FOR_SIGNATURE	Seleccione certificados en los que el valor del miembro dwKeySpec de la propiedad CERT_KEY_PROV_INFO_PROP_ID esté establecido en AT_SIGNATURE. Si se llama a esta función como parte de una aplicación habilitada para CNG y el miembro dwKeySpec de la propiedad CERT_KEY_PROV_INFO_PROP_ID se establece en -1, seleccione certificados en los que el valor de la propiedad NCRYPT_KEY_USAGE_PROPERTY de la clave privada asociada tenga establecido el NCRYPT_ALLOW_SIGNING_FLAG .
CERT_SELECT_HAS_KEY_FOR_KEY_EXCHANGE	Seleccione certificados en los que el valor del miembro dwKeySpec de la propiedad CERT_KEY_PROV_INFO_PROP_ID esté establecido en AT_KEYEXCHANGE. Si se llama a esta función como parte de una aplicación habilitada para CNG y el miembro dwKeySpec de la propiedad CERT_KEY_PROV_INFO_PROP_ID se establece en -1, seleccione certificados en los que se establezca NCRYPT_ALLOW_DECRYPT_FLAG o NCRYPT_ALLOW_KEY_AGREEMENT_FLAG .
CERT_SELECT_HARDWARE_ONLY	Seleccione certificados en los que el valor de la propiedad PP_IMPTYPE del proveedor de claves privadas asociado esté establecido en CRYPT_IMPL_HARDWARE o en CRYPT_IMPL_REMOVABLE. (En el caso de los proveedores de CNG, NCRYPT_IMPL_TYPE_PROPERTY valor de propiedad DEBE tener el NCRYPT_IMPL_HARDWARE_FLAG o NCRYPT_IMPL_REMOVABLE_FLAG conjunto de bits). Si se llama a esta función como parte de una aplicación habilitada para CNG, seleccione certificados en los que la propiedad NCRYPT_IMPL_TYPE_PROPERTY esté establecida en NCRYPT_IMPL_HARDWARE_FLAG o NCRYPT_IMPL_REMOVABLE_FLAG.
CERT_SELECT_ALLOW_DUPLICATES	Permita la selección de certificados en los que el nombre alternativo del firmante y el firmante contienen la misma información y el valor de extensión de plantilla de certificado es equivalente. De forma predeterminada, cuando los certificados coinciden con estos criterios, solo se selecciona el certificado más reciente.

[in, optional] pChainParameters

Puntero a una estructura de CERT_SELECT_CHAIN_PARA para especificar parámetros para la creación de cadenas. Si es NULL, se usarán parámetros predeterminados.

El miembro pChainPara de la estructura CERT_SELECT_CHAIN_PARA apunta a una estructura de CERT_CHAIN_PARA que se puede usar para habilitar la firma segura.

[in] cCriteria

Número de elementos de la matriz a los que apunta la matriz rgpCriteria .

[in, optional] rgpCriteria

Puntero a una matriz de estructuras de CERT_SELECT_CRITERIA que definen los criterios de selección. Si este parámetro se establece en NULL, el valor del parámetro cCriteria debe ser cero.

[in] hStore

Identificador de un almacén desde el que se van a seleccionar los certificados.

[out] pcSelection

Puntero a un valor DWORD para recibir el número de elementos de la matriz a los que apunta el parámetro pprgpSelection .

[out] pprgpSelection

Puntero a un puntero a una ubicación para recibir una matriz de CERT_CHAIN_CONTEXT estructura. La función CertSelectCertificateChains solo devuelve cadenas de certificados que coinciden con todos los criterios de selección. Las entradas de la matriz se ordenan por calidad, es decir, la cadena con la más alta calidad es la primera entrada.

La función CertSelectCertificateChains asigna almacenamiento para la matriz. Para liberar la memoria asignada, primero debe liberar cada contexto de cadena individual de la matriz llamando a la función CertFreeCertificateChain . A continuación, debe liberar la memoria llamando a la función CertFreeCertificateChainList .

Valor devuelto

Si la función se ejecuta correctamente, la función devuelve TRUE.

Si se produce un error en la función, devuelve cero (FALSE). Para obtener información de error extendida, llame a la función GetLastError .

Nota Si la selección no produce ningún resultado, la función CertSelectCertificateChains devuelve TRUE, pero el valor al que apunta el parámetro pcSelection se establece en cero.

 

Comentarios

Los criterios de selección se pueden especificar a través del parámetro dwFlags , mediante el parámetro rgpCriteria o mediante ambos parámetros. Si no se especifica ningún criterio de selección, la función se realiza correctamente y devuelve cadenas de certificados para todos los certificados del almacén especificado por el parámetro hStore .

Las cadenas de certificados seleccionadas se ordenan en función de la siguiente lógica de preferencia:

• Prefiere certificados que son certificados de tarjeta inteligente sobre certificados que no están basados en tarjetas inteligentes.
• Se prefieren los certificados que tienen un período de validez más largo (la fecha de expiración es posterior).
• Si varios certificados tienen la misma fecha de expiración, prefiera los certificados emitidos más recientemente.
• Si hay un empate, prefiere cadenas más cortas.

Ciertos criterios de selección requieren que se cree una cadena de certificados para poder seleccionar esos criterios de uso. Si los certificados intermedios necesarios para compilar la cadena no están disponibles localmente, se realiza una recuperación de red para los certificados del emisor. Esta recuperación de red se realiza si se establece la marca de CERT_SELECT_TRUSTED_ROOT o para los criterios siguientes:

• CERT_SELECT_BY_ISSUER_NAME
• CERT_SELECT_BY_ISSUER_ATTR
• CERT_SELECT_BY_POLICY_OID

Realice las siguientes acciones para habilitar la comprobación de firmas seguras:

• Cree una estructura de CERT_STRONG_SIGN_PARA , especifique los parámetros de firma seguros necesarios y establezca un puntero a la estructura del miembro pStrongSignPara de una estructura CERT_CHAIN_PARA .
• Establezca un puntero en la estructura CERT_CHAIN_PARA del miembro pChainPara de una estructura CERT_SELECT_CHAIN_PARA .
• Establezca un puntero a la estructura CERT_SELECT_CHAIN_PARA en el parámetro pChainParameters de esta función (CertSelectCertificateChains).

Al habilitar la comprobación de firmas seguras, se omitirá cualquier cadena de certificados que devuelva un error de CERT_TRUST_IS_NOT_SIGNATURE_VALID en el campo dwErrorStatus de la estructura de CERT_TRUST_STATUS . (El parámetro pprgpSelection apunta a una estructura de CERT_CHAIN_CONTEXT que, a su vez, apunta a la estructura CERT_TRUST_STATUS ). El valor de CERT_TRUST_HAS_WEAK_SIGNATURE también se establece para una firma débil.

Requisitos

Requisito	Value
Cliente mínimo compatible	Windows 7 [aplicaciones de escritorio | Aplicaciones para UWP]
Servidor mínimo compatible	Windows Server 2008 R2 [aplicaciones de escritorio | Aplicaciones para UWP]
Plataforma de destino	Windows
Encabezado	wincrypt.h
Library	Crypt32.lib
Archivo DLL	Crypt32.dll

Consulte también

CertGetCertificateContextProperty

CertSetCertificateContextProperty