Verificatore di certificati digitali, API dei servizi Web RESTful
[EN] Manuale d'uso
"X.509 verifier" è un servizio Web RESTful che può servire a convalidare i certificati X.509 e i file PDF firmati, nonché a verificare la conformità del contenuto dei certificati con la legislazione della Repubblica di Serbia.
Il servizio Web RESTful "X.509 verifier" è costituito da 2 API REST situate nell'host:
http://signatureverifier.d-logic.com
e i percorsi degli script sono:
- /x509-verificatore.php
- /pdf-sgn-verificatore.php
API REST: x509-verificatore
Versione API: 1.0
Il file PEM, il cui contenuto deve essere un certificato X.509 della versione 3, viene inviato a questa API. Dopo aver controllato il certificato, l'API restituisce il risultato della verifica nella stringa codificata JSON.
Richiesta server HTTP
Host + Percorso: http://signatureverifier.d-logic.com/x509-verifier.php
Metodo: POST
Intestazioni (obbligatorio):
Content-Type: multipart/form-data; boundary=RANDOM_STRING_BOUNDARY
Corpo:
–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}
Descrizione della richiesta del server HTTP
RANDOM_STRING_BOUNDARY è una stringa che deve avere un valore diverso e, se possibile, univoco su ogni nuova richiesta. Ad esempio, in JavaScript, le buone pratiche per acquisire RANDOM_STRING_BOUNDARY sarebbero:
var boundary = Math.random().toString().substr(2);
[FILE_BINARY_DATA] è un contenuto binario del file 'file_name.pem' scelto.
[JSON_ENCODED_PARAMETERS] sono parametri codificati JSON che devono soddisfare il seguente formato:
{
"operazione": "verifica",
"user_id": 123,
"security_token": ""
}
e la buona pratica è che questa stringa codificata JSON non contenga caratteri di spazi bianchi cioè da formare, in JavaScript, ad esempio, usando il seguente codice:
var params, json;
params= { operation: "verify", user_id: 123, security_token: "" };
json = JSON.stringify(params);
I parametri sono:
"operation": "verify" – L'operazione "verify" è l'unica operazione attualmente supportata.
"user_id": 123 – parametro numerico, tipo intero, rappresenta il numero di identificazione dell'utente (non è utilizzato nella versione API 1.0 ma è obbligatorio e riservato per l'uso futuro). Nella versione API 1.0 può essere 0.
"security_token": " – stringa che dovrebbe contenere coppie di cifre esadecimali senza un cosiddetto delimitatore (non è utilizzata nella versione API 1.0 ma è obbligatoria e riservata per l'uso futuro). Nella versione API 1.0 può essere una stringa vuota.
In ogni caso, in JavaScript, non è necessario gestire direttamente il Contenuto, ovvero il corpo HTTP. Si consiglia di utilizzare la classe FormData come esempio che è possibile scaricare dal repository git al seguente URL:
/code/NFC-RFID-reader-SDK/signature_verifier_jc_example.git
Ci sono anche esempi di come utilizzare il supporto cURL da PHP per inviare richieste a queste API REST:
/code/digital_signature_sdk/php_example.git
Risposta del server HTTP
Dopo la verifica del certificato X.509, il server restituirà la stringa codificata JSON che (nella versione API 1.0) contiene 2 argomenti:
{"status":"STATUS_STRING","msg":"MESSAGE_STRING"}
In caso di richiesta non valida, la risposta del server sarà:
HTTP/1.1 200 OK
…
Tipo di contenuto: Application/JSON
{"status":"Errore: parametri POST errati.","msg":""}
Se la verifica ha esito positivo, STATUS_STRING deve essere:
"Va bene"
mentre il MESSAGE_STRING conterrà un record validamente formattato, che contiene tag di formattazione HTML, nonché tag HTML per una nuova riga, quindi questo messaggio può essere inserito direttamente in qualsiasi contenitore HTML (ad esempio <div>).
Qualsiasi risposta il cui STATUS_STRING è diverso da "OK" viene conteggiata come un controllo il cui risultato non ha esito positivo e, in questo caso, se STATUS_STRING è diverso dai parametri POST "Errore: errore POST.", MESSAGE_STRING conterrà i dettagli del controllo del certificato che dovrebbero essere visualizzati.
API REST: pdf-sgn-verifier
Versione API: 1.0
Il file PDF, il cui contenuto deve essere firmato documento PDF, viene inviato a questa API. I formati delle firme possono essere "PKCS#7 – Detached" o "CAdES Equivalent". Dopo aver controllato il file firmato, l'API restituisce il risultato della verifica nella stringa codificata JSON.
Richiesta server HTTP
Host + Percorso: http://signatureverifier.d-logic.com/pdf-sgn-verifier.php
Metodo: POST
Intestazioni (obbligatorio):
Content-Type: multipart/form-data; boundary=RANDOM_STRING_BOUNDARY
Corpo:
–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}
Descrizione della richiesta del server HTTP
RANDOM_STRING_BOUNDARY è una stringa che deve avere un valore diverso e, se possibile, univoco su ogni nuova richiesta. Ad esempio, in JavaScript, le buone pratiche per acquisire RANDOM_STRING_BOUNDARY sarebbero:
var boundary = Math.random().toString().substr(2);
[FILE_BINARY_DATA] è un contenuto binario del file "file_name.pdf" scelto.
[JSON_ENCODED_PARAMETERS] sono parametri codificati JSON che devono soddisfare il seguente formato:
{
"operazione": "verifica",
"user_id": 123,
"security_token": ""
}
e la buona pratica è che questa stringa codificata JSON non contenga caratteri di spazi bianchi cioè da formare, in JavaScript, ad esempio, usando il seguente codice:
var params, json;
params= { operation: "verify", user_id: 123, security_token: "" };
json = JSON.stringify(params);
I parametri sono:
"operation": "verify" – L'operazione "verify" è l'unica operazione attualmente supportata.
"user_id": 123 – parametro numerico, tipo intero, rappresenta il numero di identificazione dell'utente (non è utilizzato nella versione API 1.0 ma è obbligatorio e riservato per l'uso futuro). Nella versione API 1.0 può essere 0.
"security_token": " – stringa che dovrebbe contenere coppie di cifre esadecimali senza il cosiddetto delimitatore (non è utilizzata nella versione API 1.0 ma è obbligatoria e riservata per l'uso futuro). Nella versione API 1.0 può essere una stringa vuota.
In ogni caso, in JavaScript, non è necessario gestire direttamente il Contenuto, ovvero il corpo HTTP. Si consiglia di utilizzare la classe FormData come esempio che è possibile scaricare dal repository git al seguente URL:
/code/NFC-RFID-reader-SDK/signature_verifier_jc_example.git
Ci sono anche esempi di come utilizzare il supporto cURL da PHP per inviare richieste a queste API REST:
/code/digital_signature_sdk/php_example.git
Risposta del server HTTP
Dopo la verifica del file PDF e contiene la firma, il server restituirà la stringa codificata JSON che (nella versione API 1.0) contiene 2 argomenti:
{"status":"STATUS_STRING","msg":"MESSAGE_STRING"}
In caso di richiesta non valida, la risposta del server sarà:
HTTP/1.1 200 OK
…
Tipo di contenuto: Application/JSON
{"status":"Errore: parametri POST errati.","msg":""}
Se la verifica ha esito positivo, STATUS_STRING deve essere:
"La firma PDF è VALIDA"
mentre il MESSAGE_STRING conterrà un record validamente formattato, che contiene tag di formattazione HTML, nonché tag HTML per una nuova riga, quindi questo messaggio può essere inserito direttamente in qualsiasi contenitore HTML (ad esempio <div>).
Contrariamente all'API x509-verifier, qui abbiamo risposte con STATUS_STRING diverso da "La firma PDF è VALIDA", che contava come risultato di verifica non riuscito, ma in questi casi, MESSAGE_STRING non contiene dettagli. Questi sono i casi in cui:
STATUS_STRING = "Errore: PDF è stato modificato dopo la firma!"
STATUS_STRING = "Errore: formato PDF errato (durante la ricerca dei dati della firma)"
STATUS_STRING = "Info: il file PDF non contiene la firma digitale"
STATUS_STRING = "Errore: formato PKCS#7 errato (mancano i dati "da firmare")"
Il caso in cui è
STATUS_STRING = "Convalida della firma digitale NON RIUSCITA"
il che significa che è una verifica del file PDF e contiene la firma interamente completata ma il risultato non ha successo. In questo caso, le MESSAGE_STRING contengono sempre i dettagli del controllo che dovrebbero essere visualizzati. In questo caso, MESSAGE_STRING conterrà un record validamente formattato, che contiene tag di formattazione HTML, nonché tag HTML per una nuova riga, quindi questo messaggio può essere inserito direttamente in qualsiasi contenitore HTML (ad esempio <div>).
Appendice: "Restlet Client" – File esportati dall'estensione del browser Google Chrome:
La parte di accompagnamento di questo manuale include anche i file JSON che contengono profili per l'estensione "Google Chrome" "Restlet Client". Questi file sono x509-verifier.json e pdf-sgn-verifier.json e contengono profili per le API REST x509-verifier e pdf-sgn-verifier rispettivamente. Possono essere utilizzati dopo aver installato le estensioni "Restlet client" "Google Chrome".
"Restlet Client" ha un bug noto che si manifesta sempre, al caricamento del profilo, cambia il tipo di parametro del modulo del corpo da "File" a "Testo". La soluzione consiste nel riportare il tipo modificato in "File" e quindi scegliere il file desiderato.
