Paramètres des API

réalité, les API ne sont pas aussi compliquées qu’il y paraît.

Examinons l’API Encrypt Data. La figure 2 montre le prototype de fonction C de cette API. On peut diviser les paramètres de ce prototype en six groupes.
Les paramètres qui décrivent les données d’entrée. La figure 3A nous montre ces trois paramètres. On spécifie les données à crypter dans le paramètre 1 (clear data) de l’une des deux manières suivantes :

• Un bloc de données unique est la méthode la plus simple pour spécifier les données d’entrée.
• Une matrice de pointeurs et de longueurs de données est utilisée pour crypter les données qui ne sont pas dans le stockage contigu.

Le paramètre 3 (clear data format name) indique quel format est utilisé dans le paramètre clear data. DATA0100 indique que c’est un bloc unique de données et DATA0200 indique que c’est une matrice (voir la documentation de l’API Cryptographic Services pour la structure de la matrice DATA0200, ainsi que pour les autres structures dont il est question dans cet article). Le paramètre 2 (length of clear data) indique la longueur des données dans le paramètre clear data. Pour le format DATA0100, c’est la longueur de clear data. Pour le format DATA0200, c’est le nombre d’entrées dans la matrice.

Les paramètres qui décrivent l’algorithme

cryptographique. Les deux paramètres de la figure 3B apparaissent sur beaucoup des API Cryptographic Services.
Comme les noms l’indiquent, elles décrivent l’algorithme cryptographique. On peut diviser les algorithmes cryptographiques supportés en quatre classes :

• Algorithmes de chiffrement par blocs (DES, TDES, AES, RC2)
• Algorithmes de chiffrement par flux (compatibles RC4)
• Algorithmes PKA (RSA)
• Algorithmes hash (MD5, SHA-1, SHA-256, SHA-384, SHA- 512)
(A noter que bien que les API supportent des algorithmes supplémentaires, le paramètre algorithm description n’est pas utilisé pour les décrire.)

Chacune des classes d’algorithmes ci-dessus nécessite son propre ensemble d’arguments et chacune a au moins un argument – type d’algorithme (par exemple, AES). Certaines, comme les blocs de chiffrement, ont plusieurs arguments supplémentaires (par exemple, longueur de bloc, mode, option pad).
Une structure est définie pour chacune de ces classes d’algorithmes, pour spécifier les arguments de l’algorithme. Le paramètre 4 (algorithm description) pointe vers l’une de ces structures ; le paramètre 5 (algorithm description format name) identifie la structure qui est utilisée. Les noms de formats sont :

• ALGD0200 pour les arguments de chiffrement par blocs
• ALGD0300 pour les arguments de chiffrement par flux
• ALGD0400 pour les arguments PKA
• ALGD0500 pour les arguments hash

Bien entendu, sur l’API Encrypt Data, la structure ALGD0500 ne serait pas valide parce qu’on ne peut pas crypter avec un algorithme hash. En outre, ALGD0100 est une structure de description d’algorithme spéciale qui fait référence à un contexte d’algorithme. On utilise un contexte d’algorithme pour étendre des opérations cryptographiques sur des appels multiples. Nous reviendrons plus en détail sur les contextes des algorithmes.

Les paramètres qui décrivent

la clé cryptographique. La figure 3C montre ces deux paramètres. De la même manière que l’algorithme, la clé est décrite via une structure d’arguments.
Le paramètre 6 (key description) pointe vers la structure et le paramètre 7 (key description format name) identifie la structure utilisée:

• La structure KEYD0200 spécifie le type de clé (TDES, RSA, par exemple), le format de clé (binaire ou codée BER), la longueur de clé et la valeur de clé.
• La structure KEYD0100 fait référence à un contexte de clé qui est utilisé quand la clé est cryptée ou qui sera utilisé sur des opérations multiples. (Nous reviendrons sur les contextes de clés.)

Les paramètres qui identifient le fournisseur de service cryptographique (CSP, cryptographic service provider). On voit ces deux paramètres dans la figure 3D.
Le i5/OS supporte plusieurs CSP (le matériel ou le logiciel qui met en oeuvre un ensemble d’algorithmes cryptographiques), tels que le 2058 Cryptographic Accelerator, le 4758 Cryptographic Coprocessor, le i5/OS LIC, et Java Cryptography Extensions. Les API Cryptographic Services supportent deux CSP : le LIC et le 2058 Cryptographic Accelerator.

Le paramètre 8 (cryptographic service provider) indique le CSP utilisé pour effectuer le décryptage. Une valeur de 1 exécutera l’algorithme de cryptage dans le LIC et une valeur de 2 l’exécutera sur le premier 2058 Cryptographic Accelerator disponible. Si vous désirez une unité 2058 spécifique, vous pouvez spécifier son nom dans le paramètre 9 (cryptographic device name). Si le 2058 Cryptographic Accelerator ne supporte pas l’algorithme spécifié, une erreur est renvoyée.

Le moyen le plus simple de sélectionner un CSP consiste à spécifier une valeur de 0, qui ordonne au système de choisir un CSP approprié. Le 2058 Cryptographic Accelerator est utilisé s’il y en a un de disponible et s’il supporte l’algorithme spécifié. Sinon, le cryptage est effectué dans le LIC. (A noter que certaines fonctions seront toujours effectuées dans le LIC. Pour une liste de ces fonctions, voir « OS/400 et 2058 Cryptographic Function Comparison » figurant dans l’encadré Pour en savoir plus.) Les paramètres pour les données de sortie. La figure 3E montre les trois paramètres dans cette catégorie. Le paramètre 10 (encrypted data) et le paramètre 12 (length of encrypted data returned) – qui tous deux sont des paramètres de sortie – sont l’endroit où de telles données sont renvoyées. Le paramètre 11 (length of area provided for encrypted data) – un paramètre d’entrée – est l’endroit où vous spécifiez ce genre d’information. Selon l’algorithme, les données cryptées peuvent être plus grandes que les données en clair. Ainsi, la longueur des données cryptées par RSA est toujours égale à la taille de la clé. Ou, si vous spécifiez le remplissage d’un chiffrement par blocs, le dernier bloc des données en clair sera rempli jusqu’à une taille de bloc complet avant le cryptage. Si la longueur de la zone fournie pour les données cryptées est trop petite, une erreur est renvoyée sans aucune donnée cryptée.

Le paramètre pour le code d’erreur. Enfin, le paramètre 13 (error code) dans la figure 3F renvoie une information d’erreur. Le paramètre error code est une structure de longueur variable qui est commune à toute les API système. (Vous trouverez de la documentation sur le paramètre error code à publib.boulder.ibm.com/infocenter/ iseries/v5r3/ ic2924/info/apis/error.htm#hdrerrcod.) De nombreuses API Cryptographic Services utilisent des paramètres et des structures identiques ou similaires à ceux que je viens de décrire.