# hash.dkh: hashes, tokens aleatorios y JWT `hash.dkh` calcula huellas (SHA-256, SHA-512, MD5) de textos y archivos, genera tokens aleatorios seguros, compara secretos sin filtrar información por el tiempo de respuesta, y crea y valida **JSON Web Tokens** (JWT) firmados con HS256 (secreto compartido) o RS256 (llave privada y pública, como los de Google y Microsoft). Viene con la distribución de Devkron 2.0 (`Devkron.Ext.Base.dll`). Complementa `md5`, `md5e` y `hmacsha256` de `functions.dkh`, que siguen igual. ## Cuándo usarla - Saber si un archivo cambió o detectar duplicados, por ejemplo XML de CFDI que se cargan dos veces. - Llaves de API y enlaces de un solo uso (recuperar contraseña, confirmar correo). - Sesiones sin estado para una API: su servicio entrega un JWT al iniciar sesión y lo valida en cada petición. - Aceptar tokens de un proveedor de identidad (Google, Microsoft Entra ID, Auth0) validando su firma con las llaves públicas que publica. ```dkl #include "hash.dkh" ``` ## Hashes y tokens | Función | Devuelve | Descripción | |---|---|---| | `hash.sha256(texto)` / `hash.sha512(texto)` | cadena | Hash del texto (UTF-8) en hexadecimal minúsculas | | `hash.sha256_file(archivo)` / `hash.md5_file(archivo)` | cadena | Hash del archivo; lo lee por bloques, sirve con archivos grandes | | `hash.hmac_sha256(texto, llave)` | cadena | HMAC-SHA256, igual que `hmacsha256` de `functions.dkh` | | `hash.random_token(n)` | cadena | `n` caracteres aleatorios seguros y aptos para URL (`A-Z a-z 0-9 - _`), de 1 a 4096 | | `hash.equals(a, b)` | lógico | Compara dos cadenas en tiempo constante: úsela para firmas, tokens y contraseñas | | `hash.b64url(texto)` / `hash.from_b64url(texto)` | cadena | Base64url sin relleno (UTF-8) | | `hash.pkce_challenge(verificador)` | cadena | `code_challenge` S256 de PKCE (lo usa [oauth.dkh](/es/devkron/2.0/bibliotecas/estandar/oauth.md)) | - MD5 sirve para comparar archivos, **no para seguridad**. Use SHA-256. - Con `hash.random_token(32)` o más tiene una llave de API adecuada. Guarde en la base el `hash.sha256` del token, no el token. - No compare secretos con `==`: la comparación normal termina antes cuando las cadenas difieren al inicio, y eso se puede medir. Use `hash.equals`. ## JWT | Función | Devuelve | Descripción | |---|---|---| | `jwt.encode(registro, secreto, segundos)` | cadena | Token HS256 con los datos del registro, `iat` y, si `segundos` > 0, `exp`. No modifica el registro | | `jwt.decode(token, secreto)` | registro | Los datos del token; **error** si la firma no coincide, caducó (`exp`), aún no es válido (`nbf`) o el algoritmo no es HS256 | | `jwt.read(token)` | registro | `{header, payload}` **sin verificar**: solo para ver `kid` o `iss` antes de validar, nunca para confiar en los datos | | `jwt.encode_rs256(registro, llave_pem, segundos)` | cadena | Token RS256 firmado con su llave privada PEM (PKCS#1 o PKCS#8) | | `jwt.encode_rs256_kid(registro, llave_pem, segundos, kid)` | cadena | Igual, con `kid` en el encabezado (para publicar varias llaves en un JWKS) | | `jwt.verify_rs256(token, jwks_url, emisores, audiencia)` | registro | Valida un token RS256 con la llave del JWKS que indica su `kid`; devuelve los datos | | `jwt.verify_rs256_pem(token, llave_publica_pem, emisores, audiencia)` | registro | Igual, con la llave pública PEM en lugar de un JWKS | | `jwt.clear_jwks()` | — | Vacía el caché de llaves descargadas | ### Parámetros - `registro`: los datos (*claims*) del token: `sub` (identificador del usuario), `email`, `rol`… No ponga datos sensibles: cualquiera puede leer el contenido de un JWT sin la llave. - `secreto`: cadena larga y aleatoria que solo conoce su servidor. Genérela una vez con `hash.random_token(48)` y guárdela fuera del código. - `jwks_url`: URL de las llaves públicas del proveedor. Google: `https://www.googleapis.com/oauth2/v3/certs`; Microsoft: `https://login.microsoftonline.com/common/discovery/v2.0/keys`. - `emisores`: valores aceptados de `iss`, como lista o como cadena separada por comas; `""` acepta cualquiera. Google usa `https://accounts.google.com` y `accounts.google.com`. - `audiencia`: valor esperado de `aud` (para Google, el *client ID* de su aplicación); `""` acepta cualquiera. ### Qué se valida - Las dos variantes revisan la firma, que el token no haya caducado (`exp`) y que no se use antes de tiempo (`nbf`), con 60 segundos de tolerancia para diferencias de reloj entre servidores. - `jwt.decode` solo acepta HS256 y rechaza `none`. - `jwt.verify_rs256` y `jwt.verify_rs256_pem` solo aceptan RS256 y además revisan `iss` y `aud`. ### Dónde vive el caché de llaves `jwt.verify_rs256` descarga el JWKS la primera vez y lo guarda **en la memoria del proceso** durante 6 horas. Las validaciones siguientes no salen a la red. Si llega un token con un `kid` que no está en el caché (el proveedor cambió sus llaves), vuelve a descargarlo. - En el **servidor FastCGI** el caché se comparte entre todas las peticiones y todos los sitios de ese proceso: solo la primera validación paga la descarga. - En **consola**, cada ejecución de `dkl` empieza sin caché. - Con **varios procesos** FastCGI, cada uno descarga el JWKS una vez. - El servidor necesita salida HTTPS hacia el proveedor; revise el firewall y el proxy. Si la descarga falla: `jwt.verify_rs256: no se pudieron descargar las llaves de …`. ## Ejemplo: hashes y sesión de una API con HS256 Con un archivo `f.txt` que contiene `hola` y un salto de línea: ```dkl #include "dkli.dkh" #! program "hash y jwt" { #include "functions.dkh" #include "serialize.dkh" #include "text.dkh" #include "hash.dkh" do print(hash.sha256("hola")) do print(hash.sha256_file("f.txt") + " md5: " + hash.md5_file("f.txt")) llave = hash.random_token(32) do print("Llave de API: " + str(length(llave)) + " caracteres guardar en la base: " + text.truncate(hash.sha256(llave), 16)) do print(str(hash.equals("abc", "abc")) + " " + str(hash.equals("abc", "abd")) + " b64url: " + hash.b64url("Niño?") + " -> " + hash.from_b64url(hash.b64url("Niño?"))) secreto = "MiSecretoDeEjemplo_cambie-esto-por-uno-aleatorio" new datos { @"sub": "usuario-15" @"rol": "ventas" } token = jwt.encode(datos, secreto, 3600) ref d = jwt.decode(token, secreto) do print("Usuario: " + field.str(d, "sub") + " rol: " + field.str(d, "rol") + " vigencia: " + str(field.num(d, "exp") - field.num(d, "iat")) + " s") ref r = jwt.read(token) do print("Encabezado: " + to.json(@@(r, "&header"))) prueba::t, s { ref x = jwt.decode(t, s) do print("válido") return 0 exception { do print("rechazado: " + last_error()) } } do prueba(token, "otro-secreto") do prueba(jwt.encode(datos, secreto, 1), secreto) } ``` Salida (la llave es aleatoria y su hash cambia en cada ejecución): ``` b221d9dbb083a7f33428d7c2a3c3198ae925614d70210e28716ccaa7cd4ddb79 133ee989293f92736301280c6f14c89d521200c17dcdcecca30cd20705332d44 md5: 916f4c31aaa35d6b867dae9a7f54270d Llave de API: 32 caracteres guardar en la base: 3af827b54e580e4… 1 0 b64url: TmnDsW8_ -> Niño? Usuario: usuario-15 rol: ventas vigencia: 3600 s Encabezado: {"alg":"HS256","typ":"JWT"} rechazado: {1} Error en 'jwt.decode. (jwt.decode: la firma no coincideException has been thrown by the target of an invocation.) [hash.dkl][Ln= 27] válido ``` El último token tenía 1 segundo de vigencia y aún pasa por la tolerancia de 60 segundos. En un servicio, el token llega en `Authorization: Bearer …`. Léalo con `httpreq.bearer()` de [http.dkh](/es/devkron/2.0/bibliotecas/estandar/http.md) y responda 401 si `jwt.decode` falla. ## Ejemplo: firmar y validar con RS256 y JWKS El ejemplo hace los dos papeles: firma como lo haría el proveedor de identidad y valida como su aplicación. Las llaves se generaron con OpenSSL (vea abajo) y el JWKS con la llave pública se sirvió en `http://127.0.0.1:8766/certs`: ```dkl #include "dkli.dkh" #! program "rs256" { #include "functions.dkh" #include "serialize.dkh" #include "hash.dkh" // Lado del proveedor: firma con su llave privada e indica el kid de la llave new datos { @"iss": "https://idp.ejemplo.com" @"aud": "mi-aplicacion" @"sub": "10293847" @"email": "ana@ejemplo.com" } token = jwt.encode_rs256_kid(datos, file.rtext("llaves/privada.pem"), 600, "llave-2026") do print("kid: " + field.str(@@(jwt.read(token), "&header"), "kid")) // Lado de su aplicación: valida con las llaves públicas que publica el proveedor (JWKS) jwks = "http://127.0.0.1:8766/certs" ref u = jwt.verify_rs256(token, jwks, "https://idp.ejemplo.com", "mi-aplicacion") do print("JWKS: " + field.str(u, "email")) ref u2 = jwt.verify_rs256(token, jwks, "https://idp.ejemplo.com", "mi-aplicacion") do print("segunda validación, sin descargar: " + field.str(u2, "sub")) // Con la llave pública PEM, sin JWKS ref u3 = jwt.verify_rs256_pem(token, file.rtext("llaves/publica.pem"), "https://idp.ejemplo.com", "") do print("PEM: " + field.str(u3, "sub")) prueba::t, aud { ref x = jwt.verify_rs256(t, "http://127.0.0.1:8766/certs", "https://idp.ejemplo.com", aud) return 0 exception { do print("rechazado: " + last_error()) } } do prueba(token, "otra-aplicacion") do prueba(jwt.encode(datos, "secreto", 60), "mi-aplicacion") } ``` Salida: ``` kid: llave-2026 JWKS: ana@ejemplo.com segunda validación, sin descargar: 10293847 PEM: 10293847 rechazado: {1} Error en 'jwt.verify_rs256. (jwt.verify_rs256: la audiencia no coincideException has been thrown by the target of an invocation.) [rs.dkl][Ln= 29] rechazado: {1} Error en 'jwt.verify_rs256. (jwt.verify_rs256: algoritmo no admitido 'HS256' (se espera RS256)Exception has been thrown by the target of an invocation.) [rs.dkl][Ln= 29] ``` Genere el par de llaves con: ```bash openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:2048 -out privada.pem openssl rsa -in privada.pem -pubout -out publica.pem ``` ## Ejemplo: validar un token de Google Cuando un usuario inicia sesión con Google en su página (Google Identity Services), el navegador recibe un *ID token* y se lo envía a su servidor en el campo `credential`. El servidor debe validarlo antes de confiar en el correo que trae: ```dkl #include "dkli.dkh" #! program "login google" { #include "functions.dkh" #include "serialize.dkh" #include "http.dkh" #include "hash.dkh" client_id = "1234567890-ejemplo.apps.googleusercontent.com" credencial = httpreq.arg("credential") ref u = jwt.verify_rs256(credencial, "https://www.googleapis.com/oauth2/v3/certs", "https://accounts.google.com,accounts.google.com", client_id) if field.dstr(u, "email_verified", "") != "true" && field.dnum(u, "email_verified", 0) != 1 { do httpres.status(403) do httpres.fail("Correo no verificado") return } // u.sub es el identificador permanente del usuario en Google; también trae email, name y picture do httpres.ok(u) exception { do httpres.status(401) do httpres.fail("Token de Google no válido") } } ``` Este ejemplo necesita el servidor FastCGI y un token real de Google, así que no se ejecutó aquí. La validación misma es la del ejemplo anterior. ## Errores | Mensaje | Causa | |---|---| | `jwt.decode: la firma no coincide` | Otro secreto, o el token fue alterado | | `jwt.decode: el token caducó` | Pasó `exp` (más 60 s de tolerancia) | | `jwt.decode: el token todavía no es válido (nbf)` | Antes de `nbf` | | `jwt.decode: algoritmo no admitido '…' (se espera HS256)` | Token RS256 o `none` | | `jwt.decode: el token no tiene el formato encabezado.datos.firma` / `… está mal formado` / `… está vacío` | No es un JWT | | `jwt.encode: el secreto está vacío` | Secreto vacío | | `jwt.encode_rs256: llave PEM inválida (…)` | La llave no es RSA privada en PEM | | `jwt.verify_rs256: no hay llave para el kid '…'` | El JWKS no tiene esa llave (ni después de volver a descargarlo) | | `jwt.verify_rs256: emisor no aceptado '…'` / `… la audiencia no coincide` | `iss` o `aud` distintos de los esperados | | `jwt.verify_rs256: no se pudieron descargar las llaves de …` / `… el JWKS no tiene la lista 'keys'` | Problema de red o URL que no es un JWKS | | `hash.random_token: la longitud debe estar entre 1 y 4096` | `n` fuera de rango | | `hash.sha256_file: no existe el archivo '…'` | También en `hash.md5_file` | ## Advertencias - **Nunca use `jwt.read` para decidir permisos**: no verifica la firma. - **El secreto HS256 y la llave privada no van en el código** ni en el repositorio: léalos de un archivo protegido o de una variable de entorno. - Un JWT no se puede revocar antes de que caduque. Use vigencias cortas (minutos u horas) y, si necesita cerrar sesiones, guarde una lista de tokens revocados. - El reloj del servidor debe estar sincronizado (NTP). Con un desfase de más de un minuto, tokens válidos parecen caducados o futuros.