Функция 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 может иметь одно из следующих значений:

Значение Значение
CRYPT_EXPORTABLE
0x00000001
 Импортированные ключи помечаются как доступные для экспорта. Если этот флаг не используется, вызовы функции CryptExportKey с дескриптором ключа завершаются ошибкой.
CRYPT_USER_PROTECTED
0x00000002
 Пользователь должен получать уведомление с помощью диалогового окна или другого метода при определенных попытках использовать этот ключ. Точное поведение определяется используемым поставщиком служб шифрования (CSP).

До internet Обозреватель 4.0 поставщики служб шифрования Майкрософт игнорируют этот флаг. Начиная с Internet Обозреватель 4.0, поставщики Майкрософт поддерживают этот флаг.

Если контекст поставщика был открыт с установленным флагом CRYPT_SILENT, использование этого флага приведет к сбою, а последняя ошибка имеет значение NTE_SILENT_CONTEXT.
CRYPT_MACHINE_KEYSET
0x00000020
 Закрытые ключи хранятся на локальном компьютере, а не под текущим пользователем.
CRYPT_USER_KEYSET
0x00001000
 Закрытые ключи хранятся у текущего пользователя, а не на локальном компьютере, даже если большой двоичный объект PFX указывает, что они должны перейти на локальный компьютер.
PKCS12_PREFER_CNG_KSP
0x00000100
 Указывает, что поставщик хранилища ключей CNG (KSP) является предпочтительным. Если поставщик служб конфигурации указан в PFX-файле, то используется CSP, в противном случае предпочтительнее использовать KSP. Если KSP CNG недоступен, функция PFXImportCertStore завершится ошибкой .

Windows Server 2003 и Windows XP: Это значение не поддерживается.
PKCS12_ALWAYS_CNG_KSP
0x00000200
 Указывает, что CNG KSP используется всегда. Если этот параметр указан, PFXImportCertStore пытается использовать KSP CNG независимо от сведений о поставщике в PFX-файле. Если поставщик ключей CNG недоступен, импорт не завершится ошибкой.

Windows Server 2003 и Windows XP: Это значение не поддерживается.
PKCS12_ALLOW_OVERWRITE_KEY
0x00004000
 Разрешить перезапись существующего ключа. Укажите этот флаг при возникновении сценария, в котором необходимо импортировать PFX-файл, содержащий уже существующее имя ключа. Например, при импорте PFX-файла возможно, что контейнер с таким же именем уже присутствует, так как для контейнеров ключей нет уникального пространства имен. Если вы создали "TestKey" на компьютере, а затем импортировали PFX-файл, который также содержит TestKey в качестве контейнера ключей, параметр PKCS12_ALLOW_OVERWRITE_KEY позволяет перезаписать ключ.

Windows Server 2003 и Windows XP: Это значение не поддерживается.
PKCS12_NO_PERSIST_KEY
0x00008000
 Не сохраняйте ключ. Укажите этот флаг, если не требуется сохранять ключ. Например, если не требуется хранить ключ после проверки, то вместо создания контейнера и его удаления можно указать этот флаг для немедленного удаления ключа.
Примечание Если флаг PKCS12_NO_PERSIST_KEY установлен *не*, ключи сохраняются на диске. Если вы не хотите сохранять ключи после их использования, необходимо удалить их, вызвав функцию CryptAcquireContext с флагом CRYPT_DELETEKEYSET , установленным в параметре dwFlags .
Примечание Некоторые другие рекомендации:

  • При использовании PKCS12_NO_PERSIST_KEY CERT_KEY_CONTEXT_PROP_ID свойства задается внутри сертификата, а CERT_KEY_CONTEXT_PROP_ID содержит NCRYPT_KEY_HANDLE.

  • Если PKCS12_NO_PERSIST_KEY не используется, задается свойство CERT_KEY_PROV_INFO_PROP_ID.

  • Если сертификат с несохраняющимся ключом маршалируется в другой процесс, свойство CERT_KEY_CONTEXT_PROP_ID не будет маршалировано.

  • Чтобы NO_PERSIST работали, он должен находиться в одном процессе, и пользователь PCCERT_CONTEXT должен поддерживать CERT_KEY_CONTEXT_PROP_ID. Обычно это применяется при подтверждении TLS: если подтверждение выполняется за пределами вызывающего процесса в LSASS.exe, то при переходе от вызывающего процесса к LSASS использовать PKCS12_NO_PERSIST_KEY невозможно (поскольку NCRYPT_KEY_HANDLE является указателем на структуру данных, а не дескриптор ядра).

 
Windows Server 2003 и Windows XP: Это значение не поддерживается.
PKCS12_INCLUDE_EXTENDED_PROPERTIES
0x0010
 Импортируйте все расширенные свойства сертификата, которые были сохранены в сертификате при его экспорте.

Windows Server 2003 и Windows XP: Это значение не поддерживается.
0x10000000
 Распакуйте результаты, но не сохраните их.

Возвращаемое значение

Если функция выполняется успешно, функция возвращает дескриптор в хранилище сертификатов, которое содержит импортированные сертификаты, включая доступные закрытые ключи.

Если функция завершается сбоем, то есть если параметр 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.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

Следующие команды эквивалентны предыдущим двум, но они не шифруют сертификаты:

  • 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

Требования

Требование Значение
Минимальная версия клиента Windows XP [классические приложения | Приложения UWP]
Минимальная версия сервера Windows Server 2003 [классические приложения | Приложения UWP]
Целевая платформа Windows
Header wincrypt.h
Библиотека Crypt32.lib
DLL Crypt32.dll

См. также раздел

PFXExportCertStore

PFXExportCertStoreEx