NCryptCreatePersistedKey 함수(ncrypt.h)

아티클
02/09/2024

NCryptCreatePersistedKey 함수는 새 키를 만들고 지정된 키 스토리지 공급자에 저장합니다. 이 함수를 사용하여 키를 만든 후에 는 NCryptSetProperty 함수를 사용하여 해당 속성을 설정할 수 있습니다. 그러나 NCryptFinalizeKey 함수가 호출될 때까지 키를 사용할 수 없습니다.

구문

SECURITY_STATUS NCryptCreatePersistedKey(
  [in]           NCRYPT_PROV_HANDLE hProvider,
  [out]          NCRYPT_KEY_HANDLE  *phKey,
  [in]           LPCWSTR            pszAlgId,
  [in, optional] LPCWSTR            pszKeyName,
  [in]           DWORD              dwLegacyKeySpec,
  [in]           DWORD              dwFlags
);

매개 변수

[in] hProvider

키를 만들 키 스토리지 공급자의 핸들입니다. 이 핸들은 NCryptOpenStorageProvider 함수를 사용하여 가져옵니다.

[out] phKey

키의 핸들을 수신하는 NCRYPT_KEY_HANDLE 변수의 주소입니다. 이 핸들 사용을 마쳤으면 NCryptFreeObject 함수에 전달하여 해제합니다. 디스크에서 키 파일을 삭제하려면 NCryptDeleteKey 함수에 핸들을 전달합니다. 그러면 핸들도 해제됩니다. 따라서 애플리케이션은 NCryptFreeObject 또는 NCryptDeleteKey에 핸들을 전달할 수 있지만 둘 다 전달하지는 않습니다.

[in] pszAlgId

키를 만드는 암호화 알고리즘의 식별자를 포함하는 null로 끝나는 유니코드 문자열에 대한 포인터입니다. 표준 CNG 알고리즘 식별자 또는 등록된 다른 알고리즘의 식별자 중 하나일 수 있습니다.

[in, optional] pszKeyName

키 이름을 포함하는 null로 끝나는 유니코드 문자열에 대한 포인터입니다. 이 매개 변수가 NULL이면 이 함수는 유지되지 않는 임시 키를 만듭니다.

[in] dwLegacyKeySpec

키 유형을 지정하는 레거시 식별자입니다. 다음 값 중 하나일 수 있습니다.

값	의미
AT_KEYEXCHANGE	키는 키 교환 키입니다.
AT_SIGNATURE	키는 서명 키입니다.
0	키는 위의 형식이 아닙니다.

[in] dwFlags

이 함수의 동작을 수정하는 플래그 집합입니다. 이 값은 0이거나 다음 값 중 하나 이상의 조합일 수 있습니다.

값	의미
NCRYPT_MACHINE_KEY_FLAG	키는 로컬 컴퓨터에 적용됩니다. 이 플래그가 없으면 키가 현재 사용자에게 적용됩니다.
NCRYPT_OVERWRITE_KEY_FLAG	지정된 이름의 컨테이너에 키가 이미 있는 경우 기존 키를 덮어씁니다. 이 플래그를 지정하지 않고 지정된 이름의 키가 이미 있는 경우 이 함수는 NTE_EXISTS 반환합니다.
NCRYPT_REQUIRE_VBS_FLAG	키를 VBS(가상화 기반 보안)로 보호해야 했음을 나타냅니다. VBS를 사용할 수 없는 경우 작업이 실패합니다. (*설명 참조)
NCRYPT_PREFER_VBS_FLAG	VBS(가상화 기반 보안)로 키를 보호해야 했음을 나타냅니다. 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를 사용할 수 없습니다.

설명

중요

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

RSA 키 쌍을 만드는 경우 키가 완료될 때 NCRYPT_WRITE_KEY_TO_LEGACY_STORE_FLAG 플래그를 NCryptFinalizeKey 함수에 전달하여 CryptoAPI와 함께 사용할 수 있도록 키를 레거시 스토리지에 저장할 수도 있습니다.

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

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

추가 정보

NCryptDeleteKey

NCryptFinalizeKey

Share via