Page History

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

...

Composition Setup

Deck of Cards

id	001

Expand

title

Card

label	С

Code Block

language	cpp

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

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.

dwIVLng

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

pIV

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

Reserved

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

Expand

title	Выходные параметрыВозвращаемое значение функции

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

Card

label	С#

Code Block

language	c#

public static GrdE Guardant.GrdApi.GrdTransformEx	([Handle] grdHandle,
										  	GrdAlgNum algNum,
											 byte[] data,
											 GrdAM  method,
											 byte[] iv 
											)

Handle

Expand

title	Входные параметрыПараметры метода

Expand

title	Выходные параметры

Cтандартный набор ошибок

Card

label	Visual Basic (Declaration)

Code Block

language	vb

Expand

title	Входные параметры

Expand

title	Выходные параметры

Cтандартный набор ошибок

Возвращаемое значение метода

Функция 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.

Card

label	Visual C++Java

Code Block

language	cppjava

Expand

title	Входные параметрыПараметры метода

Expand

title	Выходные параметры

Cтандартный набор ошибок

Card

label	Описание

Card

label	Примеры

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

"\%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\"

Wiki Markup

{dojo-tabs:theme=tundra|id=1}
{dojo-tab:title=C|selected=true}
*C*
int GRD_API GrdTransformEx(	
  HANDLE hGrd,
  DWORD dwAlgoNum,
  DWORD dwLng,
  void *pData,
  DWORD dwMethod,
  DWORD	dwIVLng
  void *pIV
  void	*pReserved
);		
{dojo-tab}
{dojo-tab:title=C#|selected=true}
*C#*
static GrdE Guardant.GrdApi.GrdTransformEx	([Handle001] grdHandle,
										  	GrdAlgNum algNum,
											byte[] data,
											GrdAM  method,
											byte[] iv 
											)
{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.

dwIVLng

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

pIV

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

Reserved

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

Expand

title	Выходные параметры

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

Возвращаемое значение метода

Card

label

Описание

Функция 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.

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\"

Page tree

Versions Compared

Old Version 22

New Version 23

Key

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

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

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

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