Pour mettre en place une authentification par JWT sur IBMi, on utilise l’API Qc3VerifySignature.
Le JWT
Il est composé de trois partie :
- Un entête (header)
- Une charge utile (payload)
- Une signature numérique
Pour obtenir la signature, il faut tout d’abord encoder séparément le header et le payload avec BaseURL64, ensuite, on les concatène en les séparant d’un point.
On calcule enfin une signature d’après le header et le payload afin de garantir que le jeton n’a pas été modifié, d’après l’algorithme défini dans le header (RS256, HS256, HS512, …). Cette signature binaire est elle-même encodée ensuite en Base64URL.
On obtient ainsi le JWT : { header }.{ payload }.{ signature }
Préparation
Afin de tester cette API, il faut dans un premier temps générer une clé au format PEM en suivant les étapes ci-dessous :
- openssl req -new -out monserveur.csr
Pour créer une demande certificate (.csr = certificat signing request)
Cela crée deux fichiers : monserveur.csr et privkey.pem
- openssl rsa -in privkey.pem -out monserveur.key
Cela crée le fichier monserveur.key (clé privée sans le mot de passe)
- openssl x509 -in monserveur.csr -out monserveur.cert -req -signkey monserveur.key
Cela crée le fichier monserveur.cert, qui est le certificat.
Paramètres d’appels de Qc3VerifySignature
- Signature
La signature est fournie en BASE64, il faut la convertir en binaire pour la fournir à l’API
- Longueur de signature
La longueur de la signature fournie après sa conversion
- Donnée à contrôler
{ header }.{ payload } en ASCII
- Longueur de la donnée à contrôler
- Format de la donnée à contrôler
- Description de l’algorithme
C’ ‘est une Data Structure qui contient les paramètres de l’algorithme.
- Format de la description de l’algorithme
- Description de la clé
C’ ‘est une Data Structure qui contient les paramètres de la clé.
- Format de la description de la clé
- Fournisseur de service cryptographique (0, 1 ou 2)
- Nom du périphérique de cryptographie (à blanc si fournisseur 1 ou 0)
- Code Erreur
C’est une Data Structure qui indique le code retour de l’exécution
Cinématique
Pour mettre en place l’appel à Qc3VerifySignature, nous avons défini les formats suivants :
- Données DATA0100 : La donnée est contrôlée sur sa valeur et sa longueur
- Algorithme ALGD0400 : Paramètres pour une opération de vérification de signature
- Clé KEYD0600 : Certificat PEM (voir paragraphe « Préparation »)
Données
On crée la donnée à contrôler en concaténant header et payload, séparés d’un point, comme expliqué au paragraphe précédent.
Exemple :
ATTENTION : Il faut, pour être utilisable, que celle-ci soit en ASCII. Pour ce faire on utilise le programme système QDCXLATE qui permet de faire de la conversion de chaines de caractères grâce à des tables système.
Data Structure du format ALGD0400 (algorithme) :
cipher INT(10) inz(50) // Code secret pour RSA , initialisé à 50
PKA CHAR(1) inz(1) // PKCS bloc 01
filler CHAR(3) inz(x’000000’) // Réservé : ce champ doit rester NULL
hash INT(10) inz(3) // Signature Algorithme de Hash 3=SHA256
Data Structure du format KEYD0600 (clé) :
keylen INT(10) // Longueur du certificat PEM
filler CHAR(4) inz(x’00000000′) // Réservé : ce champ doit rester NULL
key CHAR(4096) CCSID(65535) // Certificat PEM en ASCII
Code Retour
L’appel de l’API avec les paramètres choisis , retourne un Data Structure ErrorCode décrite ci-dessous :
bytesProv INT(10) inz( %size( ErrorCode ) ); // ou 64 pour voir MSGID
bytesAvail INT(10) inz(0);
MSGID CHAR(7);
filler CHAR (1);
data CHAR (48);
Dans le cas où la signature est vérifiée, les valeurs retour sont les suivantes
- BYTESPROV = 64
- BYTESAVAIL = 0
- MSGID = ‘ ‘
- FILLER = ‘ ‘
- DATA = ‘ ‘
Si la signature n’est pas vérifiée, les valeurs retour seront :
- BYTESPROV = 64
- BYTESAVAIL = 15
- MSGID = ‘CPF9DEF’
- FILLER = ‘0’
- DATA = ‘ ‘
