Función CryptSetKeyParam (wincrypt.h)

Artículo
08/27/2023

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 CryptSetKeyParam personaliza varios aspectos de las operaciones de una clave de sesión. Los valores establecidos por esta función no se conservan en la memoria y solo se pueden usar con en una sola sesión.

El proveedor criptográfico base de Microsoft no permite establecer valores para el intercambio de claves ni las claves de firma; Sin embargo, los proveedores personalizados pueden definir valores que se pueden establecer para sus claves.

Sintaxis

BOOL CryptSetKeyParam(
  [in] HCRYPTKEY  hKey,
  [in] DWORD      dwParam,
  [in] const BYTE *pbData,
  [in] DWORD      dwFlags
);

Parámetros

[in] hKey

Identificador de la clave para la que se van a establecer los valores.

[in] dwParam

Las tablas siguientes contienen valores predefinidos que se pueden usar.

Para todos los tipos de clave, este parámetro puede contener uno de los valores siguientes.

Valor	Significado
KP_ALGID	pbData apunta a un ALG_ID adecuado. Esto se usa al intercambiar claves de sesión con microsoft Base Digital Signature Standard (DSS), Diffie-Hellman proveedor criptográfico o CSP compatibles. Después de acordar una clave con la función CryptImportKey , la clave de sesión se habilita para su uso estableciendo su tipo de algoritmo.
KP_CERTIFICATE	pbData es la dirección de un búfer que contiene el certificado X.509 que se ha codificado mediante reglas de codificación distinguida (DER). La clave pública del certificado debe coincidir con la firma o clave de intercambio correspondiente.
KP_PERMISSIONS	pbData apunta a un valor DWORD que especifica cero o más marcas de permisos. Para obtener una descripción de estas marcas, consulte CryptGetKeyParam.
KP_SALT	pbData apunta a una matriz BYTE que especifica un nuevo valor de sal que se va a formar parte de la clave de sesión. El tamaño del valor de sal varía en función del CSP que se use. Antes de establecer este valor, determine el tamaño del valor de sal llamando a la función CryptGetKeyParam . Los valores de sal se usan para que las claves de sesión sean más únicas, lo que dificulta los ataques de diccionario. El valor salt es cero de forma predeterminada para el proveedor criptográfico base de Microsoft.
KP_SALT_EX	pbData apunta a una estructura de CRYPT_INTEGER_BLOB que contiene la sal. Para obtener más información, vea Especificar un valor de sal.

Si el parámetro hKey especifica una clave estándar de firma digital (DSS), el valor dwParam también se puede establecer en uno de los valores siguientes.

Valor	Significado
KP_G	pbData apunta al generador G desde el BLOB de clave DSS. Los datos están en forma de una estructura de CRYPT_INTEGER_BLOB , donde el miembro pbData es el valor y el miembro cbData es la longitud del valor. El valor se espera sin información de encabezado y en forma little-endian .
KP_P	pbData apunta al módulo principal P de un BLOB de clave DSS. Los datos están en forma de una estructura CRYPT_INTEGER_BLOB . El miembro pbData es el valor y el miembro cbData es la longitud del valor. El valor se espera sin información de encabezado y en forma little-endian .
KP_Q	pbData apunta a la Q principal de un BLOB de clave DSS. Los datos están en forma de una estructura de CRYPT_INTEGER_BLOB donde el miembro pbData es el valor y el miembro cbData es la longitud del valor. El valor se espera sin información de encabezado y en forma little-endian .
KP_X	Después de establecer los valores P, Q y G, se puede realizar una llamada que especifique el valor de KP_X para dwParam y NULL para el parámetro pbData en la función CryptSetKeyParam . Esto hace que se generen los valores X e Y.

Si hKey especifica un algoritmo Diffie-Hellman o una clave de algoritmo de firma digital (DSA), el valor dwParam también se puede establecer en uno de los siguientes valores.

Valor	Significado
KP_CMS_DH_KEY_INFO	Establece la información de una clave Diffie-Hellman importada. El parámetro pbData es la dirección de una estructura de CMS_DH_KEY_INFO que contiene la información clave que se va a establecer.
KP_PUB_PARAMS	Establece los parámetros públicos (P, Q, G, etc.) de una clave DSS o Diffie-Hellman. El identificador de clave de esta clave debe estar en estado PREGEN, generado con la marca CRYPT_PREGEN. El parámetro pbData debe ser un puntero a una estructura de DATA_BLOB donde los datos de esta estructura son un DHPUBKEY_VER3 o DSSPUBKEY_VER3 BLOB. La función copia los parámetros públicos de esta estructura de CRYPT_INTEGER_BLOB en el identificador de clave. Una vez realizada esta llamada, se debe usar el valor del parámetro KP_X con CryptSetKeyParam para crear la clave privada real. El parámetro KP_PUB_PARAMS se usa como una llamada en lugar de varias llamadas con los valores de parámetro KP_P, KP_Q y KP_G.

Valor

Significado

KP_CMS_DH_KEY_INFO

Establece la información de una clave Diffie-Hellman importada. El parámetro pbData es la dirección de una estructura de CMS_DH_KEY_INFO que contiene la información clave que se va a establecer.

KP_PUB_PARAMS

Establece los parámetros públicos (P, Q, G, etc.) de una clave DSS o Diffie-Hellman. El identificador de clave de esta clave debe estar en estado PREGEN, generado con la marca CRYPT_PREGEN. El parámetro pbData debe ser un puntero a una estructura de DATA_BLOB donde los datos de esta estructura son un DHPUBKEY_VER3 o DSSPUBKEY_VER3 BLOB. La función copia los parámetros públicos de esta estructura de CRYPT_INTEGER_BLOB en el identificador de clave. Una vez realizada esta llamada, se debe usar el valor del parámetro KP_X con CryptSetKeyParam para crear la clave privada real. El parámetro KP_PUB_PARAMS se usa como una llamada en lugar de varias llamadas con los valores de parámetro KP_P, KP_Q y KP_G.

Si el parámetro hKey especifica una clave de sesión de cifrado de bloque, el valor dwParam también se puede establecer en uno de los valores siguientes.

Valor	Significado
KP_EFFECTIVE_KEYLEN	Este tipo de valor solo se puede usar con claves RC2 y se ha agregado debido a la implementación de la función CryptSetKeyParam en el proveedor criptográfico mejorado de Microsoft antes de Windows 2000. En la implementación anterior, las claves RC2 del proveedor mejorado tenían 128 bits de intensidad, pero la longitud de clave efectiva usada para expandir las claves en la tabla de claves era de solo 40 bits. Esto redujo la intensidad del algoritmo a 40 bits. Para mantener la compatibilidad con versiones anteriores, la implementación anterior permanecerá tal cual. Sin embargo, la longitud de clave efectiva se puede establecer para que sea mayor que 40 bits mediante KP_EFFECTIVE_KEYLEN en la llamada a CryptSetKeyParam . La longitud de clave efectiva se pasa en el parámetro pbData como puntero a un valor DWORD con el valor de longitud de clave efectivo. La longitud mínima efectiva de la clave en el proveedor criptográfico base de Microsoft es una y el máximo es 40. En el proveedor criptográfico mejorado de Microsoft, el mínimo es uno y el máximo es 1024. La longitud de la clave debe establecerse antes de cifrar o descifrar con la clave.
KP_HIGHEST_VERSION	Establece la versión de Seguridad de la capa de transporte (TLS) más alta permitida. Esta propiedad solo se aplica a las claves SSL y TLS. El parámetro pbData es la dirección de una variable DWORD que contiene el número de versión de TLS más alto admitido.
KP_IV	pbData apunta a una matriz BYTE que especifica el vector de inicialización. Esta matriz debe contener elementos BlockLength/8. Por ejemplo, si la longitud del bloque es de 64 bits, el vector de inicialización consta de 8 bytes. El vector de inicialización se establece en cero de forma predeterminada para el proveedor criptográfico base de Microsoft.
KP_KEYVAL	Establezca el valor de clave para una clave estándar de cifrado de datos (DES). El parámetro pbData es la dirección de un búfer que contiene la clave. Este búfer debe tener la misma longitud que la clave. Esta propiedad solo se aplica a las claves DES.
KP_PADDING	Establezca el modo de relleno. El parámetro pbData es un puntero a un valor DWORD que recibe un identificador numérico que identifica el método de relleno utilizado por el cifrado. Puede ser uno de los siguientes valores. PKCS5_PADDING Especifica el método de relleno PKCS 5 (s 6.2). RANDOM_PADDING El relleno usa un número aleatorio. Este método de relleno no es compatible con los CSP proporcionados por Microsoft. ZERO_PADDING El relleno usa ceros. Este método de relleno no es compatible con los CSP proporcionados por Microsoft.
KP_MODE	pbData apunta a un valor DWORD que especifica el modo de cifrado que se va a usar. Para obtener una lista de los modos de cifrado definidos, vea CryptGetKeyParam. El modo de cifrado se establece en CRYPT_MODE_CBC de forma predeterminada para el proveedor criptográfico base de Microsoft.
KP_MODE_BITS	pbData apunta a un valor DWORD que indica el número de bits procesados por ciclo cuando se usa el modo de cifrado Comentarios de salida (OFB) o Comentarios de cifrado (CFB). El número de bits procesados por ciclo se establece en 8 de forma predeterminada para el proveedor criptográfico base de Microsoft.

Si se especifica una clave RSA en el parámetro hKey , el valor del parámetro dwParam puede ser el valor siguiente.

Valor	Significado
KP_OAEP_PARAMS	Establezca los parámetros de relleno de cifrado asimétrico óptimo (OAEP) (PKCS #1 versión 2) para la clave. El parámetro pbData es la dirección de una estructura de CRYPT_DATA_BLOB que contiene la etiqueta OAEP. Esta propiedad solo se aplica a las claves RSA.

Tenga en cuenta que no se usan los siguientes valores:

KP_ADMIN_PIN
KP_CMS_KEY_INFO
KP_INFO
KP_KEYEXCHANGE_PIN
KP_PRECOMP_MD5
KP_PRECOMP_SHA
KP_PREHASH
KP_PUB_EX_LEN
KP_PUB_EX_VAL
KP_RA
KP_RB
KP_ROUNDS
KP_RP
KP_SIGNATURE_PIN
KP_Y

[in] pbData

Puntero a un búfer inicializado con el valor que se va a establecer antes de llamar a CryptSetKeyParam. La forma de estos datos varía según el valor de dwParam.

[in] dwFlags

Solo se usa cuando dwParam es KP_ALGID. El parámetro dwFlags se usa para pasar valores de marca para la clave habilitada. El parámetro dwFlags puede contener valores como el tamaño de clave y los demás valores de marca permitidos al generar el mismo tipo de clave con CryptGenKey. Para obtener información sobre los valores de marca permitidos, vea CryptGenKey.

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. A continuación se indican algunos códigos de error posibles.

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.
NTE_FIXEDPARAMETER	Algunos CSP tienen valores P, Q y G codificados de forma rígida. Si este es el caso, el uso de KP_P, KP_Q y KP_G para el valor de dwParam produce este error.

Comentarios

Si los parámetros KP_Q, KP_P o KP_X se establecen en una clave PREGEN Diffie-Hellman o DSS, las longitudes de clave deben ser compatibles con la longitud de clave establecida con los 16 bits superiores del parámetro dwFlags cuando la clave se creó mediante CryptGenKey. Si no se estableció ninguna longitud de clave en CryptGenKey, se usó la longitud de clave predeterminada. Esto creará un error si se usa una longitud de clave no predeterminada para establecer P, Q o X.

Ejemplos

Para obtener un ejemplo en el que se usa esta función, vea Programa C de ejemplo: Duplicación de una clave de sesión. Para obtener más código que usa esta función, vea Programa C de ejemplo: Establecer y obtener parámetros de clave de sesión .

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