Mention SubtleCrypto alg hash config takes an object (#38046)

mdn · Feb 15, 2025 · 8e49db2 · 8e49db2
1 parent 69a705c
commit 8e49db2
Show file tree

Hide file tree

Showing 8 changed files with 42 additions and 21 deletions.
diff --git a/files/en-us/web/api/cryptokey/algorithm/index.md b/files/en-us/web/api/cryptokey/algorithm/index.md
@@ -21,6 +21,8 @@ An object matching:
 - [`EcKeyGenParams`](/en-US/docs/Web/API/EcKeyGenParams) if the algorithm is any of the EC variants.
 - [`HmacKeyGenParams`](/en-US/docs/Web/API/HmacKeyGenParams) if the algorithm is HMAC.
 
+For `RsaHashedKeyGenParams` and `HmacKeyGenParams`, the `hash` property is always in the object form (with a property called `name`), not the string form.
+
 ## Examples
 
 ```js

diff --git a/files/en-us/web/api/ecdsaparams/index.md b/files/en-us/web/api/ecdsaparams/index.md
@@ -17,7 +17,7 @@ The **`EcdsaParams`** dictionary of the [Web Crypto API](/en-US/docs/Web/API/Web
   - : A string. This should be set to `ECDSA`.
 - `hash`
 
-  - : A string. An identifier for the [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest) to use. This should be one of the following:
+  - : A string or an object containing a single property called `name` with a string value. It is an identifier for the [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest) to use. This should be one of the following:
 
     - `SHA-256`: selects the [SHA-256](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) algorithm.
     - `SHA-384`: selects the [SHA-384](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) algorithm.

diff --git a/files/en-us/web/api/hkdfparams/index.md b/files/en-us/web/api/hkdfparams/index.md
@@ -15,12 +15,13 @@ The **`HkdfParams`** dictionary of the [Web Crypto API](/en-US/docs/Web/API/Web_
   - : A string. This should be set to `HKDF`.
 - `hash`
 
-  - : A string representing the [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) to use. This may be one of:
+  - : A string or an object containing a single property called `name` with a string value. It is an identifier for the [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest) to use. This should be one of the following:
 
-    - `SHA-1`
-    - `SHA-256`
-    - `SHA-384`
-    - `SHA-512`
+    - `SHA-256`: selects the [SHA-256](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) algorithm.
+    - `SHA-384`: selects the [SHA-384](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) algorithm.
+    - `SHA-512`: selects the [SHA-512](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) algorithm.
+
+    > **Warning:** `SHA-1` is also supported here but the [SHA-1](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) algorithm is considered vulnerable and should no longer be used.
 
 - `salt`
   - : An {{jsxref("ArrayBuffer")}}, a {{jsxref("TypedArray")}}, or a {{jsxref("DataView")}}. The [HKDF specification](https://datatracker.ietf.org/doc/html/rfc5869) states that adding salt "adds significantly to the strength of HKDF". Ideally, the salt is a random or pseudo-random value with the same length as the output of the digest function. Unlike the input key material passed into `deriveKey()`, salt does not need to be kept secret.

diff --git a/files/en-us/web/api/hmacimportparams/index.md b/files/en-us/web/api/hmacimportparams/index.md
@@ -15,10 +15,13 @@ The **`HmacImportParams`** dictionary of the [Web Crypto API](/en-US/docs/Web/AP
   - : A string. This should be set to `HMAC`.
 - `hash`
 
-  - : A string representing the name of the [digest function](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) to use. The can take a value of `SHA-256`, `SHA-384`, or `SHA-512`.
+  - : A string or an object containing a single property called `name` with a string value. It is an identifier for the [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest) to use. This should be one of the following:
 
-    > [!WARNING]
-    > Although you can technically pass `SHA-1` here, this is strongly discouraged as it is considered vulnerable.
+    - `SHA-256`: selects the [SHA-256](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) algorithm.
+    - `SHA-384`: selects the [SHA-384](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) algorithm.
+    - `SHA-512`: selects the [SHA-512](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) algorithm.
+
+    > **Warning:** `SHA-1` is also supported here but the [SHA-1](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) algorithm is considered vulnerable and should no longer be used.
 
 - `length` {{optional_inline}}
   - : A `Number` representing the length in bits of the key. If this is omitted the length of the key is equal to the length of the digest generated by the digest function you have chosen. Unless you have a good reason to use a different length, omit this property and use the default.

diff --git a/files/en-us/web/api/hmackeygenparams/index.md b/files/en-us/web/api/hmackeygenparams/index.md
@@ -12,9 +12,19 @@ The **`HmacKeyGenParams`** dictionary of the [Web Crypto API](/en-US/docs/Web/AP
 ## Instance properties
 
 - `name`
+
   - : A string. This should be set to `HMAC`.
+
 - `hash`
-  - : A string representing the name of the [digest function](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) to use. You can pass any of `SHA-1`, `SHA-256`, `SHA-384`, or `SHA-512` here.
+
+  - : A string or an object containing a single property called `name` with a string value. It is an identifier for the [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest) to use. This should be one of the following:
+
+    - `SHA-256`: selects the [SHA-256](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) algorithm.
+    - `SHA-384`: selects the [SHA-384](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) algorithm.
+    - `SHA-512`: selects the [SHA-512](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) algorithm.
+
+    > **Warning:** `SHA-1` is also supported here but the [SHA-1](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) algorithm is considered vulnerable and should no longer be used.
+
 - `length` {{optional_inline}}
   - : A `Number` — the length in bits of the key. If this is omitted, the length of the key is equal to the block size of the hash function you have chosen. Unless you have a good reason to use a different length, omit this property and use the default.
 

diff --git a/files/en-us/web/api/pbkdf2params/index.md b/files/en-us/web/api/pbkdf2params/index.md
@@ -15,12 +15,11 @@ The **`Pbkdf2Params`** dictionary of the [Web Crypto API](/en-US/docs/Web/API/We
   - : A string. This should be set to `PBKDF2`.
 - `hash`
 
-  - : A string representing the [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) to use. This may be one of:
+  - : A string or an object containing a single property called `name` with a string value. It is an identifier for the [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest) to use. This should be one of the following:
 
-    - `SHA-1`
-    - `SHA-256`
-    - `SHA-384`
-    - `SHA-512`
+    - `SHA-256`: selects the [SHA-256](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) algorithm.
+    - `SHA-384`: selects the [SHA-384](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) algorithm.
+    - `SHA-512`: selects the [SHA-512](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) algorithm.
 
     > **Warning:** `SHA-1` is considered vulnerable in most cryptographic applications, but is still considered safe in PBKDF2. However, it's advisable to transition away from it everywhere, so unless you need to use `SHA-1`, don't. Use a different digest algorithm instead.
 

diff --git a/files/en-us/web/api/rsahashedimportparams/index.md b/files/en-us/web/api/rsahashedimportparams/index.md
@@ -15,10 +15,13 @@ The **`RsaHashedImportParams`** dictionary of the [Web Crypto API](/en-US/docs/W
   - : A string. This should be set to `RSASSA-PKCS1-v1_5`, `RSA-PSS`, or `RSA-OAEP`, depending on the algorithm you want to use.
 - `hash`
 
-  - : A string representing the name of the [digest function](/en-US/docs/Web/API/SubtleCrypto#supported_algorithms) to use. This can be one of `SHA-256`, `SHA-384`, or `SHA-512`.
+  - : A string or an object containing a single property called `name` with a string value. It is an identifier for the [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest) to use. This should be one of the following:
 
-    > [!WARNING]
-    > Although you can technically pass `SHA-1` here, this is strongly discouraged as it is considered vulnerable.
+    - `SHA-256`: selects the [SHA-256](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) algorithm.
+    - `SHA-384`: selects the [SHA-384](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) algorithm.
+    - `SHA-512`: selects the [SHA-512](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) algorithm.
+
+    > **Warning:** `SHA-1` is also supported here but the [SHA-1](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) algorithm is considered vulnerable and should no longer be used.
 
 ## Examples
 

diff --git a/files/en-us/web/api/rsahashedkeygenparams/index.md b/files/en-us/web/api/rsahashedkeygenparams/index.md
@@ -19,10 +19,13 @@ The **`RsaHashedKeyGenParams`** dictionary of the [Web Crypto API](/en-US/docs/W
   - : A {{jsxref("Uint8Array")}}. The public exponent. Unless you have a good reason to use something else, specify 65537 here (`[0x01, 0x00, 0x01]`).
 - `hash`
 
-  - : A string representing the name of the [digest function](/en-US/docs/Web/API/SubtleCrypto/digest) to use. You can pass any of `SHA-256`, `SHA-384`, or `SHA-512` here.
+  - : A string or an object containing a single property called `name` with a string value. It is an identifier for the [digest algorithm](/en-US/docs/Web/API/SubtleCrypto/digest) to use. This should be one of the following:
 
-    > [!WARNING]
-    > Although you can technically pass `SHA-1` as a value here, this is strongly discouraged as SHA-1 is considered vulnerable.
+    - `SHA-256`: selects the [SHA-256](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) algorithm.
+    - `SHA-384`: selects the [SHA-384](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) algorithm.
+    - `SHA-512`: selects the [SHA-512](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) algorithm.
+
+    > **Warning:** `SHA-1` is also supported here but the [SHA-1](/en-US/docs/Web/API/SubtleCrypto/digest#supported_algorithms) algorithm is considered vulnerable and should no longer be used.
 
 ## Examples