HMAC-todennus ja tietoturva

Suojaa HMAC-allekirjoitetut OG-kuva-URL:t FastOG:n HMAC-SHA256-todennuksella. Tämä opas kattaa jokaisen pyynnön allekirjoittamisen, validoinnin ja vianmäärityksen, jotta voit julkaista dynaamisia Open Graph -kuvia lennossa — tilauspohjaisesti, rajoittamattomilla renderöinneillä (ei kuukausittaista renderöintikiintiötä eikä ylityslaskutusta). Rekisteröidy, valitse Dynamic API -paketti ja luo API-avaimesi sekä HMAC-salaisuutesi hallintapaneelissa (maksulliset API-renderöinnit ovat puhtaita). Allekirjoita palvelimellasi kerran ja integroi minuuteissa.

🚀 Pika-aloitus

Uusi HMAC-allekirjoituksen parissa? Aloita tästä:

1. Pika-aloitusopas — Pääset alkuun 5 minuutissa
2. JavaScript-ohjelmointiopas — Kattava opas Node.js/Next.js-kehittäjille
3. Kaikki framework-oppaat — valitse pinosi:
   • Next.js App Router
   • Next.js Pages Router
   • React
   • SvelteKit
   • Vue/Nuxt
   • Astro
   • Express
   • Vanilla Node.js
   • JavaScript
   • PHP/Laravel
   • Python
   • Ruby/Rails

📚 Dokumentaatiohakemisto

Keskeiset käsitteet

• HMAC-allekirjoitusopas — Täydellinen viite algoritmin yksityiskohdista, vaatimuksista ja esimerkeistä JavaScriptillä, PHP:llä ja Pythonilla
• HMAC-validointi — Palvelinpuolen toteutuksen yksityiskohdat, tietoturvaominaisuudet ja virhevastaukset

Opetusohjelmat

• JavaScript/Node.js-opetusohjelma — Kattava opas, joka kattaa:

  • Pika-aloituksen (5 minuuttia)
  • Next.js App Routerin (3 mallia)
  • Next.js Pages Routerin
  • Express.js-taustapalvelimen
  • Vanhan kunnon Node.js:n
  • Frontend-integraatiomallit (SSG, SSR, selainpuoli)
  • Testauksen ja virheenjäljityksen
  • Yleiset sudenkuopat

• Next.js App Router

• Next.js Pages Router

• React

• SvelteKit

• Vue/Nuxt

• Astro

• Express

• Vanilla Node.js

• PHP/Laravel

• Python

• Ruby/Rails

Pikaviite

Algoritmi

method = "GET"
path = "/api/v1/og"
canonicalQuery = every query param EXCEPT `s` (including `key`): array values sorted too; each pair rfc3986Encode(key)=rfc3986Encode(value); pairs sorted lexicographically and joined with "&"

message = method + path + "\n" + canonicalQuery
signature = hex(HMAC-SHA256(message, hmac_secret))

URL: /api/v1/og?title=Hello&key=sk_quick_123abc&s=<signature>

Kyselyparametrit

Virhekoodit

🎯 Käyttötapaukset

Blogikirjoitukset

Luo dynaamisia OG-kuvia blogikirjoituksille:

const ogUrl = generateSignedOgUrl({
    template: "blog",
    title: post.title,
    subtitle: post.excerpt,
    author: post.author.name,
});

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

Verkkokaupan tuotteet

Luo OG-kuvia tuotesivuille:

const ogUrl = generateSignedOgUrl({
    template: "ecommerce",
    title: product.name,
    price: product.price,
    image: product.image,
});

Asiakaspalautteet

Luo OG-kuvia asiakaspalautelainauksille:

const ogUrl = generateSignedOgUrl({
    template: "testimonial",
    author_name: user.name,
    author_avatar: user.avatarUrl,
    quote: user.bio,
});

🔐 Turvallisuus

Parhaat käytännöt

1. Säilytä salaisuudet turvallisesti — Käytä ympäristömuuttujia tai salaisuuksien hallintaa
2. Älä koskaan paljasta HMAC-salaista asiakaspuolen koodissa — Allekirjoita vain palvelimella
3. Käytä HTTPS:ää — Estää MITM-hyökkäykset
4. Vaihda salaisuudet säännöllisesti — Erityisesti jos ne ovat vaarantuneet
5. Seuraa epäonnistuneita allekirjoituksia — Toistuvat epäonnistumiset voivat viitata hyökkäyksiin
6. Käyttäjäkohtainen eristys — Jokaisella API-avaimella on oma HMAC-salaisuus

HMAC-salaisuuden hankkiminen

1. Mene kohtaan Dashboard → API-avaimet
2. Luo uusi API-avain
3. Kopioi HMAC-salaisuus (näytetään vain kerran!)
4. Tallenna ympäristömuuttujiin

# .env
FASTOG_HMAC_SECRET=<your-64-char-hex-secret>

🧪 Testaus

Testi-URL:n luominen

# Node.js
node -e "
const crypto = require('crypto');
const enc = (s) => encodeURIComponent(s).replace(/[!'()*]/g, (c) => '%' + c.charCodeAt(0).toString(16).toUpperCase());
const all = { title: 'Test', key: 'sk_quick_123abc' };
const pairs = [];
for (const [k, v] of Object.entries(all)) for (const vv of Array.isArray(v) ? v : [v]) pairs.push(enc(k) + '=' + enc(vv));
pairs.sort();
const canonical = pairs.join('&');
const sig = crypto.createHmac('sha256', 'YOUR_HMAC_SECRET').update('GET/api/v1/og\n' + canonical).digest('hex');
console.log('https://fastog.com/api/v1/og?title=Test&key=sk_quick_123abc&s=' + sig);
"

Testaus curlilla

curl "https://fastog.com/api/v1/og?title=Test&key=sk_quick_123abc&s=<signature>"

Odotetut vastaukset

• ✅ Kelvollinen allekirjoitus → Palauttaa OG-kuvan (tai 422, jos malliparametrit ovat virheellisiä)
• ❌ Virheellinen allekirjoitus → {"code": "invalid_signature"}
• ❌ Puuttuvat parametrit → {"code": "missing_signature"}

🛠 Vianmääritys

Allekirjoitus ei täsmää

1. Varmista, että käytät oikeaa HMAC-salausta (tarkista API-avain hallintapaneelista)
2. Tarkista kanoninen kysely: kaikki kyselyparametrit paitsi s (mukaan lukien key), arvot rfc3986-koodattuina, avaimet lajiteltu leksikografisesti
3. Varmista, että allekirjoitus on pienaakkosina heksadesimaalimuodossa (64 merkkiä)

📖 Lisäresurssit

• API-viite — Täydellinen API-dokumentaatio
• Turvallisuuden parhaat käytännöt — Yksityiskohtainen turvallisuusopas
• Tietopohja — Tekniset toteutustiedot

❓ UKK

K: Miksi kyselyparametrit eikä otsakkeet?
V: OG-kuvat hakevat sosiaalisen median indeksointirobotit (LinkedIn, Twitter, Facebook), jotka eivät lähetä mukautettuja otsakkeita. Allekirjoituksen TÄYTYY olla URL-osoitteessa.

K: Voinko käyttää samaa allekirjoitusta useisiin pyyntöihin?
V: Kyllä. Allekirjoitus lasketaan tarkasta kyselystä (ilman s), joten sama allekirjoitettu URL pysyy voimassa niin kauan kuin parametrit eivät muutu. Jos muutat mitä tahansa parametria (mukaan lukien key), sinun on allekirjoitettava uudelleen.

K: Täytyykö minun allekirjoittaa pyynnöt kaikille mallipohjille?
V: Kyllä. Kaikki pyynnöt /api/v1/og-osoitteeseen edellyttävät HMAC-allekirjoituksia.

K: Mitä tapahtuu, jos HMAC-salaisuuteni vaarantuu?
V: Peruuta API-avain hallintapaneelissa (dashboard) ja luo uusi. Jokaisella API-avaimella on oma HMAC-salaisuutensa.

K: Voinko poistaa HMAC-validoinnin käytöstä sisäisissä palveluissa?
V: Ota yhteyttä tukeen räätälöityjä ratkaisuja varten. HMAC-validointi on pakollinen kaikissa julkisissa API-päätepisteissä.

🆘 Tuki

Tarvitsetko apua?

• Katso JavaScript-opetusohjelma täydellisiä koodiesimerkkejä varten
• Tutustu HMAC-allekirjoitusoppaaseen algoritmin yksityiskohtiin
• Ota yhteyttä tukeen osoitteessa [email protected]

Aiheeseen liittyvää

• Dokumentaatio — Kaikki FastOG-oppaat ja viitteet
• Ilmainen OG-kuvan testaaja — Esikatsele ilman tiliä
• Pika-aloitusopas — Pääset alkuun 5 minuutissa
• HMAC-allekirjoitusopas — Algoritmin yksityiskohdat
• HMAC-vahvistus — Palvelinpuolen vahvistus