title: "تأیید توکن خرید" order: 7 description: "ساختار توکن JWS ES256، کلید عمومی هر برنامه و چرخش آن، تأیید روی دستگاه و نمونه کد تأیید در سرور"

تأیید توکن خرید

پس از هر پرداخت موفق، بله‌استور یک توکن خرید صادر می‌کند. این توکن یک JWS فشرده (compact) با الگوریتم ES256 است (ECDSA روی منحنی P-256 با SHA-256) که با کلید خصوصی بله‌استور (نگه‌داری‌شده در HSM) امضا شده است. هر برنامه کلید مخصوص خودش را دارد.

base64url(header) . base64url(claims) . base64url(signature)

ساختار

Header:

{ "alg": "ES256", "kid": "<per-app key id>" }

Claims:

{
  "orderId": "6f1c2a7e-3b0d-4b8e-9f51-2f7a0c9d1e44",
  "packageName": "com.example.game",
  "productId": "vip_monthly",
  "purchaseTime": 1763539200000,
  "purchaseState": "PURCHASED",
  "developerPayload": "order-42",
  "userHash": "9c1f0e…",
  "type": "subs",
  "expiryTime": 1766131200000
}
claim توضیح
orderId شناسهٔ یکتای سفارش؛ برای جلوگیری از استفادهٔ تکراری، یکتا نگهش دارید
packageName نام بستهٔ برنامهٔ شما؛ حتماً بررسی کنید
productId شناسهٔ محصول (برای type: "app"، خرید خود برنامهٔ پولی)
purchaseTime زمان خرید، میلی‌ثانیهٔ epoch
purchaseState وضعیت در لحظهٔ صدور توکن (معمولاً PURCHASED)
developerPayload payload شما هنگام خرید
userHash شناسهٔ مستعار و پایدار کاربر در برنامهٔ شما
type "inapp"، "subs" یا "app"
expiryTime فقط برای اشتراک: پایان دوره، میلی‌ثانیهٔ epoch (اختیاری)

توکن عکس لحظهٔ خرید است. اینکه خرید بعداً مصرف، تأیید یا بازپرداخت شده یا اشتراک تمدید یا لغو شده، در توکن تغییر نمی‌کند. برای وضعیت جاری از API سرور به سرور استفاده کنید.

کلید عمومی برنامه

کلید را از کنسول (پرداخت ← کلیدها) یا با API بگیرید:

curl -sS "$API/console/v1/billing/apps/$APP_ID/keys" -H "Authorization: Bearer $CONSOLE_TOKEN"
{
  "kid": "…",
  "publicKeyPem": "-----BEGIN PUBLIC KEY-----\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE…\n-----END PUBLIC KEY-----\n",
  "publicKeyBase64": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE…",
  "algorithm": "ES256"
}

publicKeyBase64 همان کلید (SubjectPublicKeyInfo با کدگذاری DER) بدون سرآیندهای PEM است. کلید عمومی محرمانه نیست.

چرخش کلید

با POST /console/v1/billing/apps/{appId}/keys:rotate کلید تازه‌ای با kid جدید ساخته می‌شود و توکن‌های بعدی با آن امضا می‌شوند. نکته‌ها:

  • در سرور، کلیدها را بر اساس kid نگه دارید (kid → publicKey) و کلید قبلی را حذف نکنید تا توکن‌های قدیمی‌تر همچنان قابل بررسی باشند. اگر kid ناشناخته دیدید، کلید جاری را دوباره از کنسول بخوانید.
  • نسخه‌های نصب‌شدهٔ برنامه که کلید قبلی را در SecurityCheck.Enable دارند، توکن‌های تازه را رد می‌کنند (PurchaseHijackedException). پس پیش از چرخش، نسخه‌ای منتشر کنید که هر دو کلید را بشناسد یا بررسی محلی را به سرور بسپارد. چرخش را فقط در صورت ضرورت انجام دهید.

تأیید روی دستگاه

SDK اندروید دو راه دارد (SDK اندروید):

// 1) automatic: every purchase is checked; failure → purchaseFailed(PurchaseHijackedException)
PaymentConfiguration(localSecurityCheck = SecurityCheck.Enable(publicKeyPem = PEM))

// 2) manual
val v = PurchaseTokenVerifier.verify(token, PEM) // throws PurchaseTokenVerificationException
check(v.packageName == BuildConfig.APPLICATION_ID)

تأیید روی دستگاه کافی نیست: روی گوشی روت‌شده می‌توان کد برنامه را تغییر داد و بررسی را دور زد. مرجع نهایی، سرور شماست.

تأیید در سرور

بهترین روش: توکن را از برنامه به سرور بفرستید و با API سرور به سرور وضعیت جاری را بخوانید (GET /s2s/v1/apps/{packageName}/purchases/{purchaseToken}). این تنها راهی است که بازپرداخت، مصرف و تأیید را هم می‌بیند.

بررسی امضا در سرور (بدون فراخوانی شبکه) برای این موارد مفید است: رد سریع توکن‌های جعلی پیش از فراخوانی S2S، یا ادامهٔ کار وقتی S2S موقتاً در دسترس نیست. مراحل:

  1. توکن را با . به سه بخش تقسیم کنید؛ دقیقاً سه بخش باشد.
  2. header را base64url-decode کنید؛ alg باید ES256 باشد (هر مقدار دیگر، از جمله none، رد شود) و kid در فهرست کلیدهای شما باشد.
  3. امضا را base64url-decode کنید. امضای JWS در ES256 به شکل خام R || S و دقیقاً ۶۴ بایت است، نه DER. بیشتر کتابخانه‌های پایهٔ رمزنگاری (Java SHA256withECDSA، Python cryptography) DER می‌خواهند؛ یا تبدیل کنید یا از حالت P1363/raw استفاده کنید.
  4. امضا را روی رشتهٔ ASCII header_b64 + "." + claims_b64 (همان بایت‌های دریافتی) بررسی کنید.
  5. claims را decode کنید و بررسی کنید: packageName برابر بستهٔ شما، productId همان محصول مورد انتظار، type درست، برای اشتراک expiryTime نگذشته باشد، و orderId قبلاً استفاده نشده باشد.

Kotlin / Java (JVM)

import com.fasterxml.jackson.databind.JsonNode
import com.fasterxml.jackson.databind.ObjectMapper
import java.io.ByteArrayOutputStream
import java.security.KeyFactory
import java.security.PublicKey
import java.security.Signature
import java.security.spec.X509EncodedKeySpec
import java.util.Base64

class PurchaseTokenException(message: String) : Exception(message)

object ServerPurchaseTokenVerifier {
    private val mapper = ObjectMapper()

    fun publicKeyFromPem(pem: String): PublicKey {
        val b64 = pem.replace("-----BEGIN PUBLIC KEY-----", "")
            .replace("-----END PUBLIC KEY-----", "")
            .replace(Regex("\\s"), "")
        return KeyFactory.getInstance("EC").generatePublic(X509EncodedKeySpec(Base64.getDecoder().decode(b64)))
    }

    /** keysByKid: kid → public key (keep old kids after rotation). Returns the verified claims. */
    fun verify(token: String, keysByKid: Map<String, PublicKey>, expectedPackage: String): JsonNode {
        val parts = token.split('.')
        if (parts.size != 3) throw PurchaseTokenException("malformed token")
        val dec = Base64.getUrlDecoder()
        val header = mapper.readTree(dec.decode(parts[0]))
        if (header.path("alg").asText() != "ES256") throw PurchaseTokenException("unexpected alg")
        val key = keysByKid[header.path("kid").asText()] ?: throw PurchaseTokenException("unknown kid")

        val rawSig = dec.decode(parts[2])
        if (rawSig.size != 64) throw PurchaseTokenException("bad signature length")
        val verifier = Signature.getInstance("SHA256withECDSA") // expects DER → convert R||S
        verifier.initVerify(key)
        verifier.update("${parts[0]}.${parts[1]}".toByteArray(Charsets.US_ASCII))
        if (!verifier.verify(rawToDer(rawSig))) throw PurchaseTokenException("bad signature")
        // (JDK 9+ alternative without conversion: Signature.getInstance("SHA256withECDSAinP1363Format"))

        val claims = mapper.readTree(dec.decode(parts[1]))
        if (claims.path("packageName").asText() != expectedPackage) throw PurchaseTokenException("wrong package")
        return claims
    }

    /** JWS raw signature (R||S, 32+32 bytes) → ASN.1 DER SEQUENCE { INTEGER r, INTEGER s }. */
    private fun rawToDer(raw: ByteArray): ByteArray {
        fun derInt(b: ByteArray): ByteArray {
            var i = 0
            while (i < b.size - 1 && b[i] == 0.toByte()) i++
            val v = b.copyOfRange(i, b.size)
            val body = if (v[0].toInt() and 0x80 != 0) byteArrayOf(0) + v else v
            return byteArrayOf(0x02, body.size.toByte()) + body
        }
        val r = derInt(raw.copyOfRange(0, 32))
        val s = derInt(raw.copyOfRange(32, 64))
        val out = ByteArrayOutputStream()
        out.write(0x30); out.write(r.size + s.size); out.write(r); out.write(s)
        return out.toByteArray()
    }
}

Go

package purchasetoken

import (
	"crypto/ecdsa"
	"crypto/sha256"
	"crypto/x509"
	"encoding/base64"
	"encoding/json"
	"encoding/pem"
	"errors"
	"math/big"
	"strings"
)

type Claims struct {
	OrderID          string `json:"orderId"`
	PackageName      string `json:"packageName"`
	ProductID        string `json:"productId"`
	PurchaseTime     int64  `json:"purchaseTime"`
	PurchaseState    string `json:"purchaseState"`
	DeveloperPayload string `json:"developerPayload"`
	UserHash         string `json:"userHash"`
	Type             string `json:"type"`
	ExpiryTime       *int64 `json:"expiryTime,omitempty"`
}

func ParsePublicKeyPEM(p string) (*ecdsa.PublicKey, error) {
	block, _ := pem.Decode([]byte(p))
	if block == nil {
		return nil, errors.New("no PEM block")
	}
	k, err := x509.ParsePKIXPublicKey(block.Bytes)
	if err != nil {
		return nil, err
	}
	ec, ok := k.(*ecdsa.PublicKey)
	if !ok {
		return nil, errors.New("not an EC key")
	}
	return ec, nil
}

// Verify checks an ES256 purchase token. keys maps kid → public key.
func Verify(token string, keys map[string]*ecdsa.PublicKey, expectedPackage string) (*Claims, error) {
	parts := strings.Split(token, ".")
	if len(parts) != 3 {
		return nil, errors.New("malformed token")
	}
	dec := base64.RawURLEncoding
	hb, err := dec.DecodeString(parts[0])
	if err != nil {
		return nil, err
	}
	var header struct {
		Alg string `json:"alg"`
		Kid string `json:"kid"`
	}
	if err := json.Unmarshal(hb, &header); err != nil {
		return nil, err
	}
	if header.Alg != "ES256" {
		return nil, errors.New("unexpected alg")
	}
	key, ok := keys[header.Kid]
	if !ok {
		return nil, errors.New("unknown kid")
	}
	sig, err := dec.DecodeString(parts[2])
	if err != nil || len(sig) != 64 {
		return nil, errors.New("bad signature encoding") // JWS ES256 = raw R||S, 64 bytes
	}
	r := new(big.Int).SetBytes(sig[:32])
	s := new(big.Int).SetBytes(sig[32:])
	digest := sha256.Sum256([]byte(parts[0] + "." + parts[1]))
	if !ecdsa.Verify(key, digest[:], r, s) {
		return nil, errors.New("bad signature")
	}
	cb, err := dec.DecodeString(parts[1])
	if err != nil {
		return nil, err
	}
	var c Claims
	if err := json.Unmarshal(cb, &c); err != nil {
		return nil, err
	}
	if c.PackageName != expectedPackage {
		return nil, errors.New("wrong package")
	}
	return &c, nil
}

Python

import base64
import json

from cryptography.exceptions import InvalidSignature
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import ec
from cryptography.hazmat.primitives.asymmetric.utils import encode_dss_signature


def _b64url(s: str) -> bytes:
    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))


def verify_purchase_token(token: str, keys_by_kid: dict[str, str], expected_package: str) -> dict:
    """keys_by_kid: kid → publicKeyPem. Returns the verified claims or raises ValueError."""
    parts = token.split(".")
    if len(parts) != 3:
        raise ValueError("malformed token")
    header = json.loads(_b64url(parts[0]))
    if header.get("alg") != "ES256":
        raise ValueError("unexpected alg")
    pem = keys_by_kid.get(header.get("kid"))
    if pem is None:
        raise ValueError("unknown kid")
    public_key = serialization.load_pem_public_key(pem.encode())

    raw = _b64url(parts[2])
    if len(raw) != 64:  # JWS ES256 = raw R||S, not DER
        raise ValueError("bad signature length")
    der = encode_dss_signature(int.from_bytes(raw[:32], "big"), int.from_bytes(raw[32:], "big"))
    try:
        public_key.verify(der, f"{parts[0]}.{parts[1]}".encode("ascii"), ec.ECDSA(hashes.SHA256()))
    except InvalidSignature:
        raise ValueError("bad signature")

    claims = json.loads(_b64url(parts[1]))
    if claims.get("packageName") != expected_package:
        raise ValueError("wrong package")
    return claims

# Alternative with PyJWT (handles the raw signature format itself):
#   jwt.decode(token, pem, algorithms=["ES256"])   # check kid / packageName yourself

Node.js

const crypto = require("node:crypto");

/** keysByKid: { [kid]: publicKeyPem }. Returns the verified claims or throws. */
function verifyPurchaseToken(token, keysByKid, expectedPackage) {
  const parts = token.split(".");
  if (parts.length !== 3) throw new Error("malformed token");
  const header = JSON.parse(Buffer.from(parts[0], "base64url").toString("utf8"));
  if (header.alg !== "ES256") throw new Error("unexpected alg");
  const pem = keysByKid[header.kid];
  if (!pem) throw new Error("unknown kid");

  const sig = Buffer.from(parts[2], "base64url");
  if (sig.length !== 64) throw new Error("bad signature length"); // raw R||S
  const ok = crypto.verify(
    "sha256",
    Buffer.from(`${parts[0]}.${parts[1]}`, "ascii"),
    { key: pem, dsaEncoding: "ieee-p1363" }, // JWS format, not DER
    sig,
  );
  if (!ok) throw new Error("bad signature");

  const claims = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
  if (claims.packageName !== expectedPackage) throw new Error("wrong package");
  return claims;
}

// Alternative with the `jose` package: await jwtVerify(token, await importSPKI(pem, "ES256"), { algorithms: ["ES256"] })

اشتباه‌های رایج

اشتباه پیامد
استفادهٔ مستقیم از امضای ۶۴ بایتی با API که DER می‌خواهد همهٔ توکن‌ها نامعتبر دیده می‌شوند
پذیرفتن alg از header بدون محدود کردن به ES256 حملهٔ تغییر الگوریتم (مثلاً none)
بررسی نکردن packageName پذیرش توکن معتبرِ برنامهٔ دیگری
نگه نداشتن orderIdهای مصرف‌شده دادن تکراری محصول با یک توکن
تکیه بر purchaseState داخل توکن برای وضعیت جاری ندیدن بازپرداخت یا مصرف؛ از S2S استفاده کنید
re-encode کردن base64 پیش از بررسی امضا روی بایت‌های دیگری بررسی می‌شود