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

Chromium: «Cannot create a key using the specified key usages.» или «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». Проверяйте условие `e.name === "SyntaxError"`.

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

Что это означает

Массив `keyUsages` не подходит к создаваемому ключу. WebCrypto определяет, какие usages допустимы для каждого типа ключа: открытому ключу ECDSA или RSA разрешено только `verify`, закрытому ключу — только `sign`; открытые ключи ECDH не принимают usages вовсе, а создать закрытый или секретный ключ с пустым списком usages нельзя. Браузер отклоняет вызов с DOMException `SyntaxError` ещё до того, как ключ создан. Это не то же самое, что `InvalidAccessError`: ту ошибку вы получите позже, когда существующий ключ используют для операции, для которой он не создавался.

Почему это происходит

• Открытый ключ импортирован с sign (или закрытый ключ — с verify)

  часто

  Если копировать один и тот же массив `["sign", "verify"]` в каждый вызов `importKey`, импорт отдельных ключей завершается ошибкой: распределять список между двумя частями пары умеет только `generateKey`.

• Пустой список usages

  часто

  `generateKey(alg, true, [])` или импорт закрытого ключа с `[]`. Ключ должен создаваться хотя бы для одной цели.

• Перепутаны ECDH и ECDSA

  иногда

  Импорт ключа ECDH с `["sign"]` или ключа ECDSA с `["deriveBits"]` завершается ошибкой: одна и та же точка кривой для каждого алгоритма — ключ другого типа.

Как исправить

1. 1.

   Назначайте каждому ключу usages по его роли

   Открытым ключам — `verify` (подписи) или `[]` (ключи другой стороны в ECDH); закрытым ключам — `sign` или `deriveBits`/`deriveKey`. Оставляйте usages минимальными: они входят в модель минимальных привилегий 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, []);

← Открыть всю базу ошибок подписей