NOM¶

EVP_CIPHER_CTX_init, EVP_EncryptInit_ex, EVP_EncryptUpdate, EVP_EncryptFinal_ex, EVP_DecryptInit_ex, EVP_DecryptUpdate, EVP_DecryptFinal_ex, EVP_CipherInit_ex, EVP_CipherUpdate, EVP_CipherFinal_ex, EVP_CIPHER_CTX_set_key_length, EVP_CIPHER_CTX_ctrl, EVP_CIPHER_CTX_cleanup, EVP_EncryptInit, EVP_EncryptFinal, EVP_DecryptInit, EVP_DecryptFinal, EVP_CipherInit, EVP_CipherFinal, EVP_get_cipherbyname, EVP_get_cipherbynid, EVP_get_cipherbyobj, EVP_CIPHER_nid, EVP_CIPHER_block_size, EVP_CIPHER_key_length, EVP_CIPHER_iv_length, EVP_CIPHER_flags, EVP_CIPHER_mode, EVP_CIPHER_type, EVP_CIPHER_CTX_cipher, EVP_CIPHER_CTX_nid, EVP_CIPHER_CTX_block_size, EVP_CIPHER_CTX_key_length, EVP_CIPHER_CTX_iv_length, EVP_CIPHER_CTX_get_app_data, EVP_CIPHER_CTX_set_app_data, EVP_CIPHER_CTX_type, EVP_CIPHER_CTX_flags, EVP_CIPHER_CTX_mode, EVP_CIPHER_param_to_asn1, EVP_CIPHER_asn1_to_param, EVP_CIPHER_CTX_set_padding, EVP_enc_null, EVP_des_cbc, EVP_des_ecb, EVP_des_cfb, EVP_des_ofb, EVP_des_ede_cbc, EVP_des_ede, EVP_des_ede_ofb, EVP_des_ede_cfb, EVP_des_ede3_cbc, EVP_des_ede3, EVP_des_ede3_ofb, EVP_des_ede3_cfb, EVP_desx_cbc, EVP_rc4, EVP_rc4_40, EVP_idea_cbc, EVP_idea_ecb, EVP_idea_cfb, EVP_idea_ofb, EVP_idea_cbc, EVP_rc2_cbc, EVP_rc2_ecb, EVP_rc2_cfb, EVP_rc2_ofb, EVP_rc2_40_cbc, EVP_rc2_64_cbc, EVP_bf_cbc, EVP_bf_ecb, EVP_bf_cfb, EVP_bf_ofb, EVP_cast5_cbc, EVP_cast5_ecb, EVP_cast5_cfb, EVP_cast5_ofb, EVP_rc5_32_12_16_cbc, EVP_rc5_32_12_16_ecb, EVP_rc5_32_12_16_cfb, EVP_rc5_32_12_16_ofb, EVP_aes_128_gcm, EVP_aes_192_gcm, EVP_aes_256_gcm, EVP_aes_128_ccm, EVP_aes_192_ccm, EVP_aes_256_ccm - Routines de chiffrement EVP

SYNOPSIS¶

#include <openssl/evp.h>

void EVP_CIPHER_CTX_init(EVP_CIPHER_CTX *a);

int EVP_EncryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
ENGINE *impl, unsigned char *key, unsigned char *iv);
int EVP_EncryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
int *outl, unsigned char *in, int inl);
int EVP_EncryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *out,
int *outl);

int EVP_DecryptInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
ENGINE *impl, unsigned char *key, unsigned char *iv);
int EVP_DecryptUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
int *outl, unsigned char *in, int inl);
int EVP_DecryptFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm,
int *outl);

int EVP_CipherInit_ex(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
ENGINE *impl, unsigned char *key, unsigned char *iv, int enc);
int EVP_CipherUpdate(EVP_CIPHER_CTX *ctx, unsigned char *out,
int *outl, unsigned char *in, int inl);
int EVP_CipherFinal_ex(EVP_CIPHER_CTX *ctx, unsigned char *outm,
int *outlB);>

int EVP_EncryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
unsigned char *key, unsigned char *iv);
int EVP_EncryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *out,
int *outl);

int EVP_DecryptInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
unsigned char *key, unsigned char *iv);
int EVP_DecryptFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm,
int *outl);

int EVP_CipherInit(EVP_CIPHER_CTX *ctx, const EVP_CIPHER *type,
unsigned char *key, unsigned char *iv, int enc);
int EVP_CipherFinal(EVP_CIPHER_CTX *ctx, unsigned char *outm,
int *outl);

int EVP_CIPHER_CTX_set_padding(EVP_CIPHER_CTX *x, int padding);
int EVP_CIPHER_CTX_set_key_length(EVP_CIPHER_CTX *x, int keylen);
int EVP_CIPHER_CTX_ctrl(EVP_CIPHER_CTX *ctx, int type, int arg, void *ptr);
int EVP_CIPHER_CTX_cleanup(EVP_CIPHER_CTX *a);

const EVP_CIPHER *EVP_get_cipherbyname(const char *name);
#define EVP_get_cipherbynid(a) EVP_get_cipherbyname(OBJ_nid2sn(a))
#define EVP_get_cipherbyobj(a) EVP_get_cipherbynid(OBJ_obj2nid(a))

#define EVP_CIPHER_nid(e) ((e)->nid)
#define EVP_CIPHER_block_size(e) ((e)->block_size)
#define EVP_CIPHER_key_length(e) ((e)->key_len)
#define EVP_CIPHER_iv_length(e) ((e)->iv_len)
#define EVP_CIPHER_flags(e) ((e)->flags)
#define EVP_CIPHER_mode(e) ((e)->flags) & EVP_CIPH_MODE)
int EVP_CIPHER_type(const EVP_CIPHER *ctx);

#define EVP_CIPHER_CTX_cipher(e) ((e)->cipher)
#define EVP_CIPHER_CTX_nid(e) ((e)->cipher->nid)
#define EVP_CIPHER_CTX_block_size(e) ((e)->cipher->block_size)
#define EVP_CIPHER_CTX_key_length(e) ((e)->key_len)
#define EVP_CIPHER_CTX_iv_length(e) ((e)->cipher->iv_len)
#define EVP_CIPHER_CTX_get_app_data(e) ((e)->app_data)
#define EVP_CIPHER_CTX_set_app_data(e,d) ((e)->app_data=(char *)(d))
#define EVP_CIPHER_CTX_type(c) EVP_CIPHER_type(EVP_CIPHER_CTX_cipher(c))
#define EVP_CIPHER_CTX_flags(e) ((e)->cipher->flags)
#define EVP_CIPHER_CTX_mode(e) ((e)->cipher->flags & EVP_CIPH_MODE)

int EVP_CIPHER_param_to_asn1(EVP_CIPHER_CTX *c, ASN1_TYPE *type);
int EVP_CIPHER_asn1_to_param(EVP_CIPHER_CTX *c, ASN1_TYPE *type);

DESCRIPTION¶

Les routines de chiffrement EVP sont des interfaces de haut niveau pour certains algorithmes de chiffrement symétrique.

EVP_CIPHER_CTX_init() initialise le contexte de chiffrement ctx.

EVP_EncryptInit_ex() définit le contexte de chiffrement ctx pour un chiffrement avec l’algorithme de type de l’ENGINE impl. ctx doit être initialisé avant l’appel de cette fonction. type est normalement fourni par une fonction telle que EVP_des_cbc(). Si impl est NULL, alors l’implémentation par défaut est utilisée. key est la clef symétrique à utiliser et iv est le vecteur d'initialisation à utiliser (si nécessaire) ; le nombre réel d’octets à utiliser pour la clef et le vecteur dépend de l’algorithme. Il est possible de définir tous les paramètres à NULL à l’exception de type lors de l’appel initial et fournir les paramètres restants lors les prochains appels en ayant tous type définis à NULL. Cela est fait quand les paramètres de l’algorithme ne sont pas adéquats.

EVP_EncryptUpdate() chiffre inl octets du tampon in et écrit le résultat dans out. Cette fonction peut être appelée de multiples fois pour chiffrer des blocs successifs de données. Le total des données écrites est fonction de l’alignement des blocs : par conséquent, le total des données écrites peut être de zéro octet jusqu’à (inl + cipher_block_size − 1), aussi out doit être suffisamment grand. Le nombre réel d’octets écrits est placé dans outl.

Si le remplissage est activé (action par défaut), alors EVP_EncryptFinal_ex() chiffre les données « finales », c’est-à-dire les données restantes dans un bloc incomplet. Pour cela, le remplissage par bloc standard (alias remplissage PKCS) est utilisé. Les données finales chiffrées sont écrites dans out qui doit être suffisamment grand pour un bloc chiffré. Le nombre d’octets écrits est placé dans outl. Après l’appel de cette fonction l’opération de chiffrement est terminée et aucun appel ne peut plus être fait à EVP_EncryptUpdate().

Si le remplissage n’est pas activé, alors EVP_EncryptFinal_ex() ne chiffrera plus aucune donnée et une erreur sera renvoyée si quelques données subsistent dans un bloc incomplet : c’est-à-dire, la taille totale des données n’est pas un multiple de la taille du bloc.

EVP_DecryptInit_ex(), EVP_DecryptUpdate()et EVP_DecryptFinal_ex() sont les opérations de déchiffrement correspondantes. EVP_DecryptFinal() renverra un code d’erreur si le remplissage est activé et le bloc final non correctement formaté. Les paramètres et limitations sont identiques aux opérations de chiffrement à l’exception que, si le remplissage est activé, le tampon out des données déchiffrées transmis pour EVP_DecryptUpdate() doit être de taille suffisante pour (inl + cipher_block_size) octets, à moins que la taille du bloc de chiffrement soit 1, auquel cas inl octets sont suffisants.

EVP_CipherInit_ex(), EVP_CipherUpdate() et EVP_CipherFinal_ex() sont des fonctions qui peuvent être utilisées pour le chiffrement et le déchiffrement. L’opération réalisée dépend de la valeur du paramètre enc. Il doit être défini à 1 pour le chiffrement, 0 pour le déchiffrement et -1 pour ne pas changer sa valeur (la valeur du moment de « enc » fournie par un précédent appel).

EVP_CIPHER_CTX_cleanup() supprime toute donnée d’un contexte de chiffrement et libère toute mémoire qui lui soit allouée. Cette fonction doit être appelée après toute opération de chiffrement de façon qu’aucune donnée sensible ne subsiste en mémoire.

EVP_EncryptInit(), EVP_DecryptInit() et EVP_CipherInit() se comportent de manière similaire à EVP_EncryptInit_ex(), EVP_DecryptInit_ex et EVP_CipherInit_ex() à l’exception que les paramètres de ctx n’ont nul besoin d’être initialisés et utilisent toujours l’implémentation par défaut de l’algorithme de chiffrement.

EVP_EncryptFinal(), EVP_DecryptFinal() et EVP_CipherFinal() se comportent de manière similaire à EVP_EncryptFinal_ex(), EVP_DecryptFinal_ex() et EVP_CipherFinal_ex() à l’exception que ctx est automatiquement nettoyé après l’appel.

EVP_get_cipherbyname(), EVP_get_cipherbynid() et EVP_get_cipherbyobj() renvoient une structure EVP_CIPHER lorsqu’un nom d’algorithme de chiffrement, un NID ou une structure ASN1_OBJECT est fourni.

EVP_CIPHER_nid() et EVP_CIPHER_CTX_nid() renvoie l’identifiant NID d’un chiffrement lorsqu’une structure EVP_CIPHER ou EVP_CIPHER_CTX est fournie. La valeur courante du NID est une valeur interne qui pourrait ne pas avoir un OBJECT IDENTIFIER correspondant.

EVP_CIPHER_CTX_set_padding() autorise ou non le remplissage. Par défaut le remplissage des opérations de chiffrement est fait en utilisant le remplissage de bloc standard et est contrôlé puis supprimé lors du déchiffrement. Si le paramètre pad vaut zéro, alors aucun remplissage n’est réalisé, le total des données chiffrées ou déchiffrées doit alors être un multiple de la taille de bloc ou une erreur s’ensuivra.

EVP_CIPHER_key_length() et EVP_CIPHER_CTX_key_length() renvoient la longueur de clef d’un chiffrement quand une structure EVP_CIPHER ou EVP_CIPHER_CTX est fournie. La constante EVP_MAX_KEY_LENGTH est la longueur maximale de clef pour tous les algorithmes de chiffrement. Remarque : bien que EVP_CIPHER_key_length() est déterminée pour un algorithme de chiffrement, la valeur de EVP_CIPHER_CTX_key_length() peut être différente pour des longueurs de clef variables d’algorithme de chiffrement.

EVP_CIPHER_CTX_set_key_length() définit la longueur de clef d’un contexte de chiffrement. Si le chiffrement a une longueur fixe de clef, alors essayer de définir la longueur de clef à une valeur différente est fautif.

EVP_CIPHER_iv_length() et EVP_CIPHER_CTX_iv_length() renvoient la longueur du vecteur d'initialisation du chiffrement lorsque est fournie EVP_CIPHER ou EVP_CIPHER_CTX. Zéro sera renvoyé si l’algorithme de chiffrement n’utilise pas de vecteur d'initialisation. La constante EVP_MAX_IV_LENGTH est la longueur maximale du vecteur d'initialisation de tous les algorithmes de chiffrement.

EVP_CIPHER_block_size() et EVP_CIPHER_CTX_block_size3() renvoie la taille de bloc d’un chiffrement lorsqu'est fourni une structure EVP_CIPHER ou EVP_CIPHER_CTX. La constante EVP_MAX_IV_LENGTH est aussi la longueur maximale pour les algorithmes de chiffrement.

EVP_CIPHER_type() et EVP_CIPHER_CTX_type() renvoient le type des algorithmes de chiffrement ou de contexte. Ce « type » est l’identifiant NID réel de OBJECT IDENTIFIER du chiffrement et donc ignore les paramètres de l’algorithme, et RC2 40 bits et RC2 128 bits ont le même NID. Si l’algorithme n’a pas d’identifiant objet ou n’est pas pris en charge par ASN1, cette fonction renverra NID_undef.

EVP_CIPHER_CTX_cipher() renvoie la structure EVP_CIPHER lorsqu’est fournie une structure EVP_CIPHER_CTX.

EVP_CIPHER_mode() et EVP_CIPHER_CTX_mode() renvoient le mode de chiffrement par bloc : EVP_CIPH_ECB_MODE, EVP_CIPH_CBC_MODE, EVP_CIPH_CFB_MODE ou EVP_CIPH_OFB_MODE. Si le chiffrement est un chiffrement par flot, alors EVP_CIPH_STREAM_CIPHER est renvoyé.

EVP_CIPHER_param_to_asn1() définit le « paramètre » AlgorithmIdentifier en fonction de l’algorithme de chiffrement fourni. Classiquement, cela inclut n’importe quel paramètre et un vecteur d'initialisation. Le vecteur du chiffrement (s’il existe) doit être défini quand cet appel est fait. Cet appel doit être fait avant que l’algorithme soit pratiquement « utilisé » (avant n’importe quel appel EVP_EncryptUpdate(), EVP_DecryptUpdate() par exemple). Cette fonction peut échouer si l’algorithme n’est nullement pris en charge par ASN1.

EVP_CIPHER_asn1_to_param() définit les paramètres de l’algorithme de chiffrement en fonction des « paramètres » ASN1 AlgorithmIdentifier. L’effet exact dépend de l’algorithme. Dans le cas de RC2 par exemple, le vecteur d'initialisation et la clef utilisée seront définis. Cette fonction devrait être appelée après que le type de l’algorithme de base soit défini mais avant que la clef ne soit définie. Par exemple EVP_CipherInit() sera appelée avec le vecteur et la clef définis à NULL, EVP_CIPHER_asn1_to_param() sera appelée puis finalement EVP_CipherInit() le sera avec tous les paramètres sauf la clef définie à NULL. Il est possible que cette fonction échoue si l’algorithme n’est nullement pris en charge par ASN1 ou que les paramètres ne peuvent être définis (par exemple, la longueur réelle de la clef RC2 n’est pas prise en charge).

EVP_CIPHER_CTX_ctrl() permet de déterminer et définir les paramètres particuliers de différents algorithmes.

VALEURS DE RETOUR¶

EVP_EncryptInit_ex(), EVP_EncryptUpdate() et EVP_EncryptFinal_ex() renvoient 1 lors d’un succès et 0 lors d’un échec.

EVP_DecryptInit_ex() et EVP_DecryptUpdate() renvoient 1 lors d’un succès et 0 lors d’un échec. EVP_DecryptFinal_ex() renvoie 0 si le déchiffrement est un échec ou 1 si c’est une réussite.

EVP_CipherInit_ex() et EVP_CipherUpdate() renvoient 1 pour un succès et 0 pour un échec. EVP_CipherFinal_ex() renvoie 0 pour un échec de déchiffrement et 1 pour une réussite.

EVP_CIPHER_CTX_cleanup() renvoie 1 pour un succès et 0 pour un échec.

EVP_get_cipherbyname(), EVP_get_cipherbynid() et EVP_get_cipherbyobj() renvoient une structure EVP_CIPHER ou NULL en cas d’erreur.

EVP_CIPHER_nid() et EVP_CIPHER_CTX_nid() renvoient un identifiant NID.

EVP_CIPHER_block_size() et EVP_CIPHER_CTX_block_size() renvoient la taille de bloc.

EVP_CIPHER_key_length() et EVP_CIPHER_CTX_key_length() renvoient la longueur de clef.

EVP_CIPHER_CTX_set_padding() renvoie toujours 1.

EVP_CIPHER_iv_length() et EVP_CIPHER_CTX_iv_length() renvoient la longueur du vecteur d'initialisation ou 0 si l’algorithme de chiffrement n’utilise pas de vecteur.

EVP_CIPHER_type() et EVP_CIPHER_CTX_type() renvoient le NID du OBJECT IDENTIFIER de l’algorithme de chiffrement ou NID_undef s’il n’a aucun OBJECT IDENTIFIER de défini.

EVP_CIPHER_CTX_cipher() renvoie une structure EVP_CIPHER.

EVP_CIPHER_param_to_asn1() et EVP_CIPHER_asn1_to_param() renvoient 1 pour une réussite ou zéro pour un échec.

LISTE DES ALGORITHMES DE CHIFFREMENT¶

Tous les algorithmes ont une longueur fixe de clef sauf stipulation contraire.

EVP_enc_null()

Algorithme NULL, sans action

EVP_des_cbc(void), EVP_des_ecb(void), EVP_des_cfb(void), EVP_des_ofb(void)

Respectivement, DES avec les modes CBC, ECB, CFB et OFB.

EVP_des_ede_cbc(void), EVP_des_ede(), EVP_des_ede_ofb(void), EVP_des_ede_cfb(void)

Respectivement, triple DES à deux clefs avec les modes CBC, ECB, CFB et OFB.

EVP_des_ede3_cbc(void), EVP_des_ede3(), EVP_des_ede3_ofb(void), EVP_des_ede3_cfb(void)

Respectivement, triple DES à trois clefs avec les modes CBC, ECB, CFB et OFB.

EVP_desx_cbc(void)

Algorithme DESX avec le mode CBC.

EVP_rc4(void)

Chiffrement par flot RC4. Algorithme avec une longueur de clef variable, par défaut 128 bits.

EVP_rc4_40(void)

Algorithme de chiffrement RC4 avec une longueur de clef de 40 bits. Obsolète, de préférence utiliser EVP_rc4() et la fonction EVP_CIPHER_CTX_set_key_length().

EVP_idea_cbc() EVP_idea_ecb(void), EVP_idea_cfb(void), EVP_idea_ofb(void), EVP_idea_cbc(void)

Algorithme de chiffrement IDEA avec les modes CBC, ECB, CFB et OFB respectivement.

EVP_rc2_cbc(void), EVP_rc2_ecb(void), EVP_rc2_cfb(void), EVP_rc2_ofb(void)

Algorithme de chiffrement RC2 avec respectivement les modes CBC, ECB, CFB, et OFB. Algorithme avec une longueur de clef variable et un paramètre additionnel « effective key bits » ou « effective key length » (par défaut, défini à 128 bits).

EVP_rc2_40_cbc(void), EVP_rc2_64_cbc(void)

Algorithme de chiffrement RC2 avec le mode CBC et par défaut, une longueur de clef et une longueur de clef efficace de 40 et 64 bits. Obsolète, de préférence utiliser EVP_rc2_cbc(), EVP_CIPHER_CTX_set_key_length() et EVP_CIPHER_CTX_ctrl() pour définir la longueur de clef et la longueur de clef efficace.

EVP_bf_cbc(void), EVP_bf_ecb(void), EVP_bf_cfb(void), EVP_bf_ofb(void);

Algorithme de chiffrement Blowfish avec respectivement les modes CBC, ECB, CFB et OFB. Algorithme à longueur de clef variable.

EVP_cast5_cbc(void), EVP_cast5_ecb(void), EVP_cast5_cfb(void), EVP_cast5_ofb(void)

Algorithme de chiffrement CAST avec respectivement les modes CBC, ECB, CFB et OFB. Algorithme à longueur de clef variable.

EVP_rc5_32_12_16_cbc(void), EVP_rc5_32_12_16_ecb(void), EVP_rc5_32_12_16_cfb(void), EVP_rc5_32_12_16_ofb(void)

Algorithme de chiffrement RC5 avec respectivement les modes CBC, ECB, CFB et OFB. Algorithme à longueur de clef variable avec un paramètre additionnel « nombre de tours ». Par défaut, la longueur de clef est de 128 bits et le nombre de tours 12.

EVP_aes_128_gcm(void), EVP_aes_192_gcm(void), EVP_aes_256_gcm(void)

Mode AES Galois Counter (GCM) pour des clefs respectivement de 128, 192 et 256 bits. Ces algorithmes de chiffrement demandent des opérations de contrôle supplémentaires pour fonctionner correctement. Consultez la section Mode GCM ci-dessous pour plus de détails.

EVP_aes_128_ccm(void), EVP_aes_192_ccm(void), EVP_aes_256_ccm(void)

Mode AES Counter avec CBC-MAC (CCM) pour des clefs respectivement de 128, 192 et 256 bits. Ces algorithmes de chiffrement demandent des opérations de contrôle supplémentaires pour fonctionner correctement. Consultez la section Mode CCM ci-dessous pour plus de détails.

Mode GCM¶

Pour les algorithmes de chiffrement en mode GCM, le comportement de l’interface EVP est subtilement modifiée et plusieurs opérations de contrôle spécifiques à GCM sont prises en charge.

Pour indiquer n’importe quelle autre donnée d’authentification (AAD), un appel à EVP_CipherUpdate(), EVP_EncryptUpdate() ou EVP_DecryptUpdate() devrait être fait avec le paramètre de sortie out réglé à NULL.

Lors du déchiffrement, la valeur de retour de EVP_DecryptFinal() ou EVP_CipherFinal() renseigne sur la réussite de l’opération. En cas de non succès, l’opération d’authentification a échoué et aucune donnée de sortie ne doit pas être utilisée car corrompue.

Les contrôles suivants sont pris en charge dans le mode GCM :

 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_IVLEN, ivlen, NULL);

Indication de la longueur du vecteur d'initialisation pour GCM. Cet appel peut être fait seulement avant de définir un vecteur d’initialisation Sans appel, une longueur de vecteur GCM est utilisée (96 bits pour AES).
EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_GET_TAG, taglen, tag);

Écriture de taglen octets de valeur de la balise dans le tampon indiqué par tag. Cet appel peut être fait seulement lors du chiffrement des données et après le traitement de toutes les données (p. ex., après un appel à EVP_EncryptFinal()).

 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_GCM_SET_TAG, taglen, tag);

Définition de la balise attendue à taglen octets à partir de tag. Cet appel est seulement possible lors du déchiffrement des données et doit être fait avant le traitement de toute donnée (p. ex., avant n’importe quel appel EVP_DecryptUpdate()).

Consultez EXEMPLES ci-dessous par un exemple d’utilisation du mode GCM

Mode CCM¶

Le comportement des algorithmes de chiffrement de mode CCM est similaire au mode CCM mais avec quelques obligations supplémentaires et des valeurs de contrôle différentes.

Comme pour le mode GCM, n’importe quelle autre donnée d’authentification (AAD) est fournie en appelant EVP_CipherUpdate(), EVP_EncryptUpdate() ou EVP_DecryptUpdate() avec le paramètre out défini à NULL. En plus, la longueur du texte chiffré ou non doit être fournie à EVP_CipherUpdate(), EVP_EncryptUpdate() ou EVP_DecryptUpdate() avec les paramètres d’entrée et de sortie (in et out) définis à NULL et la longueur indiquée dans le paramètre inl.

Les contrôles suivants sont pris en charge dans le mode CCM :

 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_TAG, taglen, tag);

Cet appel est fait pour définir la valeur de la balise attendue CCM lors du déchiffrement, ou la longueur de la balise (avec le paramètre tag réglé à NULL) lors du chiffrement. La longueur de la balise est souvent M. Si elle n’est pas précisée, une valeur par défaut est utilisée (12 pour AES).

 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_L, ivlen, NULL);

Définition de la valeur L du CCM. Non définie, une valeur par défaut est utilisée (8 pour AES).

 EVP_CIPHER_CTX_ctrl(ctx, EVP_CTRL_CCM_SET_IVLEN, ivlen, NULL);

Définition de la longueur (vecteur d'initialisation) circonstancielle du CGM. Cet appel peut seulement être fait avant de préciser la valeur du moment. La valeur du moment est donné par 15 - L, ainsi c’est sept par défaut pour AES.

NOTES¶

Lorsque cela est possible, l’interface EVP pour les algorithmes symétriques devrait être utilisée de préférence aux interfaces de bas niveau. Cela parce que le code devient évident pour l’algorithme utilisé et plus souple. De plus, l’interface EVP garantit l’utilisation de l’accélération de chiffrement particulière à certaines plateformes telles que AES-NI (l’interface de bas niveau n’offre aucune garantie).

Le remplissage PKCS est réalisé en ajoutant n octets de valeur n pour que la longueur totale des données chiffrées soit un multiple de la taille de bloc. Comme le remplissage est toujours réalisé, si la taille des données est déjà un multiple de la taille de bloc, n sera égal à la taille de bloc. Par exemple, si la taille de bloc est 8 et 11 octets sont à chiffrés, alors 5 bits de remplissage de valeur 5 seront ajoutés.

Lors du déchiffrement, le bloc terminal est contrôlé pour s’assurer de sa forme correcte.

Bien que l’opération de déchiffrement puisse produire une erreur si le remplissage est activé, cela n’est pas un test fort pour l’exactitude des données d’entrée ou de la clef. Un bloc aléatoire a au mieux une chance sur 256 d’être d’un format correct et les problèmes avec les données précédentes ne provoqueront pas une erreur finale de déchiffrement.

Si le remplissage est activé, l’opération de déchiffrement sera toujours réussie si le total des données est un multiple de la taille de bloc.

Les fonctions EVP_EncryptInit(), EVP_EncryptFinal(), EVP_DecryptInit(), EVP_CipherInit() et EVP_CipherFinal() sont obsolètes mais sont conservées pour des raisons de compatibilité avec le code existant. EVP_EncryptInit_ex(), EVP_EncryptFinal_ex(), EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(), EVP_CipherInit_ex() et EVP_CipherFinal_ex() doivent être utilisées car elles peuvent réutiliser le contexte existant sans avoir à allouer ou libérer à chaque appel.

BOGUES¶

Pour RC5, le nombre de tours peut être actuellement être 8, 12 ou 16. C’est une limitation du code RC5 actuel plutôt que de l’interface EVP.

EVP_MAX_KEY_LENGTH et EVP_MAX_IV_LENGTH font seulement référence aux algorithmes internes de chiffrement avec des longueurs de clef par défaut. Si des algorithmes personnalisés dépassent ces longueurs, les résultats sont imprévisibles. Cela est dû au fait qu’en pratique une clef générique est définie en un tableau « unsigned char » contenant EVP_MAX_KEY_LENGTH.

Le code ASN1 est incomplet (et parfois inexact), il a été testé pour certains algorithmes communs S/MIME (RC2, DES, triple DES) avec le mode CBC.

EXEMPLES¶

Chiffrer une chaîne en utilisant IDEA :

 int do_crypt(char *outfile)
        {
        unsigned char outbuf[1024];
        int outlen, tmplen;
        /* Clef et VI bogués : normalement définis à partir
         * d’une autre source.
         */
        unsigned char key[] = {0,1,2,3,4,5,6,7,8,9,10,11,12,13,14,15};
        unsigned char iv[] = {1,2,3,4,5,6,7,8};
        char intext[] = "Un texte chiffré";
        EVP_CIPHER_CTX ctx;
        FILE *out;
        EVP_CIPHER_CTX_init(&ctx);
        EVP_EncryptInit_ex(&ctx, EVP_idea_cbc(), NULL, key, iv);
        if(!EVP_EncryptUpdate(&ctx, outbuf, &outlen, intext, strlen(intext)))
                {
                /* Erreur */
                return 0;
                }
        /* Le tampon fourni à EVP_EncryptFinal() doit, après les données
         * être juste chiffré pour éviter d’être surchargé.
         */
        if(!EVP_EncryptFinal_ex(&ctx, outbuf + outlen, &tmplen))
                {
                /* Erreur */
                return 0;
                }
        outlen += tmplen;
        EVP_CIPHER_CTX_cleanup(&ctx);
        /* Mode binaire nécessaire pour fopen car les données chiffrées sont
         * des données binaires. strlen() ne peut être utilisée car
         * elles peuvent n’être terminées par NULL et peuvent comporter des
         * NULL.
         */
        out = fopen(outfile, "wb");
        fwrite(outbuf, 1, outlen, out);
        fclose(out);
        return 1;
        }

Le texte chiffré de l’exemple ci-dessus peut être décodé en utilisant l’utilitaire openssl avec la ligne de commande (montrée sur deux lignes par souci de clarté) :

 openssl idea -d <fichier
          -K 000102030405060708090A0B0C0D0E0F -iv 0102030405060708

Exemple général de chiffrement et déchiffrement utilisant FILE I/O et AES128 avec une clef de 128 bits :

 int do_crypt(FILE *in, FILE *out, int do_encrypt)
        {
        /* Allocation d’assez d’espace dans tampon sortie pour bloc additionnel */
        unsigned char inbuf[1024], outbuf[1024 + EVP_MAX_BLOCK_LENGTH];
        int inlen, outlen;
        EVP_CIPHER_CTX ctx;
        /* Clef et VI bogués : normalement définis à partir
         * d’une autre source.
         */
        unsigned char key[] = "0123456789abcdeF";
        unsigned char iv[] = "1234567887654321";
        /* Ne pas définir maintenant la clef ou le vecteur, vérif des longueurs */
        EVP_CIPHER_CTX_init(&ctx);
        EVP_CipherInit_ex(&ctx, EVP_aes_128_cbc(), NULL, NULL, NULL,
                do_encrypt);
        OPENSSL_assert(EVP_CIPHER_CTX_key_length(&ctx) == 16);
        OPENSSL_assert(EVP_CIPHER_CTX_iv_length(&ctx) == 16);
        /* Maintenant définir la clef et le vecteur d'initialisation  */
        EVP_CipherInit_ex(&ctx, NULL, NULL, key, iv, do_encrypt);
        for(;;) 
                {
                inlen = fread(inbuf, 1, 1024, in);
                if(inlen <= 0) break;
                if(!EVP_CipherUpdate(&ctx, outbuf, &outlen, inbuf, inlen))
                        {
                        /* Erreur */
                        EVP_CIPHER_CTX_cleanup(&ctx);
                        return 0;
                        }
                fwrite(outbuf, 1, outlen, out);
                }
        if(!EVP_CipherFinal_ex(&ctx, outbuf, &outlen))
                {
                /* Erreur */
                EVP_CIPHER_CTX_cleanup(&ctx);
                return 0;
                }
        fwrite(outbuf, 1, outlen, out);
        EVP_CIPHER_CTX_cleanup(&ctx);
        return 1;
        }

VOIR AUSSI¶

evp(3)

HISTORIQUE¶

EVP_CIPHER_CTX_init(), EVP_EncryptInit_ex(), EVP_EncryptFinal_ex(), EVP_DecryptInit_ex(), EVP_DecryptFinal_ex(), EVP_CipherInit_ex(), EVP_CipherFinal_ex() et EVP_CIPHER_CTX_set_padding() sont apparues dans OpenSSL 0.9.7.

IDEA est apparu dans OpenSSL 0.9.7 mais a été souvent désactivé dû à des problèmes de droits ; le dernier brevet a expiré en 2012.

TRADUCTION¶

La traduction de cette page de manuel est maintenue par les membres de la liste <debian-l10n-french AT lists DOT debian DOT org>. Veuillez signaler toute erreur de traduction par un rapport de bogue sur le paquet manpages-fr-extra.