Función PFXImportCertStore (wincrypt.h)

  • Artículo

La función PFXImportCertStore importa un BLOB PFX y devuelve el identificador de un almacén que contiene certificados y las claves privadas asociadas.

Sintaxis

HCERTSTORE PFXImportCertStore(
  [in] CRYPT_DATA_BLOB *pPFX,
  [in] LPCWSTR         szPassword,
  [in] DWORD           dwFlags
);

Parámetros

[in] pPFX

Puntero a una estructura de CRYPT_DATA_BLOB que contiene un paquete PFX con los certificados y claves exportados y cifrados.

[in] szPassword

Contraseña de cadena usada para descifrar y comprobar el paquete PFX. Si se establece en una cadena de longitud mayor que cero o se establece en una cadena vacía o en NULL, este valor debe ser exactamente igual que el valor que se usó para cifrar el paquete.

A partir de Windows 8 y Windows Server 2012, si el paquete PFX se creó en la función PFXExportCertStoreEx mediante la marca PKCS12_PROTECT_TO_DOMAIN_SIDS, la función PFXImportCertStore intenta descifrar la contraseña mediante la entidad de seguridad de Active Directory (AD) que se usó para cifrarlo. La entidad de seguridad de AD se especifica en el parámetro pvPara . Si el parámetro szPassword de la función PFXExportCertStoreEx era una cadena vacía o NULL y el parámetro dwFlags se estableció en PKCS12_PROTECT_TO_DOMAIN_SIDS, esa función generó aleatoriamente una contraseña y la cifró en la entidad de seguridad de AD especificada en el parámetro pvPara . En ese caso, debe establecer la contraseña en el valor, la cadena vacía o NULL, que se usó cuando se creó el paquete PFX. La función PFXImportCertStore usará la entidad de seguridad de AD para descifrar la contraseña aleatoria y la contraseña generada aleatoriamente se usará para descifrar el certificado PFX.

Cuando haya terminado de usar la contraseña, desactive la memoria llamando a la función SecureZeroMemory . Para obtener más información sobre cómo proteger las contraseñas, consulte Control de contraseñas.

[in] dwFlags

El parámetro dwFlags puede ser uno de los siguientes valores:

Valor Significado
CRYPT_EXPORTABLE
0x00000001
 Las claves importadas se marcan como exportables. Si no se usa esta marca, se produce un error en las llamadas a la función CryptExportKey con el identificador de clave.
CRYPT_USER_PROTECTED
0x00000002
 El usuario debe recibir una notificación a través de un cuadro de diálogo u otro método cuando se realizan ciertos intentos de usar esta clave. El comportamiento preciso lo especifica el proveedor de servicios criptográficos (CSP) que se usa.

Antes de Internet Explorer 4.0, los proveedores de servicios criptográficos de Microsoft omiteban esta marca. A partir de Internet Explorer 4.0, los proveedores de Microsoft admiten esta marca.

Si el contexto del proveedor se abrió con la marca CRYPT_SILENT establecida, el uso de esta marca provoca un error y el último error se establece en NTE_SILENT_CONTEXT.
CRYPT_MACHINE_KEYSET
0x00000020
 Las claves privadas se almacenan en el equipo local y no en el usuario actual.
CRYPT_USER_KEYSET
0x00001000
 Las claves privadas se almacenan en el usuario actual y no en el equipo local aunque el BLOB PFX especifique que deben ir al equipo local.
PKCS12_PREFER_CNG_KSP
0x00000100
 Indica que se prefiere el proveedor de almacenamiento de claves CNG (KSP). Si el CSP se especifica en el archivo PFX, se usa el CSP; de lo contrario, se prefiere el KSP. Si el KSP de CNG no está disponible, se producirá un error en la función PFXImportCertStore .

Windows Server 2003 y Windows XP: Este valor no se admite.
PKCS12_ALWAYS_CNG_KSP
0x00000200
 Indica que siempre se usa el KSP de CNG. Cuando se especifica, PFXImportCertStore intenta usar el KSP de CNG independientemente de la información del proveedor en el archivo PFX. Si el KSP de CNG no está disponible, no se producirá un error en la importación.

Windows Server 2003 y Windows XP: Este valor no se admite.
PKCS12_ALLOW_OVERWRITE_KEY
0x00004000
 Permitir sobrescribir la clave existente. Especifique esta marca cuando encuentre un escenario en el que debe importar un archivo PFX que contenga un nombre de clave que ya exista. Por ejemplo, al importar un archivo PFX, es posible que un contenedor del mismo nombre ya esté presente porque no hay ningún espacio de nombres único para los contenedores de claves. Si ha creado un "TestKey" en el equipo y, a continuación, importa un archivo PFX que también tiene "TestKey" como contenedor de claves, la configuración de PKCS12_ALLOW_OVERWRITE_KEY permite sobrescribir la clave.

Windows Server 2003 y Windows XP: Este valor no se admite.
PKCS12_NO_PERSIST_KEY
0x00008000
 No conserve la clave. Especifique esta marca cuando no desee conservar la clave. Por ejemplo, si no es necesario almacenar la clave después de la comprobación, en lugar de crear un contenedor y, a continuación, eliminarla, puede especificar esta marca para eliminar la clave inmediatamente.
Nota Si la marca de PKCS12_NO_PERSIST_KEY es *no* establecida, las claves se conservan en el disco. Si no desea conservar las claves más allá de su uso, debe eliminarlas llamando a la función CryptAcquireContext con la marca CRYPT_DELETEKEYSET establecida en el parámetro dwFlags .
Nota Otras consideraciones:

  • Al usar PKCS12_NO_PERSIST_KEY, la propiedad CERT_KEY_CONTEXT_PROP_ID se establece internamente en el certificado y CERT_KEY_CONTEXT_PROP_ID contiene el NCRYPT_KEY_HANDLE.

  • Si no se usa el PKCS12_NO_PERSIST_KEY, se establece la propiedad CERT_KEY_PROV_INFO_PROP_ID.

  • Si el certificado con la clave no persistente se serializa en otro proceso, la propiedad CERT_KEY_CONTEXT_PROP_ID no se serializará.

  • Para que NO_PERSIST funcione, debe estar en el mismo proceso y el usuario del PCCERT_CONTEXT debe admitir el CERT_KEY_CONTEXT_PROP_ID. Esto normalmente se aplica durante un protocolo de enlace TLS: si el protocolo de enlace se realiza externamente al proceso de llamada en LSASS.exe, no es posible usar PKCS12_NO_PERSIST_KEY al pasar del proceso de llamada a LSASS (porque el NCRYPT_KEY_HANDLE es un puntero a una estructura de datos y no a un controlador de kernel).

 
Windows Server 2003 y Windows XP: Este valor no se admite.
PKCS12_INCLUDE_EXTENDED_PROPERTIES
0x0010
 Importe todas las propiedades extendidas en el certificado que se guardaron en el certificado cuando se exportó.

Windows Server 2003 y Windows XP: Este valor no se admite.
0x10000000
 Desempaquetar pero no conservar los resultados.

Valor devuelto

Si la función se ejecuta correctamente, la función devuelve un identificador a un almacén de certificados que contiene los certificados importados, incluidas las claves privadas disponibles.

Si se produce un error en la función, es decir, si el parámetro de contraseña no contiene una coincidencia exacta con la contraseña usada para cifrar el paquete exportado o si hubo otros problemas para descodificar el BLOB PFX, la función devuelve NULL y se puede encontrar un código de error llamando a la función GetLastError .

Comentarios

La función PFXImportCertStore abre un almacén temporal. Si la función se ejecuta correctamente, debe cerrar el identificador en el almacén llamando a la función CertCloseStore .

Al importar un certificado del paquete PFX, El nombre del contenedor CSP/KSP se determina mediante el atributo AttributeId con OID 1.3.6.1.4.1.311.17.1 de PKCS8ShroudedKeyBag SafeBag [bagId: 1.2.840.113549.1.12.10.1.2] (vea PKCS #12 para obtener más información sobre la estructura ASN.1 de este).

  • AttributeId: 1.3.6.1.4.1.311.17.1
  • Valor: El nombre de KSP o el nombre de CSP

Si el attributeId no está presente y se pasa la marca PREFER_CNG, se selecciona MS_KEY_STORAGE_PROVIDER. Si el attributeId no está presente y no se pasa la marca de PREFER_CNG, el nombre del proveedor se determina en función del algoritmo de clave pública (es decir, el algoritmo de clave pública viene determinado por AlgorithmIdentifier en PKCS #8):

  • RSA: MS_ENHANCED_PROV_W
  • DSA: MS_DEF_DSS_DH_PROV_W

De forma similar, la especificación de clave se determina mediante attributeId con OID 2.5.29.15 (szOID_KEY_USAGE) de la siguiente manera:

Si se usa una clave CAPI:

  • Si se establece KEY_ENCIPHERMENT o DATA_ENCIPHERMENT, la especificación de clave se establece en AT_KEYEXCHANGE.
  • Si se establece DIGITAL_SIGNATURE o CERT_SIGN o CRL_SIGN, la especificación clave se establece en AT_SIGNATURE.

Si se usa una clave CNG:

  • Si se establece KEY_ENCIPHERMENT o DATA_ENCIPHERMENT o ENCIPHER_ONLY o DECIPHER_ONLY, el uso de la clave ncrypt se establece en ALLOW_DECRYPT.
  • Si se establece DIGITAL_SIGNATURE o CERT_SIGN o CRL_SIGN, el uso de la clave ncrypt se establece en ALLOW_SIGN.
  • Si se establece KEY_AGREEMENT, el uso de la clave ncrypt se establece en ALLOW_KEY_AGREEMENT.

Si el AttributeId no está presente, el valor de clave CAPI se establece en AT_KEYEXCHANGE para RSA o DH y el algoritmo lo determina AlgorithmIdentifier en PKCS #8; de lo contrario, el algoritmo se establece en AT_SIGNATURE. Para el valor de clave CNG, se establece todo el uso de la clave ncrypt.

Nota

Si un nombre de proveedor no válido está presente en el paquete PFX, o el proveedor de criptografía base o mejorado no está presente en esta clave del Registro: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Defaults\Provider, el tipo de proveedor realiza una búsqueda de proveedor mediante esta subclave del Registro: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Defaults\Provider Types.

Microsoft solo admite dos algoritmos hash o cifrado para importar un PFX:

  • TripleDES-SHA1
  • AES256-SHA256

Para cualquiera de los algoritmos anteriores, el cifrado de los certificados es opcional.

Microsoft puede exportar un PFX desde un almacén de certificados a través de la All Tasks>Yes, export the private key selección. Allí puede seleccionar el algoritmo de cifrado o hash para que coincida con una de estas dos opciones.

Puede usar PowerShell para exportar un PFX mediante lo siguiente:

Export-PfxCertificate
[-CryptoAlgorithmOption <CryptoAlgorithmOptions>]

-CryptoAlgorithmOption especifica el algoritmo para cifrar claves privadas dentro del archivo PFX. Si no se especifica este parámetro, el valor predeterminado es TripleDES_SHA1. Los valores permitidos para este parámetro son los siguientes:

Valor Descripción
TripleDES_SHA1 Las claves privadas se cifrarán en el archivo PFX mediante el cifrado Triple DES.
AES256_SHA256 Las claves privadas se cifrarán en el archivo PFX mediante el cifrado AES-256.

OpenSSL admite los dos algoritmos anteriores mediante los siguientes comandos:

  • openssl pkcs12 -keypbe PBE-SHA1-3DES -certpbe PBE-SHA1-3DES -in in.pem -export -out out.pfx -password file:password.txt -passin file:password.txt
  • openssl pkcs12 -keypbe AES-256-CBC -certpbe AES-256-CBC -macalg sha256 -in in.pem -export -out out.pfx -password file:password.txt -passin file:password.txt

Los siguientes comandos son equivalentes a los dos anteriores, pero no cifran los certificados:

  • openssl pkcs12 -keypbe PBE-SHA1-3DES -certpbe NONE -in in.pem -export -out out.pfx -password file:password.txt -passin file:password.txt
  • openssl pkcs12 -keypbe AES-256-CBC -certpbe NONE -macalg sha256 -in in.pem -export -out out.pfx -password file:password.txt -passin file:password.txt

Requisitos

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

Consulte también

PFXExportCertStore

PFXExportCertStoreEx