Versions Compared

Old Version 4

changes.mady.by.user Timofey Matrenitskiy

Saved on

compared with

New Version 5

changes.mady.by.user Guardant R&D

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Composition Setup
 

Функция GrdTransform преобразует блок данных при помощи аппаратного алгоритма.

 

Входные параметрыВыходные параметры
Deck of Cards
id001
Wiki Markup
{dojo-tabs:theme=tundra|id=1} {dojo-tab:title=C|selected=true} *C*
Card
defaulttrue
labelС
Code Block
languagecpp
int GRD_API GrdTransform(	
  HANDLE hGrd,
  DWORD dwAlgoNum,
  DWORD dwLng,
  void *pData,
  DWORD dwMethod,
  void *pIV
);
{dojo-tab} {dojo-tab:title=C#|selected=true} *C#* {dojo-tab} {dojo-tab:title=Visual Basic (Declaration)} *Visual Basic* {dojo-tab} {dojo-tab:title=Visual C++} *Visual C++* {dojo-tab} {dojo-tabs}
 Expand
title
Параметры функции
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.
pIV
8-байтовый вектор инициализации. 
 Если в качестве указателя на вектор инициализации задан NULL, то преобразование пройдет корректно, при этом будет использован нулевой вектор 
 Для алгоритмов Guardant Stealth I и Fidus параметр не используются (значение должно быть NULL)
 Expand
title
Возвращаемые значения функции
GrdE_AlgoNotFound
Алгоритм с указанным номером не существует
GrdE_CRCErrorFunc
Ошибка CRC при выполнении алгоритма. Эта ошибка обычно возникает, если длина преобразуемой последовательности не совпадает с заданной во время создания алгоритма
GrdE_GPis0
Счетчик алгоритма достиг нулевого значения. Результат алгоритма больше нельзя получить
 Card
labelC#
 Code Block
languagec#
public static GrdE GrdTransform(Handle grdHandle, GrdAlgNum algNum, byte[] data, GrdAM method, ref long iv)
public static GrdE GrdTransform(Handle grdHandle, GrdAlgNum algNum, byte[] data, GrdAM method, byte[] iv)


 Expand
titleПараметры метода
 
 Expand
titleВозвращаемое значение метода
 
 Card
labelJava
 Code Block
languagejava
 
 Expand
titleПараметры метода
 
 Expand
titleВозвращаемое значение метода
 
 Expand
titleОписание
Функции GrdTransform позволяют преобразовывать информацию аппаратным алгоритмом ключа. Преобразование производится алгоритмом с порядковым номером, заданным в параметре 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) может оказываться занятым на более долгое время в течении каждой такой операции. Поэтому в приложениях, для которых это критично (например, со множественными независимыми параллельными запросами к ключу), лучше использовать более мелкие блоки.
Для режимов, использующих сцепление блоков, необходимо задавать 8-байтовый вектор инициализации pIV. При выполнении кодирования и декодирования необходимо задавать один и тот же вектор инициализации. Если кодирование/декодирование происходит в несколько приемов, то в качестве вектора инициализации нужно задавать значение, которое возвращается в pIV после выполнения предыдущей операции.
Для алгоритмов AES128
Для работы с аппаратными алгоритмами AES128 используйте функцию GrdTransformEx, т. к. только в этом случае есть возможность задания полного вектора инициализации (16 байт).
Для алгоритмов HASH64
Для работы с аппаратными алгоритмами HASH64 используйте функцию GrdHash. 
Для алгоритмов Guardant Stealth I и Guardant Fidus
Предупреждение
Данный тип алгоритмов не отвечает современным требованиям безопасности. Поддержка этих алгоритмов реализована исключительно в целях совместимости. В связи с этим алгоритмы данного типа не рекомендуются для использования в приложениях. Следует пользоваться алгоритмами GSII64, реализованными в Guardant Stealth/Net II/III.
Преобразование однонаправленное, т. е. для функции F(X) не существует функция F-1() такая, что X=F-1(F(X)). Оно производится алгоритмом с порядковым номером, заданным в параметре dwAlgoNum. Этот алгоритм предварительно должен быть создан. Длина массива с преобразуемыми данными (в байтах) задается параметром dwLng. Она должна быть равной длине вопроса алгоритма, заданной в его дескрипторе (допустимые значения - от 4 до 248). Сам массив должен находиться по адресу, указанному в параметре pData. Если функция выполнена успешно, по этому же адресу будет помещена последовательность преобразованных данных той же длины. В этом случае функция возвращает GrdE_OK.
 Expand
titleПример
Пример для используемого средства разработки см. в директории:
"\%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\"