¿Qué longitud debe tener una clave API?

Para una nueva clave API opaca, utilice al menos 128 bits de aleatoriedad impredecible; 256 bits aleatorios son una opción predeterminada sólida si el sistema receptor los admite. Eso no significa que cada clave deba tener 256 caracteres. El mismo valor de 256 bits se representa mediante 64 caracteres hexadecimales, 43 caracteres Base64URL sin relleno, 44 caracteres Base64 con relleno o 52 caracteres Base32 sin relleno.

Utilice el generador de claves API de ClockTools para elegir primero el nivel de aleatoriedad deseado y luego el formato. La herramienta calcula los bytes y caracteres necesarios antes de generar ningún valor, de modo que pueda respetar el límite de un campo sin confundir la longitud visible con la seguridad.

¿Cuál es la longitud adecuada de una clave API?

No existe un número universal de caracteres porque un carácter no es una unidad fija de seguridad. Un carácter hexadecimal representa 4 bits. Un carácter Base64URL elegido de manera uniforme y aleatoria representa cerca de 6 bits, salvo en el último grupo parcial. Un dígito decimal representa aproximadamente 3,32 bits. El alfabeto, el método de generación y el número de elecciones independientes determinan el espacio de búsqueda.

Como punto de partida para planificar, tenga en cuenta lo siguiente:

La documentación del módulo secrets de Python indica que 32 bytes, o 256 bits, bastan para los casos de uso habituales de ese módulo, aunque advierte que la aleatoriedad necesaria cambia con la capacidad de cómputo y las amenazas. Por ello, 256 bits son una opción predeterminada razonable, no una regla mágica de cumplimiento.

El servicio que acepta la credencial sigue siendo el que determina el formato real. Si una API existente exige 32 caracteres hexadecimales, un prefijo fijo o un token emitido por el proveedor, respete esa especificación. No alargue, trunque ni vuelva a codificar una clave del proveedor sin indicarlo.

¿Por qué difieren la entropía y el número de caracteres?

La entropía responde a una pregunta más útil que la apariencia: ¿cuántos valores secretos con la misma probabilidad podría haber producido el generador? Un valor de 128 bits generado de manera uniforme y aleatoria tiene 2^128 posibilidades. Un valor de 256 bits tiene 2^256 posibilidades. Añadir más caracteres visibles solo ayuda si aportan elecciones independientes e impredecibles.

RFC 4086 ilustra por qué importa esta distinción. Un resultado largo generado a partir de una semilla pequeña o predecible puede contener mucha menos información real de la que sugiere su longitud. Por ejemplo, un valor que parece tener 128 bits, pero que se genera a partir de una semilla de solo 8 bits, sigue ofreciendo únicamente 256 semillas posibles. La longitud no puede compensar una aleatoriedad deficiente.

Por eso, Math.random(), las marcas de tiempo, los identificadores secuenciales, los nombres de usuario o los datos concatenados de dispositivos no son bases adecuadas para los valores secretos de una API. En el navegador, MDN documenta crypto.getRandomValues() como el método para obtener valores aleatorios criptográficamente seguros. ClockTools requiere esa API y no recurre a Math.random() como alternativa.

Para alfabetos de caracteres, el cálculo teórico es:

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

Un alfabeto de 62 caracteres formado por letras y dígitos necesita 22 caracteres independientes para superar los 128 bits y 43 para superar los 256 bits. Si solo se usan dígitos, se necesitan 39 y 78 caracteres, respectivamente. Un alfabeto reducido no es débil por sí mismo; simplemente necesita más caracteres para alcanzar el mismo objetivo.

¿Cuánto mide una clave API de 256 bits en cada codificación?

La codificación cambia la representación, no los bytes aleatorios subyacentes. La herramienta de ClockTools publicada y sus pruebas de regresión utilizan 32 bytes aleatorios para alcanzar un objetivo de 256 bits. Esos bytes se representan de la siguiente manera:

Los recuentos siguen las reglas de codificación de RFC 4648. El formato hexadecimal es el más fácil de inspeccionar y está ampliamente admitido, pero necesita dos caracteres por byte. Base64URL es más compacto y evita los caracteres + y /, que pueden resultar problemáticos en las URL y los nombres de archivo. Base64 estándar puede incluir esos caracteres y utiliza relleno. Base32 no distingue entre mayúsculas y minúsculas en muchos flujos de trabajo, pero es más largo.

Elija un formato que la aplicación receptora pueda interpretar de forma fiable. No elimine el relleno salvo que el protocolo lo permita, ni suponga que un alfabeto compatible con URL implica que sea seguro exponer el valor en una URL. Los valores secretos de una API pueden filtrarse a través del historial del navegador, los datos de referencia, los registros de los proxies inversos y los sistemas de analítica.

¿Cuándo son suficientes 128 bits?

Un valor secreto opaco de 128 bits generado de manera uniforme y aleatoria ofrece un espacio enorme de valores posibles que adivinar mediante intentos en línea. En muchos sistemas, los límites de solicitudes, la supervisión, el aislamiento de las credenciales y la dificultad de comprobar los intentos hacen inviable una búsqueda exhaustiva. Aumentar el valor aleatorio a 256 bits ofrece un mayor margen y tiene un coste reducido para la mayoría de los nuevos diseños del lado del servidor.

Aun así, la elección debe ajustarse al modelo de amenazas y a las especificaciones del sistema. Considere usar 256 bits si controla el formato de la credencial, el coste de almacenamiento es insignificante y la clave protege un acceso valioso o duradero. Una clave de 128 bits bien generada puede ser adecuada si el protocolo fija el tamaño, la credencial tiene una vida corta o un campo heredado no admite más caracteres.

Más bits no compensan la exposición de un valor secreto. Una clave de 256 bits incluida en un repositorio público se puede copiar de inmediato; nadie necesita averiguarla mediante fuerza bruta. Si una clave puede haberse filtrado, revóquela o rótela en lugar de limitarse a sustituirla por una cadena más larga.

¿Un prefijo fortalece una clave API?

No, si el prefijo es fijo o predecible. Textos como live_, test_ o sk_ pueden ayudar a las personas y a las herramientas de detección de secretos a identificar una credencial, pero no añaden entropía. Un valor aleatorio de 256 bits sigue teniendo 256 bits aleatorios tanto si su representación empieza por cinco caracteres conocidos como si no.

Los prefijos pueden ser útiles de todos modos. Permiten distinguir los datos de producción de los de prueba, identificar una familia de credenciales y reducir la posibilidad de pegar una clave en el sistema equivocado. No confunda esa utilidad con la solidez de la autenticación.

La misma advertencia se aplica a los sufijos y a los identificadores públicos de las claves. Un identificador público permite localizar el registro correcto en la base de datos sin revelar el valor secreto, pero no debe aceptarse como prueba de autorización. ClockTools muestra los afijos fijos y los identificadores públicos por separado, sin incluirlos en el total de bits aleatorios.

¿Qué más importa además de la longitud?

La longitud solo interviene en la creación. La guía de gestión de secretos de OWASP aborda el ciclo de vida de un valor secreto: creación, rotación, revocación y caducidad. La guía sobre claves API de Google Cloud también destaca las restricciones, el aislamiento, la supervisión, la prevención de la exposición en el código del cliente y la rotación.

Antes de emitir una clave de producción, verifique las tres capas:

1. Aleatoriedad: genere al menos 128 bits impredecibles con una fuente criptográficamente segura; prefiera 256 bits para una nueva clave opaca si el sistema los admite.
2. Representación: elija una codificación que acepte el receptor; cuente solo la parte aleatoria, no un prefijo ni un separador fijo.
3. Ciclo de vida: limite los permisos, transmita mediante HTTPS, almacene la clave en un gestor de secretos, evite registrarla en texto sin formato, supervise su uso, defina una caducidad cuando corresponda y permita revocarla con rapidez.

En muchos diseños, las claves API son credenciales de portador: quien posee el valor puede ejercer los permisos que otorga. Por lo general, son más adecuadas para identificar la aplicación o el proyecto que realiza una llamada que para autenticar a una persona. En las acciones sensibles de los usuarios, combínelas o sustitúyalas por un método de autenticación y autorización diseñado para ese fin.

¿Cómo se puede generar la clave de forma segura?

Para generar rápidamente un valor de forma local en el navegador, abra el generador de claves API, mantenga el objetivo de aleatoriedad en 256 bits y seleccione el formato necesario. La configuración predeterminada de Base64URL genera 32 bytes aleatorios representados mediante 43 caracteres. Tanto la generación como la preparación de la exportación se realizan localmente en el navegador, y la página excluye de forma deliberada los valores secretos de los ajustes compartidos.

Para la infraestructura de producción, siempre que sea posible, genere el valor dentro del entorno de confianza que almacenará el secreto. Node.js crypto.randomBytes, Python secrets u OpenSSL permiten evitar el paso por el portapapeles. La página de ClockTools muestra los comandos para esos entornos sin incluir una clave generada.

Después de generar el valor, regístrelo en la aplicación que lo verificará. Una cadena aleatoria no se convierte en una credencial válida solo por parecer una clave API. Los permisos, la caducidad, la revocación y la verificación de las solicitudes corresponden al sistema receptor. La metodología de generación de claves API de ClockTools explica la fuente de aleatoriedad del navegador, el muestreo por rechazo, las longitudes probadas y las limitaciones; el generador de GUID está disponible para crear identificadores que no son secretos compartidos.