Función CryptAcquireCertificatePrivateKey (wincrypt.h)
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 |
|---|---|
|
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. |
|
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. |
|
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. |
|
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. |
|
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. |
|
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.
[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.
[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 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 |
|---|---|
|
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. |
|
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 |