The SubtleCrypto interface of the Web Crypto API provides a number of low-level cryptographic functions. It is accessed via the Crypto.subtle properties available in a window context (via Window.crypto).

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.

If you're not sure you know what you are doing, you probably shouldn't be using this API.

Cryptography functions

These are the functions you can use to implement security features such as privacy and authentication in a system. The SubtleCrypto API provides the following cryptography functions:

* sign() and verify(): create and verify digital signatures.
* encrypt() and decrypt(): encrypt and decrypt data.
* digest(): create a fixed-length, collision-resistant digest of some data.

Key management functions

Except for digest(), all the cryptography functions in the API use cryptographic keys. In the SubtleCrypto API a cryptographic key is represented using a CryptoKey object. To perform operations like signing and encrypting, you pass a CryptoKey object into the sign() or encrypt() function.

Generating and deriving keys

The generateKey() and deriveKey() functions both create a new CryptoKey object.

The difference is that generateKey() will generate a new distinct key value each time you call it, while deriveKey() derives a key from some initial keying material. If you provide the same keying material to two separate calls to deriveKey(), you will get two CryptoKey objects that have the same underlying value. This is useful if, for example, you want to derive an encryption key from a password and later derive the same key from the same password to decrypt the data.

Importing and exporting keys

To make keys available to your OutSystems  app, they are automatically exported to JSON Web Key (JWK) format.

If the key is sensitive you should use wrapKey(), which exports the key and then encrypts it using another key; the API calls a "key-wrapping key".

The inverse of wrapKey() is unwrapKey(), which decrypts then imports the key.

Storing keys

At the moment keys are available to OutSystems using JWK format. You can store the private keys in the local storage but at some point the key is visible in the javascript.

However for future implementation, CryptoKey objects can be stored using the structured clone algorithm, meaning that you can store and retrieve them using standard web storage APIs. The specification expects that most developers will use the IndexedDB API to store CryptoKey objects.

Supported algorithms

The cryptographic functions provided by the Web Crypto API 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:

Although the Web Crypto API implements more algorithms, these are the recommended. The rest exist for backward compatibility.