Supported algorithms

Draft
This page is not complete.

This page lists and briefly describes the cryptographic algorithms commonly supported by browsers, organized by the functions for which they are suitable.

The Web Crypto API provides functions that implement different cryptographic operations, such as sign(), verify(), encrypt(), decrypt() and so on.

Each operation can be performed by one or more different cryptographic algorithms: the algorithm argument to the function indicates which algorithm to use. Some algorithms need extra parameters: in these cases the algorithm argument is a dictionary object that includes the extra parameters.

The table below summarises which algorithms are suitable for which cryptographic operations:

 

sign()

verify()

encrypt()

decrypt()

digest()

deriveBits()

deriveKey()

wrapKey()

unwrapKey()

RSASSA-PKCS1-v1_5        
RSA-PSS        
ECDSA        
HMAC        
RSA-OAEP      
AES-CTR      
AES-CBC      
AES-GCM      
SHA-1        
SHA-256        
SHA-384        
SHA-512        
ECDH        
HKDF        
PBKDF2        
AES-KW        

Apart from the four digest algorithms and the HKDF and PBKDF2 key derivation algorithms, all the other algorithms here use keys. Algorithms that use keys can be divided into two sorts:

  • public-key or asymmetric cryptosystems: with these systems, you get a key pair: the transformation performed by one of the keys can only be undone with the other key. In the Web Crypto API a key pair is represented as a CryptoKeyPair. Typically one key is made public and the other is kept private. When used for digital signatures, the private key is used to sign and the public key to verify. When used for encryption, the public key is used to encrypt, and the private key is used to decrypt.
  • secret-key or symmetric-key algorithms: with these algorithms there is just one key. The transform performed by the key can only be undone by the same key. In the Web Crypto API a single key is represented as a CryptoKey.

Signing algorithms

These algorithms are usable by the sign() and verify() functions of the Web Crypto API.

Three of these algorithms - RSASSA-PKCS1-v1_5, RSA-PSS, and ECDSA - are public-key cryptosystems. These systems all use a digest algorithm to hash the message to a short fixed size before signing. The choice of digest algorithm is passed into the SubtleCrypto.generateKey() or SubtleCrypto.importKey() functions.

The fourth algorithm - HMAC - is a symmetric-key algorithm. Unlike the other three signing algorithms, it uses the same key for signing and for verification: this means that the verification key must be kept secret, which in turn means that this algorithm is not suitable for many signature use cases. But it can be a good choice when the signer and verifier are the same entity.

RSASSA-PKCS1-v1_5

The RSASSA-PKCS1-v1_5 algorithm is specified in RFC 3447.

RSA-PSS

The RSA-PSS algorithm is specified in RFC 3447.

It's different from RSASSA-PKCS1-v1_5 in that it incorporates a random salt in the signature operation, so the same message signed with the same key will not result in the same signature. An extra property, defining the salt length, is passed into the SubtleCrypto.sign() and SubtleCrypto.verify() functions.

ECDSA

ECDSA (Elliptic Curve Digital Signature Algorithm) is a variant of the Digital Signature Algorithm, specified in FIPS-186, that uses Elliptic Curve Cryptography (RFC 6090).

HMAC

The HMAC algorithm calculates and verifies hash-based message authentication codes according to the FIPS 198-1 standard.

Encryption algorithms

These are usable by encrypt() and decrypt(), as well as wrapKey() and unwrapKey(), that use encrypt and decrypt operations under the hood.

One of these algorithms - RSA-OAEP - is a public-key cryptosystem. Public-key encryption systems have an advantage over symmetric encryption systems in that the encryption key can be made public: so anyone can send me an encrypted message but only I will be able to decrypt it. However they are typically much slower than symmetric algorithms and the size of message they can encrypt is proportional to the size of the key, so they do not scale well for long messages.

As a result, it's common for an encryption system to use a symmetric algorithm to encrypt the message, then a public-key system to encrypt the symmetric key. This arrangement can confer the benefits of both systems.

The other three encryption algorithms here are all symmetric algorithms, and they're all based on the same underlying cipher, AES (Advanced Encryption Standard). The difference between them is the mode. AES is a block cipher, meaning that it operates on a fixed-size block of bytes. Since the block size is usually smaller than the message to encrypt, it's necessary to specify how to use a block cipher to securely encrypt messages that are longer than the block size, and that's what a mode does. Using an inappropriate mode, or using a mode incorrectly, can completely undermine the security provided by the underlying cipher.

The Web Crypto API support three different AES modes:

  • CTR (Counter Mode)
  • CBC (Cipher Block Chaining)
  • GCM (Galois/Counter Mode).

RSA-OAEP

The RSA-OAEP public-key encryption system is specified in RFC 3447.

AES-CTR

This represents AES in Counter Mode, as specified in NIST SP800-38A.

AES-CBC

This represents AES in Cipher Block Chaining Mode, as specified in NIST SP800-38A.

AES-GCM

This represents AES in Galois/Counter Mode, as specified in NIST SP800-38D.

One major difference between this mode and the others is that GCM is an "authenticated" mode, which means that it includes checks that the ciphertext has not been modified by an attacker. Authentication helps protect against chosen-ciphertext attacks, in which an attacker can ask the system to decrypt arbitrary messages, and use the result to deduce information about the secret key. While it's possible to add authentication to the other modes, they do not provide it by default.

Digest algorithms

These algorithms are usable by the digest() function of the Web Crypto API.

Digest algorithms, also known as cryptographic hash functions, transform an arbitrarily large block of data into a fixed-size output, usually much shorter than the input. They have a variety of applications in cryptography.

SHA-1

This algorithm is specified in FIPS 180-4, section 6.1. Produces an output 160 bits long.

Note that this algorithm is now considered vulnerable and should not be used.

SHA-256

This algorithm is specified in FIPS 180-4, section 6.2. Produces an output 256 bits long.

SHA-384

This algorithm is specified in FIPS 180-4, section 6.5. Produces an output 384 bits long.

SHA-512

This algorithm is specified in FIPS 180-4, section 6.4. Produces an output 512 bits long.

Key derivation algorithms

These algorithms are usable by the deriveKey() and deriveBits() functions of the Web Crypto API.

The deriveBits() function will derive an array of bits using the algorithm specified. The deriveKey() function will derive an array of bits using the algorithm specified, and then convert these bits into a CryptoKey object that can be used in other cryptographic operations (primarily encryption, since these algorithms are only used to derive symmetric keys).

The three algorithms listed here have quite different characteristics and are appropriate in different situations.

ECDH

ECDH (Elliptic Curve Diffie-Hellman) is a key-agreement algorithm. It enables two people who each have an ECDH public/private key pair to generate a shared secret: that is, a secret that they - and noone else - share. They can then use this shared secret as a symmetric key to secure their communication, or can use the secret as input to derive such a key (for example, using the HKDF algorithm).

ECDH is specified in RFC 6090.

HKDF

HKDF is a key derivation function. It's designed to derive some key material from some high-entropy input, such as the output of an ECDH key agreement operation.

It's not designed to derive keys from relatively low-entropy input such as passwords. For that, use PBKDF2.

HKDF is specified in RFC 5869.

PBKDF2

PBKDF2 is also a key derivation function. It's designed to derive some key material from some relatively low-entropy input, such as a password. It derives key material by applying a function such as HMAC to the input password along with some salt, and repeating this process many times. The more times the process is repeated, the more computationally expensive key derivation is: this makes it harder for an attacker to use brute-force to discover the key using a dictionary attack.

PBKDF2 is specified in RFC 2898.

Key wrapping algorithms

This algorithm is usable by the wrapKey() and unwrapKey() functions of the Web Crypto API. Note that all the algorithms listed under "Encryption algorithms" can also be used for key wrapping and unwrapping.

Key wrapping algorithms use a symmetric algorithm to encrypt a key, so the key is protected when in storage or transmission in untrusted environments.

AES-KW

AES-KW is a way to use the AES cipher for key wrapping.

It is specified in RFC 3394.

Document Tags and Contributors

Contributors to this page: wbamberg, mcraiha, Garitz, reaxyl, teoli
Last updated by: wbamberg,