Vérificateur de certificats numériques, API de services Web RESTful
[EN] Manuel
de l’utilisateur « X.509 verifier » est un service Web RESTful qui peut servir à valider les certificats X.509 et les fichiers PDF signés ainsi qu’à vérifier la conformité du contenu des certificats avec la législation de la République de Serbie.
Le service Web RESTful « X.509 verifier » se compose de 2 API REST situées sur l’hôte :
http://signatureverifier.d-logic.com
et les chemins d’accès des scripts sont :
API REST : vérificateur x509
Version de l’API : 1.0
Le fichier PEM, dont le contenu doit être un certificat X.509 de la version 3, est envoyé à cette API. Après avoir vérifié le certificat, l’API renvoie le résultat de la vérification dans la chaîne codée JSON.
Requête de serveur HTTP
Host + Path: http://signatureverifier.d-logic.com/x509-verifier.php
Method: POST
Headers (obligatoire):
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}
Description de la requête du serveur HTTP
RANDOM_STRING_BOUNDARY est une chaîne qui doit avoir une valeur différente et, si possible, unique à chaque nouvelle demande. Par exemple, en JavaScript, une bonne pratique pour acquérir RANDOM_STRING_BOUNDARY serait :
var boundary = Math.random().toString().substr(2);
[FILE_BINARY_DATA] est un contenu binaire du fichier 'file_name.pem' choisi.
[JSON_ENCODED_PARAMETERS] sont des paramètres codés en JSON qui doivent remplir le format suivant :
{
« opération »: « vérifier »,
« user_id »: 123,
« security_token »: « »
}
et la bonne pratique est que cette chaîne codée en JSON ne contient pas d’espaces blancs, c’est-à-dire à former, en JavaScript, par exemple, en utilisant le code suivant:
var params, json;
params= { operation: « verify », user_id: 123, security_token: « » };
json = JSON.stringify(params);
Les paramètres sont:
« opération »: « vérifier » – L’opération « vérifier » est la seule opération actuellement prise en charge.
« user_id »: 123 – paramètre numérique, type entier, représente le numéro d’identification de l’utilisateur (il n’est pas utilisé dans la version 1.0 de l’API mais il est obligatoire et réservé pour une utilisation future). Dans l’API, la version 1.0 peut être 0.
« security_token »: " – chaîne qui doit contenir des paires de chiffres hexadécimaux sans délimiteur (elle n’est pas utilisée dans la version 1.0 de l’API mais elle est obligatoire et réservée pour une utilisation future). Dans l’API version 1.0 peut être une chaîne vide.
Quoi qu’il en soit, en JavaScript, il n’est pas nécessaire de gérer directement le Contenu, c’est-à-dire le corps HTTP. Nous vous recommandons d’utiliser la classe FormData comme exemple que vous pouvez télécharger à partir du référentiel git sur l’URL suivante :
/code/NFC-RFID-reader-SDK/signature_verifier_jc_example.git
Il existe également des exemples d’utilisation de la prise en charge cURL de PHP pour envoyer des requêtes à ces API REST :
/code/digital_signature_sdk/php_example.git
Réponse du serveur HTTP
Après vérification du certificat X.509, le serveur renvoie une chaîne codée JSON qui (dans API version 1.0) contient 2 arguments :
{"status »:"STATUS_STRING »,"msg »:"MESSAGE_STRING"}
En cas de demande non valide, la réponse du serveur sera :
HTTP/1.1 200 OK
…
Content-type: application/JSON
{"status »:"Erreur : paramètres POST incorrects. »,"msg »:""}
Si la vérification réussit, STATUS_STRING doit être :
« D’accord »
tandis que le MESSAGE_STRING contiendra un enregistrement validement formaté, qui contient des balises de formatage HTML, ainsi que des balises HTML pour une nouvelle ligne, de sorte que ce message peut être directement placé dans n’importe quel conteneur HTML (par exemple <div>).
Toute réponse dont la STATUS_STRING est différente de « OK » est comptée comme une vérification dont le résultat échoue et, dans ce cas, si STATUS_STRING est différente de « Erreur: paramètres POST incorrects. », MESSAGE_STRING contiendra les détails de l’examen du certificat qui doit être affiché.
API REST : pdf-sgn-verifier
Version de l’API : 1.0
Le fichier PDF, dont le contenu doit être signé document PDF, est envoyé à cette API. Les formats de signature peuvent être « PKCS#7 – Détaché » ou « Équivalent CAdES ». Après avoir vérifié le fichier signé, l’API renvoie le résultat de la vérification dans la chaîne codée JSON.
Requête de serveur HTTP
Host + Path: http://signatureverifier.d-logic.com/pdf-sgn-verifier.php
Method: POST
Headers (obligatoire):
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}
Description de la requête du serveur HTTP
RANDOM_STRING_BOUNDARY est une chaîne qui doit avoir une valeur différente et, si possible, unique à chaque nouvelle demande. Par exemple, en JavaScript, une bonne pratique pour acquérir RANDOM_STRING_BOUNDARY serait :
var boundary = Math.random().toString().substr(2);
[FILE_BINARY_DATA] est un contenu binaire du fichier 'file_name.pdf' choisi.
[JSON_ENCODED_PARAMETERS] sont des paramètres codés en JSON qui doivent remplir le format suivant :
{
« opération »: « vérifier »,
« user_id »: 123,
« security_token »: « »
}
et la bonne pratique est que cette chaîne codée en JSON ne contient pas d’espaces blancs, c’est-à-dire à former, en JavaScript, par exemple, en utilisant le code suivant:
var params, json;
params= { operation: « verify », user_id: 123, security_token: « » };
json = JSON.stringify(params);
Les paramètres sont:
« opération »: « vérifier » – L’opération « vérifier » est la seule opération actuellement prise en charge.
« user_id »: 123 – paramètre numérique, type entier, représente le numéro d’identification de l’utilisateur (il n’est pas utilisé dans la version 1.0 de l’API mais il est obligatoire et réservé pour une utilisation future). Dans l’API, la version 1.0 peut être 0.
« security_token »: " – chaîne qui doit contenir des paires de chiffres hexadécimaux sans délimiteur (elle n’est pas utilisée dans api version 1.0 mais elle est obligatoire et réservée pour une utilisation future). Dans l’API version 1.0 peut être une chaîne vide.
Quoi qu’il en soit, en JavaScript, il n’est pas nécessaire de gérer directement le Contenu, c’est-à-dire le corps HTTP. Nous vous recommandons d’utiliser la classe FormData comme exemple que vous pouvez télécharger à partir du référentiel git sur l’URL suivante :
/code/NFC-RFID-reader-SDK/signature_verifier_jc_example.git
Il existe également des exemples d’utilisation de la prise en charge cURL de PHP pour envoyer des requêtes à ces API REST :
/code/digital_signature_sdk/php_example.git
Réponse du serveur HTTP
Après vérification du fichier PDF et de la signature, le serveur renverra une chaîne codée JSON qui (dans api version 1.0) contient 2 arguments :
{"status »:"STATUS_STRING »,"msg »:"MESSAGE_STRING"}
En cas de demande non valide, la réponse du serveur sera :
HTTP/1.1 200 OK
…
Content-type: application/JSON
{"status »:"Erreur : paramètres POST incorrects. »,"msg »:""}
Si la vérification réussit, STATUS_STRING doit être :
« La signature PDF est VALIDE »
tandis que le MESSAGE_STRING contiendra un enregistrement validement formaté, qui contient des balises de formatage HTML, ainsi que des balises HTML pour une nouvelle ligne, de sorte que ce message peut être directement placé dans n’importe quel conteneur HTML (par exemple <div>).
Contrairement à l’API x509-verifier, nous avons ici des réponses avec STATUS_STRING différentes de « PDF Signature is VALID », qui comptait comme un résultat de vérification infructueux mais dans ces cas, MESSAGE_STRING ne contient pas de détails. Ce sont les cas où:
STATUS_STRING = « Erreur : le PDF a été modifié après la signature ! »
STATUS_STRING = « Erreur : Format PDF incorrect (lors de la recherche de données de signature) »
STATUS_STRING = « Info: Le fichier PDF ne contient pas de signature numérique »
STATUS_STRING = « Erreur : Format PKCS#7 incorrect (données « à signer » manquantes) »
Le cas lorsqu’il est
STATUS_STRING = « Échec de la validation de la signature numérique »
ce qui signifie qu’il s’agit d’une vérification du fichier PDF et contient la signature entièrement terminée mais le résultat échoue. Dans ce cas, les MESSAGE_STRING contiennent toujours des détails sur l’examen qui doit être affiché. Dans ce cas, MESSAGE_STRING contiendra un enregistrement validement formaté, qui contient des balises de formatage HTML, ainsi que des balises HTML pour une nouvelle ligne, de sorte que ce message peut être directement placé dans n’importe quel conteneur HTML (par exemple <div>).
Annexe: « Restlet Client » – Fichiers exportés de l’extension de navigateur Google Chrome:
La partie d’accompagnement de ce manuel comprend également des fichiers JSON qui contiennent des profils pour l’extension « Google Chrome » « Restlet Client ». Ces fichiers sont x509-verifier.json et pdf-sgn-verifier.json et contiennent des profils pour les API REST x509-verifier et pdf-sgn-verifier respectivement. Ils peuvent être utilisés après l’installation des extensions « Restlet client » « Google Chrome ».
« Restlet Client » a un bogue connu qui se manifeste en changeant toujours, lors du chargement du profil, le type de paramètre de formulaire du corps de « Fichier » à « Texte ». La solution consiste à basculer le type modifié sur « Fichier », puis à choisir le fichier souhaité.
Comments are closed.