---
hide_title: false
hide_table_of_contents: false
pagination_next: null
pagination_prev: null
---
# importKey()

The **`importKey()`** method of the [`SubtleCrypto`](../SubtleCrypto.mdx)
interface imports a key: that is, it takes as input a key in an external, portable
format and gives you a [`CryptoKey`](../../CryptoKey/CryptoKey.mdx) object that you can use.

The function accepts several import formats: see [Supported formats](#supported-formats) for details.

## Syntax

```js
importKey(format, keyData, algorithm, extractable, keyUsages)
```

### Parameters

- `format`
  - : A string describing the data format of the key to import. It can be one of the following:
    - `raw`: [Raw](#raw) format.
    - `jwk`: [JSON Web Key](#json-web-key) format.
- `keyData`
  - : An `ArrayBuffer`, a TypedArray, a `DataView`, or a `JSONWebKey` object containing the key in
    the given format.
- `algorithm`
  - : An object defining the type of key to import and providing extra algorithm-specific parameters.
    - For RSASSA-PKCS1-v1_5:
      Pass an [`RsaHashedImportParams`](../../RsaHashedImportParams/RsaHashedImportParams.mdx) object.
    - For HMAC:
      Pass an [`HmacImportParams`](../../HmacImportParams/HmacImportParams.mdx) object.
    - For ECDSA:
      Pass an [`EcKeyImportParams`](../../EcKeyImportParams/EcKeyImportParams.mdx) object.
- `extractable`
  - : A boolean value indicating whether it will be possible to export the key.
- `keyUsages`
  - : An `Array` indicating what can be done with the key. Possible array values are:
    - `encrypt`: The key may be used to encrypt messages.
    - `decrypt`: The key may be used to decrypt messages.
    - `sign`: The key may be used to sign messages.
    - `verify`: The key may be used to verify signatures.
    - `deriveKey`: The key may be used in deriving a new key.
    - `deriveBits`: The key may be used in deriving bits.
    - `wrapKey`: The key may be used to wrap a key.
    - `unwrapKey`: The key may be used to unwrap a key.

### Return value

A [`Promise`](../../Promise/Promise.mdx)
that fulfills with the imported key as a [`CryptoKey`](../../CryptoKey/CryptoKey.mdx) object.

### Exceptions

The promise is rejected when one of the following exceptions is encountered:

- `SyntaxError`
  - : Raised when `keyUsages` is empty but the unwrapped key is of
    type `secret` or `private`.
- `TypeError`
  - : Raised when trying to use an invalid format or if the `keyData`
    is not suited for that format.

## Supported formats

This API currently supports one key import/export format: JSON Web Key.

### Raw

You can use this format to import or export AES or HMAC secret keys, or Elliptic Curve
public keys.

In this format the key is supplied as an `ArrayBuffer` containing the raw bytes for the key.


### JSON Web Key

You can use JSON Web Key format to import or export RSA or Elliptic Curve public or
private keys, as well as AES and HMAC secret keys.

JSON Web Key format is defined in [RFC 7517](https://datatracker.ietf.org/doc/html/rfc7517).
It describes a way to represent public, private, and secret keys as JSON objects.

A JSON Web Key looks something like this (this is an EC private key):

```json
{
  "crv": "P-384",
  "d": "wouCtU7Nw4E8_7n5C1-xBjB4xqSb_liZhYMsy8MGgxUny6Q8NCoH9xSiviwLFfK_",
  "ext": true,
  "key_ops": ["sign"],
  "kty": "EC",
  "x": "SzrRXmyI8VWFJg1dPUNbFcc9jZvjZEfH7ulKI1UkXAltd7RGWrcfFxqyGPcwu6AQ",
  "y": "hHUag3OvDzEr0uUQND4PXHQTXP5IDGdYhJhL-WLKjnGjQAw0rNGy5V29-aV-yseW"
};
```
