Partilhar via


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
CRYPT_EXPORTABLE
0x00000001
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.
CRYPT_USER_PROTECTED
0x00000002
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.

CRYPT_MACHINE_KEYSET
0x00000020
As chaves privadas são armazenadas no computador local e não no usuário atual.
CRYPT_USER_KEYSET
0x00001000
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.
PKCS12_PREFER_CNG_KSP
0x00000100
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.

PKCS12_ALWAYS_CNG_KSP
0x00000200
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.

PKCS12_ALLOW_OVERWRITE_KEY
0x00004000
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.

PKCS12_NO_PERSIST_KEY
0x00008000
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:
  • Ao usar PKCS12_NO_PERSIST_KEY, a propriedade CERT_KEY_CONTEXT_PROP_ID é definida internamente no certificado e CERT_KEY_CONTEXT_PROP_ID contém o NCRYPT_KEY_HANDLE.

  • Se o PKCS12_NO_PERSIST_KEY não for usado, a propriedade CERT_KEY_PROV_INFO_PROP_ID será definida.

  • Se o certificado com a chave não persistente for empacotado para outro processo, a propriedade CERT_KEY_CONTEXT_PROP_ID não será empacotada.

  • Para que NO_PERSIST funcione, ele deve estar no mesmo processo e o usuário do PCCERT_CONTEXT deve dar suporte ao CERT_KEY_CONTEXT_PROP_ID. Isso normalmente se aplica durante um handshake TLS: se o handshake for executado externamente no processo de chamada em LSASS.exe, não será possível usar PKCS12_NO_PERSIST_KEY ao mover do processo de chamada para o LSASS (porque o NCRYPT_KEY_HANDLE é um ponteiro para uma estrutura de dados e não um identificador de kernel).

 
Windows Server 2003 e Windows XP: Não há suporte para esse valor.
PKCS12_INCLUDE_EXTENDED_PROPERTIES
0x0010
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.

0x10000000
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.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

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.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 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

Confira também

PFXExportCertStore

PFXExportCertStoreEx