Skip to content

crypto.md

Latest commit

 

History

History
122 lines (89 loc) · 5.96 KB

crypto.md

File metadata and controls

122 lines (89 loc) · 5.96 KB

Криптография, хэширование, вспомогательные функции и интерфейсы

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

Интерфейс Crypto

interface Crypto {
	sha1(data: string): string;
	hash(algo: string, data: string, binary?: boolean): string | BinaryData;
	hmac(algo: string, data: string, key: string | BinaryData, binary?: boolean): string | BinaryData;
	getHashAlgorithms(): string[];
	getHmacHashAlgorithms(): string[];
}

Интерфейс для работы с криптографическими и их дополняющими функциями.

 

sha1(data: string): string;

Возвращает SHA1-хэш строки data (переданной в кодировке UTF-8), вычисленный по алгоритму US Secure Hash Algorithm 1 в виде 40-символьного шестнадцатеричного числа.

Пример использования:

let hash = om.crypto.sha1('data');
console.log(
    hash, // a17c9aaa61e80a1bf71d0d850af4e5baa9800bbd
    typeof(hash) // string
);

 

hash(algo: string, data: string, binary?: boolean): string | BinaryData;

Метод для получения хэша строки data (переданной в кодировке UTF-8) по указанному алгоритму algo. Полный список доступных алгоритмов может быть получен с помощью метода getHashAlgorithms().

Если binary = false (по умолчанию), то хэш возвращается в виде строки, использующей шестнадцатеричное кодирование в нижнем регистре (hexits).

Если binary = true, то хэш возвращается в виде бинарных данных, инкапсулированных в специальный объект BinaryData.

Пример использования:

let hash = om.crypto.hash('sha1', 'data');
console.log(
    hash // a17c9aaa61e80a1bf71d0d850af4e5baa9800bbd
);

 

hmac(algo: string, data: string, key: string | BinaryData, binary?: boolean): string | BinaryData;

Метод для получения подписи HMAC (Hash-based Message Authentication Code) для строки data (переданной в кодировке UTF-8) с использованием ключа key и алгоритма хэширования algo.

Ключ key может быть передан в виде строки в кодировке UTF-8 или в бинарном виде — инкапсулированным в объект BinaryData. Аналогично методу hash(), полный список доступных алгоритмов хэширования algo может быть получен с помощью метода getHmacHashAlgorithms().

Если binary = false (по умолчанию), то хэш возвращается в виде строки, использующей шестнадцатеричное кодирование в нижнем регистре (hexits).

Если binary = true, то хэш возвращается в виде бинарных данных, инкапсулированных в специальный объект BinaryData.

Демонстрация использования на примере получения подписи для сервиса AWS s3:

const dateKey = om.crypto.hmac('sha-256', '20130524', 'AWS4' + 'very_secret_key', true);
const regionKey = om.crypto.hmac('sha-256', 'us-east-1', dateKey, true);
const serviceKey = om.crypto.hmac('sha-256', 's3', regionKey, true);
const signingKey = om.crypto.hmac('sha-256', 'aws4_request' , serviceKey, true);
const signature = om.crypto.hmac('sha-256', 'stringToSign', signingKey);

 

getHashAlgorithms(): string[];

Возвращает список алгоритмов хэширования, которые могут быть использованы в параметре algo метода hash().

 

getHmacHashAlgorithms(): string[];

Возвращает список алгоритмов хэширования, которые могут быть использованы в параметре algo метода hmac().

 

Интерфейс BinaryData

interface BinaryData {
	getAsRawString(): string;
}

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

 

getAsRawString(): string;

Возвращает бинарные данные в виде utf-8 строки.

Пример использования:

const signature = om.crypto.hmac('sha1', 'data', 'some secret key', true);

console.log(
    signature.getAsRawString() // ��%�a�
);

 

API Reference

Оглавление