# CryptoKey

A interface `CryptoKey` representa uma chave criptográfica que um dos métodos do [SubtleCrypto](/pt-br/documentacao/devtools/runtime/api-reference/subtle-crypto/) retorna. Em uma function da Azion, uma `CryptoKey` é o objeto que você passa para o SubtleCrypto ao criptografar, descriptografar, assinar ou verificar dados. Para mais informações, consulte [CryptoKey](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey) na MDN Web Docs.

Use uma `CryptoKey` para guardar uma chave secreta importada que verifica tokens assinados ou assinaturas HMAC. Um par de chaves gerado pode assinar ou criptografar payloads antes que eles saiam da function. As suas `usages` restringem como a chave é aplicada, de modo que uma chave pode assinar, mas não descriptografar, por exemplo. A function trata a chave como um objeto opaco: o material bruto da chave fica fora do código, a menos que a chave seja extraível e você a exporte.

---

## Construtor

`CryptoKey` não tem construtor público: `new CryptoKey()` lança `TypeError: Illegal constructor`. Uma function obtém uma chave por meio destes métodos do SubtleCrypto:

| Método                        | Retorna                                                                                                                                                                |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `crypto.subtle.generateKey()` | Uma nova `CryptoKey` para um algoritmo simétrico, como AES-GCM ou AES-KW. Para um algoritmo assimétrico, como ECDSA, um objeto com uma `privateKey` e uma `publicKey`. |
| `crypto.subtle.importKey()`   | Uma `CryptoKey` construída a partir dos dados de chave que você fornece, como os bytes brutos de um segredo.                                                           |
| `crypto.subtle.deriveKey()`   | Uma `CryptoKey` derivada de uma chave base, como uma chave AES-GCM derivada com PBKDF2.                                                                                |
| `crypto.subtle.unwrapKey()`   | Uma `CryptoKey` descriptografada a partir de uma chave encapsulada, como uma chave encapsulada com AES-KW.                                                             |

---

## Propriedades

As propriedades são somente leitura. Elas descrevem o que a chave é e a quais operações ela pode ser aplicada, para que o runtime aplique uma chave apenas às operações para as quais ela foi criada:

| Propriedade                                                                             | Tipo             | Descrição                                                                                                                                                                                                                                               |
| --------------------------------------------------------------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`type`](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey/type)               | String           | Tipo de chave: `secret` para uma chave simétrica, `private` ou `public` para uma das metades de um par de chaves.                                                                                                                                       |
| [`extractable`](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey/extractable) | Boolean          | `true` quando `crypto.subtle.exportKey()` ou `crypto.subtle.wrapKey()` pode exportar a chave. O método que cria a chave define esse valor. A exportação de uma chave cujo valor é `false` é rejeitada com `InvalidAccessError: Key is not extractable`. |
| [`algorithm`](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey/algorithm)     | Object           | Algoritmo com o qual a chave é usada, em `name`, e os seus parâmetros, como `length` e `hash`.                                                                                                                                                          |
| [`usages`](https://developer.mozilla.org/en-US/docs/Web/API/CryptoKey/usages)           | Array de strings | Operações que a chave pode executar: `encrypt`, `decrypt`, `sign`, `verify`, `deriveKey`, `deriveBits`, `wrapKey` e `unwrapKey`. O método que cria a chave as define.                                                                                   |

---

## Exemplo

Este handler importa um segredo como uma chave HMAC e assina uma mensagem. Ele verifica a assinatura contra a mensagem e contra uma versão adulterada dela, depois retorna os resultados e as propriedades da chave:

```javascript
const enc = new TextEncoder();
const hex = (buf) => Array.from(new Uint8Array(buf), (b) => b.toString(16).padStart(2, '0')).join('');

export default {
  async fetch(request, env, ctx) {
    const key = await crypto.subtle.importKey('raw', enc.encode('a secret'), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign', 'verify']);
    const sig = await crypto.subtle.sign('HMAC', key, enc.encode('Azion Functions'));
    const ok = await crypto.subtle.verify('HMAC', key, sig, enc.encode('Azion Functions'));
    const bad = await crypto.subtle.verify('HMAC', key, sig, enc.encode('tampered'));
    return Response.json({
      signatureHex: hex(sig),
      verifies: ok,
      rejectsTampered: !bad,
      key: { type: key.type, extractable: key.extractable, algorithm: key.algorithm, usages: key.usages, ctor: key.constructor.name },
    });
  },
};
```

A function retorna estes valores. A chave é uma `CryptoKey` do tipo `secret` e não é extraível porque `importKey()` recebeu `false`:

```json
{
 "signatureHex": "86fec9e22ad82998c7007d637f61a5206e2b64ee2a8ac2ed12f1f359e3d14bc6",
 "verifies": true,
 "rejectsTampered": true,
 "key": {
  "type": "secret",
  "extractable": false,
  "algorithm": {
   "name": "HMAC",
   "length": 64,
   "hash": {
    "name": "SHA-256"
   }
  },
  "usages": [
   "sign",
   "verify"
  ],
  "ctor": "CryptoKey"
 }
}
```

---

## Recursos relacionados

- [SubtleCrypto](/pt-br/documentacao/devtools/runtime/api-reference/subtle-crypto.md): Os métodos que criam uma `CryptoKey` e as operações que a usam.
- [Crypto](/pt-br/documentacao/devtools/runtime/api-reference/crypto.md): O objeto global `crypto`, que dá acesso ao SubtleCrypto.
- [node:crypto](/pt-br/documentacao/devtools/runtime/node/crypto.md): O módulo crypto do Node.js, para código escrito para o Node.js.
- [Web APIs](/pt-br/documentacao/devtools/runtime/api-reference/javascript.md): As outras Web APIs que o Azion Runtime suporta.