Compartir a través de


Función CryptSetProvParam (wincrypt.h)

Importante Esta API está en desuso. El software nuevo y existente debe empezar a usar las API cryptography Next Generation. Microsoft puede quitar esta API en futuras versiones.
 
La función CryptSetProvParam personaliza las operaciones de un proveedor de servicios criptográficos (CSP). Esta función se usa normalmente para establecer un descriptor de seguridad en el contenedor de claves asociado a un CSP para controlar el acceso a las claves privadas de ese contenedor de claves.

Sintaxis

BOOL CryptSetProvParam(
  [in] HCRYPTPROV hProv,
  [in] DWORD      dwParam,
  [in] const BYTE *pbData,
  [in] DWORD      dwFlags
);

Parámetros

[in] hProv

Identificador de un CSP para el que se van a establecer valores. Este identificador ya debe haberse creado mediante la función CryptAcquireContext .

[in] dwParam

Especifica el parámetro que se va a establecer. Puede ser uno de los valores siguientes.

Valor Significado
PP_CLIENT_HWND
1 (0x1)
Establezca el identificador de ventana que el proveedor usa como elemento primario de cualquier cuadro de diálogo que cree. pbData contiene un puntero a un HWND que contiene el identificador de la ventana primaria.

Este parámetro debe establecerse antes de llamar a CryptAcquireContext porque muchos CSP mostrarán una interfaz de usuario cuando se llame a CryptAcquireContext . Puede pasar NULL para el parámetro hProv para establecer este identificador de ventana para todos los contextos criptográficos adquiridos posteriormente en este proceso.

PP_DELETEKEY
24 (0x18)
Elimine la clave efímera asociada a un contexto de hash, cifrado o comprobación. Esto liberará la memoria y borrará la configuración del Registro asociada a la clave.
PP_KEYEXCHANGE_ALG
Esta constante no se usa.
PP_KEYEXCHANGE_PIN
32 (0x20)
Especifica que el PIN de intercambio de claves se encuentra en pbData. El PIN se representa como una cadena ASCII terminada en null.
PP_KEYEXCHANGE_KEYSIZE
Esta constante no se usa.
PP_KEYSET_SEC_DESCR
8 (0x8)
Establece el descriptor de seguridad en el contenedor de almacenamiento de claves. El parámetro pbData es la dirección de una estructura de SECURITY_DESCRIPTOR que contiene el nuevo descriptor de seguridad para el contenedor de almacenamiento de claves.
PP_PIN_PROMPT_STRING
44 (0x2C)
Establece una cadena de solicitud alternativa que se mostrará al usuario cuando se solicite el PIN del usuario. El parámetro pbData es un puntero a una cadena Unicode terminada en null.
PP_ROOT_CERTSTORE
46 (0x2E)
Establece el almacén de certificados raíz de la tarjeta inteligente. El proveedor copiará los certificados raíz de este almacén en la tarjeta inteligente.

El parámetro pbData es una variable HCERTSTORE que contiene el identificador del nuevo almacén de certificados. El proveedor copiará los certificados del almacén durante esta llamada, por lo que es seguro cerrar este almacén después de llamar a esta función.

Windows XP y Windows Server 2003: Este parámetro no se admite.

PP_SIGNATURE_ALG
Esta constante no se usa.
PP_SIGNATURE_PIN
33 (0x21)
Especifica el PIN de firma. El parámetro pbData es una cadena ASCII terminada en null que representa el PIN.
PP_SIGNATURE_KEYSIZE
Esta constante no se usa.
PP_UI_PROMPT
21 (0x15)
Para un proveedor de tarjetas inteligentes, establece la cadena de búsqueda que se muestra al usuario como una solicitud para insertar la tarjeta inteligente. Esta cadena se pasa como el miembro lpstrSearchDesc de la estructura OPENCARDNAME_EX que se pasa a la función SCardUIDlgSelectCard . Esta cadena se usa durante la vigencia del proceso de llamada.

El parámetro pbData es un puntero a una cadena Unicode terminada en null.

PP_USE_HARDWARE_RNG
38 (0x26)
Especifica que el CSP debe usar exclusivamente el generador de números aleatorios de hardware (RNG). Cuando se establece PP_USE_HARDWARE_RNG , los valores aleatorios se toman exclusivamente del RNG de hardware y no se usan otros orígenes. Si el CSP admite un RNG de hardware y se puede usar exclusivamente, la función se realiza correctamente y devuelve TRUE; de lo contrario, se produce un error en la función y devuelve FALSE. El parámetro pbData debe ser NULL y dwFlags debe ser cero al usar este valor.

Ninguno de los CSP de Microsoft admite actualmente el uso de un RNG de hardware.

PP_USER_CERTSTORE
42 (0x2A)
Especifica el almacén de certificados de usuario para la tarjeta inteligente. Este almacén de certificados contiene todos los certificados de usuario almacenados en la tarjeta inteligente. Los certificados de este almacén se codifican mediante PKCS_7_ASN_ENCODING o X509_ASN_ENCODING codificación y deben contener la propiedad CERT_KEY_PROV_INFO_PROP_ID .

El parámetro pbData es una variable HCERTSTORE que recibe el identificador de un almacén de certificados en memoria. Cuando este identificador ya no es necesario, el autor de la llamada debe cerrarlo mediante la función CertCloseStore .

Windows Server 2003 y Windows XP: Este parámetro no se admite.

PP_SECURE_KEYEXCHANGE_PIN
47 (0x2F)
Especifica que un PIN de intercambio de claves cifrado se encuentra en pbData. El parámetro pbData contiene un DATA_BLOB.
PP_SECURE_SIGNATURE_PIN
48 (0x30)
Especifica que un PIN de firma cifrada se encuentra en pbData. El parámetro pbData contiene un DATA_BLOB.
PP_SMARTCARD_READER
43 (0x2B)
Especifica el nombre del lector de tarjetas inteligentes. El parámetro pbData es la dirección de una matriz de caracteres ANSI que contiene una cadena ANSI terminada en null que contiene el nombre del lector de tarjetas inteligentes.

Windows Server 2003 y Windows XP: Este parámetro no se admite.

PP_SMARTCARD_GUID
45 (0x2D)
Especifica el identificador de la tarjeta inteligente. El parámetro pbData es la dirección de una estructura GUID que contiene el identificador de la tarjeta inteligente.

Windows Server 2003 y Windows XP: Este parámetro no se admite.

[in] pbData

Puntero a un búfer de datos que contiene el valor que se va a establecer como parámetro de proveedor. El formato de estos datos varía en función del valor dwParam . Si dwParam contiene PP_USE_HARDWARE_RNG, este parámetro debe ser NULL.

[in] dwFlags

Si dwParam contiene PP_KEYSET_SEC_DESCR, dwFlags contiene las marcas de bits aplicables SECURITY_INFORMATION , tal y como se define en el SDK de plataforma. La seguridad del contenedor de claves se controla mediante SetFileSecurity y GetFileSecurity.

Estas marcas de bits se pueden combinar mediante una operación OR bit a bit. Para obtener más información, vea CryptGetProvParam.

Si dwParam es PP_USE_HARDWARE_RNG o PP_DELETEKEY, dwFlags debe establecerse en cero.

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.

Los códigos de error precedidos por "NTE" se generan mediante el CSP en particular que se usa. Los códigos de error incluyen lo siguiente.

Código devuelto Descripción
ERROR_BUSY
Otro proceso está usando el contexto de CSP.
ERROR_INVALID_HANDLE
Uno de los parámetros especifica un identificador que no es válido.
ERROR_INVALID_PARAMETER
Uno de los parámetros contiene un valor que no es válido. Suele ser un puntero que no es válido.
NTE_BAD_FLAGS
El parámetro dwFlags es distinto de cero o el búfer pbData contiene un valor que no es válido.
NTE_BAD_TYPE
El parámetro dwParam especifica un parámetro desconocido.
NTE_BAD_UID
No se encuentra el contexto de CSP que se especificó cuando no se creó la clave hKey .
NTE_FAIL
Error en la función de alguna manera inesperada.

Requisitos

Requisito Value
Cliente mínimo compatible Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado wincrypt.h
Library Advapi32.lib
Archivo DLL Advapi32.dll

Consulte también

CryptAcquireContext

CryptGetProvParam

CryptSetKeyParam

Funciones del proveedor de servicios