Función CertVerifyCTLUsage (wincrypt.h)

Artículo
08/27/2023

La función CertVerifyCTLUsage comprueba que un sujeto es de confianza para un uso especificado mediante la búsqueda de una lista de confianza de certificado (CTL) firmada y válida para el tiempo con los identificadores de uso que contienen el asunto. El sujeto de un certificado se puede identificar mediante su contexto de certificado o cualquier identificador único, como el hash SHA1 del certificado del firmante.

Sintaxis

BOOL CertVerifyCTLUsage(
  [in]           DWORD                    dwEncodingType,
  [in]           DWORD                    dwSubjectType,
  [in]           void                     *pvSubject,
  [in]           PCTL_USAGE               pSubjectUsage,
  [in]           DWORD                    dwFlags,
  [in, optional] PCTL_VERIFY_USAGE_PARA   pVerifyUsagePara,
  [in, out]      PCTL_VERIFY_USAGE_STATUS pVerifyUsageStatus
);

Parámetros

[in] dwEncodingType

Especifica el tipo de codificación usado. Actualmente, solo se usan X509_ASN_ENCODING y PKCS_7_ASN_ENCODING; sin embargo, se pueden agregar tipos de codificación adicionales en el futuro. Para cualquier tipo de codificación actual, use

X509_ASN_ENCODING | PKCS_7_ASN_ENCODING.

[in] dwSubjectType

Si el parámetro dwSubjectType se establece en CTL_CERT_SUBJECT_TYPE, pvSubject apunta a una estructura CERT_CONTEXT . El miembro SubjectAlgorithm de la estructura se examina para determinar la representación de la identidad del sujeto. Inicialmente, solo se admiten hash SHA1 y MD5 como valores para SubjectAlgorithm. La propiedad hash adecuada se obtiene de la estructura CERT_CONTEXT .

Si el parámetro dwSubjectType se establece en CTL_ANY_SUBJECT_TYPE, pvSubject apunta a la estructura CTL_ANY_SUBJECT_INFO . El miembro SubjectAlgorithm de esta estructura debe coincidir con el tipo de algoritmo del CTL y el miembro SubjectIdentifier debe coincidir con una de las entradas de CTL.

Si dwSubjectType se establece en cualquier valor anterior, dwEncodingType no se usa.

[in] pvSubject

Valor usado junto con el parámetro dwSubjectType .

[in] pSubjectUsage

Puntero a una estructura CTL_USAGE utilizada para especificar el uso previsto del asunto.

[in] dwFlags

Si no se establece el CERT_VERIFY_INHIBIT_CTL_UPDATE_FLAG, se puede reemplazar un CTL cuyo tiempo ya no es válido en uno de los almacenes especificados por rghCtlStore en CTL_VERIFY_USAGE_PARA . Cuando se reemplaza, el CERT_VERIFY_UPDATED_CTL_FLAG se establece en el miembro dwFlags de pVerifyUsageStatus. Si se establece esta marca, no se realizará una actualización, incluso si se recibe un CTL actualizado válido para un CTL que se encuentra en el almacén y cuyo tiempo ya no es válido.

Si se establece el CERT_VERIFY_TRUSTED_SIGNERS_FLAG, solo se buscan los almacenes del firmante especificados por rghSignerStore en CTL_VERIFY_USAGE_PARA para buscar el firmante. De lo contrario, los almacenes del firmante proporcionan orígenes adicionales para buscar el certificado del firmante. Para obtener más información, vea la sección Comentarios.

Si se establece CERT_VERIFY_NO_TIME_CHECK_FLAG, las CTL no se comprueban para comprobar la validez del tiempo. De lo contrario, son.

Si se establece CERT_VERIFY_ALLOW_MORE_USAGE_FLAG, el CTL puede contener identificadores de uso además de los especificados por pSubjectUsage. De lo contrario, el CTL encontrado no contendrá identificadores de uso adicionales.

[in, optional] pVerifyUsagePara

Puntero a una estructura de CTL_VERIFY_USAGE_PARA que especifica los almacenes que se van a buscar para buscar el CTL y los almacenes que contienen firmantes de CTL aceptables. Establecer el miembro ListIdentifier limita aún más la búsqueda.

[in, out] pVerifyUsageStatus

Puntero a una estructura CTL_VERIFY_USAGE_STATUS . El miembro cbSize de la estructura debe establecerse en el tamaño, en bytes, de la estructura y todos los demás campos deben establecerse en cero antes de llamar a CertVerifyCTLUsage . Para obtener más información, consulte CTL_VERIFY_USAGE_STATUS.

Valor devuelto

Si el sujeto es de confianza para el uso especificado, se devuelve TRUE . De lo contrario, se devuelve FALSE . GetLastError puede devolver uno de los siguientes códigos de error.

Valor	Descripción
CRYPT_E_NO_VERIFY_USAGE_DLL	No se encontró ningún archivo DLL o función exportada para comprobar el uso del sujeto.
CRYPT_E_NO_VERIFY_USAGE_CHECK	La función llamada no pudo realizar una comprobación de uso en el asunto.
CRYPT_E_VERIFY_USAGE_OFFLINE	El servidor estaba sin conexión; por lo tanto, la función llamada no pudo completar la comprobación de uso.
CRYPT_E_NOT_IN_CTL	El asunto no se encontró en un CTL.
CRYPT_E_NO_TRUSTED_SIGNER	No se encontró ningún firmante de confianza para comprobar la firma del mensaje o la lista de confianza.

El miembro dwError del CTL_VERIFY_USAGE_PARA al que apunta pVerifyUsageStatus se establece en el mismo código de error.

Comentarios

CertVerifyCTLUsage es un distribuidor a funciones que se pueden instalar mediante un identificador de objeto (OID). En primer lugar, intenta encontrar una función OID que coincida con el primer identificador de objeto de uso de la estructura CLT_USAGE a la que apunta pSubjectUsage. Si se produce un error, usa las funciones CertDllVerifyCTLUsage predeterminadas.

La función CertDllVerifyCTLUsage de Cryptnet.dll se puede instalar mediante un OID; tiene las siguientes propiedades:

Si rghCtlStore especifica almacenes de CTL en pVerifyUsagePara, solo se busca en esos almacenes para buscar un CTL. De lo contrario, se busca en el almacén del sistema de confianza para buscar un CTL.
Si se establece CERT_VERIFY_TRUSTED_SIGNERS_FLAG, solo se buscan los almacenes del firmante especificados por rghSignerStore en pVerifyUsagePara para buscar el certificado que corresponde al emisor y al número de serie del firmante. De lo contrario, el almacén del mensaje CTL, los almacenes del firmante especificados por rghSignerStore en pVerifyUsagePara, el almacén del sistema de confianza, el almacén del sistema de ca, el almacén del sistema de CA, el almacén del sistema ROOT y los almacenes del certificado del publicador de software (SPC) se buscan para buscar el certificado del firmante. En cualquier caso, la clave pública del certificado encontrado se usa para comprobar la firma del CTL.
Si el CTL tiene un miembro NextUpdate establecido y CERT_VERIFY_NO_TIME_CHECK no está establecido, se comprueba para la validez de la hora.
Si el CTL obtenido del almacén tiene una hora que no es válida, se intenta obtener una versión válida. La función CertDllVerifyCTLUsage usa la propiedad NextUpdateLocation o la extensión NextUpdateLocation del CTL, o busca en la información del firmante un atributo NextUpdateLocation .

Requisitos


Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	wincrypt.h
Library	Crypt32.lib
Archivo DLL	Crypt32.dll