Función CryptGetKeyParam (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 CryptGetKeyParam recupera datos que rigen las operaciones de una clave. Si se usa el proveedor de servicios criptográficos de Microsoft , este o cualquier otra función no puede obtener el material de keying simétrico base.

Sintaxis

BOOL CryptGetKeyParam(
  [in]      HCRYPTKEY hKey,
  [in]      DWORD     dwParam,
  [out]     BYTE      *pbData,
  [in, out] DWORD     *pdwDataLen,
  [in]      DWORD     dwFlags
);

Parámetros

[in] hKey

Identificador de la clave que se está consultando.

[in] dwParam

Especifica el tipo de consulta que se está realizando.

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

Valor	Significado
KP_ALGID	Recupere el algoritmo de clave. El parámetro pbData es un puntero a un valor de ALG_ID que recibe el identificador del algoritmo que se especificó cuando se creó la clave. Cuando se especifica AT_KEYEXCHANGE o AT_SIGNATURE para el parámetro Algid de la función CryptGenKey , los identificadores de algoritmo que se usan para generar la clave dependen del proveedor utilizado. Para obtener más información, consulte ALG_ID.
KP_BLOCKLEN	Si el parámetro hKey especifica una clave de sesión, recupere la longitud del bloque del cifrado de clave. El parámetro pbData es un puntero a un valor DWORD que recibe la longitud del bloque, en bits. En el caso de los cifrados de flujo, este valor siempre es cero. Si hKey especifica un par de claves pública o privada, recupere la granularidad de cifrado del par de claves. El parámetro pbData es un puntero a un valor DWORD que recibe la granularidad de cifrado, en bits. Por ejemplo, el proveedor criptográfico base de Microsoft genera pares de claves RSA de 512 bits, por lo que se devuelve un valor de 512 para estas claves. Si el algoritmo de clave pública no admite el cifrado, el valor recuperado no está definido.
KP_CERTIFICATE	pbData es la dirección de un búfer que recibe 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_GET_USE_COUNT	Este valor no se utiliza.
KP_KEYLEN	Recupere la longitud real de la clave. El parámetro pbData es un puntero a un valor DWORD que recibe la longitud de la clave, en bits. KP_KEYLEN se puede usar para obtener la longitud de cualquier tipo de clave. Los proveedores de servicios criptográficos (CSP) de Microsoft devuelven una longitud de clave de 64 bits para CALG_DES, 128 bits para CALG_3DES_112 y 192 bits para CALG_3DES. Estas longitudes son diferentes de las longitudes devueltas al enumerar algoritmos con el valor dwParam de la función CryptGetProvParam establecida en PP_ENUMALGS. La longitud devuelta por esta llamada es el tamaño real de la clave, incluidos los bits de paridad incluidos en la clave. Los CSP de Microsoft que admiten el CALG_CYLINK_MEK ALG_ID devuelven 64 bits para ese algoritmo. CALG_CYLINK_MEK es una clave de 40 bits, pero tiene paridad y bits de clave cero para que la longitud de la clave sea de 64 bits.
KP_SALT	Recupere el valor de sal de la clave. El parámetro pbData es un puntero a una matriz BYTE que recibe el valor salt en forma little-endian . El tamaño del valor de sal varía según el CSP y el algoritmo que se use. Los valores de sal no se aplican a pares de claves públicas o privadas.
KP_PERMISSIONS	Recupere los permisos de clave. El parámetro pbData es un puntero a un valor DWORD que recibe las marcas de permiso para la clave. Actualmente se definen los siguientes identificadores de permiso. Los permisos de clave pueden ser cero o una combinación de uno o varios de los valores siguientes. CRYPT_ARCHIVE Permitir la exportación durante la vigencia del identificador de la clave. Este permiso solo se puede establecer si ya está establecido en el campo permisos internos de la clave. Se omiten los intentos de borrar este permiso. CRYPT_DECRYPT Permitir descifrado. CRYPT_ENCRYPT Permitir cifrado. CRYPT_EXPORT Permitir que se exporte la clave. CRYPT_EXPORT_KEY Permitir que la clave se use para exportar claves. CRYPT_IMPORT_KEY Permita que la clave se use para importar claves. CRYPT_MAC Permitir que los códigos de autenticación de mensajes (MAC) se usen con clave. CRYPT_READ Permitir que se lean los valores. CRYPT_WRITE Permitir que se establezcan valores.

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_P	Recupere el número primo del módulo P de la clave DSS. El parámetro pbData es un puntero a un búfer que recibe el valor en forma little-endian. El parámetro pdwDataLen contiene el tamaño del búfer, en bytes.
KP_Q	Recupere el número primo del módulo Q de la clave DSS. El parámetro pbData es un puntero a un búfer que recibe el valor en forma little-endian. El parámetro pdwDataLen contiene el tamaño del búfer, en bytes.
KP_G	Recupere el generador G de la clave DSS. El parámetro pbData es un puntero a un búfer que recibe el valor en forma little-endian. El parámetro pdwDataLen contiene el tamaño del búfer, en bytes.

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	Recupere la longitud de clave efectiva de una clave RC2. El parámetro pbData es un puntero a un valor DWORD que recibe la longitud de clave efectiva.
KP_IV	Recupere el vector de inicialización de la clave. El parámetro pbData es un puntero a una matriz BYTE que recibe el vector de inicialización. El tamaño de esta matriz es el tamaño de bloque, en bytes. Por ejemplo, si la longitud del bloque es de 64 bits, el vector de inicialización consta de 8 bytes.
KP_PADDING	Recupere 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 números aleatorios. 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	Recupere el modo de cifrado. El parámetro pbData es un puntero a un valor DWORD que recibe un identificador de modo de cifrado. Para obtener más información sobre los modos de cifrado, consulte Cifrado de datos y Descifrado. Actualmente se definen los siguientes identificadores de modo de cifrado. CRYPT_MODE_CBC El modo de cifrado es el encadenamiento de bloques de cifrado. CRYPT_MODE_CFB El modo de cifrado es comentarios de cifrado (CFB). Actualmente, los CSP de Microsoft solo admiten comentarios de 8 bits en modo de comentarios cifrados. CRYPT_MODE_ECB El modo de cifrado es un libro de códigos electrónico. CRYPT_MODE_OFB El modo de cifrado es Comentarios de salida (OFB). Actualmente, los CSP de Microsoft no admiten el modo de comentarios de salida. CRYPT_MODE_CTS El modo de cifrado es el modo de robo de texto cifrado .
KP_MODE_BITS	Recupere el número de bits que se van a devolver. El parámetro pbData es un puntero a un valor DWORD que recibe el número de bits que se procesan por ciclo cuando se usan los modos de cifrado OFB o CFB.

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 el siguiente valor.

Valor	Significado
KP_VERIFY_PARAMS	Comprueba los parámetros de un algoritmo de Diffie-Hellman o una clave DSA. El parámetro pbData no se usa y el valor al que apunta pdwDataLen recibe cero. Esta función devuelve un valor distinto de cero si los parámetros de clave son válidos o cero de lo contrario.
KP_KEYVAL	Este valor no se utiliza. Windows Vista, Windows Server 2003 y Windows XP: Recupere el valor del acuerdo secreto de una clave de algoritmo Diffie-Hellman importada de tipo CALG_AGREEDKEY_ANY. El parámetro pbData es la dirección de un búfer que recibe el valor del acuerdo secreto, en formato little-endian. Este búfer debe tener la misma longitud que la clave. El parámetro dwFlags debe establecerse en 0xF42A19B6. Esta propiedad solo se puede recuperar mediante un subproceso que se ejecuta en la cuenta del sistema local. Esta propiedad está disponible para su uso en los sistemas operativos enumerados anteriormente. En versiones posteriores podría modificarse o no estar disponible.

Valor

Significado

KP_VERIFY_PARAMS

Comprueba los parámetros de un algoritmo de Diffie-Hellman o una clave DSA. El parámetro pbData no se usa y el valor al que apunta pdwDataLen recibe cero.

Esta función devuelve un valor distinto de cero si los parámetros de clave son válidos o cero de lo contrario.

KP_KEYVAL

Este valor no se utiliza.

Windows Vista, Windows Server 2003 y Windows XP: Recupere el valor del acuerdo secreto de una clave de algoritmo Diffie-Hellman importada de tipo CALG_AGREEDKEY_ANY. El parámetro pbData es la dirección de un búfer que recibe el valor del acuerdo secreto, en formato little-endian. Este búfer debe tener la misma longitud que la clave. El parámetro dwFlags debe establecerse en 0xF42A19B6. Esta propiedad solo se puede recuperar mediante un subproceso que se ejecuta en la cuenta del sistema local. Esta propiedad está disponible para su uso en los sistemas operativos enumerados anteriormente. En versiones posteriores podría modificarse o no estar disponible.

Si hKey especifica un certificado, el valor dwParam también se puede establecer en el siguiente valor.

Valor	Significado
KP_CERTIFICATE	Búfer que contiene el certificado X.509 codificado en DER. El parámetro pbData no se usa y el valor al que apunta pdwDataLen recibe cero. Esta función devuelve un valor distinto de cero si los parámetros de clave son válidos o cero de lo contrario.

[out] pbData

Puntero a un búfer que recibe los datos. El formato de estos datos depende del valor de dwParam.

Si no se conoce el tamaño de este búfer, el tamaño necesario se puede recuperar en tiempo de ejecución pasando NULL para este parámetro y estableciendo el valor al que apunta pdwDataLen en cero. Esta función colocará el tamaño necesario del búfer, en bytes, en el valor al que apunta pdwDataLen. Para obtener más información, vea Recuperar datos de longitud desconocida.

[in, out] pdwDataLen

Puntero a un valor DWORD que, en la entrada, contiene el tamaño, en bytes, del búfer al que apunta el parámetro pbData . Cuando la función devuelve, el valor DWORD contiene el número de bytes almacenados en el búfer.

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, a veces se especifican los tamaños de búfer lo suficientemente grandes como para garantizar 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.

[in] dwFlags

Este parámetro está reservado para uso futuro y debe establecerse en cero.

Valor devuelto

Si la función se ejecuta correctamente, la función devuelve un valor distinto de cero.

Si se produce un error en la función, devuelve cero. 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. Algunos códigos de error posibles incluyen lo siguiente.

Código devuelto	Descripción
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.
ERROR_MORE_DATA	Si el búfer especificado por el parámetro pbData 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 pdwDataLen.
NTE_BAD_FLAGS	El parámetro dwFlags es distinto de cero.
NTE_BAD_KEY o NTE_NO_KEY	La clave especificada por el parámetro hKey no es válida.
NTE_BAD_TYPE	El parámetro dwParam especifica un número de valor desconocido.
NTE_BAD_UID	No se encuentra el contexto de CSP que se especificó cuando se creó la clave.

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

CryptSetKeyParam

Funciones de generación y intercambio de claves