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

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

[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부터 시작하는 최소, 기본 및 최대 서명 및 교환 키 길이를 나열합니다.

세션 키 길이는 CryptDeriveKey참조하세요.

Microsoft 공급자를 사용하여 생성된 키에 대한 자세한 내용은 Microsoft 암호화 서비스 공급자참조하세요.

이 매개 변수의 하위 16비트가 0이거나 다음 값 중 하나 이상의 조합일 수 있습니다.

[out] phKey

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

반환 값

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

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

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

발언

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

요구 사항

참고 항목

CryptAcquireContext

CryptDestroyKey

CryptExportKey

CryptGetKeyParam

CryptImportKey

CryptSetKeyParam

키 생성 및 Exchange 함수

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