You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 3 Next »

Функция GrdTransformEx преобразует блок данных при помощи симметричного аппаратного алгоритма (GSII64 и AES). Расширенная версия функции GrdTransform.

 

C
int GRD_API GrdTransformEx(
HANDLE hGrd,
DWORD dwAlgoNum,
DWORD dwLng,
void *pData,
DWORD dwMethod,
DWORD dwIVLng
void *pIV
void *pReserved
);

C#

Visual Basic

Visual C++

hGrd

хэндл, через который будет выполнена данная операция

dwAlgoNum

номер аппаратного алгоритма, которым будет производиться преобразование

dwLng

длина блока данных в байтах

pData

буфер данных для преобразования

dwMethod

метод преобразования, который задается комбинацией флагов GrdAM_XXX. Для алгоритмов Guardant Stealth I и Fidus значение параметра должно быть 0

Биты 0-5 - режим работы алгоритма

GrdAM_ECB

Режим электронной кодовой книги

GrdAM_CBC

Режим сцепления кодированных блоков

GrdAM_CFB

Режим с кодированной обратной связью

GrdAM_OFB

Режим с обратной связью по выходу

Бит 6 - резерв

Бит 7 - тип операции

GrdAM_Encode

Кодировать блок

GrdAM_Decode

Декодировать блок

Флаги GrdSC_XXX тут не используются, так как это просто синоним старой функции nXkTransformEx. Мы рекомендуем вместо нее использовать функцию GrdCrypt.

dwIVLng

Длина вектора инициализации:
- для GSII64 - 8 байтов, для AES - 16 байтов,
- для алгоритмов Guardant Stealth I и Fidus значение параметра должно быть NULL, поскольку в этих алгоритмах вектор инициализации не используется

pIV

8-байтовый вектор инициализации.
Если в качестве указателя на вектор инициализации задан NULL, то преобразование пройдет корректно, при этом будет использован нулевой вектор
Для алгоритмов Guardant Stealth I и Fidus параметр не используются (значение должно быть NULL)

Reserved

не используется. Параметр должен быть равен NULL

GrdE_AlgoNotFound

Алгоритм с указанным номером не существует.

GrdE_CRCErrorFunc

Ошибка CRC при выполнении алгоритма. Эта ошибка обычно возникает, если длина преобразуемой последовательности не совпадает с заданной во время создания алгоритма.

GrdE_GPis0

Счетчик алгоритма достиг нулевого значения. Результат алгоритма больше нельзя получить.

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

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

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

Для алгоритмов GSII64

Длина массива преобразуемых данных (в байтах) pData задается параметром dwLng и зависит от режима работы алгоритма. Для режимов ECB и CBC длина данных должна быть кратной GrdARS_GSII64 (8 байт), максимально GrdAMRS_GSII64 (248 байт). Если задана длина массива, не кратная 8 байтам, функция возвращает код ошибки GrdE_InvalidArg. Для режимов CFB и OFB длина может быть произвольной, но не превышающей 255 байт. Параметр dwMethod задается суммой флагов (см. GRDAPI.H).

Массив данных для преобразования должен находиться по адресу, указанному в параметре pData. Если функция выполнена успешно, по этому же адресу будет помещена последовательность преобразованных данных той же длины. В этом случае функция возвращает GrdE_OK.

Скорость кодирования/декодирования напрямую зависит от длины dwLng блока данных pData, передаваемого в GrdTransform. Максимальная скорость достигается при максимальной длине блока. Если размер блока данных сильно превышает максимальное значение dwLng, его нужно разбивать на куски максимально возможной длины. Однако при таком подходе ключ (особенно с интерфейсом LPT) может оказываться занятым на более долгое время в течении каждой такой операции. Поэтому в приложениях, для которых это критично (например, со множественными независимыми параллельными запросами к ключу), лучше использовать более мелкие блоки.

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

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

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

Для алгоритмов HASH64

Для работы с аппаратными алгоритмами HASH64 используйте функцию GrdHash.

Пример для используемого средства разработки см. в директории:

"\%Program Files%\Guardant\Guardant 6\%PublicCode%\Samples\x86\Win32\General Guardant API\"
или
"\%Program Files%\Guardant\Guardant 6\%Public Code%\Samples\x64\Win64\General Guardant API\"

  • No labels