COM интерфейсы для работы с криптографическими алгоритмами. Signal-COM

Создание криптографического контекста
Многие функции CryptoAPI используют в качестве параметра криптографический контекст, получаемый с помощью функции CryptAcquireContext (см. MSDN). Наряду с другими параметрами в ней задаются имя и тип криптопровайдера. СКЗИ "Signal-COM CSP" включает в себя следующие криптопровайдеры (см. заголовочный файл SCCSP.H):

Имя Тип Описание
SC_ECGOST_PROV PROV_SC_ECGOST Криптопровайдер для алгоритма ГОСТ Р 34.10-2001. 
SC_CPGOST_PROV PROV_SC_CPGOST Криптопровайдер для алгоритма ГОСТ Р 34.10-2001 с параметрами, описанными в RFC 4491. 

Примечание. Для работы с устройством MS_Key в функции CryptAcquireContext необходимо задать тип провайдера PROV_SC_CPGOST и имя провайдера SC_CPGOST_PROV.

Открытие ключевого контейнера
Для открытия ключевого контейнера выполните следующие действия:

Вызовите функцию CryptAcquireContext с флагом равным нулю (можно задать дополнительные флаги CRYPT_SILENT и CRYPT_MACHINE_KEYSET, см. MSDN), задав параметры Signal-COM CSP, как указано в  Создание криптографического контекста.
Если имя ключевого контейнера в функции CryptAcquireContext не задано, СКЗИ "Signal-COM CSP" будет искать ключевой контейнер с именем текущего пользователя.
Если контейнер не найден, и флаг CRYPT_SILENT не задан, на экран будет выдано окно, с предложением вставить в считывающее устройство ключевой носитель с указанным ключевым контейнером. Если флаг CRYPT_SILENT задан, функция CryptAcquireContext завершится, установив код ошибки NTE_KEYSET_NOT_DEF.
Если датчик случайных чисел еще не был инициализирован, он будет инициализирован от данного ключевого контейнера.
Тип ключевого носителя можно задать в функции CryptAcquireContext явно (см. Создание ключевого контейнера).

Экспорт и импорт сеансового ключа
Алгоритм экспорта/импорта сеансового ключа для криптопровайдера типа SC_CPGOST_PROV (с параметрами, описанными в RFC 4491) отличается от алгоритма для криптопровайдера типа SC_ECGOST_PROV. Ниже приводится описание алгоритмов и примеры программ для каждого из криптопровайдеров.

Алгоритм экспорта/импорта сеансового ключа для криптопровайдера типа SC_CPGOST_PROV.

Для экспорта сеансового ключа выполните следующие действия:

Получите дескриптор секретного ключа отправителя с помощью функции CryptGetUserKey, передавая AT_KEYEXCHANGE в параметре dwKeySpec.
Импортируйте открытый ключ получателя с помощью функции CryptImportKey, передавая в параметре pbData указатель на BLOB открытого ключа получателя, в параметре dwDataLen длину этого BLOB и дескриптор секретного ключа отправителя в параметре hPubKey. В результате данной операции по алгоритму Diffie-Hellman будет сформирован Agreed Key (секретный ключ, общий для отправителя и получателя).
Задайте (опционально) алгоритм экспорта сеансового ключа с помощью функции CryptSetKeyParam, передавая в параметре hKey дескриптор AK, KP_ALGID в параметре dwParam и указатель на переменную со значением CALG_CP_SIMPLE_WRAP (RFC 4357, раздел 6.1) или CALG_CP_PRO_WRAP (RFC 4357, раздел 6.3) в параметре pbData. Алгоритмы экспорта (отправитель) и импорта (получатель) сеансового ключа должны совпадать! По умолчанию для экспорта сеансового ключа используется алгоритм CALG_CP_PRO_WRAP.
Для экспорта сеансового ключа вызовите функцию CryptExportKey, передавая в параметре hKey дескриптор сеансового ключа, в параметре hExpKey дескриптор ключа обмена, SIMPLEBLOB в параметре dwBlobType, нулевое значение в параметре dwFlags, в параметре pbData указатель на буфер для размещения BLOB сеансового ключа и в параметре pdwDataLen указатель на длину этого буфера.
Экспортированный таким образом сеансовый ключ должен передаваться получателю зашифрованных данных вместе с самими данными.

Для импорта сеансового ключа выполните следующие действия:

Получите дескриптор секретного ключа получателя с помощью функции CryptGetUserKey, передавая AT_KEYEXCHANGE в параметре dwKeySpec.
Импортируйте открытый ключ отправителя с помощью функции CryptImportKey, передавая в параметре pbData указатель на BLOB открытого ключа отправителя, в параметре dwDataLen  длину этого BLOB и дескриптор секретного ключа получателя в параметре hPubKey. В результате данной операции по алгоритму Diffie-Hellman будет сформирован Agreed Key.
Задайте (опционально) алгоритм импорта сеансового ключа с помощью функции CryptSetKeyParam, передавая в параметре hKey дескриптор AK, KP_ALGID в параметре dwParam и указатель на переменную со значением CALG_CP_SIMPLE_WRAP (RFC 4357, раздел 6.1) или CALG_CP_PRO_WRAP (RFC 4357, раздел 6.3) в параметре pbData. Алгоритмы экспорта (отправитель) и импорта (получатель) сеансового ключа должны совпадать! По умолчанию для импорта сеансового ключа используется алгоритм CALG_CP_PRO_WRAP.
Для импорта сеансового ключа вызовите функцию CryptImportKey, передавая в параметре pbData указатель на BLOB сеансового ключа, в параметре dwDataLen длину этого BLOB и дескриптор ключа обмена в параметре hPubKey.
Импортированный сеансовый ключ можно затем использовать для расшифрования (CryptDecrypt) данных (см. MSDN).

Алгоритм экспорта/импорта сеансового ключа для криптопровайдера типа SC_ECGOST_PROV.

Для экспорта сеансового ключа выполните следующие действия:

Получите дескриптор секретного ключа отправителя с помощью функции CryptGetUserKey, передавая AT_KEYEXCHANGE в параметре dwKeySpec.
Импортируйте открытый ключ получателя с помощью функции CryptImportKey, передавая в параметре pbData указатель на BLOB открытого ключа получателя, в параметре dwDataLen длину этого BLOB и дескриптор секретного ключа отправителя в параметре hPubKey. В результате данной операции по алгоритму Diffie-Hellman будет сформирован Agreed Key (секретный ключ, общий для отправителя и получателя).
Если для формирования Agreed Key (AK) использовался долговременный ключ отправителя (хранится в ключевом контейнере), с помощью функции CryptGenRandom сгенерируйте User Keying Material (ключевой материал пользователя). При использовании долговременных ключей, AK для определенной пары пользователей будет фиксированным, поэтому уникальный общий ключ обмена необходимо создавать на основе фиксированного AK и случайного User Keying Material (64 байта). User Keying Material (UKM) должен передаваться получателю зашифрованных данных вместе с самими данными.
С помощью функции CryptSetKeyParam установите значение UKM для AK, передавая в параметре hKey дескриптор AK, KP_IV в параметре dwParam и UKM в параметре pbData.
Для формирования ключа обмена на основе AK и UKM вызовите функцию CryptSetKeyParam, передавая в параметре hKey дескриптор AK, KP_ALGID в параметре dwParam и указатель на переменную со значением CALG_RUS_CMS_WRAP в параметре pbData.
Для экспорта сеансового ключа вызовите функцию CryptExportKey, передавая в параметре hKey дескриптор сеансового ключа, в параметре hExpKey дескриптор ключа обмена, SYMMETRICWRAPKEYBLOB в параметре dwBlobType, нулевое значение в параметре dwFlags, в параметре pbData указатель на буфер для размещения BLOB сеансового ключа и в параметре pdwDataLen указатель на длину этого буфера.
Экспортированный таким образом сеансовый ключ должен передаваться получателю зашифрованных данных вместе с самими данными.

Для импорта сеансового ключа выполните следующие действия:

Получите дескриптор секретного ключа получателя с помощью функции CryptGetUserKey, передавая AT_KEYEXCHANGE в параметре dwKeySpec.
Импортируйте открытый ключ отправителя с помощью функции CryptImportKey, передавая в параметре pbData указатель на BLOB открытого ключа отправителя, в параметре dwDataLen  длину этого BLOB и дескриптор секретного ключа получателя в параметре hPubKey. В результате данной операции по алгоритму Diffie-Hellman будет сформирован Agreed Key.
С помощью функции CryptSetKeyParam установите значение User Keying Material для Agreed Key, передавая в параметре hKey дескриптор AK , KP_IV в параметре dwParam и UKM в параметре pbData.
Для формирования ключа обмена на основе AK и UKM вызовите функцию CryptSetKeyParam, передавая в параметре hKey дескриптор AK, KP_ALGID в параметре dwParam и указатель на переменную со значением CALG_RUS_CMS_WRAP в параметре pbData.
Для импорта сеансового ключа вызовите функцию CryptImportKey, передавая в параметре pbData указатель на BLOB сеансового ключа, в параметре dwDataLen длину этого BLOB и дескриптор ключа обмена в параметре hPubKey.
Импортированный сеансовый ключ можно затем использовать для расшифрования (CryptDecrypt) данных (см. MSDN).

Пример программы на C++, демонстрирующей формирование секретного ключа обмена для пары пользователей, генерацию сеансового ключа, зашифрование данных, экспорт сеансового ключа, импорт сеансового ключа и расшифрование данных для криптопровайдеров типа SC_CPGOST_PROV (функция RFC4491ProviderSample) и SC_ECGOST_PROV (функция SignalCOMProviderSample), приводится в файле exp_sess.cpp (каталог samples\exp_sess).

Формирование сеансовых ключей на основе мастер-ключа
В СКЗИ "Signal-COM CSP" реализована возможность формирования сеансовых ключей на основе мастер-ключа с использованием PRF (Pseudo-Random Function). Мастер-ключом может быть только сеансовый ключ, созданный с помощью функции CryptGenKey (см. Зашифрование и расшифрование данных) или выработанный с помощью алгоритма Diffie-Hellman (см. Экспорт и импорт сеансового ключа). Для формирования нового сеансового ключа на основе существующего мастер-ключа выполните следующие действия:

Вызовите функцию CryptCreateHash для создания хэш-объекта, задав криптографический контекст Signal-COM CSP, идентификатор хэш-алгоритма CALG_TLS1PRF и дескриптор мастер-ключа.
С помощью функции CryptSetHashParam можно (необязательно) задать для созданного хэш-объекта значение метки - произвольную текстовую строку, передавая в качестве типа параметра HP_TLS1PRF_LABEL, а саму метку в структуре CRYPT_DATA_BLOB.
Задайте для данного хэш-объекта заранее выбранные данные (seed), не являющиеся секретными и однозначно соответствующие сеансу шифрования, для которого вырабатывается ключ (например, уникальный идентификатор сеанса связи или пакета данных). Для этого вызовите функцию CryptSetHashParam, передавая в качестве типа параметра HP_TLS1PRF_SEED, а сами данные в структуре CRYPT_DATA_BLOB.
Вызовите функцию CryptDeriveKey, задав требуемый для сеансового ключа идентификатор алгоритма шифрования и дескриптор данного хэш-объекта (вектор инициализации создается автоматически и сохраняется в контексте созданного сеансового ключа).
Пример программы на C++, демонстрирующей формирование сеансового ключа на основе мастер-ключа, приводится в файле prf_sess.cpp (каталог samples\prf_sess).

Формирование и проверка цифровой подписи сообщения
Для формирования подписи сообщения с использованием Signal-COM CSP выполните следующие действия:

Инициализируйте структуру CRYPT_SIGN_MESSAGE_PARA.
В поле pSigningCert задайте сертификат автора подписи, соответствующий формату сертификатов СКЗИ "Signal-COM CSP".
В поле HashAlgorithm.pszObjId для сертификата с параметрами Сигнал-КОМ задайте szOID_R3411, для сертификата с параметрами, описанными в RFC 4491 - szOID_CP_R3411 (см. заголовочный файл SCCSP.H).
Вызовите функцию CryptSignMessage для формирования подписи сообщения, задав структуру CRYPT_SIGN_MESSAGE_PARA и другие параметры как описано в MSDN.
Для проверки подписи сообщения используйте функцию CryptVerifyMessageSignature.

Пример программы на C++, демонстрирующей формирование и проверку подписи сообщения с использованием  СКЗИ "Signal-COM CSP", приводится в файле sign_msg.cpp (каталог samples\sign_msg).