다음을 통해 공유


CryptGenKey 함수(wincrypt.h)

중요 이 API는 더 이상 사용되지 않습니다. 신규 및 기존 소프트웨어는 암호화 차세대 API를 사용하기 시작해야 합니다. Microsoft는 이후 릴리스에서 이 API를 제거할 수 있습니다.
 
CryptGenKey 함수는 임의 암호화 세션 키 또는 공개/프라이빗 키 쌍생성합니다. 키 또는 키 쌍에 대한 핸들은 phKey반환됩니다. 그런 다음 키 핸들이 필요한 CryptoAPI 함수에서 필요에 따라 이 핸들을 사용할 수 있습니다.

호출 애플리케이션은 이 함수를 호출할 때 알고리즘을 지정해야 합니다. 이 알고리즘 형식은 키와 함께 번들로 유지되므로 애플리케이션은 실제 암호화 작업이 수행될 때 나중에 알고리즘을 지정할 필요가 없습니다.

통사론

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의 경우 다음 값 중 하나를 사용합니다.

의미
CALG_DH_EPHEM
"사용 후 삭제" Diffie-Hellman 키를 지정합니다.
CALG_DH_SF
"저장 및 전달" Diffie-Hellman 키를 지정합니다.
 

이 함수는대칭 알고리즘에 대한 세션 키를 생성하는 것 외에도퍼블릭/프라이빗 키 쌍을 생성할 수 있습니다. 각 CryptoAPI 클라이언트에는 일반적으로 두 개의 공개/프라이빗 키 쌍이 있습니다. 이러한 키 쌍 중 하나를 생성하려면 Algid 매개 변수를 다음 값 중 하나로 설정합니다.

의미
AT_KEYEXCHANGE
키 교환
AT_SIGNATURE
디지털 서명
 
참고 키 사양 AT_KEYEXCHANGE 및 AT_SIGNATURE 지정 하는 경우 키를 생성 하는 데 사용 되는 알고리즘 식별자는 사용 되는 공급자에 따라 달라 집니다. 따라서 이러한 키 사양의 경우 CryptGetKeyParam 반환된 값(KP_ALGID 매개 변수가 지정된 경우)은 사용된 공급자에 따라 달라집니다. AT_KEYEXCHANGE 및 AT_SIGNATURE 주요 사양에 대해 다른 공급자가 사용하는 알고리즘 식별자를 확인하려면 ALG_ID참조하세요.
 

[in] dwFlags

생성된 키의 유형을 지정합니다. 세션 키, RSA 서명 키 및 RSA 키 교환 키 크기는 키가 생성될 때 설정할 수 있습니다. 키 모듈러스의 길이를 비트 단위로 나타내는 키 크기는 이 매개 변수의 상위 16비트로 설정됩니다. 따라서 2,048비트 RSA 서명 키를 생성할 경우 0x08000000 값은 비트OR 연산으로 미리 정의된 값을 다른 dwFlags와 결합됩니다. 상위 16비트 0x08000000 0x0800 또는 10진수 2,048입니다. RSA1024BIT_KEY 값을 사용하여 1024비트 RSA 키를 지정할 수 있습니다.

내보내기 제어 제한 변경으로 인해 운영 체제 버전 간에 기본 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이거나 다음 값 중 하나 이상의 조합일 수 있습니다.

의미
CRYPT_ARCHIVABLE
이 플래그가 설정되면 CryptDestroyKey호출하여 핸들을 닫을 때까지 키를 내보낼 수 있습니다. 이렇게 하면 새로 생성된 키를 보관 또는 키 복구를 위해 만들 때 내보낼 수 있습니다. 핸들을 닫은 후에는 키를 더 이상 내보낼 수 없습니다.
CRYPT_CREATE_IV
이 플래그는 사용되지 않습니다.
CRYPT_CREATE_SALT
이 플래그가 설정되면 키에 자동으로 임의 솔트 값 할당됩니다. dwParam 매개 변수가 KP_SALT 설정된 CryptGetKeyParam 함수를 사용하여 이 솔트 값을 검색할 수 있습니다.

이 플래그를 설정하지 않으면 키에 솔트 값이 0으로 지정됩니다.

0이 아닌 솔트 값을 가진 키를 내보낼 때(CryptExportKey통해) 솔트 값키 BLOB가져와서 유지해야 합니다.

CRYPT_DATA_KEY
이 플래그는 사용되지 않습니다.
CRYPT_EXPORTABLE
이 플래그가 설정되면 CryptExportKey 함수를 사용하여 CSP에서 키 BLOB으로 키를 전송할 수 있습니다. 일반적으로 세션 키를 내보낼 수 있어야 하므로 이 플래그는 일반적으로 생성될 때 설정해야 합니다.

이 플래그를 설정하지 않으면 키를 내보낼 수 없습니다. 세션 키의 경우 키는 현재 세션 내에서만 사용할 수 있으며, 키를 만든 애플리케이션만 사용할 수 있음을 의미합니다. 공개/프라이빗 키 쌍경우 프라이빗 키를 전송하거나 백업할 수 없음을 의미합니다.

이 플래그는 세션 키 및 프라이빗 키 BLOB적용됩니다. 항상 내보낼 수 있는 공개 키에는 적용되지 않습니다.

CRYPT_FORCE_KEY_PROTECTION_HIGH
이 플래그는 강력한 키 보호를 지정합니다. 이 플래그를 설정하면 키를 만들 때 키에 대한 암호를 입력하라는 메시지가 사용자에게 표시됩니다. 이 키를 사용할 때마다 사용자에게 암호를 입력하라는 메시지가 표시됩니다.

이 플래그는 Microsoft에서 제공하는 CSP에서만 사용됩니다. 타사 CSP는 강력한 키 보호를 위해 자체 동작을 정의합니다.

이 플래그를 지정하면 시스템 레지스트리에 강력한 키 보호가 지정된 경우 CRYPT_USER_PROTECTED 플래그를 사용하여 이 함수를 호출하는 것과 동일한 결과가 발생합니다.

이 플래그를 지정하고 CRYPT_VERIFYCONTEXT 또는 CRYPT_SILENT 플래그를 사용하여 hProv 매개 변수의 공급자 핸들을 만든 경우 이 함수는 마지막 오류를 NTE_SILENT_CONTEXT 0으로 설정하고 0을 반환합니다.

Windows Server 2003 및 Windows XP: 이 플래그는 지원되지 않습니다.

CRYPT_KEK
이 플래그는 사용되지 않습니다.
CRYPT_INITIATOR
이 플래그는 사용되지 않습니다.
CRYPT_NO_SALT
이 플래그는 40비트 대칭 키대해 솔트 값 할당되지 않음을 지정합니다. 자세한 내용은 솔트 값 기능참조하세요.
CRYPT_ONLINE
이 플래그는 사용되지 않습니다.
CRYPT_PREGEN
이 플래그는 초기 Diffie-Hellman 또는 DSS 키 생성을 지정합니다. 이 플래그는 Diffie-Hellman 및 DSS CSP에서만 유용합니다. 사용되는 경우 dwFlags 매개 변수의 상위 16비트에서 키 길이를 지정하지 않는 한 기본 키 길이가 사용됩니다. 키 길이를 포함하는 매개 변수가 CryptSetKeyParam사용하여 PREGEN Diffie-Hellman 또는 DSS 키에 설정된 경우 키 길이는 여기에 설정된 키 길이와 호환되어야 합니다.
CRYPT_RECIPIENT
이 플래그는 사용되지 않습니다.
CRYPT_SF
이 플래그는 사용되지 않습니다.
CRYPT_SGCKEY
이 플래그는 사용되지 않습니다.
CRYPT_USER_PROTECTED
이 플래그를 설정하면 특정 작업에서 이 키를 사용하려고 할 때 대화 상자 또는 다른 메서드를 통해 사용자에게 알림을 받습니다. 정확한 동작은 사용 중인 CSP에 의해 지정됩니다. CRYPT_SILENT 플래그 집합을 사용하여 공급자 컨텍스트를 연 경우 이 플래그를 사용하면 오류가 발생하고 마지막 오류가 NTE_SILENT_CONTEXT 설정됩니다.
CRYPT_VOLATILE
이 플래그는 사용되지 않습니다.

[out] phKey

함수가 새로 생성된 키의 핸들을 복사하는 주소입니다. 키 사용을 마쳤으면 CryptDestroyKey 함수를 호출하여 키에 대한 핸들을 삭제합니다.

반환 값

성공하면 0이 아닌 값을 반환하고, 그렇지 않으면 0을 반환합니다.

확장 오류 정보는 GetLastError호출합니다.

"NTE"가 앞에 있는 오류 코드는 사용 중인 특정 CSP에 의해 생성됩니다. 다음 표에는 몇 가지 가능한 오류 코드가 나열되어 있습니다.

반환 코드 묘사
ERROR_INVALID_HANDLE
매개 변수 중 하나는 유효하지 않은 핸들을 지정합니다.
ERROR_INVALID_PARAMETER
매개 변수 중 하나에 유효하지 않은 값이 포함되어 있습니다. 이는 가장 자주 유효하지 않은 포인터입니다.
NTE_BAD_ALGID
Algid 매개 변수는 이 CSP가 지원하지 않는 알고리즘을 지정합니다.
NTE_BAD_FLAGS
dwFlags 매개 변수에는 유효하지 않은 값이 포함되어 있습니다.
NTE_BAD_UID
hProv 매개 변수는 유효한 컨텍스트 핸들을 포함하지 않습니다.
NTE_FAIL
함수가 예기치 않은 방식으로 실패했습니다.
NTE_SILENT_CONTEXT
컨텍스트가 자동으로 획득되었기 때문에 공급자가 작업을 수행할 수 없습니다.

발언

대칭블록 암호대해 키가 생성되는 경우 키는 기본적으로 초기화 벡터가 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

참고 항목

CryptAcquireContext

CryptDestroyKey

CryptExportKey

CryptGetKeyParam

CryptImportKey

CryptSetKeyParam

키 생성 및 Exchange 함수

암호화 서비스 공급자 스레딩 문제