Digital Certificates verifier, RESTful Web services API
[EN] Korisnički priručnik
"X.509 verifikator" je RESTful Web servis koji može poslužiti za validaciju X.509 sertifikata i potpisanih PDF fajlova, kao i za proveru usklađenosti sadržaja sertifikata sa zakonodavstvom Republike Srbije.
"X.509 verifikator" RESTful Web servis se sastoji od 2 REST API-ja koji se nalaze na hostu
: http://signatureverifier.d-logic.com
a putanje skripti su:
REST API: x509-verifikator
API verzija: 1.0
PEM datoteka, čiji sadržaj mora biti X.509 certifikat verzije 3, šalje se u ovaj API. Nakon provere sertifikata, API vraća rezultat verifikacije u JSON kodiranom nizu.
HTTP zahtjev servera
Host + Path: http://signatureverifier.d-logic.com/x509-verifier.php
Method: POST
Headers (mandatory):
Content-Type: multipart/form-data; boundary=RANDOM_STRING_BOUNDARY Body
: –RANDOM_STRING_BOUNDARY Content-Disposition: form-data; name="file"; filename="file_name.pem"
Content-Type: application/octet-stream
[FILE_BINARY_DATA]
—
RANDOM_STRING_BOUNDARY
Content-Disposition: form-data; name="query"
[JSON_ENCODED_PARAMETERS]
–-RANDOM_STRING_BOUNDARY–
{END}
Opis zahtjeva HTTP servera
RANDOM_STRING_BOUNDARY je niz koji treba da ima drugačiju i, ako je moguće, jedinstvenu vrednost na svakom novom zahtevu. Na primer, u JavaScript-u, dobra praksa za sticanje RANDOM_STRING_BOUNDARY bi bila:
var granica = Math.random().toString().substr(2);
[FILE_BINARY_DATA] je binarni sadržaj izabrane 'file_name.pem' datoteke.
[JSON_ENCODED_PARAMETERS] su JSON kodirani parametri koji moraju ispuniti sljedeći format:
{
"operacija": "Provjera",
"user_id": 123,
"security_token": ""
}
Dobra praksa je da ovaj JSON kodirani niz ne sadrži znakove bijelog prostora, tj. da se formira, u JavaScriptu, na primjer, koristeći sljedeći kod:
var params, json;
params= { operacija: "verifikacija", user_id: 123, security_token: "" };
json = JSON.stringify(params);
Parametri su
: "operacija": "verifikacija" – Operacija "verifikacija" je jedina operacija koja je trenutno podržana.
"user_id": 123 – numerički parametar, cjelobrojni tip, predstavlja identifikacijski broj korisnika (ne koristi se u API verziji 1.0, ali je obavezan i rezerviran za buduću upotrebu). U API verziji 1.0 može biti 0.
"security_token": " – niz koji bi trebao sadržavati parove heksadecimalnih cifara bez takozvanog razgraničavača (ne koristi se u API verziji 1.0, ali je obavezan i rezerviran za buduću upotrebu). U API verziji 1.0 može biti prazan niz.
U svakom slučaju, u JavaScript-u nije potrebno direktno upravljati sadržajem, odnosno HTTP telom. Preporučujemo korištenje klase FormData kao primjera koji možete preuzeti iz git spremišta na sljedećem URL-u: /code/NFC-RFID-reader-SDK
/signature_verifier_jc_example.git Postoje i primjeri kako koristiti cURL podršku iz PHP-a za slanje zahtjeva ovim REST API-jima:
/code/digital_signature_sdk/php_example.git
HTTP odgovor servera
Nakon X.509 verifikacije sertifikata, server će vratiti JSON kodirani niz koji (u API verziji 1.0) sadrži 2 argumenta:
{"status":"STATUS_STRING","msg":"MESSAGE_STRING"}
Na nevažeći zahtjev, odgovor servera će biti:
HTTP/1.1 200 OK
…
Vrsta sadržaja: aplikacija/json
{"status":"Error: wrong POST parameters.","msg":"}
Ako je verifikacija uspješna, STATUS_STRING mora biti:
"OK"
dok će MESSAGE_STRING sadržati validno oblikovan zapis, koji sadrži HTML oznake za oblikovanje, kao i HTML oznake za novu liniju, tako da se ova poruka može direktno smestiti u bilo koji HTML kontejner (npr. <div>).
Svaki odgovor čija se STATUS_STRING razlikuje od "OK" računa se kao provjera čiji je rezultat neuspješan i, u ovom slučaju, ako se STATUS_STRING razlikuje od "Greška: pogrešni parametri POST-a.", MESSAGE_STRING će sadržati detalje o pregledu sertifikata koji treba da budu prikazani.
REST API: pdf-sgn-verifier
API verzija: 1.0
PDF datoteka, čiji sadržaj mora biti potpisan PDF dokument, šalje se u ovaj API. Formati potpisa mogu biti "PKCS#7 – Detached" ili "CAdES Equivalent". Nakon provere potpisane datoteke, API vraća rezultat verifikacije u JSON kodiranom nizu.
HTTP zahtjev servera
Host + Path: http://signatureverifier.d-logic.com/pdf-sgn-verifier.php
Method: POST
Headers (mandatory):
Content-Type: multipart/form-data; boundary=RANDOM_STRING_BOUNDARY Body: —RANDOM_STRING_BOUNDARY
Content-Disposition: form-data; name="file"; filename="file_name.pdf"
Content-Type
:
application/pdf
[FILE_BINARY_DATA]
––RANDOM_ STRING_BOUNDARY
Content-Disposition: form-data; name="query"
[JSON_ENCODED_PARAMETERS]
–-RANDOM_STRING_BOUNDARY–
{END}
Opis zahtjeva HTTP servera
RANDOM_STRING_BOUNDARY je niz koji treba da ima drugačiju i, ako je moguće, jedinstvenu vrednost na svakom novom zahtevu. Na primer, u JavaScript-u, dobra praksa za sticanje RANDOM_STRING_BOUNDARY bi bila:
var granica = Math.random().toString().substr(2);
[FILE_BINARY_DATA] je binarni sadržaj izabrane 'file_name.pdf' datoteke.
[JSON_ENCODED_PARAMETERS] su JSON kodirani parametri koji moraju ispuniti sljedeći format:
{
"operacija": "Provjera",
"user_id": 123,
"security_token": ""
}
Dobra praksa je da ovaj JSON kodirani niz ne sadrži znakove bijelog prostora, tj. da se formira, u JavaScriptu, na primjer, koristeći sljedeći kod:
var params, json;
params= { operacija: "verifikacija", user_id: 123, security_token: "" };
json = JSON.stringify(params);
Parametri su
: "operacija": "verifikacija" – Operacija "verifikacija" je jedina operacija koja je trenutno podržana.
"user_id": 123 – numerički parametar, cjelobrojni tip, predstavlja identifikacijski broj korisnika (ne koristi se u API verziji 1.0, ali je obavezan i rezerviran za buduću upotrebu). U API verziji 1.0 može biti 0.
"security_token": " – niz koji bi trebao sadržavati parove heksadecimalnih cifara bez takozvanog razgraničavača (ne koristi se u API verziji 1.0, ali je obavezan i rezerviran za buduću upotrebu). U API verziji 1.0 može biti prazan niz.
U svakom slučaju, u JavaScript-u nije potrebno direktno upravljati sadržajem, odnosno HTTP telom. Preporučujemo korištenje klase FormData kao primjera koji možete preuzeti iz git spremišta na sljedećem URL-u: /code/NFC-RFID-reader-SDK
/signature_verifier_jc_example.git Postoje i primjeri kako koristiti cURL podršku iz PHP-a za slanje zahtjeva ovim REST API-jima:
/code/digital_signature_sdk/php_example.git
HTTP odgovor servera
Nakon verifikacije PDF datoteke i sadrži potpis, server će vratiti JSON kodirani niz koji (u API verziji 1.0) sadrži 2 argumenta:
{"status":"STATUS_STRING","msg":"MESSAGE_STRING"}
Na nevažeći zahtjev, odgovor servera će biti:
HTTP/1.1 200 OK
…
Vrsta sadržaja: aplikacija/json
{"status":"Error: wrong POST parameters.","msg":"}
Ako je verifikacija uspješna, STATUS_STRING mora biti:
PDF potpis je validan
dok će MESSAGE_STRING sadržati validno oblikovan zapis, koji sadrži HTML oznake za oblikovanje, kao i HTML oznake za novu liniju, tako da se ova poruka može direktno smestiti u bilo koji HTML kontejner (npr. <div>).
Za razliku od x509-verifier API-ja, ovdje imamo odgovore sa STATUS_STRING različitim od "PDF Signature is VALID", koji se računa kao neuspješan rezultat verifikacije, ali u tim slučajevima, MESSAGE_STRING ne sadrži detalje. Ovo su slučajevi kada:
STATUS_STRING = "Greška: PDF je promijenjen nakon potpisivanja!"
STATUS_STRING = "Error: Wrong PDF format (while searching signature data)"
STATUS_STRING = "Info: PDF datoteka ne sadrži digitalni potpis"
STATUS_STRING = "Error: Wrong PKCS#7 format (nedostaje "biti potpisan" podaci)"
Slučaj kada je
STATUS_STRING = "Digitalna validacija potpisa NIJE uspjela"
To znači da je to verifikacija PDF datoteke i sadrži potpis u potpunosti završen , ali rezultat nije uspešan. U ovom slučaju, MESSAGE_STRING uvek sadrže detalje nadzora koji treba da budu prikazani. U ovom slučaju, MESSAGE_STRING će sadržati validno oblikovan zapis, koji sadrži HTML oznake za oblikovanje, kao i HTML oznake za novu liniju, tako da se ova poruka može direktno smestiti u bilo koji HTML kontejner (npr. <div>).
Dodatak: "Restlet Client" – ekstenzija preglednika Google Chrome izvezena je datoteka:
Prateći dio ovog priručnika uključuje i JSON datoteke koje sadrže profile za ekstenziju "Google Chrome" "Restlet Client". Ove datoteke su x509-verifier.json i pdf-sgn-verifier.json i sadrže profile za REST API-je x509-verifikator i pdf-sgn-verifikator respektivno. Mogu se koristiti nakon instalacije "Restlet client" "Google Chrome" ekstenzija.
"Restlet Client" ima poznati bug koji se manifestira uvijek, prilikom učitavanja profila, mijenja tip parametra oblika tijela iz "File" u "Tekst". Zaobilaženje je prebacivanje promijenjenog tipa nazad u "Datoteka," a zatim odabir željene datoteke.
Comments are closed.