Función CryptGetKeyParam (wincrypt.h)

Artículo
07/16/2024

importante Esta API está en desuso. El software nuevo y existente debe empezar a usar las API de 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, vea 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 DWORD valor que recibe la longitud del bloque, en bits. Para cifrados de flujo, este valor siempre es cero. Si especifica un par de claves pública o privada hKey, 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 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 distintivo (DER). La clave pública del certificado debe coincidir con la firma o la clave de intercambio correspondientes.
KP_GET_USE_COUNT	Este valor no se usa.
KP_KEYLEN	Recupere la longitud real de la clave. El parámetro pbData es un puntero a un DWORD valor 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 de Microsoft (CSP) devuelven una longitud de clave de 64 bits para CALG_DES, 128 bits para CALG_3DES_112y 192 bits para CALG_3DES. Estas longitudes son diferentes de las longitudes devueltas al enumerar algoritmos con el dwParam valor 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_MEKALG_ID devuelven 64 bits para ese algoritmo. CALG_CYLINK_MEK es una clave de 40 bits, pero tiene paridad y bits de clave con 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 de que recibe el valor de sal en formato little-en dian. 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 y 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 permisos. 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 Permitir que la clave se use para importar claves. CRYPT_MAC Permitir que 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 la clave estándar de firma digital (DSS) de se especifica mediante el parámetro hKey, 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 formato 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 formato 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 formato little-endian. El parámetro pdwDataLen contiene el tamaño del búfer, en bytes.

Si el parámetro clave de sesión especifica un de cifrado de bloque , el valor dwParam 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 de 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 de BYTE de que recibe el vector de inicialización. El tamaño de esta matriz es el tamaño del 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 usado 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 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 encadenamiento de bloques de cifrado. CRYPT_MODE_CFB El modo de cifrado es comentarios de cifrado (CFB). Los CSP de Microsoft admiten actualmente solo comentarios de 8 bits en modo de comentarios cifrados. CRYPT_MODE_ECB El modo de cifrado es código electrónico. CRYPT_MODE_OFB El modo de cifrado es de comentarios de salida (OFB). Los CSP de Microsoft no admiten actualmente el modo de comentarios de salida. CRYPT_MODE_CTS El modo de cifrado es texto cifrado modo de robo.
KP_MODE_BITS	Recupere el número de bits que se van a devolver. El parámetro pbData es un puntero a un DWORD valor que recibe el número de bits que se procesan por ciclo cuando se usan los modos de cifrado OFB o CFB.

Si o clave del algoritmo de firma digital (DSA) especifica una clave de algoritmo de Diffie-Hellman hKey, el valor de 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 en caso contrario.
KP_KEYVAL	Este valor no se usa. Windows Vista, Windows Server 2003 y Windows XP: Recuperar el valor del contrato secreto de un algoritmo de Diffie-Hellman importado clave 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. Puede modificarse o no estar disponible en versiones posteriores.

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 en caso contrario.

KP_KEYVAL

Este valor no se usa.

Windows Vista, Windows Server 2003 y Windows XP: Recuperar el valor del contrato secreto de un algoritmo de Diffie-Hellman importado clave 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. Puede modificarse o no estar disponible en versiones posteriores.

Si se especifica un certificado mediante hKey, el dwParam valor 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 en caso 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 a 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 D WORD 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 de 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 tamaños de búfer lo suficientemente grandes como para asegurarse de 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	El contexto de CSP que se especificó cuando no se encontró la clave.

Requisitos

Requisito	Valor
cliente mínimo admitido	Windows XP [solo aplicaciones de escritorio]
servidor mínimo admitido	Windows Server 2003 [solo aplicaciones de escritorio]
de la plataforma de destino de	Windows
encabezado de	wincrypt.h
biblioteca de	Advapi32.lib
DLL de	Advapi32.dll

Consulte también

CryptSetKeyParam

de generación de claves y funciones de Exchange de

Compartir a través de