КриптоПро CSP  

CPImportKey

Функция CPImportKey() используется для импорта криптографического ключа из ключевого блоба в контейнер криптопровайдера, для диверсификации ключа с использованием данных, передаваемых через ключевой блоб в соответствии с RFC 4357, п. 7., а так же для диверсификации ключа в соответствии с алгоритмами, описанным в п. 4.4, 4.5 рекомендаций по стандартизации "Криптографические алгоритмы, сопутствующие применению алгоритмов электронной цифровой подписи и функции хэширования".

BOOL WINAPI CPImportKey(
  HCRYPTPROV hProv,
  CONST BYTE * pbData,
  DWORD dwDataLen,
  HCRYPTKEY hImpKey,
  DWORD dwFlags,
  HCRYPTKEY * phKey
);

Аргументы

pbData
[in] Указатель на буфер, содержащий ключевой блоб, произведенный с иcпользованием функции CPExportKey() данным или другим криптопровайдером, функционирующим на удалённом компьютере, или блоб диверсификации, используемый для диверсификации ключа на основе данных, передаваемых через блоб в соответствии с RFC 4357, п. 7. или в соответствии с п. 4.4, 4.5 рекомендаций по стандартизации "Криптографические алгоритмы, сопутствующие применению алгоритмов электронной цифровой подписи и функции хэширования"
dwDataLen
[in] Длина ключевого блоба в байтах.
hImpKey
[in] Дескриптор ключа, на котором осуществляется снятие криптографической защиты импортируемого ключа. Значение этого параметра должно соответствовать значению hExpKey, определённому для функции CPExportKey() при создании ключевого блоба. После зашифрования ключевого блоба на сессионном ключе этот параметр содержит дескриптор на сессионный ключ. Если ключевой блоб не зашифрован (например, PUBLICKEYBLOB), этот параметр не используется и должен быть равен нулю. В алгоритме диверсификации hImpKey - исходный ключ, из которого вырабатываются диверсифицированные ключи.
dwFlags
[in] Значение флага. Этот параметр в настоящее время используется только, когда ключевая пара (закрытый/открытый ключи) импортируется в криптопровайдер (в форме PRIVATEKEYBLOB). Если импортируемый ключ будет заново экспортироваться, в этот параметр помещается флаг CRYPT_EXPORTABLE. Если этот флаг не используется, вызовы функции CryptExportKey в MS CryptoAPI 2.0 World Wide Web link с дескриптором ключа будут терпеть неудачу.
phKey
[out] Адрес, по которому функция копирует дескриптор импортированного либо диверсифицированного ключа. В алгоритме диверсификации ключ phKey наследует параметры ключа hImpKey: KP_OID, KP_MODE, KP_MIXMODE, KP_PADDING. При импорте ключей CALG_GR3410EL, CALG_DH_EL_SF, CALG_DH_GR3410_12_256_SF, CALG_GR3410_12_256, CALG_DH_GR3410_12_512_SF, CALG_GR3410_12_512, CALG_UECSYMMETRIC, если ключевой контейнер не содержит соответствующих ключей AT_SIGNATURE, AT_KEYEXCHANGE, AT_UECSYMMETRICKEY, импортируемые ключи устанавливаются в ключевой контейнер

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

При успешном завершении функция возвращает TRUE, в противном случае возвращается FALSE. Если возвращается FALSE, соответствующий код ошибки (см. таблицу) может быть получен через функцию GetLastError.
Коды возвратаОписание
ERROR_INVALID_PARAMETERОдин из параметров содержит некорректное значение. Чаще всего это некорректный указатель.
NTE_BAD_DATAНе прошёл контроль целостности импортируемого ключевого блоба. Ошибочная длина блоба.
NTE_BAD_FLAGSПараметр dwFlags содержит ошибочную величину.
NTE_BAD_KEYОдин или оба из ключей, указанных hKey и hImpKey, не действительны. Байты в элементах заголовка ключевого блоба типа WORD, DWORD имеют обратный порядок по отношению к данной платформе.
NTE_BAD_TYPEТип ключевого блоба не поддерживается этим криптопровайдером и, возможно, ошибочен.
NTE_PERMПопытка импорта ключа, когда право импорта криптопровайдером не предоставлено.
NTE_NO_MEMORYКриптопровайдер во время операции исчерпал память.
NTE_FAILНарушение целостности ключей в ОЗУ. см. Дополнительные параметры и определения .
SCARD_W_CANCELLED_BY_USERПользователь прервал операцию нажатием клавиши Cancel
SCARD_W_WRONG_CHVПользователь ввёл неправильный пароль или пароль, установленный функцией SetProvParam(), неправильный
SCARD_E_INVALID_CHVПользователь ввёл пароль с нарушением формата или пароль, установленный функцией SetProvParam(), имеет неправильный формат. Например, пароль имеет недопустимую длину или содержит недопустимые символы.
SCARD_W_CHV_BLOCKEDВвод Pin-кода был заблокирован смарт-картой, т.к. исчерпалось количество попыток, разрешенное картой для ввода.
NTE_TOKEN_KEYSET_STORAGE_FULLНедостаточно места на носителе для сохранения информации.
NTE_SILENT_CONTEXTОперация не может быть выполнена без пользовательского интерфейса.
SCARD_W_REMOVED_CARDНоситель контейнера был удалён из считывателя
NTE_EXISTSПопытка импортировать ключ в случае, когда ключ соответствующего типа в контейнере существует.

Примечания

Обычно для согласования (экспорта/импорта) сессионного ключа применяют алгоритм Диффи-Хеллмана. В этом случае ключ парной связи (ключ экспорта/импорта сессионного ключа) порождается операцией импорта открытого ключа получателя (отправителя) на ключевой паре отправителя (получателя). Следует учитывать, что при использовании эфемерных ключей аутентификация пользователей не обеспечивается. Для импорта сессионного ключа следует выполнить следующие шаги:

Для ключей 2012 в качестве алгоритма согласования сессионного ключа используется алгоритм VKO GOST R 34.10-2012-256 (на основе функции хэширования ГОСТ Р 34.11-2012-256), параметр KP_CIPHEROID результирующего ключа принимает значение, установленное в параметрах импортируемого открытого ключа (если не указано, то "1.2.643.7.1.2.5.1.1", вариант ТК26 Z). Режимы шифрования, преобразования ключа и дополнения открытого текста до кратности блока для получаемого ключа устанавливаются аналогично вновь создаваемому ключу (см. CPSetKeyParam()).

Для ключей 2001 используется алгоритм VKO GOST R 34.10-2001 (на основе функции хэширования ГОСТ Р 34.11-94). При использовании данного алгоритма с долговременным ключом параметр KP_CIPHEROID полученного ключа принимает oid параметров шифрования, установленный в соответствующем долговременному ключу контейнере; при использовании с эфемерным ключом параметр KP_CIPHEROID результирующего ключа принимает установленное для провайдера значение PP_CIPHEROID. Режимы шифрования, преобразования ключа и дополнения открытого текста до кратности блока для получаемого ключа устанавливаются аналогично вновь создаваемому ключу (см. CPSetKeyParam()).

В случае импорта SIMPLEBLOB набор узлов замены устанавливается в соответствии с указанным в блобе. Режимы шифрования, преобразования ключа и дополнения открытого текста до кратности блока для получаемого ключа устанавливаются аналогично вновь создаваемому ключу (см. CPSetKeyParam()).

В случае импорта OPAQUEKEYBLOB набор узлов замены, режимы шифрования, преобразования ключа и дополнения открытого текста до кратности блока устанавливаются в соответствии с параметрами, указанными в блобе.

С помощью этой же функции в режиме диверсификации ключа (CRYPT_DIVERSBLOB ) можно создавать ключи блоков (пакетов) на основе сессионного ключа.

	    
      // Пример получения ключа блока (пакета) на основе ключа сесcии (файла, ассоциации)
      // с помощью возможности диверсификации ключа функцией CPImportKey в соответствии с
      // алгоритмом, описанным в п.7 RFC 4357.
      // bBlockNumber - байтовая последовательность, диверсифицирующая ключ.
      Blob.DiversBlobHeader.BlobHeader.bType = DIVERSKEYBLOB;
      Blob.DiversBlobHeader.BlobHeader.bVersion = 0x20;
      Blob.DiversBlobHeader.BlobHeader.reserverd = 0;
      Blob.DiversBlobHeader.BlobHeader.aiKeyAlg = CALG_G28147;
      Blob.DiversBlobHeader.aiDiversAlgId = CALG_PRO_DIVERS;
      Blob.DiversBlobHeader.dwDiversMagic = 0x31564944;
      Blob.DiversBlobHeader.cbDiversData = sizeof(bBlockNumber);
      CopyMemory((LPBYTE)Blob.bDiversData,bBlockNumber,sizeof(bBlockNumber));
      CPImportKey(hCSP, hProv, &Blob, sizeof(Blob), hSessionKey, 0, &hBlkKey);
      // Диверсификация в соответствии с алгоритмом KDF_GOSTR3411_2012_256
      // проводится аналогично с тем отличием, что в поле aiDiversAlgId
      // записывается константа CALG_PRO12_DIVERS
      ...
	

С помощью этой же функции в режиме диверсификации ключа (CRYPT_KDF_TREE_DIVERSBLOB ) можно создавать ключи блоков (пакетов) на основе процедуры диверсификации КриптоПро CSP, предусматривающей возможность выработки нескольких ключей.

	    
      ...
      // Пример выработки нескольких ключей на основе ключа диверсификации
      // с помощью алгоритма CALG_KDF_TREE_GOSTR3411_2012_256, описанного
      // в п.4.5 рекомендаций по стандартизации "Криптографические алгоритмы,
      // сопутствующие применению алгоритмов электронной цифровой подписи и функции хэширования"
      // bSeedData - байтовая последовательность Seed, диверсифицирующая ключ.
      // bLabelData - байтовая последовательность Label, диверсифицирующая ключ.
      dwBlobLen = sizeof(CRYPT_KDF_TREE_DIVERSBLOB_HEADER) + sizeof(CRYPT_KDF_TREE_DIVERS_INFO) +
          sizeof(bSeedData) + sizeof(bLabelData);
      DiversBlob.KdfTreeBlobHeader.BlobHeader.aiKeyAlg = CALG_G28147;
      DiversBlob.KdfTreeBlobHeader.BlobHeader.bType = KDF_TREE_DIVERSBLOB;
      DiversBlob.KdfTreeBlobHeader.BlobHeader.bVersion = BLOB_VERSION;
      DiversBlob.KdfTreeBlobHeader.BlobHeader.reserved = 0;
      DiversBlob.KdfTreeBlobHeader.aiDiversAlgId = CALG_KDF_TREE_GOSTR3411_2012_256;
      DiversBlob.KdfTreeBlobHeader.dwIterNum = 1;
      DiversBlob.KdfTreeDiversInfo.dwLabelLen = sizeof(bLabelData);
      DiversBlob.KdfTreeDiversInfo.dwSeedLen = sizeof(bSeedData);
      DiversBlob.KdfTreeDiversInfo.L_value = 1024;
      DiversBlob.KdfTreeDiversInfo.R_value = 2;
      CopyMemory((LPBYTE)DiversBlob.bDiversData, bSeedData, sizeof(bSeedData));
      CopyMemory((LPBYTE)DiversBlob.bDiversData + sizeof(bSeedData), bLabelData, sizeof(bLabelData));
      // Первичный вызов с передачей всех параметров диверсификации
      CPImportKey(hCSP, hProv, &DiversBlob, dwBlobLen, hSessionKey, 0, &hDivKey[0]);
      // Для последующих вызовов достаточно передачи хэдера с нужным номером ключа
      // Вызовы с различными номерами результирующих ключей могут идти не по порядку
      DiversBlob.KdfTreeBlobHeader.dwIterNum = 3;
      CPImportKey(hCSP, hProv, &DiversBlob.KdfTreeBlobHeader,
          sizeof(CRYPT_KDF_TREE_DIVERSBLOB_HEADER), hSessionKey, 0, &hDivKey[1]);
      ...
	

Полученный дескриптор ключа должен в обязательном порядке быть удалён с помощью вызова функции CPDestroyKey()  до вызова функции CPReleaseContext() для рабочего дескриптора криптопровайдера.

Требования:

AIX: 5/6/7 или выше.
FreeBSD: 7/8/9 или выше.
Linux: LSB 3.1 (RHEL 4, SuSE 10) или выше.
Solaris: 10 или выше.
Mac OSX: 10.7/8 или выше.
iOS: 6/7 или выше.
Windows 2000 или выше: Необходимо Windows 2000 SP4 или старше с Internet Explorer 6.0 или старше.
Файл описания: Прототип описан в файле wincsp.h.
Ядро ОС: Вместо неё используется аналогичная функция CPCImportKey .

См. также

CRYPT_PRIVATEKEYBLOB ,CRYPT_PUBLICKEYBLOB ,CRYPT_SIMPLELOB ,CRYPT_DIVERSBLOB ,CPExportKey() ,CPGenKey() ,CPImportKey в MS CSP World Wide Web link ,CryptImportKey в MS CryptoAPI 2.0 World Wide Web link