chore: add documentation for the new SubtleCrypto methods we support

Author: Jake Champion

documentation/app/fastly.toml

@@ -0,0 +1,23 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+# CryptoKey
+
+The **`CryptoKey`** interface represents a cryptographic key obtained from one of the [`SubtleCrypto`](../SubtleCrypto/SubtleCrypto.mdx) method [`importKey()`](../SubtleCrypto/prototype/importKey.mdx).
+
+## Instance properties
+
+- [`type`](./prototype/type.mdx) _**readonly**_
+  - : The type of key the object represents. It may take one of the following values: `"secret"`, `"private"` or `"public"`.
+
+- [`extractable`](./prototype/extractable.mdx) _**readonly**_
+  - : A boolean value indicating whether or not the key may be extracted.
+
+- [`algorithm`](./prototype/algorithm.mdx) _**readonly**_
+  - : An object describing the algorithm for which this key can be used and any associated extra parameters.
+
+- [`usages`](./prototype/usages.mdx) _**readonly**_
+  - : An `Array` of strings, indicating what can be done with the key. Possible values for array elements are `"encrypt"`, `"decrypt"`, `"sign"`, `"verify"`, `"deriveKey"`, `"deriveBits"`, `"wrapKey"`, and `"unwrapKey"`.

documentation/docs/globals/CryptoKey/CryptoKey.mdx

@@ -0,0 +1,18 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# algorithm
+
+The read-only **`algorithm`** property of the [`CryptoKey`](../CryptoKey.mdx) interface returns an object describing the algorithm for which this key can be used, and any associated extra parameters.
+
+The object returned depends of the algorithm used to generate the key.
+
+## Value
+
+An object matching:
+
+- [`RsaHashedImportParams`](../../RsaHashedImportParams/RsaHashedImportParams.mdx) if the algorithm is any of the RSA variants.

documentation/docs/globals/CryptoKey/prototype/algorithm.mdx

@@ -0,0 +1,16 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# extractable
+
+The read-only **`extractable`** property indicates whether or not the key may be extracted.
+
+If the key cannot be exported, an exception will be thrown if an attempt to extract the key is made.
+
+## Value
+
+A boolean value that is `true` if the key can be exported and `false` if not.

documentation/docs/globals/CryptoKey/prototype/extractable.mdx

@@ -0,0 +1,18 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# type
+
+The read-only **`type`** property indicates which kind of key is represented by the object. It can have the following values:
+
+- `"secret"`: This key is a secret key for use with a symmetric algorithm.
+- `"private"`: This key is the private half of an asymmetric algorithm's key pair.
+- `"public"`: This key is the public half of an asymmetric algorithm's key pair.
+
+## Value
+
+One of the following strings: `"secret"`, `"private"`, or `"public"`.

documentation/docs/globals/CryptoKey/prototype/type.mdx

@@ -0,0 +1,23 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+
+# usages
+
+The read-only **`usages`** property indicates what can be done with the key.
+
+## Value
+
+An `Array` of strings from the following list:
+
+- `"encrypt"`: The key may be used to encrypt messages.
+- `"decrypt"`: The key may be used to decrypt messages.
+- `"sign"`: The key may be used to sign messages.
+- `"verify"`: The key may be used to verify signatures.
+- `"deriveKey"`: The key may be used in deriving a new key.
+- `"deriveBits"`: The key may be used in deriving bits.
+- `"wrapKey"`: The key may be used to wrap a key.
+- `"unwrapKey"`: The key may be used to unwrap a key.

documentation/docs/globals/CryptoKey/prototype/usages.mdx

@@ -0,0 +1,19 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+# RsaHashedImportParams
+
+The **`RsaHashedImportParams`** dictionary represents the object that should be passed as the `algorithm` parameter into {{domxref("SubtleCrypto.importKey()")}}, when importing any RSA-based key pair.
+
+## Instance properties
+
+- `name`
+  - : A string. This should be set to `RSASSA-PKCS1-v1_5`.
+
+- `hash`
+  - : A string representing the name of the digest function to use. This can be one of `SHA-256`, `SHA-384`, or `SHA-512`.
+    > **Warning:** Although you can technically pass `SHA-1` here, this is strongly discouraged as it is considered vulnerable.
+

documentation/docs/globals/RsaHashedImportParams/RsaHashedImportParams.mdx

@@ -16,23 +16,3 @@ The **`SubtleCrypto`** interface provides a number of low-level cryptographic fu
 >
 > 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](https://www.crypto101.io/) can be a great place to start learning about the design and implementation of secure systems.
 
-## Instance properties
-
-_This interface doesn't inherit any properties, as it has no parent interface._
-
-## Instance methods
-
-_This interface doesn't inherit any methods, as it has no parent interface._
-
-- [`SubtleCrypto.digest()`](./prototype/digest.mdx)
-    - : Returns a [`Promise`](../Promise/Promise.mdx) that fulfills with a digest generated from the algorithm and text given as parameters.
-
-## Using SubtleCrypto
-
-We can split the functions implemented by this API into two groups: cryptography functions and key management functions.
-
-### 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:
-
-- `SubtleCrypto.digest()`: create a fixed-length, collision-resistant digest of some data.

documentation/docs/globals/SubtleCrypto/SubtleCrypto.mdx

@@ -0,0 +1,87 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+# importKey()
+
+The **`importKey()`** method of the [`SubtleCrypto`](../SubtleCrypto.mdx)
+interface imports a key: that is, it takes as input a key in an external, portable
+format and gives you a [`CryptoKey`](../../CryptoKey/CryptoKey.mdx) object that you can use.
+
+The function accepts several import formats: see [Supported formats](#supported-formats) for details.
+
+## Syntax
+
+```js
+importKey(format, keyData, algorithm, extractable, keyUsages)
+```
+
+### Parameters
+
+- `format`
+  - : A string describing the data format of the key to import. It can be one of the following:
+    - `jwk`: [JSON Web Key](#json_web_key) format.
+- `keyData`
+  - : An `ArrayBuffer`, a TypedArray, a `DataView`, or a `JSONWebKey` object containing the key in
+    the given format.
+- `algorithm`
+  - : An object defining the type of key to import and providing extra algorithm-specific parameters.
+    - For RSASSA-PKCS1-v1_5:
+      Pass an [`RsaHashedImportParams`](../../RsaHashedImportParams/RsaHashedImportParams.mdx) object.
+- `extractable`
+  - : A boolean value indicating whether it will be possible to export the key.
+- `keyUsages`
+  - : An `Array` indicating what can be done with the key. Possible array values are:
+    - `encrypt`: The key may be used to encrypt messages.
+    - `decrypt`: The key may be used to decrypt messages.
+    - `sign`: The key may be used to sign messages.
+    - `verify`: The key may be used to verify signatures.
+    - `deriveKey`: The key may be used in deriving a new key.
+    - `deriveBits`: The key may be used in deriving bits.
+    - `wrapKey`: The key may be used to wrap a key.
+    - `unwrapKey`: The key may be used to unwrap a key.
+
+### Return value
+
+A [`Promise`](../../Promise/Promise.mdx)
+that fulfills with the imported key as a [`CryptoKey`](../../CryptoKey/CryptoKey.mdx) object.
+
+### Exceptions
+
+The promise is rejected when one of the following exceptions is encountered:
+
+- `SyntaxError`
+  - : Raised when `keyUsages` is empty but the unwrapped key is of
+    type `secret` or `private`.
+- `TypeError`
+  - : Raised when trying to use an invalid format or if the `keyData`
+    is not suited for that format.
+
+## Supported formats
+
+This API currently supports one key import/export format: JSON Web Key.
+
+
+### JSON Web Key
+
+You can use JSON Web Key format to import or export RSA or Elliptic Curve public or
+private keys, as well as AES and HMAC secret keys.
+
+JSON Web Key format is defined in [RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517).
+It describes a way to represent public, private, and secret keys as JSON objects.
+
+A JSON Web Key looks something like this (this is an EC private key):
+
+```json
+{
+  "crv": "P-384",
+  "d": "wouCtU7Nw4E8_7n5C1-xBjB4xqSb_liZhYMsy8MGgxUny6Q8NCoH9xSiviwLFfK_",
+  "ext": true,
+  "key_ops": ["sign"],
+  "kty": "EC",
+  "x": "SzrRXmyI8VWFJg1dPUNbFcc9jZvjZEfH7ulKI1UkXAltd7RGWrcfFxqyGPcwu6AQ",
+  "y": "hHUag3OvDzEr0uUQND4PXHQTXP5IDGdYhJhL-WLKjnGjQAw0rNGy5V29-aV-yseW"
+};
+```

documentation/docs/globals/SubtleCrypto/prototype/importKey.mdx

@@ -0,0 +1,51 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+# sign()
+
+The **`sign()`** method of the [`SubtleCrypto`](../SubtleCrypto.mdx) interface generates a digital signature.
+
+It takes as its arguments a 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()`](./verify.mdx) method to verify the signature.
+
+## Syntax
+
+```js
+sign(algorithm, key, data)
+```
+
+### Parameters
+
+- `algorithm`
+  - : A string or object that specifies the signature algorithm to use and its parameters:
+    - To use [RSASSA-PKCS1-v1_5](#rsassa-pkcs1-v1_5), pass the string `"RSASSA-PKCS1-v1_5"` or an object of the form `{ "name": "RSASSA-PKCS1-v1_5" }`.
+- `key`
+  - : A [`CryptoKey`](../../CryptoKey/CryptoKey.mdx) object containing the key to be used for signing.
+    If `algorithm` identifies a public-key cryptosystem, this is the private key.
+- `data`
+  - : An `ArrayBuffer`, a TypedArray or a `DataView` object containing the data to be signed.
+
+### Return value
+
+A `Promise` that fulfills with an `ArrayBuffer` containing the signature.
+
+### Exceptions
+
+The promise is rejected when the following exception is encountered:
+
+- `InvalidAccessError`
+  - : Raised when the signing key is not a key for the request signing algorithm or when
+    trying to use an algorithm that is either unknown or isn't suitable for signing.
+
+## Supported algorithms
+
+### RSASSA-PKCS1-v1_5
+
+The RSASSA-PKCS1-v1_5 algorithm is specified in [RFC 3447](https://datatracker.ietf.org/doc/html/rfc3447).
+