> ## Documentation Index
> Fetch the complete documentation index at: https://docs.basaltic.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Criando uma chave

> Especificações, usos e a única escolha que você não pode alterar depois que a chave existir.

<a id="creating-a-key" />

## Criando uma chave

<Tabs>
  <Tab title="Console">
    Vá para **KMS** e escolha **Create Key**. Em **Key details**, dê um **Name** e uma **Description** opcional; em **Cryptography**, escolha uma **Key spec** e um **Key usage**.

    As opções de especificação são **AES-256 symmetric (recommended)**, **RSA-2048
    asymmetric**, **RSA-4096 asymmetric** e **ECDSA P-256 asymmetric (sign
    only)**. **Key usage** é bloqueado para qualquer especificação escolhida — uma especificação RSA é a única que permite escolher entre **Encrypt /
    Decrypt** e **Sign / Verify**.
  </Tab>

  <Tab title="API">
    ```bash theme={null}
    POST https://kms.sa-saopaulo-1.basaltic.sh/v1/keys
    {
      "name": "prod-master",
      "key_spec": "aes-256",
      "description": "Master key for the payments data store"
    }
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    basaltic kms key create \
      --name prod-master --key-spec aes-256 \
      --description "Master key for the payments data store"
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    key, err := kms.New(cfg).CreateKey(ctx, &kms.CreateKeyRequest{
        Name:        "prod-master",
        KeySpec:     "aes-256",
        Description: basaltic.String("Master key for the payments data store"),
    })
    ```

    O KMS é regional; uma chave só pode ser usada na região em que foi criada.
  </Tab>
</Tabs>

A chamada é síncrona. A resposta carrega a chave já em `enabled`, pronta para operações de criptografia — não há nada para pesquisar.

`name` é único por conta e chega no CRN, então ele tem que ser URL-safe: `^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$`.

O nome é fixo após a criação porque as políticas do IAM abordam a chave por seu CRN. Uma atualização contendo `name` retorna um erro de validação, mesmo quando o valor é inalterado, vazio ou `null`. As chaves existentes mantêm seus nomes atuais. Excluir uma chave e reutilizar seu nome não preserva a identidade da chave ou o material criptográfico.

<a id="specs-and-usages" />

### Especificações e usos

Uma chave é fixada a um **uso** na criação: ou `encrypt_decrypt` ou `sign_verify`. A **spec** decide quais usos são mesmo possíveis.

| `key_spec` | Pode criptografar | Pode assinar | Uso padrão |
| - | - | - | - |
| `aes-256` | Sim — AES-GCM | Não | `encrypt_decrypt` |
| `rsa-2048` | Sim — OAEP-SHA256 | Sim | nenhum, você deve escolher |
| `rsa-4096` | Sim — OAEP-SHA256 | Sim | nenhum, você deve escolher |
| `ecdsa-p256` | Não | Sim — SHA-256 | `sign_verify` |

Omita `key_usage` para `aes-256` ou `ecdsa-p256` e o único uso que a especificação suporta é aplicado. Omita-o para uma especificação RSA e a solicitação será rejeitada — o RSA pode fazer ambos, então o serviço não adivinhará.

<Warning>
  Uma chave RSA fixada em `encrypt_decrypt` **recusa assinar e verificar**, e vice-versa, mesmo que o algoritmo possa fazer qualquer uma das duas coisas. A recusa é `400 KMS_INVALID_KEY_USAGE`. Escolha o uso deliberadamente: nem a especificação nem o uso podem ser alterados mais tarde, e `PATCH /v1/keys/{key_id}` só edita `description` e `tags`. Para alterar qualquer um, crie uma nova chave.
</Warning>

<a id="find-a-key" />

## Encontrar uma chave

Use `GET /v1/keys?name=prod-master` para uma correspondência exata de nomes, diferenciando maiúsculas e minúsculas, em sua conta, ou passe o CRN completo da chave como o parâmetro de consulta `crn` codificado em URL. Esses filtros combinam com `state` e paginação. Um CRN mal formado ou um para outra conta, região ou tipo de recurso retorna uma página vazia.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.