Compartir a través de


Función CertGetCertificateContextProperty (wincrypt.h)

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

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 de 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 va a devolver en pvData se muestran en la tabla siguiente.

CERT_ACCESS_STATE_PROP_ID

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

Devuelve un valor DWORD que indica si se conservan las operaciones de escritura en el certificado. El DWORD valor 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 de BYTE de . El tamaño de esta matriz se especifica en el parámetro pcbData.

Devuelve una clave cifrada guardada previamente hash 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 está asociado 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 de BYTE de . 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 de BYTE de . El tamaño de esta matriz se especifica en el parámetro pcbData.

Deshabilita recuperación de la lista de revocación de certificados (CRL) para los certificados usados por la entidad de certificación de (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 de BYTE de . El tamaño de esta matriz se especifica en el parámetro pcbData.

Contiene la lista de direcciones URL de 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 es el notación de sintaxis abstracta Uno (ASN.1) bytes codificados en 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 de BYTE de . 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 CRL o listas de confianza de certificados (CTL).

La matriz BYTE de contiene una estructura de CROSS_CERT_DIST_POINTS_INFO codificada con 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 de BYTE de . 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 de 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 de BYTE de . 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 de BYTE de . 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 claves (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 de BYTE de . 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 de BYTE de . 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 de BYTE de . 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 de BYTE de . 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 devolverlo. 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 de BYTE de . El tamaño de esta matriz se especifica en el parámetro pcbData.

Hash MD5 de la clave pública de 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 de BYTE de . 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 CERT_KEY_CONTEXT.

CERT_KEY_IDENTIFIER_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores de BYTE de . 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 SubjectPublicKeyInfo del certificado miembro para generar los valores de identificador.

CERT_KEY_PROV_HANDLE_PROP_ID

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

CERT_KEY_SPEC_PROP_ID

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

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 del dwKeySpec.

CERT_MD5_HASH_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores de BYTE de . 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 si procede.

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 devolverlo. 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 de BYTE de . El tamaño de esta matriz se especifica en el parámetro pcbData.

Devuelve la estructura 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 de BYTE de . 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 del bit. 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 compatibilidad con esta propiedad.

CERT_PUBKEY_ALG_PARA_PROP_ID

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

En el caso de las claves públicas que admiten la herencia de parámetros de algoritmo, devuelve los parámetros PublicKey Algorithm codificados por ASN.1. Para estándar de firma digital (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 de BYTE de . 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 de BYTE de . 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 de BYTE de . 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 de BYTE de . 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_ENCODING OR bit a bitPKCS_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 de BYTE de . 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_SHA1_SHA256_HASH_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores de BYTE de . El tamaño de esta matriz es de 52 bytes, 20 bytes para el hash SHA1 y 32 bytes para el hash SHA256.

Devuelve una combinación del hash SHA1 y el hash SHA256. Si el hash no existe, se calcula mediante la función CryptHashCertificate.

CERT_SHA256_HASH_PROP_ID

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

Devuelve el hash SHA256. 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 de <SIGNATURE> identifica el algoritmo de clave pública CNG. Se admiten los algoritmos siguientes:

  • L"RSA" (BCRYPT_RSA_ALGORITHM)
  • L"DSA" (BCRYPT_DSA_ALGORITHM)
  • L"ECDSA" (SSL_ECDSA_ALGORITHM)

El valor de <HASH> identifica el algoritmo hash de CNG. Se admiten los algoritmos siguientes:

  • 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 compatibilidad con esta propiedad.

CERT_SIGNATURE_HASH_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores de BYTE de . 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 de BYTE de . 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 de BYTE de . 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 de BYTE de . 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 de BYTE de . El tamaño de esta matriz se especifica en el parámetro pcbData.

Devuelve un hash MD5 del nombre del firmante 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 de DWORD de .

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

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

CERT_SUBJECT_PUBLIC_KEY_MD5_HASH_PROP_ID

Tipo de datos de pvData: puntero a una matriz de valores de BYTE de . 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 de 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 devueltas 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 se devuelve la función, el valor DWORD contiene el número de bytes que se van a almacenar 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_DATAy 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 de 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.

A continuación se indican 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.

Observaciones

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 los almacenes de usuarios. Todos los demás tipos de propiedades 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

Requisito Valor
cliente mínimo admitido Windows XP [aplicaciones de escritorio | Aplicaciones para UWP]
servidor mínimo admitido Windows Server 2003 [aplicaciones de escritorio | Aplicaciones para UWP]
de la plataforma de destino de Windows
encabezado de wincrypt.h
biblioteca de Crypt32.lib
DLL de Crypt32.dll

Consulte también

CERT_KEY_CONTEXT

CertCreateCertificateContext

CertSetCertificateContextProperty

CryptHashCertificate

CryptHashToBeSigned

funciones de propiedad extendidas