SyntaxError: Cannot create a key using the specified key usages.

Chromium: «Cannot create a key using the specified key usages.» o «Usages cannot be empty when creating a key.»; Firefox: «An invalid or illegal string was specified»; Safari/WebKit: «A required parameter was missing or out-of-range». Detecta el error con `e.name === "SyntaxError"`.

WebCrypto SubtleCrypto.importKey / generateKey — DOMException SyntaxError (Chromium / Firefox / WebKit)

Qué significa

El array `keyUsages` no encaja con la clave que se está creando. WebCrypto define qué usos puede tener cada tipo de clave: una clave pública ECDSA o RSA solo puede tener `verify`, y una privada, solo `sign`; las claves públicas ECDH no admiten ningún uso; y no se permite crear una clave privada o una clave secreta con una lista de usos vacía. El navegador rechaza la llamada con una DOMException `SyntaxError` antes de que exista la clave. Esto es distinto de `InvalidAccessError`, que aparece más tarde, cuando una clave existente se usa para una operación para la que no se creó.

Por qué ocurre

• Una clave pública importada con sign (o una clave privada con verify)

  frecuente

  Copiar el mismo array `["sign", "verify"]` en todas las llamadas a `importKey` falla con claves individuales: solo `generateKey` reparte la lista entre las dos mitades de un par.

• Una lista de usos vacía

  frecuente

  `generateKey(alg, true, [])` o importar una clave privada con `[]`. Las claves deben crearse para al menos un propósito.

• Confusión entre ECDH y ECDSA

  ocasional

  Una clave ECDH importada con `["sign"]` o una clave ECDSA con `["deriveBits"]` falla: el mismo punto de la curva es un tipo de clave distinto para cada algoritmo.

Cómo solucionarlo

1. 1.

   Dar a cada clave los usos de su rol

   Claves públicas: `verify` (firmas) o `[]` (claves del otro extremo en ECDH); claves privadas: `sign` o `deriveBits`/`deriveKey`. Mantén los usos al mínimo: forman parte del modelo de mínimo privilegio de WebCrypto.

   const alg = { name: "ECDSA", namedCurve: "P-256" };
   // Public keys verify, private keys sign:
   const publicKey = await crypto.subtle.importKey("spki", spkiDer, alg, false, ["verify"]);
   const privateKey = await crypto.subtle.importKey("pkcs8", pkcs8Der, alg, false, ["sign"]);
   // ECDH keys derive; their public half takes no usages at all:
   const peer = await crypto.subtle.importKey("raw", point, { name: "ECDH", namedCurve: "P-256" }, false, []);

← Explorar toda la base de datos de errores de firma