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 موقتاً در دسترس نیست. مراحل:
- توکن را با
.به سه بخش تقسیم کنید؛ دقیقاً سه بخش باشد. - header را base64url-decode کنید؛
algبایدES256باشد (هر مقدار دیگر، از جملهnone، رد شود) وkidدر فهرست کلیدهای شما باشد. - امضا را base64url-decode کنید. امضای JWS در ES256 به شکل خام
R || Sو دقیقاً ۶۴ بایت است، نه DER. بیشتر کتابخانههای پایهٔ رمزنگاری (JavaSHA256withECDSA، Pythoncryptography) DER میخواهند؛ یا تبدیل کنید یا از حالت P1363/raw استفاده کنید. - امضا را روی رشتهٔ ASCII
header_b64 + "." + claims_b64(همان بایتهای دریافتی) بررسی کنید. - 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 پیش از بررسی | امضا روی بایتهای دیگری بررسی میشود |