docs: improve generate key/secret and import function descriptions

panva · Feb 24, 2025 · cd06359 · cd06359
1 parent df99550
commit cd06359
Show file tree

Hide file tree

Showing 6 changed files with 25 additions and 5 deletions.
diff --git a/docs/key/generate_secret/functions/generateSecret.md b/docs/key/generate_secret/functions/generateSecret.md
@@ -10,6 +10,9 @@ Generates a symmetric secret key for a given JWA algorithm identifier.
 
 Note: The secret key is generated with `extractable` set to `false` by default.
 
+Note: Because A128CBC-HS256, A192CBC-HS384, and A256CBC-HS512 secrets cannot be represented as
+[CryptoKey](https://developer.mozilla.org/docs/Web/API/CryptoKey) this method yields a [Uint8Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) for them instead.
+
 This function is exported (as a named export) from the main `'jose'` module entry point as well
 as from its subpath export `'jose/generate/secret'`.
 

diff --git a/docs/key/generate_secret/interfaces/GenerateSecretOptions.md b/docs/key/generate_secret/interfaces/GenerateSecretOptions.md
@@ -13,3 +13,6 @@ Secret generation function options.
 • `optional` **extractable**: `boolean`
 
 The value to use as [SubtleCrypto.generateKey](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/generateKey) `extractable` argument. Default is false.
+
+Note: Because A128CBC-HS256, A192CBC-HS384, and A256CBC-HS512 secrets cannot be represented as
+[CryptoKey](https://developer.mozilla.org/docs/Web/API/CryptoKey) this option has no effect for them.
diff --git a/docs/key/import/functions/importJWK.md b/docs/key/import/functions/importJWK.md
@@ -7,11 +7,14 @@ Support from the community to continue maintaining and improving this module is
 ▸ **importJWK**(`jwk`, `alg`?, `options`?): [`Promise`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)\<[`CryptoKey`](../../../types/type-aliases/CryptoKey.md) \| [`Uint8Array`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array)\>
 
 Imports a JWK to a [CryptoKey](https://developer.mozilla.org/docs/Web/API/CryptoKey). Either the JWK "alg" (Algorithm) Parameter, or the optional
-"alg" argument, must be present.
+"alg" argument, must be present for asymmetric JSON Web Key imports.
 
 Note: The JSON Web Key parameters "use", "key_ops", and "ext" are also used in the
 [CryptoKey](https://developer.mozilla.org/docs/Web/API/CryptoKey) import process.
 
+Note: Symmetric JSON Web Keys (i.e. `kty: "oct"`) yield back an [Uint8Array](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Uint8Array) instead of a
+[CryptoKey](https://developer.mozilla.org/docs/Web/API/CryptoKey).
+
 This function is exported (as a named export) from the main `'jose'` module entry point as well
 as from its subpath export `'jose/key/import'`.
 

diff --git a/docs/key/import/interfaces/KeyImportOptions.md b/docs/key/import/interfaces/KeyImportOptions.md
@@ -13,4 +13,4 @@ Key Import Function options.
 • `optional` **extractable**: `boolean`
 
 The value to use as [SubtleCrypto.importKey](https://developer.mozilla.org/docs/Web/API/SubtleCrypto/importKey) `extractable` argument. Default is false for
-private and secret keys, true otherwise.
+private keys, true otherwise.
diff --git a/src/key/generate_secret.ts b/src/key/generate_secret.ts
@@ -10,7 +10,12 @@ import type * as types from '../types.d.ts'
 
 /** Secret generation function options. */
 export interface GenerateSecretOptions {
-  /** The value to use as {@link !SubtleCrypto.generateKey} `extractable` argument. Default is false. */
+  /**
+   * The value to use as {@link !SubtleCrypto.generateKey} `extractable` argument. Default is false.
+   *
+   * Note: Because A128CBC-HS256, A192CBC-HS384, and A256CBC-HS512 secrets cannot be represented as
+   * {@link !CryptoKey} this option has no effect for them.
+   */
   extractable?: boolean
 }
 
@@ -19,6 +24,9 @@ export interface GenerateSecretOptions {
  *
  * Note: The secret key is generated with `extractable` set to `false` by default.
  *
+ * Note: Because A128CBC-HS256, A192CBC-HS384, and A256CBC-HS512 secrets cannot be represented as
+ * {@link !CryptoKey} this method yields a {@link !Uint8Array} for them instead.
+ *
  * This function is exported (as a named export) from the main `'jose'` module entry point as well
  * as from its subpath export `'jose/generate/secret'`.
  *

diff --git a/src/key/import.ts b/src/key/import.ts
@@ -16,7 +16,7 @@ import type * as types from '../types.d.ts'
 export interface KeyImportOptions {
   /**
    * The value to use as {@link !SubtleCrypto.importKey} `extractable` argument. Default is false for
-   * private and secret keys, true otherwise.
+   * private keys, true otherwise.
    */
   extractable?: boolean
 }
@@ -138,11 +138,14 @@ export async function importPKCS8(
 
 /**
  * Imports a JWK to a {@link !CryptoKey}. Either the JWK "alg" (Algorithm) Parameter, or the optional
- * "alg" argument, must be present.
+ * "alg" argument, must be present for asymmetric JSON Web Key imports.
  *
  * Note: The JSON Web Key parameters "use", "key_ops", and "ext" are also used in the
  * {@link !CryptoKey} import process.
  *
+ * Note: Symmetric JSON Web Keys (i.e. `kty: "oct"`) yield back an {@link !Uint8Array} instead of a
+ * {@link !CryptoKey}.
+ *
  * This function is exported (as a named export) from the main `'jose'` module entry point as well
  * as from its subpath export `'jose/key/import'`.
  *