SubtleCrypto

Интерфейс SubtleCrypto API шифрования веб-приложений предоставляет ряд низкоуровневых криптографических функций.

Имя интерфейса включает термин «скрытый», чтобы указать, что многие его алгоритмы имеют тонкие требования к использованию, и, следовательно, он должен использоваться с осторожностью, чтобы обеспечить соответствующие гарантии безопасности.

Экземпляр SubtleCrypto доступен как свойство subtle интерфейса Crypto, который, в свою очередь, доступен в окнах через свойство Window.crypto и в рабочих процессах через свойство WorkerGlobalScope.crypto.

Этот интерфейс не наследует никаких свойств, так как у него нет родительского интерфейса.

Этот интерфейс не наследует никаких методов, так как у него нет родительского интерфейса.

SubtleCrypto.encrypt()

Возвращает Promise, который выполняется с зашифрованными данными, соответствующими заданному открытому тексту, алгоритму и ключу.

SubtleCrypto.decrypt()

Возвращает Promise, который выполняется с открытыми данными, соответствующими зашифрованному тексту, алгоритму и ключу.

SubtleCrypto.sign()

Возвращает Promise, который выполняется с подписью, соответствующей тексту, алгоритму и ключу.

SubtleCrypto.verify()

Возвращает Promise, который выполняется со значением булевого типа, указывающим, соответствует ли заданная подпись тексту, алгоритму и ключу.

SubtleCrypto.digest()

Возвращает Promise, который выполняется с дайджестом, сгенерированным из алгоритма и текста.

SubtleCrypto.generateKey()

Возвращает Promise, который выполняется с только что сгенерированным CryptoKey для симметричных алгоритмов или CryptoKeyPair, содержащим два только что сгенерированных ключа для асимметричных алгоритмов. Они будут соответствовать заданному алгоритму, правам доступа и возможности извлечения.

SubtleCrypto.deriveKey()

Возвращает Promise, который выполняется с только что сгенерированным CryptoKey, полученным из основного ключа и заданного алгоритма.

SubtleCrypto.deriveBits()

Возвращает Promise, который выполняется с только что сгенерированным буфером псевдослучайных битов, полученных из основного ключа и заданного алгоритма.

SubtleCrypto.importKey()

Возвращает Promise, который выполняется с CryptoKey, соответствующим формату, алгоритму, сырым данным ключа, правам доступа и возможности извлечения.

SubtleCrypto.exportKey()

Возвращает Promise, который выполняется с сырыми данными ключа, содержащими ключ в требуемом формате.

SubtleCrypto.wrapKey()

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

SubtleCrypto.unwrapKey()

Возвращает Promise, который выполняется с CryptoKey, соответствующим зашифрованному ключу.

Мы можем разделить функции, реализованные этим API, на две группы: криптографические функции и функции управления ключами.

Это функции, которые вы можете использовать для реализации функций безопасности, таких как конфиденциальность и аутентификация в системе. API SubtleCrypto предоставляет следующие криптографические функции:

• sign() и verify(): создание и проверка цифровых подписей.
• encrypt() и decrypt(): шифрование и дешифрование данных.
• digest(): создание дайджеста фиксированной длины и стойкого к коллизиям некоторых данных.

За исключением digest(), все криптографические функции в API используют криптографические ключи. В API SubtleCrypto криптографический ключ представлен с помощью объекта CryptoKey. Для выполнения операций, таких как подпись и шифрование, вы передаёте объект CryptoKey в функцию sign() или encrypt().

Генерация и вычисление ключей

Функции generateKey() и deriveKey() обе создают новый объект CryptoKey.

Разница в том, что generateKey() каждый раз при вызове будет генерировать новое уникальное значение ключа, а deriveKey() вычисляет ключ из исходного набора ключей. Если вы предоставите один и тот же набор ключей двум разным вызовам функции deriveKey(), вы получите два объекта CryptoKey с одинаковым внутренним значением. Это полезно, например, для вычисления ключа шифрования из пароля и последующего вычисления того же ключа из того же пароля для расшифровки данных.

Импорт и экспорт ключей

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

Обратной функцией к exportKey() является importKey(). Вы можете импортировать ключи из других систем, и поддержка стандартных форматов, таких как PKCS #8 и JSON Web Key, поможет вам в этом. Функция exportKey() экспортирует ключ в нешифрованном формате.

Если ключ является конфиденциальным, вы должны использовать wrapKey(), которая экспортирует ключ, а затем шифрует его с помощью другого ключа; API использует «ключ для упаковки ключей».

Обратной функцией к wrapKey() является unwrapKey(), которая расшифровывает и затем импортирует ключ.

Хранение ключей

CryptoKey является сериализуемым объектом, что позволяет хранить и извлекать ключи с помощью стандартных API веб-хранилища.

В спецификации предполагается, что большинство разработчиков будут использовать API IndexedDB, храня объекты CryptoKey по идентификатору ключа, имеющему смысл для приложения, наряду с любой другой метаданными, которую оно посчитает полезной. Это позволяет хранить и извлекать объект CryptoKey без необходимости раскрывать его внутренний ключ материалу приложения или среде JavaScript.

Криптографические функции, предоставляемые API Web Crypto, могут выполняться одним или несколькими различными криптографическими алгоритмами: аргумент algorithm функции указывает, какой алгоритм использовать. Некоторые алгоритмы требуют дополнительных параметров: в таких случаях аргумент algorithm — это объект словаря, содержащий дополнительные параметры.

В таблице ниже показано, какие алгоритмы подходят для каких криптографических операций:

• Web Crypto API
• Non-cryptographic uses of SubtleCrypto
• Web security
• Privacy, permissions, and information security
• Crypto и Crypto.subtle.
• Crypto 101: вводный курс по криптографии.