NCryptImportKey 함수(ncrypt.h)

아티클
05/29/2024

NCryptImportKey 함수는 메모리 BLOB에서 Cryptography API: Next Generation(CNG) 키를 가져옵니다.

구문

SECURITY_STATUS NCryptImportKey(
  [in]           NCRYPT_PROV_HANDLE hProvider,
  [in, optional] NCRYPT_KEY_HANDLE  hImportKey,
  [in]           LPCWSTR            pszBlobType,
  [in, optional] NCryptBufferDesc   *pParameterList,
  [out]          NCRYPT_KEY_HANDLE  *phKey,
  [in]           PBYTE              pbData,
  [in]           DWORD              cbData,
  [in]           DWORD              dwFlags
);

매개 변수

[in] hProvider

키 스토리지 공급자의 핸들입니다.

[in, optional] hImportKey

가져온 키 BLOB 내의 키 데이터가 암호화된 암호화 키의 핸들입니다. NCryptExportKey 함수의 hExportKey 매개 변수에 전달된 것과 동일한 키에 대한 핸들이어야 합니다. 이 매개 변수가 NULL인 경우 키 BLOB은 암호화되지 않은 것으로 간주됩니다.

[in] pszBlobType

키 BLOB의 형식을 지정하는 식별자를 포함하는 null로 끝나는 유니코드 문자열입니다. 이러한 형식은 특정 키 스토리지 공급자와 관련이 있습니다. Microsoft 공급자가 지원하는 BLOB 형식은 비고를 참조하세요.

[in, optional] pParameterList

키에 대한 매개 변수 정보가 포함된 버퍼 배열을 가리키는 NCryptBufferDesc 구조체의 주소입니다.

[out] phKey

키의 핸들을 수신하는 NCRYPT_KEY_HANDLE 변수의 주소입니다. 이 핸들 사용을 마쳤으면 NCryptFreeObject 함수에 전달하여 해제합니다.

[in] pbData

가져올 키 BLOB이 포함된 버퍼의 주소입니다. cbData 매개 변수에는 이 버퍼의 크기가 포함됩니다.

[in] cbData

pbData 버퍼의 크기(바이트)입니다.

[in] dwFlags

함수 동작을 수정하는 플래그입니다. 이 값은 0이거나 다음 값 중 하나 이상의 조합일 수 있습니다. 유효한 플래그 집합은 각 키 스토리지 공급자에 따라 다릅니다.

값	의미
NCRYPT_SILENT_FLAG	KSP(키 서비스 공급자)가 사용자 인터페이스를 표시하지 않도록 요청합니다. 공급자가 작동할 UI를 표시해야 하는 경우 호출이 실패하고 KSP가 NTE_SILENT_CONTEXT 오류 코드를 마지막 오류로 설정해야 합니다.
NCRYPT_REQUIRE_VBS_FLAG	키를 VBS(가상화 기반 보안)로 보호해야 했음을 나타냅니다. 기본적으로 다시 부팅 주기 동안 유지되는 디스크에 저장된 부팅 간 지속형 키를 만듭니다. VBS를 사용할 수 없는 경우 작업이 실패합니다. (*설명 참조)
NCRYPT_PREFER_VBS_FLAG	VBS(가상화 기반 보안)로 키를 보호해야 했음을 나타냅니다. 기본적으로 다시 부팅 주기 동안 유지되는 디스크에 저장된 부팅 간 지속형 키를 만듭니다. VBS를 사용할 수 없는 경우 작업은 소프트웨어 격리 키를 생성합니다. (*설명 참조)
NCRYPT_USE_PER_BOOT_KEY_FLAG	NCRYPT_REQUIRE_VBS_FLAG 또는NCRYPT_PREFER_VBS_FLAG 함께 사용할 수 있는 추가 플래그입니다. VBS(가상화 기반 보안)에 디스크에 저장되어 있지만 부팅 주기 동안 재사용할 수 없는 부팅당 키로 클라이언트 키를 보호하도록 지시합니다. (*설명 참조)

반환 값

함수의 성공 또는 실패를 나타내는 상태 코드를 반환합니다.

가능한 반환 코드에는 다음이 포함되지만 이에 국한되지는 않습니다.

반환 코드	설명
ERROR_SUCCESS	함수가 성공했습니다.
NTE_BAD_FLAGS	dwFlags 매개 변수에는 유효하지 않은 값이 포함되어 있습니다.
NTE_EXISTS	지정된 이름의 키가 이미 있고 NCRYPT_OVERWRITE_KEY_FLAG 지정되지 않았습니다.
NTE_INVALID_HANDLE	hProvider 매개 변수가 잘못되었습니다.
NTE_INVALID_PARAMETER	하나 이상의 매개 변수가 유효하지 않습니다.
NTE_NO_MEMORY	메모리 할당 오류가 발생했습니다.
NTE_VBS_UNAVAILABLE	VBS를 사용할 수 없습니다.
NTE_VBS_CANNOT_DECRYPT_KEY	VBS에서 암호 해독 작업에 실패했습니다.

설명

중요

VBS 플래그에 대한 정보는 상용 출시 전에 실질적으로 수정될 수 있는 시험판 제품과 관련이 있습니다. Microsoft는 여기에 제공된 정보에 대해 어떠한 명시적이거나 묵시적인 보증도 하지 않습니다.

서비스에서 StartService 함수에서 이 함수를 호출해서는 안됩니다. 서비스에서 StartService 함수에서 이 함수를 호출하면 교착 상태가 발생할 수 있으며 서비스가 응답을 중지할 수 있습니다.

다음 섹션에서는 Microsoft 키 스토리지 공급자와 관련된 동작에 대해 설명합니다.

Microsoft Software KSP
Microsoft 스마트 카드 KSP

Microsoft Software KSP

다음 상수는 pszBlobType 매개 변수에 대한 Microsoft 소프트웨어 KSP에서 지원됩니다.

키 이름이 제공되지 않으면 Microsoft Software KSP는 키를 임시로 처리하고 영구적으로 저장하지 않습니다. NCRYPT_OPAQUETRANSPORT_BLOB 형식의 경우 키 이름은 내보낼 때 BLOB 내에 저장됩니다. 다른 BLOB 형식의 경우 pParameterList 매개 변수 내의 NCRYPTBUFFER_PKCS_KEY_NAME 버퍼 매개 변수에 이름을 제공할 수 있습니다.

Windows Server 2008 및 Windows Vista에서는 위의 방법을 사용하여 PKCS #7 봉투 BLOB(NCRYPT_PKCS7_ENVELOPE_BLOB) 또는 PKCS #8 프라이빗 키 BLOB(NCRYPT_PKCS8_PRIVATE_KEY_BLOB)으로 가져온 키만 유지할 수 있습니다. 이러한 플랫폼에서 다른 BLOB 형식을 통해 가져온 키를 유지하려면 키 가져오기 및 내보내기에서 문서화된 메서드를 사용합니다.

다음 플래그는 이 KSP에서 지원됩니다.

용어	Description
NCRYPT_NO_KEY_VALIDATION	키 쌍의 공개 부분의 유효성을 검사하지 마세요. 이 플래그는 퍼블릭/프라이빗 키 쌍에만 적용됩니다.
NCRYPT_DO_NOT_FINALIZE_FLAG	키를 완료하지 마세요. 이 옵션은 키를 가져온 후 키의 속성을 추가하거나 수정해야 하는 경우에 유용합니다. 키 핸들을 NCryptFinalizeKey 함수에 전달하여 키를 사용하려면 먼저 키를 완료해야 합니다. 이 플래그는 프라이빗 키 PKCS #7 및 PKCS #8에 대해 지원되지만 공개 키는 지원되지 않습니다.
NCRYPT_MACHINE_KEY_FLAG	키는 로컬 컴퓨터에 적용됩니다. 이 플래그가 없으면 키가 현재 사용자에게 적용됩니다.
NCRYPT_OVERWRITE_KEY_FLAG	지정된 이름의 컨테이너에 키가 이미 있는 경우 기존 키를 덮어씁니다. 이 플래그를 지정하지 않고 지정된 이름의 키가 이미 있는 경우 이 함수는 NTE_EXISTS 반환합니다.
NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FLAG	또한 레거시 스토리지에 키를 저장합니다. 이렇게 하면 암호화API와 함께 키를 사용할 수 있습니다. 이 플래그는 RSA 키에만 적용됩니다.

Microsoft 스마트 카드 KSP

이 KSP에서 지원하는 주요 BLOB 형식 및 플래그 집합은 Microsoft Software KSP에서 지원하는 집합과 동일합니다.

Windows Server 2008 및 Windows Vista에서 Microsoft 스마트 카드 KSP는 모든 키를 Microsoft 소프트웨어 KSP로 가져옵니다. 따라서 이 API를 사용하여 스마트 카드에 키를 유지할 수 없으며, 위의 섹션의 지침은 Microsoft Software KSP 내에서 키를 유지하려고 할 때 적용됩니다.

Windows Server 2008 R2 및 Windows 7에서 Microsoft 스마트 카드 키 스토리지 공급자는 다음 조건이 충족되면 프라이빗 키를 스마트 카드로 가져올 수 있습니다.

카드의 키 컨테이너 이름이 유효합니다.
프라이빗 키 가져오기는 스마트 카드에서 지원됩니다.
다음 두 레지스트리 키는 의 0x1DWORD로 설정됩니다.
- HKLM\SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Microsoft Base Smart Card Crypto Provider\AllowPrivateExchangeKeyImport
- HKLM\SOFTWARE\Microsoft\Cryptography\Defaults\Provider\Microsoft Base Smart Card Crypto Provider\AllowPrivateSignatureKeyImport

키 컨테이너 이름이 NULL인 경우 Microsoft 스마트 카드 KSP는 키를 임시로 처리하고 Microsoft 소프트웨어 KSP로 가져옵니다.

VBS 키에 대한 추가 하드웨어 요구 사항

컴퓨터에 적절한 OS가 설치되어 있을 수 있지만 VBS를 사용하여 키를 생성하고 보호하려면 다음과 같은 추가 하드웨어 요구 사항을 충족해야 합니다.

VBS 사용(VBS(가상화 기반 보안) 참조)
TPM 사용
- 운영 체제 미설치 환경의 경우 TPM 2.0이 필요합니다.
- VM 환경의 경우 vTPM(가상 TPM)이 지원됩니다.
SECUREBoot 프로필을 사용하여 BIOS를 UEFI로 업그레이드해야 합니다.

하드웨어 요구 사항에 대한 자세한 내용은 다음을 수행합니다.

VBS에는 Hyper-V(Windows 하이퍼바이저), 64비트 아키텍처 및 IOMMU 지원을 포함하여 실행해야 하는 몇 가지 하드웨어 요구 사항이 있습니다. VBS 하드웨어 요구 사항의 전체 목록은 여기에서 찾을 수 있습니다.
매우 안전한 디바이스에 대한 요구 사항은 여기에서 찾을 수 있습니다.

요구 사항

요구 사항	값
지원되는 최소 클라이언트	Windows Vista [데스크톱 앱 \| UWP 앱]
지원되는 최소 서버	Windows Server 2008 [데스크톱 앱 \| UWP 앱]
대상 플랫폼	Windows
헤더	ncrypt.h
라이브러리	Ncrypt.lib
DLL	Ncrypt.dll

추가 정보

NCryptBuffer

다음을 통해 공유