Функция CryptGenKey (wincrypt.h)

Вызывающее приложение должно указать алгоритм при вызове этой функции. Так как этот тип алгоритма хранится в пакете с ключом, приложению не нужно указывать алгоритм позже при выполнении фактических криптографических операций.

Синтаксис

BOOL CryptGenKey(
  [in]  HCRYPTPROV hProv,
  [in]  ALG_ID     Algid,
  [in]  DWORD      dwFlags,
  [out] HCRYPTKEY  *phKey
);

Параметры

[in] hProv

Дескри птор поставщика криптографических служб (CSP), созданного вызовом CryptAcquireContext.

[in] Algid

Значение ALG_ID, определяющее алгоритм, для которого создается ключ. Значения этого параметра зависят от используемого CSP.

Сведения о ALG_ID значениях, используемых с поставщиком шифрования Microsoft Base, см. в базовых алгоритмов поставщиков.

Сведения о ALG_ID значениях, используемых с поставщиком шифрования Microsoft Strong или поставщиком расширенного шифрования Майкрософт, см. в расширенных алгоритмов поставщиков.

Для Diffie-Hellman CSP используйте одно из следующих значений.

Помимо создания ключей сеансов для симметричные алгоритмы, эта функция также может создавать пары открытых и закрытых ключей. Каждый клиент CryptoAPI обычно обладает двумя парами открытых и закрытых ключей. Чтобы создать одну из этих пар ключей, задайте для параметра Algid одно из следующих значений.

[in] dwFlags

Указывает тип созданного ключа. Размеры ключа сеанса, ключа подписи RSA и ключа RSA ключ обмена можно задать при создании ключа. Размер ключа, представляющий длину модуля ключа в битах, устанавливается с верхними 16 битами этого параметра. Таким образом, если создается 2048-разрядный ключ подписи RSA, значение 0x08000000 объединяется с любым другим dwFlags предопределенным значением с побитовойИЛИ операцией. Верхние 16 битов 0x08000000 0x0800 или десятичные 2048. Значение RSA1024BIT_KEY можно использовать для указания 1024-разрядного ключа RSA.

В связи с изменением ограничений управления экспортом служба CSP по умолчанию и длина ключа по умолчанию может измениться между версиями операционной системы. Важно, чтобы шифрование и расшифровка использовали один И тот же CSP и что длина ключа должна быть явно задана с помощью параметра dwFlags для обеспечения взаимодействия на разных платформах операционной системы.

В частности, поставщик полнофункционных служб RSA по умолчанию является поставщиком надежных криптографических служб Microsoft RSA. По умолчанию поставщик служб шифрования DSS Diffie-Hellman поставщик служб шифрования — это поставщик расширенных служб DSS майкрософт Diffie-Hellman шифрования. Каждая из этих поставщиков служб по умолчанию имеет 128-разрядную длину симметричного ключа для RC2 и RC4 и 1024-разрядную длину ключа по умолчанию для алгоритмов открытого ключа.

Если верхний 16 бит равен нулю, создается размер ключа по умолчанию. Если ключ больше или меньше минимального значения, вызов завершается сбоем с кодом ERROR_INVALID_PARAMETER.

В следующей таблице перечислены минимальные, стандартные и максимальные длины подписей и ключей exchange, начиная с Windows XP.

Сведения о длине ключа сеанса см. в CryptDeriveKey.

Дополнительные сведения о ключах, созданных с помощью поставщиков Майкрософт, см. в поставщиков криптографических служб Майкрософт.

Ниже 16-разрядных значений этого параметра может быть равно нулю или сочетанию одного или нескольких из следующих значений.

[out] phKey

Адрес, в который функция копирует дескриптор только что созданного ключа. После завершения использования ключа удалите дескриптор ключа, вызвав функцию CryptDekey.

Возвращаемое значение

Возвращает ненулевое значение, если успешно или ноль в противном случае.

Для получения расширенных сведений об ошибке вызовите GetLastError.

Коды ошибок, предуставленные NTE, создаются конкретным используемым поставщиком служб CSP. Некоторые возможные коды ошибок перечислены в следующей таблице.

Замечания

Если ключи создаются для симметричныеблочных шифров, ключ по умолчанию настраивается в режиме цепочки блоков (CBC) с вектором инициализации нуля. Этот режим шифра предоставляет хороший метод по умолчанию для массового шифрования данных. Чтобы изменить эти параметры, используйте функцию CryptSetKeyParam.

Чтобы выбрать соответствующую длину ключа , рекомендуется использовать следующие методы:

• Перечисление алгоритмов, поддерживаемых поставщиком служб CSP, и получение максимальной и минимальной длины ключей для каждого алгоритма. Для этого вызовите CryptGetProvParam с PP_ENUMALGS_EX.
• Используйте минимальную и максимальную длину ключа, чтобы выбрать соответствующую длину ключа. Не всегда рекомендуется выбрать максимальную длину, так как это может привести к проблемам с производительностью.
• После выбора требуемой длины ключа используйте верхние 16 битов dwFlags, чтобы указать длину ключа.

Примеры

В следующем примере показано создание случайного ключа сеанса. Пример, содержащий полный контекст этого примера, см. в разделе Пример программы 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

CryptDeskkey

CryptExportKey

CryptGetKeyParam

CryptImportKey

CryptSetKeyParam

функции создания ключей и функций Exchange

проблемы потоков с поставщиками служб шифрования