GrdCryptEx

Набор ошибок Guardant API

Функция GrdCryptEx позволяет зашифровать или расшифровать данные с помощью аппаратного или программно-реализованного симметричного алгоритма. электронного ключа.GrdCryptEx является расширенной версией функции GrdCrypt и предназначена для работы с алгоритмами шифрования с переменным вектором инициализации. По сравнению с GrdCrypt функция содержит 2 новых параметра: длина вектора инициализации (dwIVLng) и зарезервированное значение. Шифрование выполняется алгоритмом с числовым именем, заданным в параметре dwAlgo. Этот алгоритм предварительно должен быть создан, в противном случае возвращается ошибка GrdE_AlgoNotFound. Если в дескрипторе алгоритма установлен флаг "уменьшение счетчика", то вычитание счетчика алгоритма происходит при каждом вызове GrdCryptEx. При достижении счетчиком нулевого значения, возвращается ошибка GrdE_GPis0. Если при создании алгоритма или в процессе работы он был переведен в неактивное состояние, возвращается ошибка GrdE_InactiveItem.

Преобразование производится алгоритмом с порядковым номером, заданным в параметре dwAlgo. В зависимости от своего параметра dwAlgo функция определяет тип алгоритма и каким образом он реализован  аппаратным или программным.  Если параметр соответствует аппаратному алгоритму(GSII64 или AES128), вызов переадресуется функции GrdTransformEx. Иначе, если алгоритм реализован программно (dwAlgo=GrdSC_AES256), вызывается соответствующая функция программного шифрования.

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

Длина буфера данных задаётся параметром dwLng. Для режимов ECB и CBC она должна быть кратна размеру блока алгоритма шифрования, в противном случае возвращается ошибка GrdE_InvalidArg. Для режимов CFB и OFB длина может быть произвольной, т.к. в этих режимах открытый или зашифрованный текст складываются по модулю 2 с ключевыми блоками полученными в результате работы операции блочного шифра. Открытый или зашифрованный текст должны находиться по адресу, указанному в параметре pData. Если функция выполнена успешно, то по этому адресу будут размещены зашифрованные или расшифрованные данные той же длины. В этом случае функция возвращает GrdE_OK.

В таких режимах шифрования, как CBC, CFB и OFB функции необходимо передать указатель на вектор инициализации pIV и длину вектора инициализации в параметре dwIVLng. После выполнения операции буфер, на который указывает pIV, будет содержать значение необходимое функции для повторного вызова. Длина вектора инициализации должна быть равна размеру блока алгоритма шифрования. Если длина окажется больше указанной величины, то лишние байты будут проигнорированы. Если длина окажется меньше указанной величины, то исходный буфер будет дополнен нулями. При вызове функции с нулевым указателем на вектор инициализации, ситуация равноценна использованию вектора инициализации состоящего из нулевых значений или вектора инициализации нулевой длины.

Программно-реализованные алгоритмы шифрования при шифровании больших массивов данных используют контекст, память для которого размером не менее GrdXXXXXX_CONTEXT_SIZE должна быть зарезервирована до вызова функции. Указатель на буфер для контекста передается через параметр pContext.

Если шифрование на аппаратно-реализованном алгоритме выполнялось блоками произвольной длины, то для корректного расшифрования длина и порядок обработки блоков должны сохраняться. При выполнении операций шифрования и расшифрования следует использовать один и тот же вектор инициализации, если предполагается получить исходный открытый текст.

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

Новый параметр (dwIVLng) имеет смысл для аппаратных алгоритмов с переменным вектором инициализации, которые появятся в будущем. На существующих алгоритмах (к примеру GSII64) это отразится лишь в том случае, если указывается длина вектора инициализации от 0 до 8 байт (включительно). При указании длины более 8 байт шифрование происходит с использованием первых 8 байт указанного вектора инициализации.

При вызове функций GrdCrypt и GrdCryptEx с нулевым указателем на вектор инициализации возвращается GrdE_OK, шифрование и последующее расшифрование происходит нормально в любых режимах (в т. ч. тех, которые требуют вектор инициализации). Ситуация полность аналогична использованию нулевого вектора инициализации или вектора инициализации нулевой длины.

Функция GrdCryptEx позволяет зашифровывать и расшифровывать данные с использованием аппаратно или программно-реализованных симметричных алгоритмов. GrdCryptEx является расширенной версией функции GrdCrypt и предназначена для работы с алгоритмами шифрования с переменным вектором инициализации. По сравнению с GrdCrypt функция содержит 2 новых параметра: длина вектора инициализации (dwIVLng) и зарезервированное значение.

Преобразование производится алгоритмом с порядковым номером, заданным в параметре dwAlgo. В зависимости от номера алгоритма dwAlgo функция определяет, каким образом реализован алгоритм - аппаратным или программным. Если номер алгоритма соответствует аппаратному алгоритму, вызов переадресуется функции GrdTransform. Аппаратно реализованный алгоритм должен быть типа GSII64. Иначе, если алгоритм реализован программно (dwAlgo>=GrdSA_SoftAlgo), вызывается соответствующая функция программного шифрования.

Программно-реализованные алгоритмы шифрования при шифровании больших массивов данных используют контекст, память для которого размером не менее GrdXXXXXX_CONTEXT_SIZE должна быть зарезервирована до вызова функции. Указатель на буфер для контекста передается через параметр pContext.

Длина шифруемых блоков данных зависит от метода шифрования (см. описание методов в Руководство пользователя, часть 2). Для методов CFB и OFB длина шифруемых блоков может быть произвольной.

Если шифрование на аппаратно-реализованном алгоритме выполнялось блоками произвольной длины (т. е. использовались флаги GrdSC_First, GrdSC_Next, GrdSC_Last), то для корректного расшифрования длина и порядок обработки блоков должны сохраняться. Для программно-реализованных алгоритмов такое ограничение отсутствует.

Если в дескрипторе аппаратного алгоритма установлен флаг nsafl_GP_dec (уменьшение счетчика), вычитание счетчика GP происходит при каждом вызове GrdCrypt.

Новый параметр (dwIVLng) имеет смысл для аппаратных алгоритмов с переменным вектором инициализации, которые появятся в будущем. На существующих алгоритмах (к примеру GSII64) это отразится лишь в том случае, если указывается длина вектора инициализации от 0 до 8 байт (включительно). При указании длины более 8 байт шифрование происходит с использованием первых 8 байт указанного вектора инициализации.

При вызове функций GrdCrypt и GrdCryptEx с нулевым указателем на вектор инициализации возвращается GrdE_OK, шифрование и последующее расшифрование происходит нормально в любых режимах (в т. ч. тех, которые требуют вектор инициализации). Ситуация полность аналогична использованию нулевого вектора инициализации или вектора инициализации нулевой длины.