docs: add import key notes about OID id-RSASSA-PSS support

panva · Feb 10, 2024 · f23a29a · f23a29a
1 parent d85e3eb
commit f23a29a
Show file tree

Hide file tree

Showing 5 changed files with 34 additions and 8 deletions.
diff --git a/docs/functions/key_import.importJWK.md b/docs/functions/key_import.importJWK.md
@@ -8,10 +8,11 @@ Support from the community to continue maintaining and improving this module is
 
 ▸ **importJWK**\<`KeyLikeType`\>(`jwk`, `alg?`): [`Promise`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise )\<`KeyLikeType` \| [`Uint8Array`]( https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array )\>
 
-Imports a JWK to a runtime-specific key representation (KeyLike). Either JWK "alg" (Algorithm)
-Parameter must be present or the optional "alg" argument. When running on a runtime using
-[Web Cryptography API](https://www.w3.org/TR/WebCryptoAPI/) the jwk parameters "use",
-"key_ops", and "ext" are also used in the resulting `CryptoKey`.
+Imports a JWK to a runtime-specific key representation (KeyLike). Either the JWK "alg"
+(Algorithm) Parameter, or the optional "alg" argument, must be present.
+
+Note: When the runtime is using [Web Cryptography API](https://w3c.github.io/webcrypto/) the
+jwk parameters "use", "key_ops", and "ext" are also used in the resulting `CryptoKey`.
 
 #### Type parameters
 

diff --git a/docs/functions/key_import.importPKCS8.md b/docs/functions/key_import.importPKCS8.md
@@ -11,6 +11,10 @@ Support from the community to continue maintaining and improving this module is
 Imports a PEM-encoded PKCS#8 string as a runtime-specific private key representation (KeyObject
 or CryptoKey).
 
+Note: The OID id-RSASSA-PSS (1.2.840.113549.1.1.10) is not supported in
+[Web Cryptography API](https://w3c.github.io/webcrypto/), use the OID rsaEncryption
+(1.2.840.113549.1.1.1) instead for all RSA algorithms.
+
 #### Type parameters
 
 | Name | Type |

diff --git a/docs/functions/key_import.importSPKI.md b/docs/functions/key_import.importSPKI.md
@@ -11,6 +11,10 @@ Support from the community to continue maintaining and improving this module is
 Imports a PEM-encoded SPKI string as a runtime-specific public key representation (KeyObject or
 CryptoKey).
 
+Note: The OID id-RSASSA-PSS (1.2.840.113549.1.1.10) is not supported in
+[Web Cryptography API](https://w3c.github.io/webcrypto/), use the OID rsaEncryption
+(1.2.840.113549.1.1.1) instead for all RSA algorithms.
+
 #### Type parameters
 
 | Name | Type |

diff --git a/docs/functions/key_import.importX509.md b/docs/functions/key_import.importX509.md
@@ -11,6 +11,10 @@ Support from the community to continue maintaining and improving this module is
 Imports the SPKI from an X.509 string certificate as a runtime-specific public key representation
 (KeyObject or CryptoKey).
 
+Note: The OID id-RSASSA-PSS (1.2.840.113549.1.1.10) is not supported in
+[Web Cryptography API](https://w3c.github.io/webcrypto/), use the OID rsaEncryption
+(1.2.840.113549.1.1.1) instead for all RSA algorithms.
+
 #### Type parameters
 
 | Name | Type |

diff --git a/src/key/import.ts b/src/key/import.ts
@@ -19,6 +19,10 @@ export interface PEMImportOptions {
  * Imports a PEM-encoded SPKI string as a runtime-specific public key representation (KeyObject or
  * CryptoKey).
  *
+ * Note: The OID id-RSASSA-PSS (1.2.840.113549.1.1.10) is not supported in
+ * {@link https://w3c.github.io/webcrypto/ Web Cryptography API}, use the OID rsaEncryption
+ * (1.2.840.113549.1.1.1) instead for all RSA algorithms.
+ *
  * @example
  *
  * ```js
@@ -51,6 +55,10 @@ export async function importSPKI<KeyLikeType extends KeyLike = KeyLike>(
  * Imports the SPKI from an X.509 string certificate as a runtime-specific public key representation
  * (KeyObject or CryptoKey).
  *
+ * Note: The OID id-RSASSA-PSS (1.2.840.113549.1.1.10) is not supported in
+ * {@link https://w3c.github.io/webcrypto/ Web Cryptography API}, use the OID rsaEncryption
+ * (1.2.840.113549.1.1.1) instead for all RSA algorithms.
+ *
  * @example
  *
  * ```js
@@ -89,6 +97,10 @@ export async function importX509<KeyLikeType extends KeyLike = KeyLike>(
  * Imports a PEM-encoded PKCS#8 string as a runtime-specific private key representation (KeyObject
  * or CryptoKey).
  *
+ * Note: The OID id-RSASSA-PSS (1.2.840.113549.1.1.10) is not supported in
+ * {@link https://w3c.github.io/webcrypto/ Web Cryptography API}, use the OID rsaEncryption
+ * (1.2.840.113549.1.1.1) instead for all RSA algorithms.
+ *
  * @example
  *
  * ```js
@@ -119,10 +131,11 @@ export async function importPKCS8<KeyLikeType extends KeyLike = KeyLike>(
 }
 
 /**
- * Imports a JWK to a runtime-specific key representation (KeyLike). Either JWK "alg" (Algorithm)
- * Parameter must be present or the optional "alg" argument. When running on a runtime using
- * {@link https://www.w3.org/TR/WebCryptoAPI/ Web Cryptography API} the jwk parameters "use",
- * "key_ops", and "ext" are also used in the resulting `CryptoKey`.
+ * Imports a JWK to a runtime-specific key representation (KeyLike). Either the JWK "alg"
+ * (Algorithm) Parameter, or the optional "alg" argument, must be present.
+ *
+ * Note: When the runtime is using {@link https://w3c.github.io/webcrypto/ Web Cryptography API} the
+ * jwk parameters "use", "key_ops", and "ext" are also used in the resulting `CryptoKey`.
  *
  * @example
  *