Функция PFXImportCertStore (wincrypt.h)
Функция PFXImportCertStore импортирует большой двоичный объект PFX и возвращает дескриптор хранилища, содержащего сертификаты и все связанные закрытые ключи.
Синтаксис
HCERTSTORE PFXImportCertStore(
[in] CRYPT_DATA_BLOB *pPFX,
[in] LPCWSTR szPassword,
[in] DWORD dwFlags
);
Параметры
[in] pPFX
Указатель на структуру CRYPT_DATA_BLOB , содержащую пакет PFX с экспортируемыми и зашифрованными сертификатами и ключами.
[in] szPassword
Строковый пароль, используемый для расшифровки и проверки пакета PFX. Независимо от того, задано ли значение строки длиной больше нуля или для пустой строки или значения NULL, это значение должно быть точно таким же, как и значение, использованное для шифрования пакета.
Начиная с Windows 8 и Windows Server 2012, если пакет PFX был создан в функции PFXExportCertStoreEx с помощью флага PKCS12_PROTECT_TO_DOMAIN_SIDS, функция PFXImportCertStore попытается расшифровать пароль с помощью субъекта Active Directory (AD), который использовался для его шифрования. Субъект AD указывается в параметре pvPara . Если параметр szPassword в функции PFXExportCertStoreEx был пустой строкой или значением NULL , а параметру dwFlags было присвоено значение PKCS12_PROTECT_TO_DOMAIN_SIDS, эта функция случайным образом сгенерировала пароль и зашифровала его для субъекта AD, указанного в параметре pvPara . В этом случае следует задать для пароля значение пустой строки или NULL, которое использовалось при создании пакета PFX. Функция PFXImportCertStore будет использовать субъект AD для расшифровки случайного пароля, а случайно созданный пароль будет использоваться для расшифровки сертификата PFX.
Завершив использование пароля, очистите его из памяти, вызвав функцию SecureZeroMemory . Дополнительные сведения о защите паролей см. в разделе Обработка паролей.
[in] dwFlags
Параметр dwFlags может иметь одно из следующих значений:
| Значение | Значение |
|---|---|
|
Импортированные ключи помечаются как доступные для экспорта. Если этот флаг не используется, вызовы функции CryptExportKey с дескриптором ключа завершаются ошибкой. |
|
Пользователь должен получать уведомление с помощью диалогового окна или другого метода при определенных попытках использовать этот ключ. Точное поведение определяется используемым поставщиком служб шифрования (CSP).
До internet Обозреватель 4.0 поставщики служб шифрования Майкрософт игнорируют этот флаг. Начиная с Internet Обозреватель 4.0, поставщики Майкрософт поддерживают этот флаг. Если контекст поставщика был открыт с установленным флагом CRYPT_SILENT, использование этого флага приведет к сбою, а последняя ошибка имеет значение NTE_SILENT_CONTEXT. |
|
Закрытые ключи хранятся на локальном компьютере, а не под текущим пользователем. |
|
Закрытые ключи хранятся у текущего пользователя, а не на локальном компьютере, даже если большой двоичный объект PFX указывает, что они должны перейти на локальный компьютер. |
|
Указывает, что поставщик хранилища ключей CNG (KSP) является предпочтительным. Если поставщик служб конфигурации указан в PFX-файле, то используется CSP, в противном случае предпочтительнее использовать KSP. Если KSP CNG недоступен, функция PFXImportCertStore завершится ошибкой .
Windows Server 2003 и Windows XP: Это значение не поддерживается. |
|
Указывает, что CNG KSP используется всегда. Если этот параметр указан, PFXImportCertStore пытается использовать KSP CNG независимо от сведений о поставщике в PFX-файле. Если поставщик ключей CNG недоступен, импорт не завершится ошибкой.
Windows Server 2003 и Windows XP: Это значение не поддерживается. |
|
Разрешить перезапись существующего ключа. Укажите этот флаг при возникновении сценария, в котором необходимо импортировать PFX-файл, содержащий уже существующее имя ключа. Например, при импорте PFX-файла возможно, что контейнер с таким же именем уже присутствует, так как для контейнеров ключей нет уникального пространства имен. Если вы создали "TestKey" на компьютере, а затем импортировали PFX-файл, который также содержит TestKey в качестве контейнера ключей, параметр PKCS12_ALLOW_OVERWRITE_KEY позволяет перезаписать ключ.
Windows Server 2003 и Windows XP: Это значение не поддерживается. |
|
Не сохраняйте ключ. Укажите этот флаг, если не требуется сохранять ключ. Например, если не требуется хранить ключ после проверки, то вместо создания контейнера и его удаления можно указать этот флаг для немедленного удаления ключа.
Примечание Если флаг PKCS12_NO_PERSIST_KEY установлен *не*, ключи сохраняются на диске. Если вы не хотите сохранять ключи после их использования, необходимо удалить их, вызвав функцию CryptAcquireContext с флагом CRYPT_DELETEKEYSET , установленным в параметре dwFlags .
Примечание Некоторые другие рекомендации:
|
|
Импортируйте все расширенные свойства сертификата, которые были сохранены в сертификате при его экспорте.
Windows Server 2003 и Windows XP: Это значение не поддерживается. |
|
Распакуйте результаты, но не сохраните их. |
Возвращаемое значение
Если функция выполняется успешно, функция возвращает дескриптор в хранилище сертификатов, которое содержит импортированные сертификаты, включая доступные закрытые ключи.
Если функция завершается сбоем, то есть если параметр password не содержит точного совпадения с паролем, используемым для шифрования экспортированного пакета, или возникли другие проблемы с декодированием большого двоичного объекта PFX, функция возвращает значение NULL, и код ошибки можно найти, вызвав функцию GetLastError .
Комментарии
Функция PFXImportCertStore открывает временное хранилище. Если функция завершается успешно, следует закрыть дескриптор для хранилища, вызвав функцию CertCloseStore .
При импорте сертификата из пакета PFX Имя контейнера CSP/KSP определяется с помощью AttributeId с идентификатором OID 1.3.6.1.4.1.311.17.1 объекта PKCS8ShroudedKeyBag SafeBag [bagId: 1.2.840.113549.1.12.10.1.2] (дополнительные сведения о структуре ASN.1 см. в разделе PKCS #12 ).
- AttributeId: 1.3.6.1.4.1.311.17.1
- Значение: Имя KSP или CSP
Если attributeId отсутствует и флаг PREFER_CNG передается, выбирается MS_KEY_STORAGE_PROVIDER. Если атрибут AttributeId отсутствует и флаг PREFER_CNG не передается, имя поставщика определяется на основе алгоритма открытого ключа (то есть алгоритм открытого ключа определяется алгоритмом AlgorithmIdentifier в PKCS #8):
- RSA: MS_ENHANCED_PROV_W
- DSA: MS_DEF_DSS_DH_PROV_W
Аналогичным образом спецификация ключа определяется с помощью AttributeId с OID 2.5.29.15 (szOID_KEY_USAGE) следующим образом:
Если используется ключ CAPI:
- Если задано KEY_ENCIPHERMENT или DATA_ENCIPHERMENT, то для спецификации ключа устанавливается значение AT_KEYEXCHANGE.
- Если задано DIGITAL_SIGNATURE, CERT_SIGN или CRL_SIGN, то для спецификации ключа устанавливается значение AT_SIGNATURE.
Если используется ключ CNG:
- Если задан KEY_ENCIPHERMENT, DATA_ENCIPHERMENT, ENCIPHER_ONLY или DECIPHER_ONLY, то для использования ключа ncrypt устанавливается значение ALLOW_DECRYPT.
- Если задано DIGITAL_SIGNATURE, CERT_SIGN или CRL_SIGN, для использования ключа ncrypt устанавливается значение ALLOW_SIGN.
- Если задано KEY_AGREEMENT, то для использования ключа ncrypt устанавливается значение ALLOW_KEY_AGREEMENT.
Если атрибут AttributeId отсутствует, значение ключа CAPI устанавливается в AT_KEYEXCHANGE для RSA или DH, а алгоритм определяется алгоритмом AlgorithmIdentifier в PKCS #8; В противном случае для алгоритма задано значение AT_SIGNATURE. Для значения ключа CNG задается все использование ключа ncrypt.
Примечание
Если в пакете PFX присутствует недопустимое имя поставщика или базовый или расширенный поставщик шифрования отсутствует в этом разделе реестра: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Defaults\Provider, то поиск поставщика выполняется поставщиком типа с помощью этого подраздела реестра: HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Defaults\Provider Types.
Корпорация Майкрософт поддерживает только два алгоритма шифрования и хэширования для импорта PFX:
- TripleDES-SHA1
- AES256-SHA256
Для любого из приведенных выше алгоритмов шифрование сертификатов является необязательным.
Корпорация Майкрософт может экспортировать PFX-файл из хранилища сертификатов с помощью выбранного All Tasks>Yes, export the private key элемента. Здесь можно выбрать алгоритм шифрования и хэширования, чтобы он соответствовал одному из этих двух вариантов.
С помощью PowerShell можно экспортировать PFX-файл следующим образом:
Export-PfxCertificate
[-CryptoAlgorithmOption <CryptoAlgorithmOptions>]
-CryptoAlgorithmOption задает алгоритм шифрования закрытых ключей в PFX-файле. Если этот параметр не указан, по умолчанию используется значение TripleDES_SHA1. Допустимые значения для этого параметра:
| Значение | Описание |
|---|---|
TripleDES_SHA1 |
Закрытые ключи будут зашифрованы в PFX-файле с помощью шифрования Triple DES. |
AES256_SHA256 |
Закрытые ключи будут зашифрованы в PFX-файле с помощью шифрования AES-256. |
OpenSSL поддерживает указанные выше два алгоритма с помощью следующих команд:
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
Следующие команды эквивалентны предыдущим двум, но они не шифруют сертификаты:
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
Требования
| Требование | Значение |
|---|---|
| Минимальная версия клиента | Windows XP [классические приложения | Приложения UWP] |
| Минимальная версия сервера | Windows Server 2003 [классические приложения | Приложения UWP] |
| Целевая платформа | Windows |
| Header | wincrypt.h |
| Библиотека | Crypt32.lib |
| DLL | Crypt32.dll |