Class SubtleCrypto

Namespace

CSharpToJavaScript.APIs.JS

Assembly

CSharpToJavaScript.dll

The SubtleCrypto interface of the Web Crypto API provides a number of low-level cryptographic functions.

[Value("SubtleCrypto")]
public class SubtleCrypto

Inheritance

object

SubtleCrypto

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Remarks

The interface name includes the term "subtle" to indicate that many of its algorithms have subtle usage requirements, and hence that it must be used carefully in order to provide suitable security guarantees.

An instance of SubtleCrypto is available as the Subtle property of the Crypto interface, which in turn is available in windows through the Window.Crypto property and in workers through the WorkerGlobalScope.Crypto property.

WARNING

This API provides a number of low-level cryptographic primitives. It's very easy to misuse them, and the pitfalls involved can be very subtle.

Even assuming you use the basic cryptographic functions correctly, secure key management and overall security system design are extremely hard to get right, and are generally the domain of specialist security experts.

Errors in security system design and implementation can make the security of the system completely ineffective.

Please learn and experiment, but don't guarantee or imply the security of your work before an individual knowledgeable in this subject matter thoroughly reviews it. The Crypto 101 Course can be a great place to start learning about the design and implementation of secure systems.

-Web Crypto API
-Non-cryptographic uses of SubtleCrypto
-Web security
-Privacy, permissions, and information security
-Crypto and Subtle.
-Crypto 101: an introductory course on cryptography.

See also on MDN

Constructors

SubtleCrypto()

public SubtleCrypto()

Methods

Decrypt(Union187, CryptoKey, Union224)

The decrypt() method of the SubtleCrypto interface decrypts some encrypted data.
It takes as arguments a key to decrypt with, some optional extra parameters, and the data to decrypt (also known as "ciphertext").
It returns a Promise which will be fulfilled with the decrypted data (also known as "plaintext").

[Value("decrypt")]
public Task<ArrayBuffer> Decrypt(Union187 algorithm, CryptoKey key, Union224 data)

Parameters

algorithm Union187

key CryptoKey

data Union224

Returns

Task<ArrayBuffer>

A Promise that fulfills with an ArrayBuffer containing the plaintext.

Remarks

-Encrypt(Union187, CryptoKey, Union224).
-RFC 3447 specifies RSAOAEP.
-NIST SP800-38A specifies CTR mode.
-NIST SP800-38A specifies CBC mode.
-NIST SP800-38D specifies GCM mode.
-FIPS 198-1 specifies HMAC.

See also on MDN

DeriveBits(Union187, CryptoKey, ulong?)

The deriveBits() method of the
SubtleCrypto interface can be used to derive an array of bits from a base
key.

[Value("deriveBits")]
public Task<ArrayBuffer> DeriveBits(Union187 algorithm, CryptoKey baseKey, ulong? length = null)

Parameters

algorithm Union187

baseKey CryptoKey

length ulong?

Returns

Task<ArrayBuffer>

A Promise
that fulfills with an ArrayBuffer
containing the derived bits.

Remarks

It takes as its arguments the base key, the derivation algorithm to use, and the length
of the bits to derive. It returns a Promise
which will be fulfilled with an
ArrayBuffer
containing the derived bits.

This method is very similar to
SubtleCrypto.deriveKey(),
except that deriveKey() returns a
CryptoKey object rather than an
ArrayBuffer. Essentially deriveKey() is composed of
deriveBits() followed by
importKey().

This function supports the same derivation algorithms as deriveKey(): ECDH, HKDF, PBKDF2, and X25519.
See Supported algorithms for some more detail on these algorithms.

-HKDF specification.
-NIST guidelines for password-based key derivation.
-Password storage cheat sheet.
-Advice on choosing an iteration count for PBKDF2.

See also on MDN

DeriveKey(Union187, CryptoKey, Union187, bool, List<KeyUsage>)

The deriveKey() method of the SubtleCrypto interface can be used to derive a secret key from a master key.

[Value("deriveKey")]
public Task<CryptoKey> DeriveKey(Union187 algorithm, CryptoKey baseKey, Union187 derivedKeyType, bool extractable, List<KeyUsage> keyUsages)

Parameters

algorithm Union187

baseKey CryptoKey

derivedKeyType Union187

extractable bool

keyUsages List<KeyUsage>

Returns

Task<CryptoKey>

A {{jsxref("Promise")}} that fulfills with a CryptoKey.

Remarks

It takes as arguments some initial key material, the derivation algorithm to use, and the desired properties for the key to derive.
It returns a Promise which will be fulfilled with a CryptoKey object representing the new key.

It&apos;s worth noting that the supported key derivation algorithms have quite different characteristics and are appropriate in quite different situations.
See Supported algorithms for some more detail on this.

-HKDF specification.
-NIST guidelines for password-based key derivation.
-Password storage cheat sheet.
-Advice on choosing an iteration count for PBKDF2.

See also on MDN

Digest(Union187, Union224)

The digest() method of the SubtleCrypto interface generates a digest of the given data, using the specified hash function.
A digest is a short fixed-length value derived from some variable-length input.
Cryptographic digests should exhibit collision-resistance, meaning that it&apos;s hard to come up with two different inputs that have the same digest value.

[Value("digest")]
public Task<ArrayBuffer> Digest(Union187 algorithm, Union224 data)

Parameters

algorithm Union187

data Union224

Returns

Task<ArrayBuffer>

A Promise that fulfills with an ArrayBuffer containing the digest.

Remarks

It takes as its arguments an identifier for the digest algorithm to use and the data to digest.
It returns a Promise which will be fulfilled with the digest.

Note that this API does not support streaming input: you must read the entire input into memory before passing it into the digest function.

-Non-cryptographic uses of SubtleCrypto
-Chromium secure origins specification
-FIPS 180-4 specifies the SHA family of digest algorithms.

See also on MDN

Encrypt(Union187, CryptoKey, Union224)

The encrypt() method of the SubtleCrypto interface encrypts data.

[Value("encrypt")]
public Task<ArrayBuffer> Encrypt(Union187 algorithm, CryptoKey key, Union224 data)

Parameters

algorithm Union187

key CryptoKey

data Union224

Returns

Task<ArrayBuffer>

A Promise that fulfills with an ArrayBuffer containing the "ciphertext".

Remarks

It takes as its arguments a key to encrypt with, some algorithm-specific parameters, and the data to encrypt (also known as "plaintext").
It returns a Promise which will be fulfilled with the encrypted data (also known as "ciphertext").

-Decrypt(Union187, CryptoKey, Union224).
-RFC 3447 specifies RSAOAEP.
-NIST SP800-38A specifies CTR mode.
-NIST SP800-38A specifies CBC mode.
-NIST SP800-38D specifies GCM mode.

See also on MDN

ExportKey(KeyFormat, CryptoKey)

The exportKey() method of the SubtleCrypto
interface exports a key: that is, it takes as input a CryptoKey object
and gives you the key in an external, portable format.

[Value("exportKey")]
public Task<ArrayBuffer> ExportKey(KeyFormat format, CryptoKey key)

Parameters

format KeyFormat

key CryptoKey

Returns

Task<ArrayBuffer>

A Promise.

Remarks

To export a key, the key must have Extractable set to
true.

Keys can be exported in several formats: see Supported formats in the
SubtleCrypto.importKey()
page for details.

Keys are not exported in an encrypted format: to encrypt keys when exporting them use
the
SubtleCrypto.wrapKey()
API instead.

-SubtleCrypto.importKey()
-SubtleCrypto.wrapKey()
-PKCS #8 format.
-SubjectPublicKeyInfo format.
-JSON Web Key format.

See also on MDN

GenerateKey(Union187, bool, List<KeyUsage>)

The generateKey() method of the SubtleCrypto interface is used to generate a new key (for symmetric algorithms) or key pair (for public-key algorithms).

[Value("generateKey")]
public Task<CryptoKey> GenerateKey(Union187 algorithm, bool extractable, List<KeyUsage> keyUsages)

Parameters

algorithm Union187

extractable bool

keyUsages List<KeyUsage>

Returns

Task<CryptoKey>

A {{jsxref("Promise")}} that fulfills with a CryptoKey (for symmetric algorithms) or a CryptoKeyPair (for public-key algorithms).

Remarks

-Cryptographic key length recommendations.
-NIST Transitioning the Use of Cryptographic Algorithms and Key Lengths.

See also on MDN

ImportKey(KeyFormat, Union188, Union187, bool, List<KeyUsage>)

The importKey() method of the SubtleCrypto
interface imports a key: that is, it takes as input a key in an external, portable
format and gives you a CryptoKey object that you can use in the Web Crypto API.

[Value("importKey")]
public Task<CryptoKey> ImportKey(KeyFormat format, Union188 keyData, Union187 algorithm, bool extractable, List<KeyUsage> keyUsages)

Parameters

format KeyFormat

keyData Union188

algorithm Union187

extractable bool

keyUsages List<KeyUsage>

Returns

Task<CryptoKey>

A Promise
that fulfills with the imported key as a CryptoKey object.

Remarks

The function accepts several import formats: see Supported formats for details.

-SubtleCrypto.exportKey()
-PKCS #8 format.
-SubjectPublicKeyInfo format.
-JSON Web Key format.

See also on MDN

Sign(Union187, CryptoKey, Union224)

The sign() method of the SubtleCrypto interface generates a digital {{glossary("signature")}}.

[Value("sign")]
public Task<ArrayBuffer> Sign(Union187 algorithm, CryptoKey key, Union224 data)

Parameters

algorithm Union187

key CryptoKey

data Union224

Returns

Task<ArrayBuffer>

A Promise that fulfills with an ArrayBuffer containing the signature.

Remarks

It takes as its arguments a {{glossary("key")}} to sign with, some algorithm-specific parameters, and the data to sign. It returns a Promise which will be fulfilled with the signature.

You can use the corresponding Verify(Union187, CryptoKey, Union224, Union224) method to verify the signature.

-Verify(Union187, CryptoKey, Union224, Union224).
-RFC 3447 specifies RSASSA-PKCS1-v1_5.
-RFC 3447 specifies RSA-PSS.
-FIPS-186 specifies ECDSA.
-FIPS 198-1 specifies HMAC.

See also on MDN

UnwrapKey(KeyFormat, Union224, CryptoKey, Union187, Union187, bool, List<KeyUsage>)

The unwrapKey() method of the SubtleCrypto interface "unwraps" a key.
This means that it takes as its input a key that has been exported and then encrypted (also called &quot;wrapped&quot;).
It decrypts the key and then imports it, returning a CryptoKey object that can be used in the Web Crypto API.

[Value("unwrapKey")]
public Task<CryptoKey> UnwrapKey(KeyFormat format, Union224 wrappedKey, CryptoKey unwrappingKey, Union187 unwrapAlgorithm, Union187 unwrappedKeyAlgorithm, bool extractable, List<KeyUsage> keyUsages)

Parameters

format KeyFormat

wrappedKey Union224

unwrappingKey CryptoKey

unwrapAlgorithm Union187

unwrappedKeyAlgorithm Union187

extractable bool

keyUsages List<KeyUsage>

Returns

Task<CryptoKey>

A Promise that fulfills with the unwrapped key as a CryptoKey object.

Remarks

As with SubtleCrypto.importKey(), you specify the key&apos;s import format and other attributes of the key to import details such as whether it is extractable, and which operations it can be used for.

But because unwrapKey() also decrypts the key to be imported, you also need to pass in the key that must be used to decrypt it.
This is sometimes called the &quot;unwrapping key&quot;.

The inverse of unwrapKey() is WrapKey(KeyFormat, CryptoKey, CryptoKey, Union187): while unwrapKey is composed of decrypt + import, wrapKey is composed of encrypt + export.

-SubtleCrypto.importKey()
-PKCS #8 format.
-SubjectPublicKeyInfo format.
-JSON Web Key format.
-AES-KW specification.

See also on MDN

Verify(Union187, CryptoKey, Union224, Union224)

The verify() method of the SubtleCrypto
interface verifies a digital signature.

[Value("verify")]
public Task<bool> Verify(Union187 algorithm, CryptoKey key, Union224 signature, Union224 data)

Parameters

algorithm Union187

key CryptoKey

signature Union224

data Union224

Returns

Task<bool>

A Promise that fulfills with a
boolean value: true if the signature is valid, false
otherwise.

Remarks

It takes as its arguments a key to verify the signature with, some algorithm-specific parameters, the signature, and the original signed data.
It returns a Promise which will be fulfilled with a boolean value indicating whether the signature is valid.

-Sign(Union187, CryptoKey, Union224).
-RFC 3447 specifies RSASSA-PKCS1-v1_5.
-RFC 3447 specifies RSA-PSS.
-FIPS-186 specifies ECDSA.
-FIPS 198-1 specifies HMAC.

See also on MDN

WrapKey(KeyFormat, CryptoKey, CryptoKey, Union187)

The wrapKey() method of the SubtleCrypto interface "wraps" a key.
This means that it exports the key in an external, portable format, then encrypts the exported key.
Wrapping a key helps protect it in untrusted environments, such as inside an otherwise unprotected data store or in transmission over an unprotected network.

[Value("wrapKey")]
public Task<ArrayBuffer> WrapKey(KeyFormat format, CryptoKey key, CryptoKey wrappingKey, Union187 wrapAlgorithm)

Parameters

format KeyFormat

key CryptoKey

wrappingKey CryptoKey

wrapAlgorithm Union187

Returns

Task<ArrayBuffer>

A Promise that fulfills with
an ArrayBuffer
containing the encrypted exported key.

Remarks

As with ExportKey(KeyFormat, CryptoKey), you specify an export format for the key.
To export a key, it must have Extractable set to true.

But because wrapKey() also encrypts the key to be exported, you also need to pass in the key that must be used to encrypt it.
This is sometimes called the &quot;wrapping key&quot;.

The inverse of wrapKey() is UnwrapKey(KeyFormat, Union224, CryptoKey, Union187, Union187, bool, List<KeyUsage>): while wrapKey is composed of export + encrypt, unwrapKey is composed of import + decrypt.

-SubtleCrypto.exportKey()
-PKCS #8 format.
-SubjectPublicKeyInfo format.
-JSON Web Key format.
-AES-KW specification.

See also on MDN