Versions Compared

Key

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

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

Composition Setup
 

...

Синтаксис 

Входные параметры
Deck of Cards
id001
Wiki Markup
{dojo-tabs:theme=tundra|id=1} {dojo-tab:title=C|selected=true} *C*
Card
labelС
Code Block
languagecpp
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#* {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

открытого или зашифрованного текста

dwMethod

cледующие флаги позволяют указать режим работы алгоритма и тип операции:

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

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

GrdAM_ECB

Режим электронной кодовой книги (режим простой замены). Каждый блок открытого текста заменяется блоком шифротекста. Шифрование двух одинаковых блоков даст идентичный результат. Скорость обработки блоков в режиме ЕСВ фиксирована. Недостаток ECB, в сравнении c другими режимами шифрования, — сохранение статистических особенностей открытого текста. 

GrdAM_CBC

Режим сцепления

кодированных блоков

блоков шифротекста. Каждый блок открытого текста (кроме первого) побитово складывается по модулю 2 (операция XOR) с предыдущим результатом шифрования.Таким образом, каждый блок зашифрованного текста зависит от всех блоков открытого текста, обработанных до него. Режим CBC лишён недостатка алгоритма ECB, но всё же имеет ряд недостатков с точки зрения безопасности.

GrdAM_CFB

Режим обратной связи по шифротексту (режим гаммирования с

кодированной

обратной связью). Для шифрования следующего блока открытого текста он складывается по модулю 2 с перешифрованным (блочным шифром) результатом шифрования предыдущего блока. Криптостойкость СFВ определяется криптостойкостью используемого шифра.

GrdAM_OFB

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

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

Бит 6 - резерв

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

GrdAM_

Encode

Encrypt

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

Зашифровать блок данных

GrdAM_

Decode

Decrypt

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

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

dwIVLng

Длина

Расшифровать блок данных

dwIVLng

длина вектора инициализации: 

-

для GSII64 - 8

байтов

байт, для

AES

AES128 и AES256 - 16

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

pIV

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

байт. 

pIV

указатель на вектор инициализации для режимов шифрования CBC, CFB и OFB. Для режима ECB данный параметр игнорируется

Reserved

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

Expand
title
Выходные параметры
Возвращаемое значение функции
GrdE_OKОперация выполнена успешно.

GrdE_AlgoNotFound

Алгоритм

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

GrdE_InvalidArg

Задано недопустимое значение одного из аргументов функции.

GrdE_

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

NoService

Для алгоритма/ячейки сервис не предусмотрен.

GrdE_GPis0Счетчик алгоритма достиг нулевого значения.
Результат алгоритма больше нельзя получить.
GrdE_InactiveItemАлгоритм/ячейка находятся в неактивном состоянии, команда не выполнена.
Перейти к списку всех ошибок Guardant API
Expand
titleОписание

Функция GrdTransformEx позволяет

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

зашифровать или расшифровать данные с помощью аппаратно-реализованного в электронном ключе криптографического алгоритма. Шифрование выполняется алгоритмом с номером, заданным в параметре dwAlgoNum. Этот алгоритм предварительно должен быть создан, в противном случае возвращается ошибка GrdE_AlgoNotFound. Если в дескрипторе алгоритма установлен

флаг nsafl_GP_dec (

флаг "уменьшение счетчика

)

",

вычитание

то вычитание счетчика

GP

алгоритма происходит при каждом вызове

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

GrdTransformEx. При достижении счетчиком нулевого значения, возвращается ошибка GrdE_GPis0. Если при создании алгоритма или в процессе работы он был переведен в неактивное состояние, возвращается ошибка GrdE_InactiveItem.

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

Длина буфера данных задаётся параметром dwLng

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

Длина массива преобразуемых данных (в байтах) pData задается параметром dwLng и зависит от режима работы алгоритма

. Для режимов ECB и CBC

длина данных должна быть кратной GrdARS_GSII64 (8 байт), максимально GrdAMRS_GSII64 (248 байт). Если задана длина массива, не кратная 8 байтам, функция возвращает код ошибки

она должна быть кратна размеру блока алгоритма шифрования, в противном случае возвращается ошибка GrdE_InvalidArg.

Для

 Для режимов CFB и OFB длина может быть произвольной,

но не превышающей 255 байт. Параметр dwMethod задается суммой флагов (см. GRDAPI.H).Массив данных для преобразования должен

т.к. в этих режимах открытый или зашифрованный текст складываются по модулю 2 с ключевыми блоками полученными в результате работы операции блочного шифра. Открытый или зашифрованный текст должны находиться по адресу, указанному в параметре 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\"

.

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

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

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

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

Размер блока алгоритма шифрования равен 8 байт. Для ключей Stealth II максимальная длина пакета 248 байт (GrdAMRS_GSII64), а для линейки моделей Sign 16384 байт.

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

Размер блока алгоритма шифрования равен 16 байт. Максимальная длина пакета 16384 байт.

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

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

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

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

Card
labelС#
Code Block
languagec#
public static GrdE GrdTransformEx(Handle grdHandle, GrdAlgNum algNum, byte[] data, GrdAM method, byte[] iv)
Expand
titleПараметры метода

grdHandle [in] 

Тип: Handle

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

algNum [in]

Тип: GrdAlgNum , GrdAN

Номер дескриптора алгоритма, которым будет проводиться шифрование или расшифрование. В примерах используются объекты класса GrdAN для передачи номеров демонстрационных алгоритмов.

data [in,out]

Тип: byte [ ]

Массив данных открытого или зашифрованного текста.

method [in]

Тип: GrdAM

Для одновременной передачи методу режима работы алгоритма и типа операции шифрования, класс GrdAM содержит перегрузки оператора сложения. Например, чтобы зашифровать блок данных в режиме электронной кодовой книги, методу достаточно передать GrdAM.ECB + GrdAM.Encrypt.

iv [in,out]

Тип: byte [ ]

Вектор инициализации для режимов шифрования CBC, CFB и OFB:

для GSII64 - 8 байт, для AES128 и AES256 - 16 байт. 

Expand
titleВозвращаемое значение метода
GrdE.OKОперация выполнена успешно.

GrdE.AlgoNotFound

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

GrdE.InvalidArg

Задано недопустимое значение одного из аргументов функции.

GrdE.NoService

Для алгоритма/ячейки сервис не предусмотрен.

GrdE.GPis0Счетчик алгоритма достиг нулевого значения.
GrdE.InactiveItemАлгоритм/ячейка находятся в неактивном состоянии, команда не выполнена.
Перейти к списку всех ошибок Guardant API
Expand
titleОписание

Метод GrdTransformEx позволяет зашифровать или расшифровать данные с помощью аппаратно-реализованного в электронном ключе криптографического алгоритма. Шифрование выполняется алгоритмом с номером, заданным в параметре algNum. Этот алгоритм предварительно должен быть создан, в противном случае возвращается ошибка GrdE.AlgoNotFound. Если в дескрипторе алгоритма установлен флаг "уменьшение счетчика", то вычитание счетчика алгоритма происходит при каждом вызове GrdTransformEx. При достижении счетчиком нулевого значения, возвращается ошибка GrdE.GPis0. Если при создании алгоритма или в процессе работы он был переведен в неактивное состояние, возвращается ошибка GrdE.InactiveItem

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

Для режимов ECB и CBC длина массива данных (в байтах) должна быть кратна размеру блока алгоритма шифрования, в противном случае возвращается ошибка GrdE.InvalidArg. Для режимов CFB и OFB длина может быть произвольной, т.к. в этих режимах открытый или зашифрованный текст складываются по модулю 2 с ключевыми блоками полученными в результате работы операции блочного шифра. Открытый или зашифрованный текст должны находиться в массиве передаваемом по ссылке в параметре data. Если метод выполнен успешно, то в этом же массиве будут размещены зашифрованные или расшифрованные данные той же длины. В этом случае метод возвращает GrdE.OK.

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

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

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

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

Размер блока алгоритма шифрования равен 8 байт. Максимальная длина пакета 248 байт.

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

Размер блока алгоритма шифрования равен 16 байт. Максимальная длина пакета 16384 байт.

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

Для работы с аппаратно-реализованными алгоритмами ECC160 используйте метод GrdSign.

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

Для работы с аппаратно-реализованными алгоритмами HASH64 используйте метод GrdHashEx.

Card
labelJava
Code Block
languagejava
 public static GrdE GrdTransformEx(Handle grdHandle, int algoNum, byte[] data, GrdAM method, byte[] iv)
Expand
titleПараметры метода

grdHandle [in] 

Тип: Handle

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

algNum [in]

Тип: int

Номер дескриптора алгоритма, которым будет проводиться шифрование или расшифрование. В примерах используются объекты класса GrdAN для передачи номеров демонстрационных алгоритмов.

data [in,out]

Тип: byte [ ]

Массив данных открытого или зашифрованного текста.

method [in]

Тип: GrdAM

Режим работы алгоритма и тип операции.

iv [in,out]

Тип: byte [ ]

Вектор инициализации для режимов шифрования CBC, CFB и OFB:

для GSII64 - 8 байт, для AES128 и AES256 - 16 байт. 

Expand
titleВозвращаемое значение метода
GrdE.OKОперация выполнена успешно.

GrdE.AlgoNotFound

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

GrdE.InvalidArg

Задано недопустимое значение одного из аргументов функции.

GrdE.NoService

Для алгоритма/ячейки сервис не предусмотрен.

GrdE.GPis0Счетчик алгоритма достиг нулевого значения.
GrdE.InactiveItemАлгоритм/ячейка находятся в неактивном состоянии, команда не выполнена.
Перейти к списку всех ошибок Guardant API
Expand
titleОписание

Метод GrdTransformEx позволяет зашифровать или расшифровать данные с помощью аппаратно-реализованного в электронном ключе криптографического алгоритма. Шифрование выполняется алгоритмом с номером, заданным в параметре algNum. Этот алгоритм предварительно должен быть создан, в противном случае возвращается ошибка GrdE.AlgoNotFound. Если в дескрипторе алгоритма установлен флаг "уменьшение счетчика", то вычитание счетчика алгоритма происходит при каждом вызове GrdTransformEx. При достижении счетчиком нулевого значения, возвращается ошибка GrdE.GPis0. Если при создании алгоритма или в процессе работы он был переведен в неактивное состояние, возвращается ошибка GrdE.InactiveItem

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

Для режимов ECB и CBC длина массива данных (в байтах) должна быть кратна размеру блока алгоритма шифрования, в противном случае возвращается ошибка GrdE.InvalidArg.  Для режимов CFB и OFB длина может быть произвольной, т.к. в этих режимах открытый или зашифрованный текст складываются по модулю 2 с ключевыми блоками полученными в результате работы операции блочного шифра. Открытый или зашифрованный текст должны находиться в массиве передаваемом по ссылке в параметре data. Если метод выполнен успешно, то в этом же массиве будут размещены зашифрованные или расшифрованные данные той же длины. В этом случае метод возвращает GrdE.OK.

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

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

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

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

Размер блока алгоритма шифрования равен 8 байт. Максимальная длина пакета 248 байт.

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

Размер блока алгоритма шифрования равен 16 байт. Максимальная длина пакета 16384 байт.

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

Для работы с аппаратно-реализованными алгоритмами ECC160 используйте метод GrdSign.

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

Для работы с аппаратно-реализованными алгоритмами HASH64 используйте метод GrdHashEx.