HMAC Doğrulaması

HMAC doğrulaması, FastOG'un abonelik tabanlı her OG görseli isteğinin kendi sunucunuzdan geldiğini doğrulama yöntemidir — imzalı URL'ler kredilerinizi güvende tutar. Kaydolun, ardından bir Dynamic API planı seçin ve panelde API anahtarınızı ile HMAC sırrınızı oluşturun; ücretli API işlemleri temizdir. Bu sayfa, dinamik Open Graph görsellerinin arkasındaki sunucu tarafı kurallarını, kanonik sorgu imzalamadan sabit zamanlı karşılaştırmaya kadar kapsar.

Genel Bakış

/api/v1/og uç noktasına, API kotasının yetkisiz kullanımını önlemek amacıyla HMAC-SHA256 imza doğrulaması eklenmiştir. Bu, yalnızca meşru web sitesinden gelen isteklerin OG görselleri oluşturabilmesini sağlar.

Mimari

İki katmanlı kimlik doğrulama:

1. HMAC İmzası (ilk) - İsteğin güvenilir bir kaynaktan (web sitesi) geldiğini doğrular
2. API Anahtarı (ikinci) - İşleme kotası muhasebesi için kullanıcı hesabını tanımlar

Tek ara katman (ApiKeyAuth): imzayı (sorgu parametreleri) doğrular ve API anahtarını işleme kotası muhasebesi için tek geçişte çözer — geçersiz imzalarda hızlı başarısız olur.

Başlıklar değil, sorgu parametreleri: OG görselleri özel başlıklar göndermeyen sosyal ağ tarayıcıları (LinkedIn, Twitter, Facebook) tarafından getirildiğinden, imza URL sorgu parametrelerinde iletilir:

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

Uygulama

Oluşturulan/Değiştirilen Dosyalar

• app/Http/Middleware/HmacSignature.php - HMAC imzalarını doğrulayan yeni ara katman (sorgu parametreleri)
• routes/api.php - OG rotasına HMAC ara katmanı eklendi
• bootstrap/app.php - hmac ara katman takma adı kaydedildi
• app/Models/ApiKey.php - hmac_secret alanı eklendi (kullanıcı başına gizli anahtarlar)
• app/Http/Controllers/DashboardController.php - API anahtarı oluşturulurken HMAC gizli anahtarı üretir
• database/migrations/2026_08_03_214931_add_hmac_secret_to_api_keys_table.php - hmac_secret sütunu için geçiş (migration)
• resources/js/Pages/Dashboard/ApiKeys.svelte - HMAC gizli anahtarını kullanıcıya gösterir (yalnızca bir kez)
• docs/hmac-signature-guide.md - İstemci uygulama kılavuzu
• tests/Feature/HmacSignatureTest.php - 8 geçen test

İmza Algoritması

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, kurallı sorgunun bir parçasıdır; bu nedenle imza, API anahtarına bağlıdır. Herhangi bir parametreyi (başlık, şablon, görsel vb.) veya anahtarın kendisini değiştirmek, kurallı sorguyu değiştirir → imza uyuşmazlığı → 401 → işleme alınmaz, kota sayılmaz. Aynı parametreler → aynı imza → aynı URL → uçta süresiz olarak önbelleğe alınır, kota sayılmadan tekrar oynatılır.

Güvenlik Özellikleri

• İçerik adresli imza - Herhangi bir parametre değişikliği → 401 → işleme alınmaz, kota sayılmaz (URL'nin kendisi kanıttır)
• Zaman damgası yok - URL'ler herkese açık HTML'e gömülür ve süresiz önbelleğe alınır; 5 dakikadan uzun yaşamaları gerekir
• Sabit zamanlı karşılaştırma (hash_equals()) - Zamanlama saldırılarını önler
• Mesajda API anahtarı - İmza anahtara bağlıdır; anahtar değiştirilirse doğrulama başarısız olur
• Yola özgü - İmza yalnızca tam yol için geçerlidir
• Yönteme özgü - GET imzası POST için çalışmaz
• Kullanıcı başına gizli anahtarlar - Her API anahtarının kendi HMAC gizli anahtarı vardır ve bağımsız olarak iptal edilebilir (döndürme = sızdırılan URL'ler için kapatma anahtarı)

Yapılandırma

Gizli Anahtar Üretimi (Otomatik)

HMAC gizli anahtarı, panelde bir API anahtarı oluşturulduğunda otomatik olarak üretilir. API anahtarıyla birlikte yalnızca bir kez gösterilir ve bir daha asla görüntülenmez.

Manuel üretim (gerekirse):

openssl rand -hex 32

Veritabanı Şeması

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

Ortam Değişkenleri

Global bir ortam değişkenine gerek yoktur - gizli anahtarlar api_keys tablosunda kullanıcı başına saklanır.

Kullanım Örneği (Web Sitesi Arka Ucu)

// 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}" />

Hata Yanıtları

Test Etme

Testleri çalıştırın:

php artisan test --filter HmacSignatureTest

8 testin tamamı geçer:

• ✅ İmza olmadan yapılan istek reddedilir
• ✅ Eksik anahtar parametresi içeren istek reddedilir
• ✅ Değiştirilmiş içerik parametresi (başlık değiştirilmiş) reddedilir
• ✅ Eklenen parametre reddedilir
• ✅ Geçersiz imza reddedilir
• ✅ Geçerli imza HMAC kontrolünden geçer
• ✅ İmza yola özgüdür
• ✅ İmza yönteme özgüdür
• ✅ Farklı API anahtarlarının farklı sırları vardır

Performans Etkisi

• Önemsiz - HMAC-SHA256 hesaplaması istek başına ~0,1 ms sürer
• Ek ağ çağrısı yok - Doğrulama yerel olarak yapılır
• Hızlı başarısız olur - Geçersiz imzalar, API anahtarı aramasından önce reddedilir

Güvenlik Hususları

1. Gizli anahtarı asla istemci tarafı kodda açığa çıkarmayın - Yalnızca sunucuda imzalayın
2. HTTPS kullanın - HMAC yetkisiz isteklere karşı korur, HTTPS MITM saldırılarına karşı korur
3. Gizli anahtarları periyodik olarak değiştirin - Özellikle tehlikeye girerse (API anahtarının yeniden oluşturulmasını gerektirir)
4. Başarısız imzaları izleyin - Tekrarlanan başarısızlıklar saldırı girişimlerine işaret edebilir
5. Kullanıcı başına izolasyon - Her API anahtarının kendi HMAC gizli anahtarı vardır, birinin tehlikeye girmesi diğerlerini etkilemez

Referanslar

• İstemciler için HMAC İmza Kılavuzu
• Hızlı Başlangıç Kılavuzu
• OWASP: Kriptografik Depolama Hile Sayfası
• PHP: hash_hmac()

Tam API Referansı

• OG Görsel API Referansı
• HMAC Kimlik Doğrulama ve Güvenlik

İlgili

• Dokümantasyon
• Ücretsiz OG Görsel Test Aracı
• HMAC İmza Kılavuzu
• OG Görsel API Referansı
• PHP ve Laravel'de OG Görselleri
• Python'da OG Görselleri