Función CertGetCTLContextProperty (wincrypt.h)

Artículo
03/15/2023

La función CertGetCTLContextProperty recupera una propiedad extendida de un contexto de lista de confianza de certificados (CTL).

Sintaxis

BOOL CertGetCTLContextProperty(
  [in]      PCCTL_CONTEXT pCtlContext,
  [in]      DWORD         dwPropId,
  [out]     void          *pvData,
  [in, out] DWORD         *pcbData
);

Parámetros

[in] pCtlContext

Puntero a la estructura CTL_CONTEXT .

[in] dwPropId

Identifica la propiedad que se va a recuperar. Los identificadores definidos actualmente y el tipo de datos que se devolverán en pvData se enumeran en la tabla siguiente.

Valor	Significado
CERT_ACCESS_STATE_PROP_ID	Tipo de datos para pvData: puntero a un DWORD Devuelve un valor DWORD que indica si se conservan las operaciones de escritura en el certificado. El valor DWORD no se establece si el certificado está en un almacén de memoria o en un almacén basado en el Registro que se abre como de solo lectura.
CERT_ARCHIVED_PROP_ID	Tipo de datos para pvData: NULL Indica que el certificado se omite durante las enumeraciones. Un certificado con este conjunto de propiedades se encuentra con operaciones de búsqueda explícitas, como las usadas para buscar un certificado con un hash específico o un número de serie. No hay datos en pvData asociados a esta propiedad.
CERT_AUTO_ENROLL_PROP_ID	Tipo de datos para pvData: puntero a una matriz BYTE Devuelve una cadena Unicode terminada en null que denomina el tipo de certificado para el que se ha inscrito automáticamente el certificado.
CERT_CTL_USAGE_PROP_ID	Tipo de datos para pvData: puntero a una matriz BYTE Devuelve una matriz de bytes que contiene una estructura de CTL_USAGE codificada en notación de sintaxis abstracta uno (ASN.1).
CERT_DESCRIPTION_PROP_ID	Tipo de datos para pvData: puntero a una matriz BYTE Devuelve la propiedad mostrada por la interfaz de usuario del certificado. Esta propiedad permite al usuario describir el uso del certificado.
CERT_ENHKEY_USAGE_PROP_ID	Tipo de datos para pvData: puntero a una matriz BYTE Devuelve una matriz de bytes que contiene una estructura de CERT_ENHKEY_USAGE codificada en ASN.1.
CERT_FRIENDLY_NAME_PROP_ID	Tipo de datos para pvData: puntero a una matriz BYTE Devuelve una cadena de caracteres Unicode terminada en null que contiene el nombre para mostrar del CTL.
CERT_HASH_PROP_ID	Tipo de datos para pvData: puntero a una matriz BYTE Devuelve el hash SHA1. Si el hash no existe, se calcula mediante CryptHashCertificate.
CERT_KEY_CONTEXT_PROP_ID	Tipo de datos para pvData: puntero a un CERT_KEY_CONTEXT Devuelve una estructura CERT_KEY_CONTEXT .
CERT_KEY_IDENTIFIER_PROP_ID	Tipo de datos para pvData: puntero a una matriz BYTE Si no existe, busca la extensión szOID_SUBJECT_KEY_IDENTIFIER. Si se produce un error, se realiza un hash SHA1 en el miembro SubjectPublicKeyInfo del certificado para generar los valores de identificador.
CERT_KEY_PROV_HANDLE_PROP_ID	Tipo de datos para pvData: puntero a un HCRYPTPROV Devuelve el identificador de proveedor obtenido del CERT_KEY_CONTEXT_PROP_ID.
CERT_KEY_PROV_INFO_PROP_ID	Tipo de datos para pvData: puntero a una estructura de CRYPT_KEY_PROV_INFO Devuelve un puntero a un CRYPT_KEY_PROV_INFO.
CERT_KEY_SPEC_PROP_ID	Tipo de datos para pvData: puntero a un DWORD Devuelve un valor DWORD que especifica la clave privada obtenida de CERT_KEY_CONTEXT_PROP_ID propiedad si existe. De lo contrario, si CERT_KEY_PROV_INFO_PROP_ID existe, es el origen de dwKeySpec.
CERT_MD5_HASH_PROP_ID	Tipo de datos para pvData: puntero a una matriz BYTE Devuelve el hash MD5. Si el hash no existe, se calcula mediante CryptHashCertificate.
CERT_NEXT_UPDATE_LOCATION_PROP_ID	Tipo de datos para pvData: puntero a una matriz BYTE Devuelve la estructura de CERT_ALT_NAME_INFO codificada en ASN.1. CERT_NEXT_UPDATE_LOCATION_PROP_ID solo se usa actualmente con CTL.
CERT_PVK_FILE_PROP_ID	Tipo de datos para pvData: puntero a una matriz BYTE Devuelve una cadena de caracteres anchos Unicode terminada en NULL que especifica el nombre de archivo que contiene la clave privada asociada a la clave pública del certificado.
CERT_SHA1_HASH_PROP_ID	Tipo de datos para pvData: puntero a una matriz BYTE Devuelve el hash SHA1. Si el hash no existe, se calcula mediante CryptHashCertificate.
CERT_SIGNATURE_HASH_PROP_ID	Tipo de datos para pvData: puntero a una matriz BYTE Devuelve el hash de firma. Si el hash no existe, se calcula con CryptHashToBeSigned. La longitud del hash es de 20 bytes para SHA y 16 para MD5.

Para todos los demás identificadores de propiedad, pvData apunta a una matriz de bytes y no a un CRYPT_DATA_BLOB como señala el parámetro pvData en CertSetCertificateContextProperty.

Para obtener más información sobre cada identificador de propiedad, consulte la documentación sobre el parámetro dwPropId en CertSetCertificateContextProperty. CERT_SHA1_HASH_PROP_ID y CERT_NEXT_UPDATE_LOCATION_PROP_ID son las propiedades predefinidas de mayor interés.

[out] pvData

Puntero a un búfer para recibir los datos según lo determinado por dwPropId. Las estructuras a las que apuntan los miembros de una estructura devuelta también se devuelven después de la estructura base. Por lo tanto, el tamaño contenido en pcbData suele superar el tamaño de la estructura base.

Este parámetro puede ser NULL para establecer el tamaño de la información con fines de asignación de memoria. Para obtener más información, vea Recuperación de datos de longitud desconocida.

[in, out] pcbData

Puntero a un valor DWORD que especifica el tamaño, en bytes, del búfer al que apunta el parámetro pvData . Cuando la función devuelve, el valor DWORD contiene el número de bytes que se almacenarán en el búfer.

Nota Al procesar los datos devueltos en el búfer, las aplicaciones deben usar el tamaño real de los datos devueltos. El tamaño real puede ser ligeramente menor que el tamaño del búfer especificado en la entrada. (En la entrada, los tamaños del búfer suelen especificarse lo suficientemente grandes como para asegurarse de que los datos de salida más grandes posibles se ajusten al búfer). En la salida, la variable a la que apunta este parámetro se actualiza para reflejar el tamaño real de los datos copiados en el búfer.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es TRUE.

Si se produce un error en la función, el valor devuelto es FALSE.

Los errores de la función llamada , CryptHashCertificate, se pueden propagar a esta función. Para obtener información de error extendida, llame a GetLastError.

A continuación se indican algunos códigos de error posibles.

Código devuelto	Descripción
CRYPT_E_NOT_FOUND	El CTL no tiene la propiedad especificada.
ERROR_MORE_DATA	Si el búfer especificado por el parámetro pvData no es lo suficientemente grande como para contener los datos devueltos, la función establece el código ERROR_MORE_DATA y almacena el tamaño de búfer necesario, en bytes, en la variable a la que apunta pcbData.

Requisitos

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

Consulte también

CertEnumCTLContextProperties

CertGetCertificateContextProperty

CertSetCTLContextProperty

CryptHashCertificate

Funciones de propiedad extendidas