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
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
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
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
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
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
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
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
CERT_CTL_USAGE_PROP_ID
Tipo de datos de
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
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
CERT_PUBKEY_HASH_RESERVED_PROP_ID
Este identificador está reservado.
CERT_PVK_FILE_PROP_ID
Tipo de datos de
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
Devuelve el hash del certificado renovado.
CERT_REQUEST_ORIGINATOR_PROP_ID
Tipo de datos de
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
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
CERT_ROOT_PROGRAM_NAME_CONSTRAINTS_PROP_ID
Este identificador está reservado.
CERT_SHA1_HASH_PROP_ID
Tipo de datos de
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
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
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
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
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
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
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
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
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
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
[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 |