Função PFXImportCertStore (wincrypt.h)
A função PFXImportCertStore importa um BLOB PFX e retorna o identificador de um repositório que contém certificados e quaisquer chaves privadas associadas.
Sintaxe
HCERTSTORE PFXImportCertStore(
[in] CRYPT_DATA_BLOB *pPFX,
[in] LPCWSTR szPassword,
[in] DWORD dwFlags
);
Parâmetros
[in] pPFX
Um ponteiro para uma estrutura CRYPT_DATA_BLOB que contém um pacote PFX com os certificados e chaves exportados e criptografados.
[in] szPassword
Uma senha de cadeia de caracteres usada para descriptografar e verificar o pacote PFX. Seja definido como uma cadeia de caracteres de comprimento maior que zero ou definido como uma cadeia de caracteres vazia ou como NULL, esse valor deve ser exatamente o mesmo que o valor usado para criptografar o pacote.
Começando com Windows 8 e Windows Server 2012, se o pacote PFX tiver sido criado na função PFXExportCertStoreEx usando o sinalizador PKCS12_PROTECT_TO_DOMAIN_SIDS, a função PFXImportCertStore tentará descriptografar a senha usando a entidade de segurança do Active Directory (AD) usada para criptografá-la. A entidade de segurança do AD é especificada no parâmetro pvPara . Se o parâmetro szPassword na função PFXExportCertStoreEx era uma cadeia de caracteres vazia ou NULL e o parâmetro dwFlags foi definido como PKCS12_PROTECT_TO_DOMAIN_SIDS, essa função gerou aleatoriamente uma senha e a criptografou para a entidade de segurança do AD especificada no parâmetro pvPara . Nesse caso, você deve definir a senha para o valor, cadeia de caracteres vazia ou NULL, que foi usado quando o pacote PFX foi criado. A função PFXImportCertStore usará a entidade de segurança do AD para descriptografar a senha aleatória e a senha gerada aleatoriamente será usada para descriptografar o certificado PFX.
Quando terminar de usar a senha, limpe-a da memória chamando a função SecureZeroMemory . Para obter mais informações sobre como proteger senhas, consulte Manipulando senhas.
[in] dwFlags
O parâmetro dwFlags pode ser um dos seguintes valores:
| Valor | Significado |
|---|---|
|
As chaves importadas são marcadas como exportáveis. Se esse sinalizador não for usado, as chamadas para a função CryptExportKey com o identificador de chave falharão. |
|
O usuário deve ser notificado por meio de uma caixa de diálogo ou outro método quando determinadas tentativas de usar essa chave forem feitas. O comportamento preciso é especificado pelo CSP ( provedor de serviços criptográficos ) que está sendo usado.
Antes do Internet Explorer 4.0, os provedores de serviços criptográficos da Microsoft ignoravam esse sinalizador. A partir do Internet Explorer 4.0, os provedores da Microsoft dão suporte a esse sinalizador. Se o contexto do provedor foi aberto com o sinalizador CRYPT_SILENT definido, usar esse sinalizador causará uma falha e o último erro será definido como NTE_SILENT_CONTEXT. |
|
As chaves privadas são armazenadas no computador local e não no usuário atual. |
|
As chaves privadas são armazenadas no usuário atual e não no computador local, mesmo que o BLOB PFX especifique que elas devem entrar no computador local. |
|
Indica que o KSP ( provedor de armazenamento de chaves CNG) é preferencial. Se o CSP for especificado no arquivo PFX, o CSP será usado, caso contrário, o KSP será preferencial. Se o CNG KSP não estiver disponível, a função PFXImportCertStore falhará.
Windows Server 2003 e Windows XP: Não há suporte para esse valor. |
|
Indica que o CNG KSP é sempre usado. Quando especificado, PFXImportCertStore tenta usar o KSP do CNG, independentemente das informações do provedor no arquivo PFX. Se o CNG KSP não estiver disponível, a importação não falhará.
Windows Server 2003 e Windows XP: Não há suporte para esse valor. |
|
Permitir substituição da chave existente. Especifique esse sinalizador quando encontrar um cenário no qual você deve importar um arquivo PFX que contenha um nome de chave que já existe. Por exemplo, quando você importa um arquivo PFX, é possível que um contêiner de mesmo nome já esteja presente porque não há namespace exclusivo para contêineres de chave. Se você tiver criado uma "TestKey" no computador e importar um arquivo PFX que também tenha "TestKey" como o contêiner de chave, a configuração PKCS12_ALLOW_OVERWRITE_KEY permitirá que a chave seja substituída.
Windows Server 2003 e Windows XP: Não há suporte para esse valor. |
|
Não persista a chave. Especifique esse sinalizador quando você não quiser persistir a chave. Por exemplo, se não for necessário armazenar a chave após a verificação, em vez de criar um contêiner e excluí-la, você poderá especificar esse sinalizador para descartar a chave imediatamente.
Nota Se o sinalizador PKCS12_NO_PERSIST_KEY for *not* definido, as chaves serão mantidas no disco. Se você não quiser persistir as chaves além do uso, exclua-as chamando a função CryptAcquireContext com o sinalizador CRYPT_DELETEKEYSET definido no parâmetro dwFlags .
Nota Algumas outras considerações:
|
|
Importe todas as propriedades estendidas no certificado que foram salvas no certificado quando ele foi exportado.
Windows Server 2003 e Windows XP: Não há suporte para esse valor. |
|
Desempacotar, mas não persistir os resultados. |
Retornar valor
Se a função for bem-sucedida, a função retornará um identificador para um repositório de certificados que contém os certificados importados, incluindo chaves privadas disponíveis.
Se a função falhar, ou seja, se o parâmetro de senha não contiver uma correspondência exata com a senha usada para criptografar o pacote exportado ou se houver outros problemas ao decodificar o BLOB PFX, a função retornará NULL e um código de erro poderá ser encontrado chamando a função GetLastError .
Comentários
A função PFXImportCertStore abre um repositório temporário. Se a função for bem-sucedida, você deverá fechar o identificador para o repositório chamando a função CertCloseStore .
Quando você importa um certificado do pacote PFX, o nome do contêiner CSP/KSP é determinado usando o AttributeId com OID 1.3.6.1.4.1.311.17.1 do cofre PKCS8ShroudedKeyBagBag [bagId: 1.2.840.113549.1.12.10.1.2] (consulte PKCS #12 para obter detalhes sobre a estrutura ASN.1 disso).
- AttributeId: 1.3.6.1.4.1.311.17.1
- Valor: O nome KSP ou o nome CSP
Se a AttributeId não estiver presente e o sinalizador PREFER_CNG for passado, MS_KEY_STORAGE_PROVIDER será escolhido. Se a AttributeId não estiver presente e o sinalizador PREFER_CNG não for passado, o nome do provedor será determinado com base no algoritmo de chave pública (ou seja, o algoritmo de chave pública é determinado pelo AlgorithmIdentifier no PKCS #8):
- RSA: MS_ENHANCED_PROV_W
- DSA: MS_DEF_DSS_DH_PROV_W
Da mesma forma, a especificação de chave é determinada usando a AttributeId com o OID 2.5.29.15 (szOID_KEY_USAGE) da seguinte maneira:
Se uma chave CAPI for usada:
- Se KEY_ENCIPHERMENT ou DATA_ENCIPHERMENT estiver definido, a especificação de chave será definida como AT_KEYEXCHANGE.
- Se DIGITAL_SIGNATURE ou CERT_SIGN ou CRL_SIGN estiver definido, a especificação de chave será definida como AT_SIGNATURE.
Se uma chave CNG for usada:
- Se KEY_ENCIPHERMENT ou DATA_ENCIPHERMENT ou ENCIPHER_ONLY ou DECIPHER_ONLY estiver definido, o uso da chave ncrypt será definido como ALLOW_DECRYPT.
- Se DIGITAL_SIGNATURE ou CERT_SIGN ou CRL_SIGN estiver definido, o uso da chave ncrypt será definido como ALLOW_SIGN.
- Se KEY_AGREEMENT estiver definido, o uso da chave ncrypt será definido como ALLOW_KEY_AGREEMENT.
Se a AttributeId não estiver presente, o valor da chave CAPI será definido como AT_KEYEXCHANGE para RSA ou DH e o algoritmo será determinado pelo AlgorithmIdentifier no PKCS #8; caso contrário, o algoritmo será definido como AT_SIGNATURE. Para o valor da chave CNG, todo o uso da chave ncrypt é definido.
Observação
Se um nome de provedor inválido estiver presente no pacote PFX ou o provedor de criptografia base ou aprimorado não estiver presente nesta chave do Registro: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Defaults\Provider, uma pesquisa de provedor será executada pelo tipo de provedor usando esta subchave do Registro: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Defaults\Provider Types.
A Microsoft só dá suporte a dois algoritmos de criptografia/hash para importar um PFX:
- TripleDES-SHA1
- AES256-SHA256
Para qualquer um dos algoritmos acima, a criptografia dos certificados é opcional.
A Microsoft pode exportar um PFX de um repositório de certificados por meio da All Tasks>Yes, export the private key seleção. Lá, você pode selecionar o algoritmo de criptografia/hash para corresponder a uma dessas duas opções.
Você pode usar o PowerShell para exportar um PFX por meio do seguinte:
Export-PfxCertificate
[-CryptoAlgorithmOption <CryptoAlgorithmOptions>]
-CryptoAlgorithmOption especifica o algoritmo para criptografar chaves privadas dentro do arquivo PFX. Se esse parâmetro não for especificado, o padrão será TripleDES_SHA1. Os valores aceitáveis para esse parâmetro são:
| Valor | Descrição |
|---|---|
TripleDES_SHA1 |
As chaves privadas serão criptografadas no arquivo PFX usando a criptografia DES tripla. |
AES256_SHA256 |
As chaves privadas serão criptografadas no arquivo PFX usando a criptografia AES-256. |
O OpenSSL dá suporte aos dois algoritmos acima por meio dos seguintes 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.txtopenssl 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
Os comandos a seguir são equivalentes aos dois anteriores, mas não criptografam os certificados:
openssl pkcs12 -keypbe PBE-SHA1-3DES -certpbe NONE -in in.pem -export -out out.pfx -password file:password.txt -passin file:password.txtopenssl 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 | Valor |
|---|---|
| Cliente mínimo com suporte | Windows XP [aplicativos da área de trabalho | aplicativos UWP] |
| Servidor mínimo com suporte | Windows Server 2003 [aplicativos da área de trabalho | Aplicativos UWP] |
| Plataforma de Destino | Windows |
| Cabeçalho | wincrypt.h |
| Biblioteca | Crypt32.lib |
| DLL | Crypt32.dll |