Función CryptAcquireCertificatePrivateKey (wincrypt.h)

  • Artículo

La función CryptAcquireCertificatePrivateKey obtiene la clave privada de un certificado. Esta función se usa para obtener acceso a la clave privada de un usuario cuando el certificado del usuario está disponible, pero el identificador del contenedor de claves del usuario no está disponible. Esta función solo puede ser utilizada por el propietario de una clave privada y no por ningún otro usuario.

Si hay disponible un identificador csp y el contenedor de claves que contiene la clave privada de un usuario, se debe usar la función CryptGetUserKey en su lugar.

Sintaxis

BOOL CryptAcquireCertificatePrivateKey(
  [in]           PCCERT_CONTEXT                  pCert,
  [in]           DWORD                           dwFlags,
  [in, optional] void                            *pvParameters,
  [out]          HCRYPTPROV_OR_NCRYPT_KEY_HANDLE *phCryptProvOrNCryptKey,
  [out]          DWORD                           *pdwKeySpec,
  [out]          BOOL                            *pfCallerFreeProvOrNCryptKey
);

Parámetros

[in] pCert

Dirección de una estructura de CERT_CONTEXT que contiene el contexto de certificado para el que se obtendrá una clave privada.

[in] dwFlags

Conjunto de marcas que modifican el comportamiento de esta función. Puede ser cero o una combinación de uno o varios de los valores siguientes.

Value Significado
CRYPT_ACQUIRE_CACHE_FLAG
 Si ya se ha adquirido y almacenado en caché un identificador, se devuelve ese mismo identificador. De lo contrario, se adquiere y almacena en caché un nuevo identificador mediante la propiedad CERT_KEY_CONTEXT_PROP_ID del certificado.

Cuando se establece esta marca, el parámetro pfCallerFreeProvOrNCryptKey recibe FALSE y la aplicación que realiza la llamada no debe liberar el identificador. El identificador se libera cuando se libera el contexto del certificado; Sin embargo, debe conservar el contexto del certificado al que hace referencia el parámetro pCert siempre que la clave esté en uso; de lo contrario, se producirá un error en las operaciones que se basan en la clave.
CRYPT_ACQUIRE_COMPARE_KEY_FLAG
 La clave pública del certificado se compara con la clave pública devuelta por el proveedor de servicios criptográficos (CSP). Si las claves no coinciden, se produce un error en la operación de adquisición y el último código de error se establece en NTE_BAD_PUBLIC_KEY. Si se devuelve un identificador almacenado en caché, no se realiza ninguna comparación.
CRYPT_ACQUIRE_NO_HEALING
 Esta función no intentará volver a crear la propiedad CERT_KEY_PROV_INFO_PROP_ID en el contexto del certificado si no se puede recuperar esta propiedad.
CRYPT_ACQUIRE_SILENT_FLAG
 El CSP no debe mostrar ninguna interfaz de usuario (UI) para este contexto. Si el CSP debe mostrar la interfaz de usuario para funcionar, se produce un error en la llamada y el código de error del NTE_SILENT_CONTEXT se establece como el último error.
CRYPT_ACQUIRE_USE_PROV_INFO_FLAG
 Usa la propiedad CERT_KEY_PROV_INFO_PROP_ID del certificado para determinar si se debe realizar el almacenamiento en caché. Para obtener más información sobre la propiedad CERT_KEY_PROV_INFO_PROP_ID , vea CertSetCertificateContextProperty.

Esta función solo usará el almacenamiento en caché si durante una llamada anterior, el miembro dwFlags de la estructura CRYPT_KEY_PROV_INFO incluida CERT_SET_KEY_CONTEXT_PROP.
CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG
 Cualquier interfaz de usuario que necesite csp o KSP será un elemento secundario del HWND que se proporciona en el parámetro pvParameters . En el caso de una clave CSP, el uso de esta marca hará que se llame a la función CryptSetProvParam con la marca PP_CLIENT_HWND mediante este HWND con NULL para HCRYPTPROV. Para una clave KSP, el uso de esta marca hará que se llame a la función NCryptSetProperty con la marca NCRYPT_WINDOW_HANDLE_PROPERTY mediante el HWND.

No use esta marca con CRYPT_ACQUIRE_SILENT_FLAG.
 

Las marcas siguientes determinan qué tecnología se usa para obtener la clave. Si ninguna de estas marcas está presente, esta función solo intentará obtener la clave mediante CryptoAPI.

Windows Server 2003 y Windows XP: No se admiten estas marcas.

Value Significado
CRYPT_ACQUIRE_ALLOW_NCRYPT_KEY_FLAG
 Esta función intentará obtener la clave mediante CryptoAPI. Si se produce un error, esta función intentará obtener la clave mediante cryptography API: Next Generation (CNG).

La variable pdwKeySpec recibe la marca CERT_NCRYPT_KEY_SPEC si se usa CNG para obtener la clave.
CRYPT_ACQUIRE_ONLY_NCRYPT_KEY_FLAG
Esta función solo intentará obtener la clave mediante CNG y no usará CryptoAPI para obtener la clave.

La variable pdwKeySpec recibe la marca CERT_NCRYPT_KEY_SPEC si se usa CNG para obtener la clave.
CRYPT_ACQUIRE_PREFER_NCRYPT_KEY_FLAG
 Esta función intentará obtener la clave mediante CNG. Si se produce un error, esta función intentará obtener la clave mediante CryptoAPI.

La variable pdwKeySpec recibe la marca CERT_NCRYPT_KEY_SPEC si se usa CNG para obtener la clave.

Nota CryptoAPI no admite el Diffie-Hellman CNG ni los algoritmos asimétricos DSA. CryptoAPI solo admite claves públicas Diffie-Hellman y DSA a través de los CSP heredados. Si se establece esta marca para un certificado que contiene una clave pública de Diffie-Hellman o DSA, esta función cambiará implícitamente esta marca a CRYPT_ACQUIRE_ALLOW_NCRYPT_KEY_FLAG para intentar primero usar CryptoAPI para obtener la clave.
 

[in, optional] pvParameters

Si se establece el CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG , esta es la dirección de un HWND. Si no se establece el CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG , este parámetro debe ser NULL.

Windows Server 2008 R2, Windows 7, Windows Server 2008, Windows Vista, Windows Server 2003 y Windows XP: Este parámetro se llamó pvReserved y se reservó para su uso futuro y debe ser NULL.

[out] phCryptProvOrNCryptKey

Dirección de una variable de HCRYPTPROV_OR_NCRYPT_KEY_HANDLE que recibe el identificador del proveedor CryptoAPI o de la clave CNG. Si la variable pdwKeySpec recibe la marca CERT_NCRYPT_KEY_SPEC , se trata de un identificador de clave CNG de tipo NCRYPT_KEY_HANDLE; de lo contrario, se trata de un identificador de proveedor CryptoAPI de tipo HCRYPTPROV.

Para obtener más información sobre cuándo y cómo liberar este identificador, vea la descripción del parámetro pfCallerFreeProvOrNCryptKey .

[out] pdwKeySpec

Dirección de una variable DWORD que recibe información adicional sobre la clave. Puede ser uno de los siguientes valores.

Value Significado
AT_KEYEXCHANGE
 El par de claves es un par de intercambio de claves.
AT_SIGNATURE
 El par de claves es un par de firmas.
CERT_NCRYPT_KEY_SPEC
 La clave es una clave CNG.

Windows Server 2003 y Windows XP: Este valor no se admite.

[out] pfCallerFreeProvOrNCryptKey

Dirección de una variable BOOL que recibe un valor que indica si el autor de la llamada debe liberar el identificador devuelto en la variable phCryptProvOrNCryptKey . Esto recibe FALSE si se cumple alguna de las siguientes condiciones:

  • Se produce un error en la adquisición o comparación de claves públicas.
  • El parámetro dwFlags contiene la marca CRYPT_ACQUIRE_CACHE_FLAG .
  • El parámetro dwFlags contiene la marca CRYPT_ACQUIRE_USE_PROV_INFO_FLAG , la propiedad de contexto del certificado se establece en CERT_KEY_PROV_INFO_PROP_ID con la estructura CRYPT_KEY_PROV_INFO y el miembro dwFlags de la estructura CRYPT_KEY_PROV_INFO se establece en CERT_SET_KEY_CONTEXT_PROP_ID.
Si esta variable recibe FALSE, la aplicación que realiza la llamada no debe liberar el identificador devuelto en la variable phCryptProvOrNCryptKey . El identificador se liberará en la última acción libre del contexto del certificado.

Si esta variable recibe TRUE, el autor de la llamada es responsable de liberar el identificador devuelto en la variable phCryptProvOrNCryptKey . Si la variable pdwKeySpec recibe el valor de CERT_NCRYPT_KEY_SPEC , el identificador se debe liberar pasando a la función NCryptFreeObject ; de lo contrario, el identificador se libera pasando a la función CryptReleaseContext .

Valor devuelto

Si la función se ejecuta correctamente, el valor devuelto es distinto de cero (TRUE).

Si se produce un error en la función, el valor devuelto es cero (FALSE). Para obtener información de error extendida, llame a GetLastError. Un posible código de error es el siguiente.

Código devuelto Descripción
NTE_BAD_PUBLIC_KEY
 La clave pública del certificado no coincide con la clave pública devuelta por el CSP. Este código de error se devuelve si se establece el CRYPT_ACQUIRE_COMPARE_KEY_FLAG y la clave pública del certificado no coincide con la clave pública devuelta por el proveedor criptográfico.
NTE_SILENT_CONTEXT
 El parámetro dwFlags contenía la marca CRYPT_ACQUIRE_SILENT_FLAG y el CSP no pudo continuar una operación sin mostrar una interfaz de usuario.

Comentarios

Cuando se establece CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG , el autor de la llamada debe asegurarse de que HWND es válido. Si el HWND ya no es válido, para CSP, el autor de la llamada debe llamar a CryptSetProvParam mediante la marca PP_CLIENT_HWND con NULL para HWND y NULL para HCRYPTPROV. Para KSP, el autor de la llamada debe establecer el NCRYPT_WINDOW_HANDLE_PROPERTY de la clave ncrypt como NULL. Cuando se establece CRYPT_ACQUIRE_WINDOW_HANDLE_FLAG marca para KSP, el NCRYPT_WINDOW_HANDLE_PROPERTY se establece en el proveedor de almacenamiento y la clave. Si se produce un error en ambas llamadas, se produce un error en la función. Si solo se produce un error, la función se realiza correctamente. Tenga en cuenta que al establecer HWND en NULL , se quita HWND de la clave HCRYPTPROV o ncrypt.

Ejemplos

Para obtener un ejemplo que usa esta función, vea Ejemplo de programa C: Envío y recepción de un mensaje firmado y cifrado.

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

CRYPT_KEY_PROV_INFO

CertSetCertificateContextProperty

CryptReleaseContext

Generación de claves y funciones de Exchange