Autenticación y firmas criptográficas

Seguridad mediante firmas HMAC-SHA256, marcas de tiempo y prevención de ataques de reproducción.

Para garantizar la máxima seguridad en entornos de producción, SmallPict utiliza un esquema de firma criptográfica HMAC-SHA256 en cada solicitud mutativa. Esto impide la manipulación de datos en tránsito y neutraliza ataques de reproducción (Replay Attacks).

Cabeceras HTTP obligatorias

Cabecera	Tipo	Descripción
`X-API-Key`	String	Tu clave pública de API (`sp_live_...` o `sp_test_...`).
`X-Timestamp`	Integer	Marca de tiempo Unix en segundos UTC (ejemplo: `1716301234`).
`X-Signature`	String	Firma calculada con algoritmo HMAC-SHA256 en formato hexadecimal.

Algoritmo de generación de la firma

La firma se calcula aplicando HMAC-SHA256 utilizando tu Secret Key como clave criptográfica sobre la siguiente cadena canónica:

TEXT

CANONICAL_STRING = HTTP_METHOD + "\n" + REQUEST_PATH + "\n" + TIMESTAMP + "\n" + SHA256_HEX(REQUEST_BODY)

Importante: La marca de tiempo enviada en X-Timestamp debe encontrarse dentro de una ventana de tolerancia de ±300 segundos (5 minutos) respecto a la hora oficial de los servidores de SmallPict. Cualquier solicitud fuera de este margen será rechazada con error 401 Unauthorized.

Ejemplos de implementación en código

Node.js / TypeScript

TypeScript

import crypto from "crypto";
function generateSignature(method: string, path: string, timestamp: number, body: string, secretKey: string): string {  const bodyHash = crypto.createHash("sha256").update(body).digest("hex");  const canonical = `${method.toUpperCase()}\n${path}\n${timestamp}\n${bodyHash}`;  return crypto.createHmac("sha256", secretKey).update(canonical).digest("hex");}

Python

import hmac, hashlib
def generate_signature(method: str, path: str, timestamp: int, body: bytes, secret_key: str) -> str:    body_hash = hashlib.sha256(body).hexdigest()    canonical = f"{method.upper()}\n{path}\n{timestamp}\n{body_hash}"    return hmac.new(secret_key.encode('utf-8'), canonical.encode('utf-8'), hashlib.sha256).hexdigest()

Golang

package main
import (    "crypto/hmac"    "crypto/sha256"    "encoding/hex"    "fmt"    "strings")
func GenerateSignature(method, path string, timestamp int64, body []byte, secretKey string) string {    bodyHash := sha256.Sum256(body)    canonical := fmt.Sprintf("%s\n%s\n%d\n%s", strings.ToUpper(method), path, timestamp, hex.EncodeToString(bodyHash[:]))    mac := hmac.New(sha256.New, []byte(secretKey))    mac.Write([]byte(canonical))    return hex.EncodeToString(mac.Sum(nil))}