Verifikator digitalnih certifikata, API restful web usluga
[EN] Korisnički priručnik
"X.509 verifikator" je RESTful web usluga koja može poslužiti za potvrđivanje X.509 certifikata i potpisanih PDF datoteka, kao i za provjeru usklađenosti sadržaja certifikata sa zakonskim propisima Republike Srbije.
"X.509 verifikator" RESTful Web usluga sastoji se od 2 REST API-ja smještena na domaćinu:
http://signatureverifier.d-logic.com
a putovi skripti su:
REST API: x509-verifikator
API verzija: 1.0
PEM datoteka, čiji sadržaj mora biti X.509 certifikat verzije 3, šalje se ovom API-ju. Nakon provjere certifikata, API vraća rezultat provjere u JSON kodiranom nizu.
Zahtjev HTTP poslužitelja
Glavno računalo + put: http://signatureverifier.d-logic.com/x509-verifier.php
Metoda: POST
zaglavlja (obavezno):
Vrsta sadržaja: višedijelni/obrazac-podaci; granica=RANDOM_STRING_BOUNDARY
Tijelo:
–RANDOM_STRING_BOUNDARY
Sadržaj-Dispozicija: obrazac-podaci; naziv ="datoteka"; naziv datoteke="file_name.pem"
Vrsta sadržaja: aplikacija/oktet-stream
[FILE_BINARY_DATA]
— RANDOM_STRING_BOUNDARY
Sadržaj-Dispozicija: obrazac-podaci; naziv="upit"
[JSON_ENCODED_PARAMETERS]
–RANDOM_STRING_BOUNDARY–
{END}
Opis zahtjeva HTTP poslužitelja
RANDOM_STRING_BOUNDARY je niz koji mora imati drugačiju i, ako je moguće, jedinstvenu vrijednost na svakom novom zahtjevu. Na primjer, u JavaScriptu bi dobra praksa za stjecanje RANDOM_STRING_BOUNDARY bila:
var granica = Math.random().toString().substring().substr(2);
[FILE_BINARY_DATA] binarni je sadržaj odabrane datoteke "file_name.pem".
[JSON_ENCODED_PARAMETERS] su JSON kodirani parametri koji moraju ispuniti sljedeći format:
{
"operacija": "provjera",
"user_id": 123,
"security_token": ""
}
a dobra praksa je da ovaj JSON kodirani niz ne sadrži znakove razmaka, tj.
var params, json;
params= { operation: "verify", user_id: 123, security_token: "" };
json = JSON.stringify(params);
Parametri su:
"operacija": "provjera" – Operacija "provjera" je jedina operacija koja je trenutno podržana.
"user_id": 123 – numerički parametar, cijeli broj, predstavlja identifikacijski broj korisnika (ne koristi se u API verziji 1.0, ali je obvezan i rezerviran za buduću uporabu). U API verziji 1.0 može biti 0.
"security_token": " – niz koji bi trebao sadržavati parove heksadecimalnih znamenki bez takozvanog graničnika (ne koristi se u API verziji 1.0, ali je obavezan i rezerviran za buduću uporabu). U API verziji 1.0 može biti prazan niz.
U svakom slučaju, u JavaScriptu nije potrebno izravno upravljati Sadržajem, tj. Preporučujemo korištenje klase FormData kao primjera koji možete preuzeti iz git repozitorija na sljedećem URL-u: /code/NFC-RFID-reader-SDK/signature_verifier_jc_example.git
Postoje i primjeri kako koristiti cURL podršku PHP-a za slanje zahtjeva ovim REST API-jevima:
/code/digital_signature_sdk/php_example.git
Odgovor HTTP poslužitelja
Nakon provjere X.509 certifikata, poslužitelj će vratiti JSON kodirani niz koji (u API verziji 1.0) sadrži 2 argumenta:
{"status":"STATUS_STRING","msg":"MESSAGE_STRING"}
Na zahtjev koji nije valjan, odgovor poslužitelja bit će:
HTTP/1.1 200 OK
…
Vrsta sadržaja: aplikacija/json
{"status":"Pogreška: pogrešni POST parametri.","msg":""}
Ako je provjera uspješna, STATUS_STRING mora biti:
"OK"
dok će MESSAGE_STRING sadržavati valjano oblikovani zapis koji sadrži HTML oznake oblikovanja, kao i HTML oznake za novi redak, tako da se ova poruka može izravno smjestiti u bilo koji HTML spremnik (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 "Pogreška: pogrešni POST parametri.", MESSAGE_STRING sadržavat će pojedinosti o nadzoru certifikata koji bi trebali biti prikazani.
REST API: pdf-sgn-verifikator
API verzija: 1.0
PDF datoteka, čiji sadržaj mora biti potpisan PDF dokumentom, šalje se ovom API-ju. Oblici potpisa mogu biti "PKCS#7 – Odvojeni" ili "ekvivalent CAdES". Nakon provjere potpisane datoteke, API vraća rezultat provjere u JSON kodiranom nizu.
Zahtjev HTTP poslužitelja
Glavno računalo + put:
http://signatureverifier.d-logic.com/pdf-sgn-verifier.php Metoda: POST
zaglavlja (obavezno):
Vrsta sadržaja: vrsta sadržaja: multipart/form-data; boundary=RANDOM_STRING_BOUNDARY
Tijelo:
–RANDOM_STRING_BOUNDARY
Sadržaj-Dispozicija: obrazac-podaci; naziv ="datoteka"; naziv datoteke ="file_name.pdf"
Vrsta sadržaja: aplikacija /pdf
[FILE_BINARY_DATA]
–RANDOM_ STRING_BOUNDARY
Content-Disposition: form-data; name="query"
[JSON_ENCODED_PARAMETERS]
–RANDOM_STRING_BOUNDARY–
{END}
Opis zahtjeva HTTP poslužitelja
RANDOM_STRING_BOUNDARY je niz koji mora imati drugačiju i, ako je moguće, jedinstvenu vrijednost na svakom novom zahtjevu. Na primjer, u JavaScriptu bi dobra praksa za stjecanje RANDOM_STRING_BOUNDARY bila:
var granica = Math.random().toString().substring().substr(2);
[FILE_BINARY_DATA] binarni je sadržaj odabrane datoteke "file_name.pdf".
[JSON_ENCODED_PARAMETERS] su JSON kodirani parametri koji moraju ispuniti sljedeći format:
{
"operacija": "provjera",
"user_id": 123,
"security_token": ""
}
a dobra praksa je da ovaj JSON kodirani niz ne sadrži znakove razmaka, tj.
var params, json;
params= { operation: "verify", user_id: 123, security_token: "" };
json = JSON.stringify(params);
Parametri su:
"operacija": "provjera" – Operacija "provjera" je jedina operacija koja je trenutno podržana.
"user_id": 123 – numerički parametar, cijeli broj, predstavlja identifikacijski broj korisnika (ne koristi se u API verziji 1.0, ali je obvezan i rezerviran za buduću uporabu). U API verziji 1.0 može biti 0.
"security_token": " – niz koji bi trebao sadržavati parove heksadecimalnih znamenki bez takozvanog graničnika (ne koristi se u API verziji 1.0, ali je obavezan i rezerviran za buduću uporabu). U API verziji 1.0 može biti prazan niz.
U svakom slučaju, u JavaScriptu nije potrebno izravno upravljati Sadržajem, tj. Preporučujemo korištenje klase FormData kao primjera koji možete preuzeti iz git repozitorija na sljedećem URL-u: /code/NFC-RFID-reader-SDK/signature_verifier_jc_example.git
Postoje i primjeri kako koristiti cURL podršku PHP-a za slanje zahtjeva ovim REST API-jevima:
/code/digital_signature_sdk/php_example.git
Odgovor HTTP poslužitelja
Nakon provjere PDF datoteke i sadrži potpis, poslužitelj će vratiti JSON kodirani niz koji (u API verziji 1.0) sadrži 2 argumenta:
{"status":"STATUS_STRING","msg":"MESSAGE_STRING"}
Na zahtjev koji nije valjan, odgovor poslužitelja bit će:
HTTP/1.1 200 OK
…
Vrsta sadržaja: aplikacija/json
{"status":"Pogreška: pogrešni POST parametri.","msg":""}
Ako je provjera uspješna, STATUS_STRING mora biti:
"PDF potpis je VALJAN"
dok će MESSAGE_STRING sadržavati valjano oblikovani zapis koji sadrži HTML oznake oblikovanja, kao i HTML oznake za novi redak, tako da se ova poruka može izravno smjestiti u bilo koji HTML spremnik (npr. <div>).
Suprotno X509-verifikatorskom API-ju, ovdje imamo odgovore s STATUS_STRING se razlikuju od "PDF potpis je VALJAN", koji se računao kao neuspješan rezultat provjere, ali u tim slučajevima MESSAGE_STRING ne sadrži detalje. To su slučajevi kada:
STATUS_STRING = "Pogreška: PDF je promijenjen nakon potpisivanja!"
STATUS_STRING = "Pogreška: pogrešan PDF format (tijekom pretraživanja podataka o potpisu)"
STATUS_STRING = "Informacije: PDF datoteka ne sadrži digitalni potpis"
STATUS_STRING = "Pogreška: Pogrešan PKCS#7 format (nedostaju podaci "za potpisivanje")"
Slučaj kada je
STATUS_STRING = "Provjera valjanosti digitalnog potpisa NIJE USPJELA"
što znači da je to provjera PDF datoteke i sadrži potpis u potpunosti dovršen, ali rezultat je neuspješan. U tom slučaju, MESSAGE_STRING uvijek sadrže detalje nadzora koji bi trebali biti prikazani. U tom slučaju, MESSAGE_STRING će sadržavati valjano oblikovan zapis koji sadrži HTML oznake oblikovanja, kao i HTML oznake za novi redak, tako da se ova poruka može izravno smjestiti u bilo koji HTML spremnik (npr. <div>).
Dodatak: "Restlet Client" – izvezene datoteke proširenja preglednika Google Chrome:
Popratni dio ovog priručnika uključuje i JSON datoteke koje sadrže profile za proširenje "Google Chrome" "Restlet Client". Te su datoteke x509-verifier.json i pdf-sgn-verifier.json i sadrže profile za REST API-jeve x509-verifikator i pdf-sgn-verifikator. Mogu se koristiti nakon instaliranja proširenja "Restlet client" "Google Chrome".
"Restlet Client" ima poznatu grešku koja se manifestira tako što uvijek, prilikom učitavanja profila, mijenja vrstu parametra oblika tijela iz "Datoteka" u "Tekst". Zaobilazno rješenje je vraćanje promijenjene vrste na "Datoteka", a zatim odabir željene datoteke.
Comments are closed.