Función CryptGetProvParam (wincrypt.h)
Sintaxis
BOOL CryptGetProvParam(
[in] HCRYPTPROV hProv,
[in] DWORD dwParam,
[out] BYTE *pbData,
[in, out] DWORD *pdwDataLen,
[in] DWORD dwFlags
);
Parámetros
[in] hProv
Identificador del destino csp de la consulta. Este identificador debe haberse creado mediante la función CryptAcquireContext .
[in] dwParam
Naturaleza de la consulta. Se definen las siguientes consultas.
| Valor | Significado |
|---|---|
|
Devuelve el número de identificación personal (PIN) del administrador en el parámetro pbData como LPSTR. |
|
Esta constante no se usa. |
|
Esta constante no se usa. |
|
Devuelve la cadena de certificados asociada al identificador hProv . La cadena de certificados devuelta se X509_ASN_ENCODING codifica. |
|
Nombre del contenedor de claves actual como una cadena CHAR terminada en null. Esta cadena es exactamente la misma que la pasada en el parámetro pszContainer de la función CryptAcquireContext para especificar el contenedor de claves que se va a usar. El parámetro pszContainer se puede leer para determinar el nombre del contenedor de claves predeterminado. |
|
No implementado por los CSP de Microsoft. Otros CSP pueden implementar este comportamiento.
Windows XP: Este parámetro no se admite. |
|
Estructura PROV_ENUMALGS que contiene información sobre un algoritmo admitido por el CSP que se consulta.
La primera vez que se lee este valor, el parámetro dwFlags debe contener la marca CRYPT_FIRST . Al hacerlo, esta función recuperará el primer elemento de la enumeración. Los elementos posteriores se pueden recuperar estableciendo la marca CRYPT_NEXT en el parámetro dwFlags . Cuando se produce un error en esta función con el código de error ERROR_NO_MORE_ITEMS , se ha alcanzado el final de la enumeración. Esta función no es segura para subprocesos y es posible que todos los algoritmos disponibles no se enumeren si esta función se usa en un contexto multiproceso. |
|
Estructura PROV_ENUMALGS_EX que contiene información sobre un algoritmo admitido por el CSP que se consulta. La estructura devuelta contiene más información sobre el algoritmo que la estructura devuelta para PP_ENUMALGS.
La primera vez que se lee este valor, el parámetro dwFlags debe contener la marca CRYPT_FIRST . Al hacerlo, esta función recuperará el primer elemento de la enumeración. Los elementos posteriores se pueden recuperar estableciendo la marca CRYPT_NEXT en el parámetro dwFlags . Cuando se produce un error en esta función con el código de error ERROR_NO_MORE_ITEMS , se ha alcanzado el final de la enumeración. Esta función no es segura para subprocesos y es posible que todos los algoritmos disponibles no se enumeren si esta función se usa en un contexto multiproceso. |
|
Nombre de uno de los contenedores de claves mantenidos por el CSP en forma de una cadena CHAR terminada en null.
La primera vez que se lee este valor, el parámetro dwFlags debe contener la marca CRYPT_FIRST . Al hacerlo, esta función recuperará el primer elemento de la enumeración. Los elementos posteriores se pueden recuperar estableciendo la marca CRYPT_NEXT en el parámetro dwFlags . Cuando se produce un error en esta función con el código de error ERROR_NO_MORE_ITEMS , se ha alcanzado el final de la enumeración. Para enumerar los contenedores de claves asociados a un equipo, llame primero a CryptAcquireContext mediante la marca CRYPT_MACHINE_KEYSET y, a continuación, use el identificador devuelto desde CryptAcquireContext como parámetro hProv en la llamada a CryptGetProvParam. Esta función no es segura para subprocesos y es posible que todos los algoritmos disponibles no se enumeren si esta función se usa en un contexto multiproceso. |
|
Esta constante no se usa. |
|
Indica que el CSP actual admite el miembro dwProtocols de la estructura PROV_ENUMALGS_EX . Si esta función se ejecuta correctamente, el CSP admite el miembro dwProtocols de la estructura PROV_ENUMALGS_EX . Si se produce un error en esta función con un código de error NTE_BAD_TYPE , el CSP no admite el miembro dwProtocols . |
|
Esta constante no se usa. |
|
Valor DWORD que indica cómo se implementa el CSP. Para obtener una tabla de valores posibles, vea Comentarios. |
|
Esta consulta no se usa. |
|
Especifica que el PIN de intercambio de claves está incluido en pbData. El PIN se representa como una cadena ASCII terminada en null. |
|
Recupera el descriptor de seguridad del contenedor de almacenamiento de claves. El parámetro pbData es la dirección de una estructura de SECURITY_DESCRIPTOR que recibe el descriptor de seguridad para el contenedor de almacenamiento de claves. El descriptor de seguridad se devuelve en formato relativo propio. |
|
Determina si el parámetro hProv es un conjunto de claves de equipo. El parámetro pbData debe ser un DWORD; DWORD se establecerá en la marca CRYPT_MACHINE_KEYSET si esa marca se pasó a la función CryptAcquireContext . |
|
Devuelve información sobre los valores del especificador de clave que admite el CSP. Los valores del especificador de clave se combinan en un OR lógico y se devuelven en el parámetro pbData de la llamada como DWORD. Por ejemplo, la versión 1.0 del proveedor criptográfico base de Microsoft devuelve un valor DWORD de AT_SIGNATURE | AT_KEYEXCHANGE. |
|
Devuelve un valor DWORD de CRYPT_SEC_DESCR. |
|
Número de bits para la longitud de incremento de AT_KEYEXCHANGE. Esta información se usa con la información devuelta en el valor de PP_ENUMALGS_EX. Con la información devuelta al usar PP_ENUMALGS_EX y PP_KEYX_KEYSIZE_INC, se pueden determinar las longitudes de clave válidas para AT_KEYEXCHANGE. Estas longitudes de clave se pueden usar con CryptGenKey. Por ejemplo, si un CSP enumera CALG_RSA_KEYX (AT_KEYEXCHANGE) con una longitud de clave mínima de 512 bits y un máximo de 1024 bits, y devuelve la longitud de incremento como 64 bits, las longitudes de clave válidas son 512, 576, 640,... 1024. |
|
Nombre del CSP en forma de cadena CHAR terminada en null. Esta cadena es idéntica a la que se pasa en el parámetro pszProvider de la función CryptAcquireContext para especificar que se use el CSP actual. |
|
Valor DWORD que indica el tipo de proveedor del CSP. |
|
Obtiene el almacén de certificados raíz de la tarjeta inteligente. Este almacén de certificados contiene todos los certificados raíz almacenados en la tarjeta inteligente.
El parámetro pbData es la dirección de una variable HCERTSTORE que recibe el identificador del almacén de certificados. 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. |
|
Tamaño, en bits, de la clave de sesión. |
|
Se usa con criptografía controlada por el servidor. |
|
Número de bits para la longitud de incremento de AT_SIGNATURE. Esta información se usa con la información devuelta en el valor de PP_ENUMALGS_EX. Con la información devuelta al usar PP_ENUMALGS_EX y PP_SIG_KEYSIZE_INC, se pueden determinar las longitudes de clave válidas para AT_SIGNATURE. Estas longitudes de clave se pueden usar con CryptGenKey.
Por ejemplo, si un CSP enumera CALG_RSA_SIGN (AT_SIGNATURE) con una longitud de clave mínima de 512 bits y un máximo de 1024 bits, y devuelve la longitud de incremento como 64 bits, las longitudes de clave válidas son 512, 576, 640,... 1024. |
|
Especifica que el PIN de firma de clave está incluido en pbData. El PIN se representa como una cadena ASCII terminada en null. |
|
Obtiene el identificador de la tarjeta inteligente. El parámetro pbData es la dirección de una estructura GUID que recibe el identificador de la tarjeta inteligente.
Windows Server 2003 y Windows XP: Este parámetro no se admite. |
|
Obtiene el nombre del lector de tarjetas inteligentes. El parámetro pbData es la dirección de una matriz de caracteres ANSI que recibe una cadena ANSI terminada en null que contiene el nombre del lector de tarjetas inteligentes. El tamaño de este búfer, contenido en la variable a la que apunta el parámetro pdwDataLen , debe incluir el terminador NULL .
Windows Server 2003 y Windows XP: Este parámetro no se admite. |
|
Tamaño de la clave simétrica. |
|
Esta consulta no se usa. |
|
Nombre de contenedor único del contenedor de claves actual en forma de cadena CHAR terminada en null. Para muchos CSP, este nombre es el mismo nombre que se devuelve cuando se usa el valor de PP_CONTAINER. La función CryptAcquireContext debe funcionar con este nombre de contenedor. |
|
Indica si se admite un generador de números aleatorios de hardware (RNG). Cuando se especifica PP_USE_HARDWARE_RNG , la función se realiza correctamente y devuelve TRUE si se admite un RNG de hardware. La función produce un error y devuelve FALSE si no se admite un RNG de hardware. Si se admite un RNG, PP_USE_HARDWARE_RNG se puede establecer en CryptSetProvParam para indicar que el CSP debe usar exclusivamente el RNG de hardware para este contexto de proveedor. Cuando se usa PP_USE_HARDWARE_RNG , el parámetro pbData debe ser NULL y dwFlags debe ser cero.
Ninguno de los CSP de Microsoft admite actualmente el uso de un RNG de hardware. |
|
Obtiene 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 la dirección de 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. |
|
Número de versión del CSP. El byte menos significativo contiene el número de versión secundaria y el siguiente byte más significativo el número de versión principal. La versión 2.0 se representa como 0x00000200. Para mantener la compatibilidad con versiones anteriores del proveedor criptográfico base de Microsoft y el proveedor criptográfico mejorado de Microsoft, los nombres de proveedor conservan la designación "v1.0" en versiones posteriores. |
[out] pbData
Puntero a un búfer para recibir los datos. El formato de estos datos varía en función del valor de dwParam. Cuando dwParam se establece en PP_USE_HARDWARE_RNG, pbData debe establecerse en NULL.
Este parámetro puede ser NULL para establecer el tamaño de esta información con fines de asignación de memoria. Para obtener más información, vea Recuperar datos de longitud desconocida.
[in, out] pdwDataLen
Puntero a un valor DWORD que especifica 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 o que se almacenarán en el búfer.
Si se establece PP_ENUMALGS o PP_ENUMALGS_EX, el parámetro pdwDataLen funciona de forma algo diferente. Si pbData es NULL o el valor al que apunta pdwDataLen es demasiado pequeño, el valor devuelto en este parámetro es el tamaño del elemento más grande de la lista de enumeraciones en lugar del tamaño del elemento que se está leyendo actualmente.
Si se establece PP_ENUMCONTAINERS, la primera llamada a la función devuelve el tamaño del contenedor de claves máximo permitido por el proveedor actual. Esto contrasta con otros comportamientos posibles, como devolver la longitud del contenedor existente más largo o la longitud del contenedor actual. Las llamadas de enumeración posteriores no cambiarán el parámetro dwLen . Para cada contenedor enumerado, el autor de la llamada puede determinar la longitud de la cadena terminada en NULL mediante programación, si lo desea. Si se lee uno de los valores de enumeración y el parámetro pbData es NULL, se debe especificar la marca CRYPT_FIRST para que la información de tamaño se recupere correctamente.
[in] dwFlags
Si dwParam está PP_KEYSET_SEC_DESCR, se recupera el descriptor de seguridad en el contenedor de claves donde se almacenan las claves. En este caso, dwFlags se usa para pasar las marcas de bits de SECURITY_INFORMATION que indican la información de seguridad solicitada, tal como se define en el SDK de plataforma. SECURITY_INFORMATION marcas de bits se pueden combinar con una operación OR bit a bit.
Los siguientes valores se definen para su uso con PP_KEYSET_SEC_DESCR.
Los siguientes valores se definen para su uso con PP_ENUMALGS, PP_ENUMALGS_EX y PP_ENUMCONTAINERS.
| Valor | Significado |
|---|---|
|
Recupere el primer elemento de la enumeración . Esto tiene el mismo efecto que restablecer el enumerador. |
|
Recupere el siguiente elemento de la enumeración . Cuando no hay más elementos que recuperar, se producirá un error en esta función y se establecerá el último error en ERROR_NO_MORE_ITEMS. |
|
Recupere certificados habilitados para criptografía controlada por el servidor (SGC). Los certificados habilitados para SGC ya no se admiten. |
|
Esta marca no se usa. |
|
Esta marca no se usa. |
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 concreto que se usa. A continuación se indican algunos códigos de error posibles.
| Código devuelto | Descripción |
|---|---|
|
Uno de los parámetros especifica un identificador que no es válido. |
|
Uno de los parámetros contiene un valor que no es válido. Suele ser un puntero que no es válido. |
|
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. |
|
Se ha alcanzado el final de la lista de enumeraciones. No se han colocado datos válidos en el búfer pbData . Este código de error solo se devuelve cuando dwParam es igual a PP_ENUMALGS o PP_ENUMCONTAINERS. |
|
El parámetro dwFlags especifica una marca que no es válida. |
|
El parámetro dwParam especifica un número de valor desconocido. |
|
El contexto de CSP especificado por hProv no es válido. |
Comentarios
Esta función no se debe usar en un subproceso de un programa multiproceso.
Los valores siguientes se devuelven en pbData si dwParam es PP_IMPTYPE.
| Valor | Significado |
|---|---|
| CRYPT_IMPL_HARDWARE 0x01 |
La implementación está en hardware. |
| CRYPT_IMPL_SOFTWARE 0x02 |
La implementación está en software. |
| CRYPT_IMPL_MIXED 0x03 |
La implementación implica hardware y software. |
| CRYPT_IMPL_UNKNOWN 0x04 |
El tipo de implementación es desconocido. |
| CRYPT_IMPL_REMOVABLE 0x08 |
La implementación está en medios extraíbles. |
El parámetro dwFlags se usa para pasar las marcas de bits de SECURITY_INFORMATION que indican la información de seguridad solicitada. El puntero al descriptor de seguridad se devuelve en el parámetro pbData y la longitud del descriptor de seguridad se devuelve en el parámetro pdwDataLen . La seguridad del contenedor de claves se controla con SetFileSecurity y GetFileSecurity.
Se puede determinar la clase de un algoritmo enumerado con dwParam establecido en PP_ENUMALGS o PP_ENUMALGS_EX. Esto puede hacerse para mostrar una lista de algoritmos de cifrado admitidos y para ignorar el resto. La macro GET_ALG_CLASS(x) toma un identificador de algoritmo como argumento y devuelve un código que indica la clase general de ese algoritmo. Entre los posibles valores devueltos se incluyen:
- ALG_CLASS_DATA_ENCRYPT
- ALG_CLASS_HASH
- ALG_CLASS_KEY_EXCHANGE
- ALG_CLASS_SIGNATURE
En la tabla siguiente se enumeran los algoritmos admitidos por el proveedor criptográfico base de Microsoft junto con la clase de cada algoritmo.
| Nombre | Identificador | Clase |
|---|---|---|
| "MD2" | CALG_MD2 | ALG_CLASS_HASH |
| "MD5" | CALG_MD5 | ALG_CLASS_HASH |
| "SHA" | CALG_SHA | ALG_CLASS_HASH |
| "MAC" | CALG_MAC | ALG_CLASS_HASH |
| "RSA_SIGN" | CALG_RSA_SIGN | ALG_CLASS_SIGNATURE |
| "RSA_KEYX" | CALG_RSA_KEYX | ALG_CLASS_KEY_EXCHANGE |
| "RC2" | CALG_RC2 | ALG_CLASS_DATA_ENCRYPT |
| "RC4" | CALG_RC4 | ALG_CLASS_DATA_ENCRYPT |
Las aplicaciones no deben usar un algoritmo con un identificador de algoritmo que no se reconozca. El uso de un algoritmo criptográfico desconocido puede producir resultados imprevisibles.
Ejemplos
En el ejemplo siguiente se muestra cómo buscar el nombre del CSP asociado a un identificador de proveedor de servicios criptográficos y el nombre del contenedor de claves asociado al identificador. Para obtener el contexto completo de este ejemplo, vea Ejemplo de programa C: Uso de CryptAcquireContext.
Para obtener otro ejemplo que usa esta función, vea Programa C de ejemplo: Enumeración de proveedores y tipos de proveedor de CSP.
//-----------------------------------------------------------------
// Declare and initialize variables.
HCRYPTPROV hCryptProv;
BYTE pbData[1000]; // 1000 will hold the longest
// key container name.
DWORD cbData;
//-------------------------------------------------------------------
// An HCRYPTPROV must be acquired before using code like that in
// "Example C Program Using CryptAcquireContext."
//-------------------------------------------------------------------
// Read the name of the default CSP.
cbData = 1000;
if(CryptGetProvParam(
hCryptProv,
PP_NAME,
pbData,
&cbData,
0))
{
printf("CryptGetProvParam succeeded.\n");
printf("Provider name: %s\n", pbData);
}
else
{
printf("Error reading CSP name. \n");
exit(1);
}
//--------------------------------------------------------------------
// Read the name of the default key container.
cbData = 1000;
if(CryptGetProvParam(
hCryptProv,
PP_CONTAINER,
pbData,
&cbData,
0))
{
printf("CryptGetProvParam succeeded. \n");
printf("Key Container name: %s\n", pbData);
}
else
{
printf("Error reading key container name. \n");
exit(1);
}
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 |