Función CertGetCertificateContextProperty (wincrypt.h)

La función CertGetCertificateContextProperty recupera la información contenida en una propiedad extendida de un contexto de certificado.

Sintaxis

BOOL CertGetCertificateContextProperty(
  [in]      PCCERT_CONTEXT pCertContext,
  [in]      DWORD          dwPropId,
  [out]     void           *pvData,
  [in, out] DWORD          *pcbData
);

Parámetros

[in] pCertContext

Puntero a la estructura CERT_CONTEXT del certificado que contiene la propiedad que se va a recuperar.

[in] dwPropId

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.

CERT_ACCESS_STATE_PROP_ID

Tipo de datos de pvData: puntero a un valor 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_AIA_URL_RETRIEVED_PROP_ID

Este identificador está reservado.

CERT_ARCHIVED_KEY_HASH_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Devuelve un hash de clave cifrada guardado previamente para el contexto del certificado.

CERT_ARCHIVED_PROP_ID

Tipo de datos de pvData: NULL. Si la función CertGetCertificateContextProperty devuelve true, el identificador de propiedad especificado existe para el CERT_CONTEXT.

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_AUTHORITY_INFO_ACCESS_PROP_ID

Este identificador está reservado.

CERT_AUTO_ENROLL_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Devuelve una cadena Unicode terminada en null que asigna un nombre al tipo de certificado para el que se ha inscrito automáticamente el certificado.

CERT_AUTO_ENROLL_RETRY_PROP_ID

Este identificador está reservado.

CERT_BACKED_UP_PROP_ID

Este identificador está reservado.

CERT_CA_DISABLE_CRL_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Deshabilita la recuperación de la lista de revocación de certificados (CRL) para los certificados usados por la entidad de certificación (CA). Si el certificado de entidad de certificación contiene esta propiedad, también debe incluir la propiedad CERT_CA_OCSP_AUTHORITY_INFO_ACCESS_PROP_ID .

CERT_CA_OCSP_AUTHORITY_INFO_ACCESS_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Contiene la lista de direcciones URL del protocolo de estado de certificado en línea (OCSP) que se van a usar para los certificados emitidos por el certificado de entidad de certificación. El contenido de la matriz son los bytes codificados en notación de sintaxis abstracta uno (ASN.1) de una estructura de X509_AUTHORITY_INFO_ACCESS donde pszAccessMethod se establece en szOID_PKIX_OCSP.

CERT_CROSS_CERT_DIST_POINTS_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Ubicación de los certificados cruzados. Actualmente, este identificador solo es aplicable a los certificados y no a las LISTAS de confianza de certificados (CTL).

La matriz BYTE contiene una estructura de CROSS_CERT_DIST_POINTS_INFO codificada por ASN.1 mediante la función CryptDecodeObject con un valor de X509_CROSS_CERT_DIST_POINTS para el parámetro lpszStuctType .

CERT_CTL_USAGE_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Devuelve una matriz de bytes que contienen una estructura de CTL_USAGE codificada en ASN.1.

CERT_DATE_STAMP_PROP_ID

Tipo de datos de pvData: puntero a una estructura FILETIME .

Hora a la que se agregó el certificado al almacén.

CERT_DESCRIPTION_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Devuelve la propiedad mostrada por la interfaz de usuario del certificado. Esta propiedad permite al usuario describir el uso del certificado.

CERT_EFS_PROP_ID

Este identificador está reservado.

CERT_ENHKEY_USAGE_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Devuelve una matriz de bytes que contienen una estructura de CERT_ENHKEY_USAGE codificada en ASN.1. Esta estructura contiene una matriz de identificadores de objeto de uso mejorado de clave (OID), cada uno de los cuales especifica un uso válido del certificado.

CERT_ENROLLMENT_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Información de inscripción de la solicitud pendiente que contiene RequestID, CADNSName, CAName y DisplayName. El formato de datos se define de la siguiente manera.

Bytes Contenido
Primeros 4 bytes Identificador de solicitud pendiente
4 bytes siguientes Tamaño de CADNSName, en caracteres, incluido el carácter nulo de terminación, seguido de la cadena CADNSName con carácter NULO de terminación
4 bytes siguientes Tamaño de CAName, en caracteres, incluido el carácter nulo de terminación, seguido de la cadena CAName con carácter nulo de terminación
4 bytes siguientes Tamaño de DisplayName, en caracteres, incluido el carácter nulo de terminación, seguido de la cadena DisplayName con carácter nulo de terminación
 

CERT_EXTENDED_ERROR_INFO_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Devuelve una cadena de caracteres Unicode terminada en null que contiene información de error extendida para el contexto del certificado.

CERT_FORTEZZA_DATA_PROP_ID

Este identificador está reservado.

CERT_FRIENDLY_NAME_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Devuelve una cadena de caracteres Unicode terminada en null que contiene el nombre para mostrar del certificado.

CERT_HASH_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Devuelve el hash SHA1. Si el hash no existe, se calcula mediante la función CryptHashCertificate .

CERT_HCRYPTPROV_OR_NCRYPT_KEY_HANDLE_PROP_ID

Tipo de datos de pvData: puntero a un tipo de datos HCRYPTPROV_OR_NCRYPT_KEY_HANDLE .

Devuelve el HCRYPTPROV o NCRYPT_KEY_HANDLE opción.

CERT_HCRYPTPROV_TRANSFER_PROP_ID

Devuelve el identificador de clave de Cryptography API (CAPI) asociado al certificado. El autor de la llamada es responsable de liberar el identificador. No se liberará cuando se libere el contexto. El valor de la propiedad se quita después de que se devuelva. Si llama a esta propiedad en un contexto que tiene una clave CNG, se devuelve CRYPT_E_NOT_FOUND .

CERT_IE30_RESERVED_PROP_ID

Este identificador está reservado.

CERT_ISSUER_PUBLIC_KEY_MD5_HASH_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Hash MD5 de la clave pública asociada a la clave privada usada para firmar este certificado.

CERT_ISSUER_SERIAL_NUMBER_MD5_HASH_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Hash MD5 del nombre del emisor y el número de serie de este certificado.

CERT_KEY_CONTEXT_PROP_ID

Tipo de datos de pvData: puntero a una estructura de CERT_KEY_CONTEXT .

Devuelve una estructura de CERT_KEY_CONTEXT .

CERT_KEY_IDENTIFIER_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

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 de pvData: puntero a un valor HCRYPTPROV .

Devuelve el identificador de proveedor obtenido de CERT_KEY_CONTEXT_PROP_ID.

CERT_KEY_PROV_INFO_PROP_ID

Tipo de datos de pvData: puntero a una estructura de CRYPT_KEY_PROV_INFO .

Devuelve un puntero a una estructura de CRYPT_KEY_PROV_INFO .

CERT_KEY_SPEC_PROP_ID

Tipo de datos de pvData: puntero a un valor DWORD .

Devuelve un valor DWORD que especifica la clave privada obtenida de CERT_KEY_CONTEXT_PROP_ID 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 de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Devuelve el hash MD5. Si el hash no existe, se calcula mediante la función CryptHashCertificate .

CERT_NCRYPT_KEY_HANDLE_PROP_ID

Tipo de datos de pvData: puntero a un tipo de datos NCRYPT_KEY_HANDLE .

Devuelve una opción de CERT_NCRYPT_KEY_SPEC cuando corresponda.

CERT_NCRYPT_KEY_HANDLE_TRANSFER_PROP_ID

Devuelve el identificador de clave CNG asociado al certificado. El autor de la llamada es responsable de liberar el identificador. No se liberará cuando se libere el contexto. El valor de la propiedad se quita después de que se devuelva. Si llama a esta propiedad en un contexto que tiene una clave heredada (CAPI), se devuelve CRYPT_E_NOT_FOUND .

CERT_NEW_KEY_PROP_ID

Este identificador está reservado.

CERT_NEXT_UPDATE_LOCATION_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

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_NO_AUTO_EXPIRE_CHECK_PROP_ID

Este identificador está reservado.

CERT_OCSP_CACHE_PREFIX_PROP_ID

Este identificador está reservado.

CERT_OCSP_RESPONSE_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Devuelve una respuesta OCSP codificada para este certificado.

CERT_PUB_KEY_CNG_ALG_BIT_LENGTH_PROP_ID

Tipo de datos de pvData: puntero a una cadena Unicode terminada en null.

Devuelve una cadena L"<PUBKEY>/<BITLENGTH>" que representa el algoritmo de clave pública del certificado y la longitud de bits. Se admiten los siguientes <algoritmos PUBKEY> :

  • L"RSA" (BCRYPT_RSA_ALGORITHM)
  • L"DSA" (BCRYPT_DSA_ALGORITHM)
  • L"ECDSA" (SSL_ECDSA_ALGORITHM)
Windows 8 y Windows Server 2012: comienza la compatibilidad con esta propiedad.

CERT_PUBKEY_ALG_PARA_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Para las claves públicas que admiten la herencia de parámetros de algoritmo, devuelve los parámetros PublicKey Algorithm codificados por ASN.1. Para Digital Signature Standard (DSS), devuelve los parámetros codificados mediante la función CryptEncodeObject . Esta propiedad solo se usa si se define CMS_PKCS7.

CERT_PUBKEY_HASH_RESERVED_PROP_ID

Este identificador está reservado.

CERT_PVK_FILE_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Devuelve una cadena de caracteres anchos Unicode terminada en NULL que contiene el nombre de archivo que contiene la clave privada asociada a la clave pública del certificado.

CERT_RENEWAL_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Devuelve el hash del certificado renovado.

CERT_REQUEST_ORIGINATOR_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Devuelve una cadena Unicode terminada en null que contiene el nombre del equipo DNS para la originación de la solicitud de contexto del certificado.

CERT_ROOT_PROGRAM_CERT_POLICIES_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Devuelve un puntero a una estructura de CERT_POLICIES_INFO codificada que contiene las directivas de aplicación del certificado raíz para el contexto. Esta propiedad se puede descodificar mediante la función CryptDecodeObject con el parámetro lpszStructType establecido en X509_CERT_POLICIES y el parámetro dwCertEncodingType establecido en una combinación de X509_ASN_ENCODINGor orbit a bit PKCS_7_ASN_ENCODING.

CERT_ROOT_PROGRAM_NAME_CONSTRAINTS_PROP_ID

Este identificador está reservado.

CERT_SHA1_HASH_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Devuelve el hash SHA1. Si el hash no existe, se calcula mediante la función CryptHashCertificate .

CERT_SIGN_HASH_CNG_ALG_PROP_ID

Tipo de datos de pvData: puntero a una cadena Unicode terminada en null.

Devuelve la cadena L"<SIGNATURE>/<HASH>" que representa la firma del certificado. El <valor SIGNATURE> identifica el algoritmo de clave pública CNG. Se admiten los siguientes algoritmos:

  • L"RSA" (BCRYPT_RSA_ALGORITHM)
  • L"DSA" (BCRYPT_DSA_ALGORITHM)
  • L"ECDSA" (SSL_ECDSA_ALGORITHM)
El <valor HASH> identifica el algoritmo hash CNG. Se admiten los siguientes algoritmos:
  • L"MD5" (BCRYPT_MD5_ALGORITHM)
  • L"SHA1" (BCRYPT_SHA1_ALGORITHM)
  • L"SHA256" (BCRYPT_SHA256_ALGORITHM)
  • L"SHA384" (BCRYPT_SHA384_ALGORITHM)
  • L"SHA512" (BCRYPT_SHA512_ALGORITHM)
A continuación se muestran ejemplos comunes:
  • L"RSA/SHA1"
  • L"RSA/SHA256"
  • L"ECDSA/SHA256"
Windows 7 y Windows Server 2008 R2: Comienza la compatibilidad con esta propiedad.

CERT_SIGNATURE_HASH_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Devuelve el hash de firma. Si el hash no existe, se calcula mediante la función CryptHashToBeSigned . La longitud del hash es de 20 bytes para SHA y 16 para MD5.

CERT_SMART_CARD_DATA_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Devuelve un puntero a los datos de tarjeta inteligente codificados. Antes de llamar a CertGetCertificateContextProperty, puede usar esta constante para recuperar un certificado de tarjeta inteligente mediante la función CertFindCertificateInStore con el parámetro pvFindPara establecido en CERT_SMART_CARD_DATA_PROP_ID y el parámetro dwFindType establecido en CERT_FIND_PROPERTY.

CERT_SMART_CARD_ROOT_INFO_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Devuelve un puntero a una estructura de CRYPT_SMART_CARD_ROOT_INFO codificada.

CERT_SOURCE_LOCATION_PROP_ID

Este identificador está reservado.

CERT_SOURCE_URL_PROP_ID

Este identificador está reservado.

CERT_SUBJECT_DISABLE_CRL_PROP_ID

Este identificador está reservado.

CERT_SUBJECT_INFO_ACCESS_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Devuelve la extensión de acceso a la información del firmante del contexto del certificado como una estructura de CERT_SUBJECT_INFO_ACCESS codificada.

CERT_SUBJECT_NAME_MD5_HASH_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Devuelve un hash MD5 del nombre de sujeto codificado del contexto del certificado.

CERT_SUBJECT_OCSP_AUTHORITY_INFO_ACCESS_PROP_ID

Este identificador está reservado.

CERT_SUBJECT_PUB_KEY_BIT_LENGTH_PROP_ID

Tipo de datos de pvData: puntero a un valor DWORD .

Devuelve la longitud, en bits, de la clave pública del certificado.

Windows 8 y Windows Server 2012: comienza la compatibilidad con esta propiedad.

CERT_SUBJECT_PUBLIC_KEY_MD5_HASH_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores BYTE . El tamaño de esta matriz se especifica en el parámetro pcbData .

Devuelve el hash MD5 de la clave pública de este certificado.

Para todos los identificadores de propiedad definidos por el usuario, pvData apunta a una matriz de valores BYTE .

Para obtener más información sobre cada identificador de propiedad, consulte la documentación sobre el parámetro dwPropId en CertSetCertificateContextProperty.

[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 Recuperar 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.

Para obtener el tamaño necesario de un búfer en tiempo de ejecución, pase NULL para el parámetro pvData y establezca el valor al que apunta este parámetro en cero. Si el parámetro pvData no es NULL y el tamaño especificado en pcbData es menor que el número de bytes necesarios para contener los datos, se produce un error en la función, GetLastError devuelve ERROR_MORE_DATA y el tamaño necesario se coloca en la variable a la que apunta el parámetro pcbData .

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 ejecuta correctamente, la función devuelve TRUE.

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

Siguen algunos códigos de error posibles.

Código devuelto Descripción
CRYPT_E_NOT_FOUND
El certificado 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.
 

Los errores de la función llamada CryptHashCertificate se pueden propagar a esta función.

Comentarios

Las propiedades no se almacenan dentro de un certificado. Normalmente, se asocian a un certificado después de recibir la respuesta del certificado y, a continuación, se guardan con el certificado en el almacén. Por motivos de seguridad, se recomienda validar los valores de propiedad antes de guardarlos y guardar solo propiedades informativas, como el valor de CERT_FRIENDLY_NAME_PROP_ID en almacenes de usuarios. Todos los demás tipos de propiedad deben guardarse en almacenes de equipos locales.

El código puede usar una macro para evaluar la clase de hash de un contexto de certificado. Para obtener más información, vea CertSetCertificateContextProperty.

Ejemplos

Para obtener ejemplos que usan esta función, vea Programa C de ejemplo: Obtener y establecer propiedades de certificado y Programa C de ejemplo: Enumerar los certificados en un almacén.

Requisitos

   
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

CERT_KEY_CONTEXT

CertCreateCertificateContext

CertSetCertificateContextProperty

CryptHashCertificate

CryptHashToBeSigned

Funciones de propiedad extendidas