PFXImportCertStore 함수(wincrypt.h)

  • 아티클

PFXImportCertStore 함수는 PFX BLOB을 가져오고 인증서 및 연결된 프라이빗 키가 포함된 저장소의 핸들을 반환합니다.

구문

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

매개 변수

[in] pPFX

내보낸 인증서와 암호화된 인증서 및 키가 있는 PFX 패킷을 포함하는 CRYPT_DATA_BLOB 구조체에 대한 포인터입니다.

[in] szPassword

PFX 패킷의 암호를 해독하고 확인하는 데 사용되는 문자열 암호입니다. 길이가 0보다 큰 문자열로 설정하든 빈 문자열로 설정하든 NULL로 설정하든 이 값은 패킷을 암호화하는 데 사용된 값과 정확히 동일해야 합니다.

Windows 8 및 Windows Server 2012 시작하여 PFX 패킷이 PKCS12_PROTECT_TO_DOMAIN_SIDS 플래그를 사용하여 PFXExportCertStoreEx 함수에서 만들어진 경우 PFXImportCertStore 함수는 암호를 암호화하는 데 사용된 AD(Active Directory) 보안 주체를 사용하여 암호 해독을 시도합니다. AD 보안 주체는 pvPara 매개 변수에 지정됩니다. PFXExportCertStoreEx 함수의 szPassword 매개 변수가 빈 문자열이거나 NULL이고 dwFlags 매개 변수가 PKCS12_PROTECT_TO_DOMAIN_SIDS 설정된 경우 해당 함수는 임의로 암호를 생성하고 pvPara 매개 변수에 지정된 AD 보안 주체로 암호화합니다. 이 경우 PFX 패킷을 만들 때 사용된 빈 문자열 또는 NULL 값으로 암호를 설정해야 합니다. PFXImportCertStore 함수는 AD 보안 주체를 사용하여 임의 암호를 해독하고 임의로 생성된 암호를 사용하여 PFX 인증서의 암호를 해독합니다.

암호 사용을 마쳤으면 SecureZeroMemory 함수를 호출하여 메모리에서 암호를 지웁 수 있습니다. 암호 보호에 대한 자세한 내용은 암호 처리를 참조하세요.

[in] dwFlags

dwFlags 매개 변수는 다음 값 중 하나일 수 있습니다.

값 의미
CRYPT_EXPORTABLE
0x00000001
 가져온 키가 내보낼 수 있음으로 표시됩니다. 이 플래그를 사용하지 않으면 키 핸들이 있는 CryptExportKey 함수에 대한 호출이 실패합니다.
CRYPT_USER_PROTECTED
0x00000002
 이 키를 사용하려는 특정 시도가 수행되면 대화 상자 또는 다른 방법을 통해 사용자에게 알림을 받습니다. 정확한 동작은 사용 중인 CSP( 암호화 서비스 공급자 )에 의해 지정됩니다.

인터넷 Explorer 4.0 이전에는 Microsoft 암호화 서비스 공급자가 이 플래그를 무시했습니다. 인터넷 Explorer 4.0부터 Microsoft 공급자는 이 플래그를 지원합니다.

공급자 컨텍스트가 CRYPT_SILENT 플래그 집합으로 열린 경우 이 플래그를 사용하면 오류가 발생하고 마지막 오류가 NTE_SILENT_CONTEXT 설정됩니다.
CRYPT_MACHINE_KEYSET
0x00000020
 프라이빗 키는 현재 사용자가 아닌 로컬 컴퓨터 아래에 저장됩니다.
CRYPT_USER_KEYSET
0x00001000
 프라이빗 키는 PFX BLOB이 로컬 컴퓨터로 이동해야 한다고 지정하더라도 로컬 컴퓨터가 아닌 현재 사용자 아래에 저장됩니다.
PKCS12_PREFER_CNG_KSP
0x00000100
 CNG KSP( 키 스토리지 공급자 )가 선호됨을 나타냅니다. CSP가 PFX 파일에 지정된 경우 CSP가 사용되고, 그렇지 않으면 KSP가 선호됩니다. CNG KSP를 사용할 수 없는 경우 PFXImportCertStore 함수가 실패합니다.

Windows Server 2003 및 Windows XP: 이 값은 지원되지 않습니다.
PKCS12_ALWAYS_CNG_KSP
0x00000200
 CNG KSP가 항상 사용됨을 나타냅니다. 지정된 경우 PFXImportCertStore는 PFX 파일의 공급자 정보에 관계없이 CNG KSP를 사용하려고 시도합니다. CNG KSP를 사용할 수 없는 경우 가져오기가 실패하지 않습니다.

Windows Server 2003 및 Windows XP: 이 값은 지원되지 않습니다.
PKCS12_ALLOW_OVERWRITE_KEY
0x00004000
 기존 키를 덮어쓸 수 있습니다. 이미 존재하는 키 이름이 포함된 PFX 파일을 가져와야 하는 시나리오가 발생할 때 이 플래그를 지정합니다. 예를 들어 PFX 파일을 가져올 때 키 컨테이너에 대한 고유한 네임스페이스가 없으므로 동일한 이름의 컨테이너가 이미 있을 수 있습니다. 컴퓨터에 "TestKey"를 만든 다음 "TestKey"가 키 컨테이너로 포함된 PFX 파일을 가져오는 경우 PKCS12_ALLOW_OVERWRITE_KEY 설정을 사용하면 키를 덮어쓸 수 있습니다.

Windows Server 2003 및 Windows XP: 이 값은 지원되지 않습니다.
PKCS12_NO_PERSIST_KEY
0x00008000
 키를 유지하지 마세요. 키를 유지하지 않으려면 이 플래그를 지정합니다. 예를 들어 확인 후 키를 저장할 필요가 없는 경우 컨테이너를 만든 다음 삭제하는 대신 이 플래그를 지정하여 키를 즉시 삭제할 수 있습니다.
참고PKCS12_NO_PERSIST_KEY 플래그가 *not* 설정된 경우 키는 디스크에 유지됩니다. 키를 사용하지 않으려면 dwFlags 매개 변수에 설정된 CRYPT_DELETEKEYSET 플래그를 사용하여 CryptAcquireContext 함수를 호출하여 키를 삭제해야 합니다.
참고 몇 가지 다른 고려 사항:

  • 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
 압축을 풀지만 결과를 유지하지 않습니다.

반환 값

함수가 성공하면 함수는 사용 가능한 프라이빗 키를 포함하여 가져온 인증서를 포함하는 인증서 저장소에 대한 핸들을 반환합니다.

함수가 실패하는 경우, 즉 암호 매개 변수에 내보낸 패킷을 암호화하는 데 사용된 암호와 정확히 일치하지 않거나 PFX BLOB을 디코딩하는 데 다른 문제가 있는 경우 함수는 NULL을 반환하고 GetLastError 함수를 호출하여 오류 코드를 찾을 수 있습니다.

설명

PFXImportCertStore 함수는 임시 저장소를 엽니다. 함수가 성공하면 CertCloseStore 함수를 호출하여 저장소에 대한 핸들을 닫아야 합니다.

PFX 패킷에서 인증서를 가져올 때 CSP/KSP 컨테이너 이름은 PKCS8Shroud의 OID 1.3.6.1.4.1.311.17.1과 함께 AttributeId를 사용하여 결정됩니다.edKeyBag 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 플래그가 전달되지 않으면 공급자 이름은 공개 키 알고리즘에 따라 결정됩니다(즉, 공개 키 알고리즘은 PKCS #8의 AlgorithmIdentifier에 의해 결정됨).

  • Rsa: MS_ENHANCED_PROV_W
  • Dsa: MS_DEF_DSS_DH_PROV_W

마찬가지로 키 사양은 다음과 같이 OID 2.5.29.15(szOID_KEY_USAGE)와 함께 AttributeId를 사용하여 결정됩니다.

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 키 값이 RSA 또는 DH에 대해 AT_KEYEXCHANGE 설정되고 알고리즘은 PKCS #8의 AlgorithmIdentifier에 의해 결정됩니다. 그렇지 않으면 알고리즘이 AT_SIGNATURE 설정됩니다. CNG 키 값의 경우 모든 ncrypt 키 사용이 설정됩니다.

참고

PFX 패킷에 잘못된 공급자 이름이 있거나 기본 또는 향상된 암호화 공급자가 이 레지스트리 키( HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Defaults\Provider)에 없는 경우 이 레지스트리 하위 키인 HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Cryptography\Defaults\Provider Types를 사용하여 공급자 유형에서 공급자 조회를 수행합니다.

Microsoft는 PFX를 가져오기 위한 두 가지 암호화/해시 알고리즘만 지원합니다.

  • TripleDES-SHA1
  • AES256-SHA256

위의 알고리즘 중 하나에 대해 인증서 암호화는 선택 사항입니다.

Microsoft는 선택 항목을 통해 인증서 저장소에서 PFX를 내보낼 All Tasks>Yes, export the private key 수 있습니다. 이 두 가지 선택 항목 중 하나와 일치하도록 암호화/해시 알고리즘을 선택할 수 있습니다.

PowerShell을 사용하여 다음을 통해 PFX를 내보낼 수 있습니다.

Export-PfxCertificate
[-CryptoAlgorithmOption <CryptoAlgorithmOptions>]

-CryptoAlgorithmOption 는 PFX 파일 내에서 프라이빗 키를 암호화하기 위한 알고리즘을 지정합니다. 이 매개 변수를 지정하지 않으면 기본값은 입니다 TripleDES_SHA1. 이 매개 변수에 허용되는 값은 다음과 같습니다.

값 Description
TripleDES_SHA1 프라이빗 키는 Triple DES 암호화를 사용하여 PFX 파일에서 암호화됩니다.
AES256_SHA256 프라이빗 키는 AES-256 암호화를 사용하여 PFX 파일에서 암호화됩니다.

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
헤더 wincrypt.h
라이브러리 Crypt32.lib
DLL Crypt32.dll

추가 정보

PFXExportCertStore

PFXExportCertStoreEx