HMAC-ellenőrzés

Az HMAC-ellenőrzés az a mechanizmus, amellyel a FastOG igazolja, hogy minden előfizetés-alapú OG-képkérés az Ön saját szerveréről érkezett — az aláírt URL-ek biztosítják, hogy a kreditek biztonságban maradjanak. Regisztráljon, majd válasszon Dynamic API-csomagot, és hozza létre az API-kulcsát és HMAC-titkát az irányítópulton; a fizetős API-megjelenítések tiszták. Ez az oldal a dinamikus Open Graph-képek mögötti szerveroldali szabályokat ismerteti, a kanonikus lekérdezés-aláírástól az állandó idejű összehasonlításig.

Áttekintés

A /api/v1/og végponthoz HMAC-SHA256 aláírás-ellenőrzés került hozzáadásra, hogy megakadályozza az API-kvóta jogosulatlan használatát. Ez biztosítja, hogy csak a legitim weboldalról érkező kérések generálhassanak OG-képeket.

Architektúra

Kétrétegű hitelesítés:

1. HMAC-aláírás (első) – Ellenőrzi, hogy a kérés megbízható forrásból (a weboldalról) érkezett-e
2. API-kulcs (második) – Azonosítja a felhasználói fiókot a renderelési kvóta elszámolásához

Egyetlen middleware (ApiKeyAuth): egy menetben ellenőrzi az aláírást (lekérdezési paraméterek) és feloldja az API-kulcsot a renderelési kvóta elszámolásához – hibás aláírás esetén azonnali elutasítás.

Lekérdezési paraméterek, nem fejlécek: Mivel az OG-képeket közösségi hálózati robotok (LinkedIn, Twitter, Facebook) töltik le, amelyek nem küldenek egyéni fejléceket, az aláírás az URL lekérdezési paramétereiben kerül átadásra:

GET /api/v1/og?title=Hello&key=sk_quick_123abc&s=<hmac>

Megvalósítás

Létrehozott/módosított fájlok

• app/Http/Middleware/HmacSignature.php – Új middleware, amely a HMAC-aláírásokat ellenőrzi (lekérdezési paraméterek)
• routes/api.php – HMAC middleware hozzáadva az OG-útvonalhoz
• bootstrap/app.php – hmac middleware-álcás regisztrálva
• app/Models/ApiKey.php – hmac_secret mező hozzáadva (felhasználónkénti titkok)
• app/Http/Controllers/DashboardController.php – HMAC-titok generálása API-kulcs létrehozásakor
• database/migrations/2026_08_03_214931_add_hmac_secret_to_api_keys_table.php – Migráció a hmac_secret oszlophoz
• resources/js/Pages/Dashboard/ApiKeys.svelte – A HMAC-titok megjelenítése a felhasználónak (egyszer)
• docs/hmac-signature-guide.md – Kliensoldali megvalósítási útmutató
• tests/Feature/HmacSignatureTest.php – 8 sikeres teszt

Aláírási algoritmus

method = HTTP method (e.g., "GET")
path  = request path (e.g., "/api/v1/og")
query = the request's DECODED query params

canonical = every param except `s`, keys sorted (array values sorted too),
            each `key=value` RFC-3986 encoded (unreserved-only), joined with "&"
message   = method + "/" + path + "\n" + canonical
signature = HMAC-SHA256(message, hmac_secret)

Query parameters:
  key=<apiKey>
  s=<signature>
  (no timestamp)

key a kanonikus lekérdezés része, így az aláírás az API-kulcshoz van kötve. Bármely paraméter (cím, sablon, kép stb.) vagy magának a kulcsnak a módosítása megváltoztatja a kanonikus értéket → aláírás-eltérés → 401 → nincs renderelés, nincs kvótaszámítás. Azonos paraméterek → azonos aláírás → azonos URL → örökre gyorsítótárazható a peremhálózaton, visszajátszható kvótaszámítás nélkül.

Biztonsági funkciók

• Tartalom-címzett aláírás – Bármely paraméterváltozás → 401 → nincs renderelés, nincs kvótaszámítás (maga az URL a bizonyíték)
• Nincs időbélyeg – Az URL-ek nyilvános HTML-be ágyazva és örökre gyorsítótárazva vannak; túl kell élniük az 5 percet
• Konstans idejű összehasonlítás (hash_equals()) – Megakadályozza az időzítési támadásokat
• API-kulcs az üzenetben – Az aláírás a kulcshoz van kötve; a kulcsok cseréje hibát okoz
• Útvonalspecifikus – Az aláírás csak a pontos útvonalra érvényes
• Metódusspecifikus – A GET-aláírás nem működik POST esetén
• Felhasználónkénti titkok – Minden API-kulcsnak saját HMAC-titka van, amely egymástól függetlenül visszavonható (rotáció = vészleállító kapcsoló a kiszivárgott URL-ekhez)

Konfiguráció

Titkos kulcs generálása (automatikus)

Az HMAC-titkos kulcs automatikusan generálódik, amikor API-kulcsot hoz létre az irányítópulton (dashboard). Egyszer jelenik meg az API-kulcs mellett, ezután soha többé nem látható.

Manuális generálás (ha szükséges):

openssl rand -hex 32

Adatbázis séma

ALTER TABLE api_keys ADD COLUMN hmac_secret VARCHAR(64)
  COMMENT 'HMAC-SHA256 secret for signing OG image URLs (hex, 64 chars)';

Környezeti változók

Nincs szükség globális környezeti változóra – a titkos kulcsok felhasználónként vannak tárolva a api_keys táblában.

Használati példa (weboldal háttérrendszer)

// Node.js example - generate signed OG image URL
const crypto = require("crypto");

// RFC-3986 encode (encodeURIComponent leaves !'()* unencoded).
const enc = (s) =>
    encodeURIComponent(s).replace(
        /[!'()*]/g,
        (c) => "%" + c.charCodeAt(0).toString(16).toUpperCase(),
    );

function generateOgImageUrl(baseUrl, params, apiKey, hmacSecret) {
    const all = { ...params, key: apiKey };

    // Canonical: every param (except s), sorted, RFC-3986 encoded, joined with "&".
    const pairs = [];
    for (const [k, v] of Object.entries(all)) {
        for (const vv of Array.isArray(v) ? [...v].sort() : [v])
            pairs.push(`${enc(k)}=${enc(vv)}`);
    }
    pairs.sort();
    const canonical = pairs.join("&");

    const message = `GET/api/v1/og\n${canonical}`;
    const signature = crypto
        .createHmac("sha256", hmacSecret)
        .update(message)
        .digest("hex");

    const url = new URL(baseUrl);
    for (const [k, v] of Object.entries(all)) {
        const isArray = Array.isArray(v);
        for (const vv of isArray ? v : [v])
            url.searchParams.append(isArray ? `${k}[]` : k, vv);
    }
    url.searchParams.set("s", signature);
    return url.toString();
}

// Usage in meta tag
const ogUrl = generateOgImageUrl(
    "https://fastog.com/api/v1/og",
    { title: "Como criar um SaaS", template: "blog" },
    "sk_quick_123abc",
    process.env.HMAC_SECRET,
);

// <meta property="og:image" content="{ogUrl}" />

Hibaválaszok

Tesztelés

A tesztek futtatása:

php artisan test --filter HmacSignatureTest

Mind a 8 teszt sikeresen lefut:

• ✅ Az aláírás nélküli kérés elutasításra kerül
• ✅ A hiányzó kulcs paramétert tartalmazó kérés elutasításra kerül
• ✅ A módosított tartalom paraméter (megváltozott cím) elutasításra kerül
• ✅ A hozzáadott paraméter elutasításra kerül
• ✅ Az érvénytelen aláírás elutasításra kerül
• ✅ Az érvényes aláírás átmegy az HMAC-ellenőrzésen
• ✅ Az aláírás útvonalspecifikus
• ✅ Az aláírás metódusspecifikus
• ✅ A különböző API-kulcsokhoz különböző titkos kulcsok tartoznak

Teljesítményhatás

• Elhanyagolható – az HMAC-SHA256 számítás körülbelül 0,1 ms kérésenként
• Nincs további hálózati hívás – az ellenőrzés helyben történik
• Gyors hibaelutasítás – az érvénytelen aláírások elutasításra kerülnek az API-kulcs keresése előtt

Biztonsági szempontok

1. Soha ne tegye közzé a titkos kulcsot kliensoldali kódban – csak a szerveren írjon alá
2. Használjon HTTPS-t – az HMAC a jogosulatlan kérések ellen véd, a HTTPS pedig a MITM-támadások ellen
3. Forgassa a titkos kulcsokat rendszeresen – különösen, ha kompromittálódtak (ehhez új API-kulcs generálása szükséges)
4. Figyelje a sikertelen aláírásokat – az ismétlődő hibák támadásokra utalhatnak
5. Felhasználónkénti elkülönítés – minden API-kulcs saját HMAC-titokkal rendelkezik, így az egyik kompromittálódása nem érinti a többieket

Referenciák

• HMAC-aláírás útmutató ügyfeleknek
• Gyorsindítási útmutató
• OWASP: Kriptográfiai tárolási segédlet
• PHP: hash_hmac()

Teljes API-referencia

• OG-kép API-referencia
• HMAC-hitelesítés és biztonság

Kapcsolódó

• Dokumentáció
• Ingyenes OG-képtesztelő
• HMAC-aláírás útmutató
• OG-kép API referencia
• OG-képek PHP-ban és Laravelben
• OG-képek Pythonban