Download the PHP package verifyblind/verifyblind-php without Composer

VerifyBlind PHP

Kimliğinizi Kanıtlayın, Gizliliğinizi Koruyun · Prove Your Identity, Protect Your Privacy

🇬🇧 English

Türkçe

VerifyBlind doğrulama sonucunu kendi PHP sunucunuzda birkaç satırla doğrulamanızı sağlayan resmi kütüphane. En zor kısım olan RSA-PSS imza kontrolünü (PHP'nin openssl_verify() fonksiyonu PSS yapamaz) sizin yerinize yapar.

Mimari

Kütüphane yalnız doğrulama tarafını yapar. Generate aracısı (API anahtarınızı ekleyen ve validations'ı kendi ayarınızdan koyan uç) hâlâ sizdedir; örnek: example-web-php → api/generate.php.

Kurulum

PHP 7.4 veya üstü. Tek bağımlılık phpseclib/phpseclib ~3.0 (saf PHP; ek eklenti ya da shell_exec gerekmez, paylaşımlı hostinglerde de çalışır).

Hızlı Başlangıç

Doğrulama ucu (POST /verifyblind/verify), yaklaşık 15 satır:

$result->userId(), nsbdId(), docId() kişiye özel takma kodlardır: veritabanınıza yazın, karar için userId() kullanın (ör. engel listesi), ama asla loglamayın (aşağıya bakın).

Nonce kuralı

Generate çağrısı size bir nonce döndürür. Onu sorduğunuz doğrulamalarla birlikte saklayın (Redis/veritabanı, süre 960 saniye). Doğrulamada aynı nonce tam bir kez tüketilir (al ve sil); bilinmiyorsa, süresi geçtiyse ya da daha önce kullanıldıysa sonuç reddedilir. Bu, aynı token'ın ikinci kez gönderilmesini (replay) engeller. Depo sizin uygulamanızdadır; kütüphane yalnız bir fonksiyon ister:

Generate ve doğrulama aynı tarayıcı oturumundan geliyorsa (web widget'ı) PHP oturumu da yeter: $_SESSION['vb'][$nonce] = $asked; diye saklayın, doğrulamada okuyup hemen unset() edin.

Sorulan doğrulamalar kuralı

Sonucu sizin sunucunuzun sorduğuna göre okuyun; tarayıcının ya da uygulamanın söylediğine asla. Generate isteğinin gövdesi DevTools'ta değiştirilebilir: "18+" yerine "1+" soran ziyaretçi, enclave'den dürüstçe imzalanmış bir age: true alır, ama "1+" koşulu için. verify() (ve tek başına Verifier::checkAsked($asked, $validations)) şunları denetler:

• Yaş sorduysanız: validations.age true/false olmalı ve validations.age_condition sorduğunuz koşulla birebir aynı olmalı. Eksik ya da farklıysa → ret.
• Yaş sormadıysanız: cevapta yaş bulunmamalı.
• user_id sorduysanız: dolu bir user_id gelmeli.

checkAsked() sorun yoksa null, varsa hata metni döndürür.

Demo kart: validations.is_test: true ya da TEST_ ile başlayan kodlar demo karttan gelir (yalnız test partner'larında). verify() bunları varsayılan olarak reddeder; test ortamında allowTestCards => true verin. $result->isTest() ile de ayırabilirsiniz.

İptal webhook'u (revoke)

Kullanıcı VerifyBlind uygulamasında onayını geri çekerse ya da silme isterse VerifyBlind, partner portalı Ayarlar'daki revoke adresinize imzalı bir JSON gönderir. İmza: "{X-Webhook-Timestamp}.{ham gövde}" üzerinde RSA-PSS-SHA256 (salt 32), anahtar /api/public/webhook-signing-key. Bu, API anahtarınızla HMAC değildir. Zaman damgası ±5 dakikadan eskiyse reddedilir.

Aynı fonksiyon B deseninin (sunucuda çözme) callback imzasını da doğrular; şifreli içeriği çözme bu kütüphanede yoktur (bkz. example-web-dotnet).

Konfigürasyon Parametreleri

PHP-FPM/Apache'de bellek önbelleği tek istek yaşar; her doğrulama anahtarı bir kez çeker. Bunu önlemek için FileCache ya da kendi PSR-16 önbelleğinizi verin. İmza tutmazsa anahtar bir kez tazelenip tekrar denenir.

Hata kodları

Tüm istisnalar VerifyBlind\Exception\VerifyBlindException'dan türer; getErrorCode() sabit bir kod, getHttpStatus() önerilen HTTP durumunu verir.

Güvenlik Notları

• Kimlik kodlarını asla loglamayın. user_id, nsbd_id, doc_id takma adlı kişisel veridir: diğer kullanıcı verileriniz gibi koruyun, log'a, hata mesajına ya da analitiğe yazmayın. Kütüphane hiçbir şey loglamaz, hata mesajlarında bu kodlar geçmez, var_dump($result) / print_r($result) da onları gizler.
• Karar yalnız sunucuda. Widget'ın onSuccess verisine ya da uygulamanın gösterdiğine güvenmeyin; token'ı sunucunuza gönderip burada doğrulayın.
• API anahtarı sunucu sırrıdır. Bu kütüphane API anahtarı istemez; generate aracınızda ortam değişkeninden okuyun.
• verifySignature() phpseclib'in süreç genelindeki RSA::disableSaltLengthDiscovery() ayarını açar. Bu ayar kapalıyken phpseclib başka salt uzunluklarıyla yapılmış imzaları da kabul eder.

Sürüm Geçmişi

English

The official library for verifying a VerifyBlind result on your own PHP server in a few lines. It does the hard part for you: RSA-PSS signature verification (PHP's openssl_verify() cannot do PSS).

Architecture

The library covers verification only. The generate proxy (the endpoint that adds your API key and sets validations from your own configuration) stays in your app; see example-web-php → api/generate.php.

Installation

PHP 7.4 or newer. The only dependency is phpseclib/phpseclib ~3.0 (pure PHP; no extension or shell_exec needed, so it works on shared hosting).

Quick Start

Verify endpoint (POST /verifyblind/verify), about 15 lines:

$result->userId(), nsbdId() and docId() are pseudonymous person codes: store them, use userId() for decisions (e.g. block lists), and never log them (see below).

Nonce rule

Generate returns a nonce. Store it together with the validations you asked (Redis/database, TTL 960 seconds). At verification the nonce is consumed exactly once (get and delete); unknown, expired or already used means reject. This stops the same token from being replayed. The store lives in your app; the library only needs a function:

When generate and verify come from the same browser session (web widget), a PHP session also works: store $_SESSION['vb'][$nonce] = $asked; and read it then unset() it at verification.

Asked-validations rule

Read the answer against what your server asked, never against what the browser or app says. The generate request body can be edited in DevTools: a visitor who changes "18+" to "1+" gets an honestly signed age: true — for "1+". verify() (and on its own Verifier::checkAsked($asked, $validations)) checks:

• Age asked: validations.age must be true/false and validations.age_condition must equal the asked condition exactly. Missing or different → reject.
• Age not asked: no age answer may be present.
• user_id asked: a non-empty user_id must be present.

checkAsked() returns null when the answer matches, or an error text.

Demo card: validations.is_test: true or codes starting with TEST_ come from a demo card (test partners only). verify() rejects them by default; pass allowTestCards => true on test setups. $result->isTest() tells them apart too.

Revoke webhook

When a user withdraws consent or asks for erasure in the VerifyBlind app, VerifyBlind POSTs signed JSON to the revoke URL set in the partner portal Settings. Signature: RSA-PSS-SHA256 (salt 32) over "{X-Webhook-Timestamp}.{raw body}", key from /api/public/webhook-signing-key. It is not an HMAC with your API key. Timestamps more than ±5 minutes off are rejected.

The same method verifies pattern B (server decrypt) callback signatures; decrypting the encrypted response is not part of this library (see example-web-dotnet).

Configuration Parameters

Under PHP-FPM/Apache the memory cache lives for one request, so each verification fetches the key once. Pass FileCache or your own PSR-16 cache to avoid that. When a signature fails, the key is refreshed once and the check is retried.

Error codes

Every exception extends VerifyBlind\Exception\VerifyBlindException; getErrorCode() gives a stable code and getHttpStatus() a suggested HTTP status.

Security Notes

• Never log identity codes. user_id, nsbd_id and doc_id are pseudonymous personal data: protect them like your other user data and keep them out of logs, error messages and analytics. The library logs nothing, its error messages never contain these codes, and var_dump($result) / print_r($result) hide them.
• Decide on the server only. Do not trust the widget's onSuccess data or what an app shows; send the token to your server and verify it here.
• The API key is a server secret. This library does not need it; read it from an environment variable in your generate proxy.
• verifySignature() turns on phpseclib's process-wide RSA::disableSaltLengthDiscovery(). Without it phpseclib also accepts signatures made with other salt lengths.

Version History

Lisans · License

Apache License 2.0 — bkz. / see LICENSE.