Функция GrdTransformEx преобразует блок данных при помощи симметричного аппаратного алгоритма (GSII64 и AES). Расширенная версия функции GrdTransform.
int GRD_API GrdTransformEx( HANDLE hGrd, DWORD dwAlgoNum, DWORD dwLng, void *pData, DWORD dwMethod, DWORD dwIVLng void *pIV void *pReserved );
static GrdE Guardant.GrdApi.GrdTransformEx (Handle grdHandle, GrdAlgNum algNum, byte[] data, GrdAM method, byte[] iv )
Функция 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\"
C C# Visual Basic Visual C++
int GRD_API GrdTransformEx(
HANDLE hGrd,
DWORD dwAlgoNum,
DWORD dwLng,
void *pData,
DWORD dwMethod,
DWORD dwIVLng
void *pIV
void *pReserved
);