importKey

importKey is a function in the Web Crypto API, provided by the SubtleCrypto interface, used to bring external key material into a usable CryptoKey object. It returns a Promise that resolves to a CryptoKey or rejects with an error if the import fails. The method requires five parameters: format, keyData, algorithm, extractable, and keyUsages.

Format specifies how the key material is encoded and can be one of several values: "raw" for a binary key, "pkcs8" for private keys in PKCS#8 format, "spki" for public keys in SPKI format, or "jwk" for a JSON Web Key. KeyData is the actual key material, supplied as an ArrayBuffer, TypedArray, DataView, or, in the case of "jwk", a JSON Web Key object. Algorithm describes the cryptographic algorithm that will use the key (for example, {name: "AES-GCM"} or {name: "RSASSA-PKCS1-v1_5"}). This parameter often informs validation and parameter constraints during import. Extractable is a boolean that indicates whether the imported key may be exported later. KeyUsages is an array of strings describing permitted operations for the key, such as "encrypt", "decrypt", "sign", "verify", "wrapKey", and "unwrapKey".

On success, importKey yields a CryptoKey that can be used with other Web Crypto operations. On failure, the returned promise rejects with an appropriate error (for example, NotSupportedError, DataError, or TypeError), typically due to format mismatches, algorithm incompatibilities, or invalid key data.

Usage considerations include ensuring the environment supports the chosen format and algorithm, and that the key material is handled securely. The method is widely supported in modern browsers and is a foundational step for working with cryptographic keys in web applications.