Qual deve ser o comprimento de uma chave de API?

Para uma nova chave de API opaca, use pelo menos 128 bits de aleatoriedade imprevisível; 256 bits aleatórios são uma opção padrão robusta quando o sistema receptor os aceita. Isso não significa que toda chave deva ter 256 caracteres. O mesmo valor de 256 bits corresponde a 64 caracteres hexadecimais, 43 caracteres em Base64URL sem preenchimento, 44 caracteres em Base64 com preenchimento ou 52 caracteres em Base32 sem preenchimento.

Use o Gerador de Chaves de API do ClockTools para escolher primeiro o nível de aleatoriedade desejado e depois o formato. A ferramenta calcula os bytes e caracteres necessários antes de gerar qualquer valor, para que você respeite o limite de um campo sem confundir comprimento visual com segurança.

Qual é o comprimento correto da chave de API?

Não existe uma contagem universal de caracteres, porque um caractere não é uma unidade fixa de segurança. Um caractere hexadecimal representa 4 bits. Um caractere Base64URL escolhido de maneira uniformemente aleatória representa aproximadamente 6 bits, com exceção do último grupo parcial. Um dígito decimal representa cerca de 3,32 bits. O alfabeto, o método de geração e o número de escolhas independentes determinam o espaço de busca.

Para um planejamento prático, comece aqui:

A documentação de secrets do Python descreve 32 bytes, ou 256 bits, como suficientes para os casos de uso típicos desse módulo, mas alerta que a aleatoriedade adequada muda conforme a capacidade computacional e a ameaça. Isso faz de 256 bits uma opção padrão sensata, não uma regra mágica de conformidade.

O serviço que aceita a credencial ainda controla o formato real. Se uma API existente especificar 32 caracteres hexadecimais, um prefixo fixo ou um token emitido pelo provedor, siga esse contrato. Não aumente, trunque ou recodifique silenciosamente uma chave emitida pelo provedor.

Por que a entropia e a contagem de caracteres são diferentes?

A entropia responde a uma pergunta mais útil do que a aparência: quantos segredos igualmente prováveis o gerador poderia ter produzido? Um valor uniformemente aleatório de 128 bits tem 2^128 possibilidades. Um valor de 256 bits tem 2^256 possibilidades. Acrescentar caracteres à representação só ajuda se eles acrescentarem escolhas independentes e imprevisíveis.

A RFC 4086 mostra por que essa distinção importa. Uma saída longa gerada a partir de uma semente pequena ou previsível pode conter muito menos informação real do que seu comprimento sugere. Por exemplo, um valor com aparência de 128 bits, produzido a partir de uma semente de apenas 8 bits, ainda expõe somente 256 possibilidades de semente. O comprimento não compensa uma aleatoriedade fraca.

Por isso, Math.random(), registros de data e hora, IDs sequenciais, nomes de usuário ou dados concatenados de dispositivos são bases inadequadas para segredos de API. No navegador, a documentação da MDN sobre crypto.getRandomValues() apresenta esse método como uma fonte de valores aleatórios criptograficamente fortes. O ClockTools exige essa API e não usa Math.random() como alternativa.

Para alfabetos de caracteres, o cálculo teórico é:

entropy bits = character count × log2(number of distinct characters)

Um alfabeto de 62 caracteres, composto por letras e dígitos, exige 22 caracteres independentes para ultrapassar 128 bits e 43 para ultrapassar 256 bits. Um alfabeto composto apenas por dígitos exige 39 e 78 caracteres, respectivamente. Um alfabeto menor não é automaticamente fraco; ele apenas exige mais caracteres para atingir a mesma meta.

Qual é o comprimento de uma chave de API de 256 bits em cada codificação?

A codificação muda a representação, não os bytes aleatórios subjacentes. A ferramenta do ClockTools em funcionamento e seus testes de regressão usam 32 bytes aleatórios para uma meta de 256 bits. Esses bytes são representados da seguinte forma:

As contagens seguem as regras de codificação da RFC 4648. A codificação hexadecimal é mais fácil de examinar e amplamente aceita, mas exige dois caracteres por byte. Base64URL é mais compacta e evita os caracteres + e /, que podem causar dificuldades em URLs e nomes de arquivos. A Base64 comum pode incluir esses caracteres e usa preenchimento. A Base32 não diferencia maiúsculas de minúsculas em muitos fluxos de trabalho, mas é mais longa.

Escolha o formato que o aplicativo receptor consegue interpretar de forma confiável. Não remova o preenchimento a menos que o protocolo permita e não presuma que um alfabeto seguro para URLs torne o valor seguro para exposição em uma URL. Segredos de API podem vazar pelo histórico do navegador, por dados de referência, por logs de proxy reverso e por ferramentas de análise.

Quando 128 bits são suficientes?

Um segredo opaco de 128 bits gerado de maneira uniformemente aleatória oferece um enorme espaço de busca para tentativas on-line. Em muitos sistemas, os limites de requisições, o monitoramento, o isolamento de credenciais e a dificuldade de testar tentativas tornam a busca exaustiva impraticável. Aumentar o valor aleatório para 256 bits cria uma margem maior e custa pouco na maioria dos novos projetos do lado do servidor.

A escolha ainda deve seguir um modelo de ameaças e o contrato do sistema. Considere 256 bits quando você controlar o formato da credencial, o custo de armazenamento for insignificante e a chave proteger acesso valioso ou de longa duração. Uma chave de 128 bits bem gerada pode ser adequada quando um protocolo fixa o tamanho, a credencial tem curta duração ou um campo legado não comporta mais caracteres.

Mais bits não compensam um segredo exposto. Uma chave de 256 bits incluída em um repositório público pode ser copiada imediatamente; ninguém precisa aplicar força bruta para obtê-la. Se houver possibilidade de vazamento de uma chave, revogue-a ou faça sua rotação, em vez de apenas substituí-la por uma string mais longa.

Um prefixo torna uma chave de API mais forte?

Não, se o prefixo for fixo ou previsível. Textos como live_, test_ ou sk_ podem ajudar pessoas e ferramentas de detecção de segredos a identificar uma credencial, mas não acrescentam entropia. Um valor aleatório de 256 bits continua contendo 256 bits aleatórios, quer sua representação comece com cinco caracteres conhecidos ou nenhum.

Prefixos ainda podem ser úteis. Eles permitem distinguir material de produção de material de teste, identificar uma família de credenciais e reduzir a chance de colar uma chave no sistema errado. Mantenha essa finalidade separada da robustez da autenticação.

O mesmo alerta se aplica a sufixos e IDs públicos de chaves. Um identificador público pode localizar o registro correto no banco de dados sem revelar o segredo, mas o ID não deve ser aceito como prova de autorização. O ClockTools apresenta os afixos fixos e os IDs públicos separadamente do total de bits aleatórios.

O que mais importa além do comprimento?

O comprimento diz respeito apenas à etapa de criação. As orientações de gerenciamento de segredos da OWASP tratam o segredo ao longo de um ciclo de vida: criação, rotação, revogação e expiração. As orientações sobre chaves de API do Google Cloud também enfatizam restrições, isolamento, monitoramento, prevenção da exposição de segredos no código do cliente e rotação.

Antes de emitir uma chave de produção, verifique todas as três camadas:

1. Aleatoriedade: gere pelo menos 128 bits imprevisíveis com uma fonte criptograficamente segura; prefira 256 bits para uma nova chave opaca quando houver compatibilidade.
2. Representação: escolha uma codificação aceita pelo sistema receptor; conte apenas a parte aleatória, não um prefixo ou separador fixo.
3. Ciclo de vida: limite o escopo das permissões, transmita por HTTPS, armazene em um gerenciador de segredos, impeça logs em texto aberto, monitore o uso, defina a expiração quando apropriado e permita revogação rápida.

As chaves de API são credenciais de portador em muitos projetos: quem possui o valor pode exercer as permissões associadas a ele. Elas costumam ser mais adequadas para identificar o aplicativo ou projeto que faz a chamada do que para autenticar um usuário humano. Para ações sensíveis do usuário, combine-as ou substitua-as por um método de autenticação e autorização projetado para essa finalidade.

Como você pode gerar a chave com segurança?

Para gerar rapidamente um valor localmente no navegador, abra o Gerador de Chaves de API, mantenha a meta de aleatoriedade em 256 bits e selecione o formato necessário. A configuração padrão Base64URL produz 32 bytes aleatórios representados por 43 caracteres. A geração e a preparação para exportação acontecem localmente no navegador, e a página exclui intencionalmente os valores secretos das configurações compartilhadas.

Para infraestrutura de produção, gere o valor no ambiente confiável em que o segredo será armazenado sempre que possível. Node.js crypto.randomBytes, Python secrets ou OpenSSL podem evitar uma cópia pela área de transferência. A página do ClockTools exibe comandos para esses ambientes sem incorporar uma chave gerada.

Após a geração, registre o valor no aplicativo que irá verificá-lo. A string aleatória não se torna uma credencial funcional só por se parecer com uma chave de API. Permissões, expiração, revogação e verificação de requisições são responsabilidades do sistema receptor. A metodologia de chaves de API do ClockTools explica a fonte de aleatoriedade do navegador, a amostragem por rejeição, os comprimentos testados e as limitações; o Gerador de GUID está disponível para identificadores que não são segredos compartilhados.