BCryptDeriveKey 함수(bcrypt.h)

아티클
07/16/2024

BCryptDeriveKey 함수는 비밀 계약 값에서 키를 파생합니다.

지정된 비밀에서 키 파생은 BCryptKeyDerivation참조하세요.

통사론

NTSTATUS BCryptDeriveKey(
  [in]            BCRYPT_SECRET_HANDLE hSharedSecret,
  [in]            LPCWSTR              pwszKDF,
  [in, optional]  BCryptBufferDesc     *pParameterList,
  [out, optional] PUCHAR               pbDerivedKey,
  [in]            ULONG                cbDerivedKey,
  [out]           ULONG                *pcbResult,
  [in]            ULONG                dwFlags
);

매개 변수

[in] hSharedSecret

키를 만들 비밀 계약 핸들입니다. 이 핸들은 BCryptSecretAgreement 함수에서 가져옵니다.

[in] pwszKDF

키를 파생하는 데 사용할 KDF(키 파생 함수)를 식별하는 null로 끝나는 유니코드 문자열에 대한 포인터입니다. 다음 문자열 중 하나일 수 있습니다.

BCRYPT_KDF_HASH(L"HASH")

해시 키 파생 함수를 사용합니다.

cbDerivedKey 매개 변수가 파생 키의 크기보다 작으면 이 함수는 지정된 바이트 수만 pbDerivedKey 버퍼에 복사합니다. cbDerivedKey 매개 변수가 파생 키의 크기보다 큰 경우 이 함수는 키를 pbDerivedKey 버퍼에 복사하고 pcbResult 가리키는 변수를 복사된 실제 바이트 수로 설정합니다.

pParameterList 매개 변수로 식별되는 매개 변수는 필수 또는 선택적 열에 표시된 대로 다음 매개 변수를 포함하거나 포함해야 합니다.

매개 변수	묘사	필수 또는 선택 사항
KDF_HASH_ALGORITHM	사용할 해시 알고리즘을 식별하는 null로 끝나는 유니코드 문자열입니다. 이는 CNG 알고리즘 식별자 표준 해시 알고리즘 식별자 또는 등록된 다른 해시 알고리즘의 식별자 중 하나일 수 있습니다. 이 매개 변수를 지정하지 않으면 SHA1 해시 알고리즘이 사용됩니다.	선택적
KDF_SECRET_PREPEND	해시 함수에 메시지 입력의 시작 부분에 추가할 값입니다. 자세한 내용은 비고를 참조하세요.	선택적
KDF_SECRET_APPEND	해시 함수에 메시지 입력의 끝에 추가할 값입니다. 자세한 내용은 비고를 참조하세요.	선택적

KDF에 대한 호출은 다음 의사 코드와 같이 수행됩니다.

KDF-Prepend = KDF_SECRET_PREPEND[0] + 
    KDF_SECRET_PREPEND[1] + 
    ... +
    KDF_SECRET_PREPEND[n]

KDF-Append = KDF_SECRET_APPEND[0] + 
    KDF_SECRET_APPEND[1] + 
    ... + 
    KDF_SECRET_APPEND[n]

KDF-Output = Hash(
    KDF-Prepend + 
    hSharedSecret + 
    KDF-Append)

BCRYPT_KDF_HMAC(L"HMAC")

Hash-Based HMAC(메시지 인증 코드) 키 파생 함수를 사용합니다.

pParameterList 매개 변수로 식별되는 매개 변수는 필수 또는 선택적 열에 표시된 대로 다음 매개 변수를 포함하거나 포함해야 합니다.

매개 변수	묘사	필수 또는 선택 사항
KDF_HASH_ALGORITHM	사용할 해시 알고리즘을 식별하는 null로 끝나는 유니코드 문자열입니다. 이는 CNG 알고리즘 식별자 표준 해시 알고리즘 식별자 또는 등록된 다른 해시 알고리즘의 식별자 중 하나일 수 있습니다. 이 매개 변수를 지정하지 않으면 SHA1 해시 알고리즘이 사용됩니다.	선택적
KDF_HMAC_KEY	PRF(의사 임의 함수)에 사용할 키입니다.	선택적
KDF_SECRET_PREPEND	해시 함수에 메시지 입력의 시작 부분에 추가할 값입니다. 자세한 내용은 비고를 참조하세요.	선택적
KDF_SECRET_APPEND	해시 함수에 메시지 입력의 끝에 추가할 값입니다. 자세한 내용은 비고를 참조하세요.	선택적

KDF에 대한 호출은 다음 의사 코드와 같이 수행됩니다.

KDF-Prepend = KDF_SECRET_PREPEND[0] + 
    KDF_SECRET_PREPEND[1] + 
    ... +
    KDF_SECRET_PREPEND[n]

KDF-Append = KDF_SECRET_APPEND[0] + 
    KDF_SECRET_APPEND[1] + 
    ... + 
    KDF_SECRET_APPEND[n]

KDF-Output = HMAC-Hash(
    KDF_HMAC_KEY,
    KDF-Prepend + 
    hSharedSecret + 
    KDF-Append)

BCRYPT_KDF_TLS_PRF(L"TLS_PRF")

TLS(전송 계층 보안) PRF(의사 임의 함수) 키 파생 함수를 사용합니다. 파생 키의 크기는 항상 48바이트이므로 cbDerivedKey 매개 변수는 48이어야 합니다.

pParameterList 매개 변수로 식별되는 매개 변수는 필수 또는 선택적 열에 표시된 대로 다음 매개 변수를 포함하거나 포함해야 합니다.

매개 변수	묘사	필수 또는 선택 사항
KDF_TLS_PRF_LABEL	PRF 레이블을 포함하는 ANSI 문자열입니다.	필수
KDF_TLS_PRF_SEED	PRF 시드입니다. 시드 길이는 64바이트여야 합니다.	필수
KDF_TLS_PRF_PROTOCOL	PRF 알고리즘을 사용할 TLS 프로토콜 버전을 지정하는 DWORD 값입니다. 유효한 값은 다음과 같습니다. SSL2_PROTOCOL_VERSION(0x0002) SSL3_PROTOCOL_VERSION(0x0300) TLS1_PROTOCOL_VERSION(0x0301) TLS1_0_PROTOCOL_VERSION(0x0301) TLS1_1_PROTOCOL_VERSION(0x0302) TLS1_2_PROTOCOL_VERSION(0x0303) DTLS1_0_PROTOCOL_VERSION(0xfeff) Windows Server 2008 및 Windows Vista: TLS1_1_PROTOCOL_VERSION, TLS1_2_PROTOCOL_VERSION 및 DTLS1_0_PROTOCOL_VERSION 지원되지 않습니다. Windows Server 2008 R2, Windows 7, Windows Server 2008 및 Windows Vista: DTLS1_0_PROTOCOL_VERSION 지원되지 않습니다.	선택적
KDF_HASH_ALGORITHM	TLS 1.2 프로토콜 버전에 대해 PRF의 HMAC와 함께 사용할 해시의 CNG 알고리즘 ID입니다. 유효한 선택은 SHA-256 및 SHA-384입니다. 지정하지 않으면 SHA-256이 사용됩니다.	선택적

KDF에 대한 호출은 다음 의사 코드와 같이 수행됩니다.

KDF-Output = PRF(
    hSharedSecret, 
    KDF_TLS_PRF_LABEL, 
    KDF_TLS_PRF_SEED)

BCRYPT_KDF_SP80056A_CONCAT(L"SP800_56A_CONCAT")

SP800-56A 키 파생 함수를 사용합니다.

pParameterList 매개 변수로 식별되는 매개 변수는 필수 또는 선택적 열에 표시된 대로 다음 매개 변수를 포함하거나 포함해야 합니다. 모든 매개 변수 값은 불투명 바이트 배열로 처리됩니다.

매개 변수	묘사	필수 또는 선택 사항
KDF_ALGORITHMID	SP800-56A 키 파생 함수에서 OtherInfo 필드의 AlgorithmID 하위 필드를 지정합니다. 파생 키의 의도된 용도를 나타냅니다.	필수
KDF_PARTYUINFO	SP800-56A 키 파생 함수에서 OtherInfo 필드의 PartyUInfo 하위 필드를 지정합니다. 필드에는 개시자가 제공한 공개 정보가 포함됩니다.	필수
KDF_PARTYVINFO	SP800-56A 키 파생 함수에서 OtherInfo 필드의 PartyVInfo 하위 필드를 지정합니다. 필드에는 응답자가 제공한 공개 정보가 포함됩니다.	필수
KDF_SUPPPUBINFO	SP800-56A 키 파생 함수에서 OtherInfo 필드의 SuppPubInfo 하위 필드를 지정합니다. 필드에는 개시자와 응답자 모두에게 알려진 공개 정보가 포함됩니다.	선택적
KDF_SUPPPRIVINFO	SP800-56A 키 파생 함수에서 OtherInfo 필드의 SuppPrivInfo 하위 필드를 지정합니다. 여기에는 개시자와 응답자 모두에게 알려진 개인 정보(예: 공유 비밀)가 포함됩니다.	선택적

KDF에 대한 호출은 다음 의사 코드와 같이 수행됩니다.

KDF-Output = SP_800-56A_KDF(
	   hSharedSecret,
	   KDF_ALGORITHMID,
	   KDF_PARTYUINFO,
	   KDF_PARTYVINFO,
	   KDF_SUPPPUBINFO,
	   KDF_SUPPPRIVINFO)

Windows Server 2008, Windows Vista, Windows Server 2003 및 Windows XP: 이 값은 지원되지 않습니다.

BCRYPT_KDF_RAW_SECRET(L"TRUNCATE")

수정 없이 원시 비밀의 little-endian 표현을 반환합니다.

Windows 8, Windows Server 2008, Windows Vista, Windows Server 2003 및 Windows XP: 이 값은 지원되지 않습니다.

[in, optional] pParameterList

KDF 매개 변수를 포함하는 BCryptBufferDesc 구조체의 주소입니다. 이 매개 변수는 선택 사항이며 필요하지 않은 경우 NULL 수 있습니다.

[out, optional] pbDerivedKey

키를 받는 버퍼의 주소입니다. cbDerivedKey 매개 변수에는 이 버퍼의 크기가 포함됩니다. 이 매개 변수가 NULL경우 이 함수는 pcbResult 매개 변수가 가리키는 ULONG 필요한 크기를 바이트 단위로 배치합니다.

[in] cbDerivedKey

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

[out] pcbResult

pbDerivedKey 버퍼에 복사된 바이트 수를 수신하는 ULONG 대한 포인터입니다. pbDerivedKey 매개 변수가 NULL경우 이 함수는 이 매개 변수가 가리키는 ULONG 필요한 크기를 바이트 단위로 배치합니다.

[in] dwFlags

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

값	의미
KDF_USE_SECRET_AS_HMAC_KEY_FLAG	비밀 계약 값도 HMAC 키 역할을 합니다. 이 플래그를 지정하면 KDF_HMAC_KEY 매개 변수가 pParameterList 매개 변수의 매개 변수 집합에 포함되지 않아야 합니다. 이 플래그는 BCRYPT_KDF_HMAC 키 파생 함수에서만 사용됩니다.

반환 값

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

가능한 반환 코드는 다음을 포함하지만 제한되지는 않습니다.

반환 코드	묘사
STATUS_SUCCESS	함수가 성공했습니다.
STATUS_INTERNAL_ERROR	내부 오류가 발생했습니다.
STATUS_INVALID_HANDLE	hSharedSecret 매개 변수의 핸들이 잘못되었습니다.
STATUS_INVALID_PARAMETER	하나 이상의 매개 변수가 잘못되었습니다.

발언

pParameterList 매개 변수의 BCryptBufferDesc 구조에는 KDF_SECRET_PREPEND 및 KDF_SECRET_APPEND 매개 변수 중 하나 이상이 포함될 수 있습니다. 이러한 매개 변수 중 하나 이상을 지정하면 KDF가 호출되기 전에 매개 변수 값이 배열에 포함된 순서대로 연결됩니다. 예를 들어 다음 매개 변수 값이 지정되어 있다고 가정합니다.

BYTE pbValue0[1] = {0x01};
BYTE pbValue1[2] = {0x04, 0x05};
BYTE pbValue2[3] = {0x10, 0x11, 0x12};
BYTE pbValue3[4] = {0x20, 0x21, 0x22, 0x23};

Parameter[0].type = KDF_SECRET_APPEND
Parameter[0].value = pbValue0;
Parameter[0].length = sizeof  (pbValue0);
Parameter[1].type = KDF_SECRET_PREPEND
Parameter[1].value = pbValue1;
Parameter[1].length = sizeof (pbValue1);
Parameter[2].type = KDF_SECRET_APPEND
Parameter[2].value = pbValue2;
Parameter[2].length = sizeof (pbValue2);
Parameter[3].type = KDF_SECRET_PREPEND
Parameter[3].value = pbValue3;
Parameter[3].length = sizeof (pbValue3);

위의 매개 변수 값을 지정하면 실제 KDF에 연결된 값은 다음과 같습니다.

Type: KDF_SECRET_PREPEND
Value: {0x04, 0x05, 0x20, 0x21, 0x22, 0x23}, length 6

Type: KDF_SECRET_APPEND
Value: {0x01, 0x10, 0x11, 0x12}, length 4

pwszKDF 매개 변수가 BCRYPT_KDF_RAW_SECRET설정되면 반환된 비밀(다른 pwszKDF 값과 달리)은 little-endian 형식으로 인코딩됩니다. 대부분의 경우 big-endian 인코딩된 입력을 사용하므로 다른 CNG 함수에서 원시 비밀을 사용할 때 이 점을 유의해야 합니다.

공급자가 지원하는 프로세서 모드에 따라 BCryptDeriveKey 사용자 모드 또는 커널 모드에서 호출할 수 있습니다. 커널 모드 호출자는 PASSIVE_LEVELIRQL 또는 DISPATCH_LEVEL IRQL에서 실행할 수 있습니다. 현재 IRQL 수준이 DISPATCH_LEVEL경우 hSharedSecret 매개 변수에 제공된 핸들은 비페이지(또는 잠긴) 메모리에 있어야 하며 BCRYPT_PROV_DISPATCH 플래그를 사용하여 연 공급자가 반환한 알고리즘 핸들에서 파생되어야 합니다.

커널 모드에서 이 함수를 호출하려면 DDK(드라이버 개발 키트)의 일부인 Cng.lib를 사용합니다. Windows Server 2008 및 Windows Vista: 커널 모드에서 이 함수를 호출하려면 Ksecdd.lib를 사용합니다.

요구 사항

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

참고 항목

BCryptSecretAgreement

다음을 통해 공유

BCryptDeriveKey 함수(bcrypt.h)

통사론

매개 변수

BCRYPT_KDF_HASH(L"HASH")

BCRYPT_KDF_HMAC(L"HMAC")

BCRYPT_KDF_TLS_PRF(L"TLS_PRF")

BCRYPT_KDF_SP80056A_CONCAT(L"SP800_56A_CONCAT")

BCRYPT_KDF_RAW_SECRET(L"TRUNCATE")

반환 값

발언

요구 사항

참고 항목

피드백

추가 리소스