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

Chromium: “Cannot create a key using the specified key usages.” ou “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”. Para identificar o erro, use `e.name === "SyntaxError"`.

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

O que significa

O array `keyUsages` não combina com a chave que está sendo criada. O WebCrypto define quais usos cada tipo de chave pode ter: uma chave pública ECDSA ou RSA só pode ter o uso `verify`, e uma chave privada, só `sign`; chaves públicas ECDH não recebem nenhum uso; e não é permitido criar uma chave privada ou uma chave secreta com uma lista de usos vazia. O navegador rejeita a chamada com uma DOMException `SyntaxError` antes que a chave exista. Isso é diferente de `InvalidAccessError`, que aparece depois, quando uma chave já existente é usada em uma operação para a qual não foi criada.

Por que acontece

• Uma chave pública importada com sign (ou uma chave privada com verify)

  comum

  Copiar o mesmo array `["sign", "verify"]` para todas as chamadas `importKey` falha com chaves avulsas: só o `generateKey` divide a lista entre as duas metades de um par.

• Uma lista de usos vazia

  comum

  `generateKey(alg, true, [])` ou a importação de uma chave privada com `[]`. As chaves precisam ser criadas para pelo menos uma finalidade.

• ECDH e ECDSA confundidos

  ocasional

  Uma chave ECDH importada com `["sign"]` ou uma chave ECDSA com `["deriveBits"]` falha: o mesmo ponto da curva é um tipo de chave diferente para cada algoritmo.

Como corrigir

1. 1.

   Dar a cada chave os usos do papel dela

   Chaves públicas: `verify` (assinaturas) ou `[]` (chaves ECDH da outra parte); chaves privadas: `sign` ou `deriveBits`/`deriveKey`. Mantenha os usos no mínimo — eles fazem parte do modelo de menor privilégio do 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, []);

← Ver toda a base de erros de assinatura