CryptGenKey 함수(wincrypt.h)
호출 애플리케이션은 이 함수를 호출할 때 알고리즘을 지정해야 합니다. 이 알고리즘 형식은 키와 함께 번들로 유지되므로 애플리케이션은 실제 암호화 작업이 수행될 때 나중에 알고리즘을 지정할 필요가 없습니다.
통사론
BOOL CryptGenKey(
[in] HCRYPTPROV hProv,
[in] ALG_ID Algid,
[in] DWORD dwFlags,
[out] HCRYPTKEY *phKey
);
매개 변수
[in] hProv
CryptAcquireContext호출로 만든 CSP(암호화 서비스 공급자)에 대한 핸들입니다.
[in] Algid
키를 생성할 알고리즘을 식별하는 ALG_ID 값입니다. 이 매개 변수의 값은 사용된 CSP에 따라 달라집니다.
Microsoft 기본 암호화 공급자와 함께 사용할 ALG_ID 값은 기본 공급자 알고리즘참조하세요.
Microsoft 강력한 암호화 공급자 또는 Microsoft 고급 암호화 공급자와 함께 사용할 ALG_ID 값은 고급 공급자 알고리즘참조하세요.
Diffie-Hellman CSP의 경우 다음 값 중 하나를 사용합니다.
| 값 | 의미 |
|---|---|
|
"사용 후 삭제" Diffie-Hellman 키를 지정합니다. |
|
"저장 및 전달" Diffie-Hellman 키를 지정합니다. |
이 함수는
| 값 | 의미 |
|---|---|
|
키 교환 |
|
디지털 서명 |
[in] dwFlags
생성된 키의 유형을 지정합니다. 세션 키, RSA 서명 키 및 RSA 키 교환 키 크기는 키가 생성될 때 설정할 수 있습니다. 키 모듈러스의 길이를 비트 단위로 나타내는 키 크기는 이 매개 변수의 상위 16비트로 설정됩니다. 따라서 2,048비트 RSA 서명 키를 생성할 경우 0x08000000 값은 비트
내보내기 제어 제한 변경으로 인해 운영 체제 버전 간에 기본 CSP 및 기본 키 길이 변경 될 수 있습니다. 암호화와 암호 해독 모두 동일한 CSP를 사용하고 다른 운영 체제 플랫폼에서 상호 운용성을 보장하기 위해 dwFlags 매개 변수를 사용하여 키 길이를 명시적으로 설정하는 것이 중요합니다.
특히 기본 RSA 전체 암호화 서비스 공급자는 Microsoft RSA 강력한 암호화 공급자입니다. 암호화 서비스 공급자에 Diffie-Hellman 기본 DSS 서명은 Microsoft 고급 DSS Diffie-Hellman 암호화 공급자입니다. 이러한 각 CSP에는 RC2 및 RC4의 기본 128비트 대칭 키 길이와 공개 키 알고리즘에 대한 1,024비트 기본 키 길이가 있습니다.
상위 16비트가 0이면 기본 키 크기가 생성됩니다. 최댓값보다 크거나 최소값보다 작은 키를 지정하면 ERROR_INVALID_PARAMETER 코드로 호출이 실패합니다.
다음 표에서는 Windows XP부터 시작하는 최소, 기본 및 최대 서명 및 교환 키 길이를 나열합니다.
| 키 유형 및 공급자 | 최소 길이 | 기본 길이 | 최대 길이 |
|---|---|---|---|
|
RSA 기본 공급자 서명 및 ExchangeKeys |
384 | 512 | 16,384 |
|
RSA 강력하고 향상된 공급자 서명 및 Exchange 키 |
384 | 1,024 | 16,384 |
|
DSS 기본 공급자 서명 키 |
512 | 1,024 | 1,024 |
|
DSS 기본 공급자 Exchange 키 |
해당 없음 | 해당 없음 | 해당 없음 |
|
DSS/DH 기본 공급자 서명 키 |
512 | 1,024 | 1,024 |
|
DSS/DH 기본 공급자 Exchange 키 |
512 | 512 | 1,024 |
|
DSS/DH 고급 공급자 서명 키 |
512 | 1,024 | 1,024 |
|
DSS/DH 고급 공급자 Exchange 키 |
512 | 1,024 | 4,096 |
세션 키 길이는 CryptDeriveKey참조하세요.
Microsoft 공급자를 사용하여 생성된 키에 대한 자세한 내용은 Microsoft 암호화 서비스 공급자
이 매개 변수의 하위 16비트가 0이거나 다음 값 중 하나 이상의 조합일 수 있습니다.
| 값 | 의미 |
|---|---|
|
이 플래그가 설정되면 CryptDestroyKey호출하여 핸들을 닫을 때까지 키를 내보낼 수 있습니다. 이렇게 하면 새로 생성된 키를 보관 또는 키 복구를 위해 만들 때 내보낼 수 있습니다. 핸들을 닫은 후에는 키를 더 이상 내보낼 수 없습니다. |
|
이 플래그는 사용되지 않습니다. |
|
이 플래그가 설정되면 키에 자동으로 임의 솔트 값 할당됩니다.
dwParam 매개 변수가 KP_SALT 설정된 CryptGetKeyParam 함수를 사용하여 이 솔트 값을 검색할 수 있습니다.
이 플래그를 설정하지 않으면 키에 솔트 값이 0으로 지정됩니다. 0이 아닌 솔트 값을 가진 키를 내보낼 때(CryptExportKey통해) 솔트 값키 BLOB가져와서 유지해야 합니다. |
|
이 플래그는 사용되지 않습니다. |
|
이 플래그가 설정되면 CryptExportKey 함수를 사용하여 CSP에서 키 BLOB으로 키를 전송할 수 있습니다. 일반적으로 세션 키를 내보낼 수 있어야 하므로 이 플래그는 일반적으로 생성될 때 설정해야 합니다.
이 플래그를 설정하지 않으면 키를 내보낼 수 없습니다. 세션 키의 경우 키는 현재 세션 내에서만 사용할 수 있으며, 키를 만든 애플리케이션만 사용할 수 있음을 의미합니다. 공개/프라이빗 키 쌍경우 프라이빗 키를 전송하거나 백업할 수 없음을 의미합니다. 이 플래그는 세션 키 및 프라이빗 키 BLOB적용됩니다. 항상 내보낼 수 있는 공개 키에는 적용되지 않습니다. |
|
이 플래그는 강력한 키 보호를 지정합니다. 이 플래그를 설정하면 키를 만들 때 키에 대한 암호를 입력하라는 메시지가 사용자에게 표시됩니다. 이 키를 사용할 때마다 사용자에게 암호를 입력하라는 메시지가 표시됩니다.
이 플래그는 Microsoft에서 제공하는 CSP에서만 사용됩니다. 타사 CSP는 강력한 키 보호를 위해 자체 동작을 정의합니다. 이 플래그를 지정하면 시스템 레지스트리에 강력한 키 보호가 지정된 경우 CRYPT_USER_PROTECTED 플래그를 사용하여 이 함수를 호출하는 것과 동일한 결과가 발생합니다. 이 플래그를 지정하고 CRYPT_VERIFYCONTEXT 또는 CRYPT_SILENT 플래그를 사용하여 hProv 매개 변수의 공급자 핸들을 만든 경우 이 함수는 마지막 오류를 NTE_SILENT_CONTEXT 0으로 설정하고 0을 반환합니다. Windows Server 2003 및 Windows XP: 이 플래그는 지원되지 않습니다. |
|
이 플래그는 사용되지 않습니다. |
|
이 플래그는 사용되지 않습니다. |
|
이 플래그는 40비트 대칭 키대해 솔트 값 할당되지 않음을 지정합니다. 자세한 내용은 솔트 값 기능참조하세요. |
|
이 플래그는 사용되지 않습니다. |
|
이 플래그는 초기 Diffie-Hellman 또는 DSS 키 생성을 지정합니다. 이 플래그는 Diffie-Hellman 및 DSS CSP에서만 유용합니다. 사용되는 경우 dwFlags 매개 변수의 상위 16비트에서 키 길이를 지정하지 않는 한 기본 키 길이가 사용됩니다. 키 길이를 포함하는 매개 변수가 CryptSetKeyParam사용하여 PREGEN Diffie-Hellman 또는 DSS 키에 설정된 경우 키 길이는 여기에 설정된 키 길이와 호환되어야 합니다. |
|
이 플래그는 사용되지 않습니다. |
|
이 플래그는 사용되지 않습니다. |
|
이 플래그는 사용되지 않습니다. |
|
이 플래그를 설정하면 특정 작업에서 이 키를 사용하려고 할 때 대화 상자 또는 다른 메서드를 통해 사용자에게 알림을 받습니다. 정확한 동작은 사용 중인 CSP에 의해 지정됩니다. CRYPT_SILENT 플래그 집합을 사용하여 공급자 컨텍스트를 연 경우 이 플래그를 사용하면 오류가 발생하고 마지막 오류가 NTE_SILENT_CONTEXT 설정됩니다. |
|
이 플래그는 사용되지 않습니다. |
[out] phKey
함수가 새로 생성된 키의 핸들을 복사하는 주소입니다. 키 사용을 마쳤으면 CryptDestroyKey 함수를 호출하여 키에 대한 핸들을 삭제합니다.
반환 값
성공하면 0이 아닌 값을 반환하고, 그렇지 않으면 0을 반환합니다.
확장 오류 정보는 GetLastError호출합니다.
"NTE"가 앞에 있는 오류 코드는 사용 중인 특정 CSP에 의해 생성됩니다. 다음 표에는 몇 가지 가능한 오류 코드가 나열되어 있습니다.
| 반환 코드 | 묘사 |
|---|---|
|
매개 변수 중 하나는 유효하지 않은 핸들을 지정합니다. |
|
매개 변수 중 하나에 유효하지 않은 값이 포함되어 있습니다. 이는 가장 자주 유효하지 않은 포인터입니다. |
|
Algid 매개 변수는 이 CSP가 지원하지 않는 알고리즘을 지정합니다. |
|
dwFlags 매개 변수에는 유효하지 않은 값이 포함되어 있습니다. |
|
hProv 매개 변수는 유효한 컨텍스트 핸들을 포함하지 않습니다. |
|
함수가 예기치 않은 방식으로 실패했습니다. |
|
컨텍스트가 자동으로 획득되었기 때문에 공급자가 작업을 수행할 수 없습니다. |
발언
대칭블록 암호대해 키가 생성되는 경우 키는 기본적으로 초기화 벡터가 0인 CBC(암호화 블록 체인) 모드로 설정됩니다. 이 암호화 모드 데이터를 대량 암호화하기 위한 좋은 기본 방법을 제공합니다. 이러한 매개 변수를 변경하려면 CryptSetKeyParam 함수를 사용합니다.
적절한 키 길이선택하려면 다음 방법을 사용하는 것이 좋습니다.
- CSP에서 지원하는 알고리즘을 열거하고 각 알고리즘에 대한 최대 및 최소 키 길이를 가져옵니다. 이렇게 하려면 PP_ENUMALGS_EX 사용하여 CryptGetProvParam 호출합니다.
- 최소 및 최대 길이를 사용하여 적절한 키 길이를 선택합니다. 성능 문제가 발생할 수 있으므로 최대 길이를 선택하는 것이 항상 권장되는 것은 아닙니다.
- 원하는 키 길이를 선택한 후 dwFlags 매개 변수의 상위 16비트에서 키 길이를 지정합니다.
예제
다음 예제에서는 임의 세션 키의 생성을 보여줍니다. 이 예제의 전체 컨텍스트를 포함하는 예제는 예제 C 프로그램: 파일암호화를 참조하세요. 이 함수를 사용하는 다른 예제는 예제 C 프로그램: 파일암호 해독을 참조하세요.
//-------------------------------------------------------------------
// Declare the handle to the key.
HCRYPTKEY hKey;
//-------------------------------------------------------------------
// This example assumes that a cryptographic context
// has been acquired, and that it is stored in hCryptProv.
//---------------------------------------------------------------
// Create a random session key.
if(CryptGenKey(
hCryptProv,
ENCRYPT_ALGORITHM,
KEYLENGTH | CRYPT_EXPORTABLE,
&hKey))
{
printf("A session key has been created.\n");
}
else
{
printf("Error during CryptGenKey.\n");
exit(1);
}
//-------------------------------------------------------------------
// The key created can be exported into a key BLOB that can be
// written to a file.
// ...
// When you have finished using the key, free the resource.
if (!CryptDestroyKey(hKey))
{
printf("Error during CryptDestroyKey.\n");
exit(1);
}
요구 사항
| 요구 | 값 |
|---|---|
| 지원되는 최소 클라이언트 | Windows XP [데스크톱 앱만 해당] |
| 지원되는 최소 서버 | Windows Server 2003 [데스크톱 앱만 해당] |
| 대상 플랫폼 | Windows |
| 헤더 | wincrypt.h |
| 라이브러리 | Advapi32.lib |
| DLL | Advapi32.dll |
참고 항목
암호화 서비스 공급자