, , Authentification par JWT (Json Web Token)

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 = ‘                                                ‘
, , , QCMDEXC en Fonction SQL

Depuis la TR4 de la version V7R4, vous pouvez utiliser la fonction QCMDEXC

C’est l’occasion de faire un rappel sur les différents usages disponibles jusque la

1 ) C’est une api (un programme) que vous pouvez appelez depuis un programme RPG ou CLP

en RPGLE

Dcl-Pr Exec_Commande QCMDEXC ExtPgm(‘QCMDEXC’);
Cmd Char(3000) Const;
CmdLen packed(15:5) Const;
End-Pr;

Dcl-S Gbl_Cmd Char(3000);

Gbl_Cmd = ‘Votre commande’ ;

Exec_commande(Gbl_Cmd : %len(Gbl_Cmd)) ;

En CLLE

PGM
DCL &CMD *CHAR 300
DCL &LEN *DEC (15 5)

CHGVAR &CMD (‘VOTRE COMMANDE’)
CHGVAR &LEN %LEN(&CMD)
CALL QCMDEXC (&CMD &LEN)

2) C’est une procédure SQL

call qcmdexc(‘votre commande’)

en sql embarqué

Dcl-S Gbl_Cmd Char(3000);

call qcmdexc(:Gbl_Cmd)

3) C’est une Fonction SQL à partir de la TR4

réorganisation des fichiers BD

SELECT qcmdexc(‘RGZPFM FILE(‘ concat
trim(substr(TABLE_SCHEMA, 1 , 10))
concat ‘/’ concat
substr(TABLE_NAME, 1 , 10) concat ‘)’) as résultat
FROM systables WHERE TABLE_SCHEMA =
‘GDATA’ and FILE_TYPE = ‘D’

la fonction renvoi 1 si ok et -1 si ko

Conclusion :
Vous avez un aperçu des possibilités qcmdexc sur la machine, à vous de jouer !

, , UTILISATION DES API EN SQL

Récupérer une API

Il existe un grand nombre d’API aux fonctionnalités diverses dont certaines nous permettent de récupérer des données structurées dans différents formats (XML, JSON, …).

Grace aux fonctions SQL de l’IBMi nous pouvons récupérer ces données pour les insérer dans les fichiers de la base de données.

Pour les exemples qui suivent, on se base sur trois API tirées du site https://openweathermap.org/ :

  • Une première qui récupère la météo dans une ville donnée

https://api.openweathermap.org/data/2.5/weather?q={city name}&appid={API key}&mode=xml’

  • Une qui récupère jusqu’à 50 communes autour de coordonnées choisies

https://api.openweathermap.org/data/2.5/find?lat=45.75&lon=4.5833&cnt=50&appid={API key}&mode=xml

  • Une qui récupère jusqu’à des communes dans un rectangle de coordonnées choisies

https:// api.openweathermap.org/data/2.5/box/city?bbox=4,45,8,46,50&appid={API key}

Extraire les données de l’API

Sortie API en XML

La commande SQL suivante permet d’afficher les données dans un champ DATA 

SELECT DATA FROM (values
char(SYSTOOLS.HTTPGETCLOB('https://api.openweathermap.org/data/2.5/weather?q={city name}&appid={API key}&mode=xml',''), 4096))
ws(data);

Sortie API en JSON

La commande SQL suivante permet d’afficher les données dans un champ DATA 

SELECT DATA FROM (values
char(SYSTOOLS.HTTPGETCLOB('api.openweathermap.org/data/2.5/weather?q={city name}&appid={API key}',''), 4096))
ws(data);

Sortie API en HTML

La commande SQL suivante permet d’afficher les données dans un champ DATA 

SELECT DATA FROM (values
char(SYSTOOLS.HTTPGETCLOB('https://api.openweathermap.org/data/2.5/weather?q={city name}&appid={API key}&mode=html',''), 4096))
ws(data);

Récupération des données

En XML

On crée un fichier qui contiendra les colonnes que l’on veut récupérer (Ville, Température en cours, date, …)

CREATE TABLE GG/METEODB
(VILLE_ID DECIMAL (9, 0) NOT NULL WITH DEFAULT,
VILLE_NOM CHAR (50) NOT NULL WITH DEFAULT,
TEMPERATURE DECIMAL (5, 2) NOT NULL WITH DEFAULT,
TEMP_MIN DECIMAL (5, 2) NOT NULL WITH DEFAULT,
TEMP_MAX DECIMAL (5, 2) NOT NULL WITH DEFAULT,
DATE_MAJ CHAR (20) NOT NULL WITH DEFAULT)
;

Récupérer les données de l’API dans le fichier créé :

INSERT INTO GG.METEODB
select xdata.* FROM xmltable('$doc/cities/list/item'
PASSING XMLPARSE(document SYSTOOLS.HTTPGETCLOB('https://api.openweathermap.org/data/2.5/find?lat=45.75&lon=4.5833&cnt=10&appid={API key}&mode=xml','')) AS "doc"
COLUMNS
ville_id decimal(9, 0) PATH 'city/@id',
ville_nom varchar(50) PATH 'city/@name',
temperature decimal(5, 2) PATH 'temperature/@value',
temp_min decimal(5, 2) PATH 'temperature/@min',
temp_max decimal(5, 2) PATH 'temperature/@max',
date_maj varchar(20) PATH 'lastupdate/@value' ) as xdata;

En JSON

Contrairement à XML, on peut créer tout de suite un fichier qui contiendra les colonnes que l’on veut récupérer.

CREATE TABLE GG.METEOBD
(VILLE_ID DECIMAL (9, 0) NOT NULL WITH DEFAULT,
VILLE_NOM CHAR (50) NOT NULL WITH DEFAULT,
TEMPERATURE DECIMAL (5, 2) NOT NULL WITH DEFAULT,
TEMP_MIN DECIMAL (5, 2) NOT NULL WITH DEFAULT,
TEMP_MAX DECIMAL (5, 2) NOT NULL WITH DEFAULT,
DATE_UX_MAJ DECIMAL (12, 0) NOT NULL WITH DEFAULT)

Récupérer les données de l’API dans le fichier créé :

INSERT INTO GG.METEOBD
select * from JSON_TABLE(SYSTOOLS.HTTPGETCLOB('https://api.openweathermap.org/data/2.5/box/city?bbox=4,45,8,46,50&appid={API key}','') ,
'$.list[*]'
COLUMNS
(ville_id decimal(9, 0) PATH '$.id',
ville_nom varchar(50) PATH '$.name',
temperature decimal(5, 2) PATH '$.main.temp',
temp_min decimal(5, 2) PATH '$.main.temp_min',
temp_max decimal(5, 2) PATH '$.main.temp_max',
date_ux_maj decimal(12, 0) PATH '$.dt'));

Pour aller plus loin

En utilisant une API de LA POSTE qui ne nécessite pas d’inscription au préalable, ni d’identification. Nous pouvons réaliser un programme qui nous aide à retrouver une commune à partir d’un code postal, dans l’optique d’aider au remplissage de certains formulaires.
On crée un fichier temporaire en interrogeant directement l’API.