SYNOPSIS
#include <openssl/evp.h>
void EVP_MD_CTX_init(EVP_MD_CTX *ctx);
EVP_MD_CTX *EVP_MD_CTX_create(void);
int EVP_DigestInit_ex(EVP_MD_CTX *ctx, const EVP_MD *type, ENGINE *impl);
int EVP_DigestUpdate(EVP_MD_CTX *ctx, const void *d, size_t cnt);
int EVP_DigestFinal_ex(EVP_MD_CTX *ctx, unsigned char *md,
unsigned int *s);
int EVP_MD_CTX_cleanup(EVP_MD_CTX *ctx);
void EVP_MD_CTX_destroy(EVP_MD_CTX *ctx);
int EVP_MD_CTX_copy_ex(EVP_MD_CTX *out,const EVP_MD_CTX *in);
int EVP_DigestInit(EVP_MD_CTX *ctx, const EVP_MD *type);
int EVP_DigestFinal(EVP_MD_CTX *ctx, unsigned char *md,
unsigned int *s);
int EVP_MD_CTX_copy(EVP_MD_CTX *out,EVP_MD_CTX *in);
#define EVP_MAX_MD_SIZE 64 /* SHA512 */
int EVP_MD_type(const EVP_MD *md);
int EVP_MD_pkey_type(const EVP_MD *md);
int EVP_MD_size(const EVP_MD *md);
int EVP_MD_block_size(const EVP_MD *md);
const EVP_MD *EVP_MD_CTX_md(const EVP_MD_CTX *ctx);
#define EVP_MD_CTX_size(e) EVP_MD_size(EVP_MD_CTX_md(e))
#define EVP_MD_CTX_block_size(e) EVP_MD_block_size((e)->digest)
#define EVP_MD_CTX_type(e) EVP_MD_type((e)->digest)
const EVP_MD *EVP_md_null(void);
const EVP_MD *EVP_md2(void);
const EVP_MD *EVP_md5(void);
const EVP_MD *EVP_sha(void);
const EVP_MD *EVP_sha1(void);
const EVP_MD *EVP_dss(void);
const EVP_MD *EVP_dss1(void);
const EVP_MD *EVP_mdc2(void);
const EVP_MD *EVP_ripemd160(void);
const EVP_MD *EVP_sha224(void);
const EVP_MD *EVP_sha256(void);
const EVP_MD *EVP_sha384(void);
const EVP_MD *EVP_sha512(void);
const EVP_MD *EVP_get_digestbyname(const char *name);
#define EVP_get_digestbynid(a) EVP_get_digestbyname(OBJ_nid2sn(a))
#define EVP_get_digestbyobj(a) EVP_get_digestbynid(OBJ_obj2nid(a))
DESCRIPTION
Les routines EVP pour algorithme de hachage sont des interfaces de haut niveau pour les condensés de message.EVP_MD_CTX_init() initialise le contexte ctx du condensé de message.
EVP_MD_CTX_create() alloue, initialise et renvoie un contexte de condensé de message.
EVP_DigestInit_ex() définit un contexte de condensé de message ctx pour utiliser un type d’algorithme à partir de l’ENGINE impl. ctx doit être initialisé avant d’appeler cette fonction. type est habituellement fourni par une fonction telle que EVP_sha1(). Si impl est NULL, alors l’implémentation du type par défaut est utilisée.
EVP_DigestUpdate() produit un hachage de cnt octets de données vers d dans le contexte de condensé de message ctx. Cette fonction peut être appelée plusieurs fois pour produire un hachage de données supplémentaires.
EVP_DigestFinal_ex() récupère la valeur de condensé de message de ctx et la place dans md. Si le paramètre s n’est pas NULL, le nombre d’octets de données sera écrit (c’est-à-dire la dimension du condensé de message) sur s (de type entier), au maximum EVP_MAX_MD_SIZE octets seront écrits. Après l’appel de EVP_DigestFinal_ex(), aucun appel supplémentaire à EVP_DigestUpdate() ne pourra être fait, mais EVP_DigestInit_ex() pourra être appelée pour initialiser une nouvelle opération de condensé de message.
EVP_MD_CTX_cleanup() nettoie le contexte ctx du condensé de message et devrait être appelée si ce contexte n’est plus nécessaire.
EVP_MD_CTX_destroy() nettoie le contexte ctx du condensé de message et libère l’espace qui lui était alloué. Elle devrait être appelée seulement pour un contexte créé en utilisant EVP_MD_CTX_create().
EVP_MD_CTX_copy_ex() peut être utilisée pour copier l’état du condensé de message de in vers out. Cela est utile si le hachage de grandes quantités de données, qui différent seulement par leurs derniers octets, est à réaliser. out doit être initialisée avant d’appeler cette fonction.
EVP_DigestInit() fonctionne comme EVP_DigestInit_ex() sauf que le contexte indiqué ctx n’a nul besoin d’être initialisé et qu’elle utilise toujours l’algorithme implémenté par défaut.
EVP_DigestFinal() est similaire à EVP_DigestFinal_ex() sauf que le contexte du condensé de message ctx est automatiquement nettoyé.
EVP_MD_CTX_copy() est similaire à EVP_MD_CTX_copy_ex() sauf que la destination out ne doit pas être initialisée.
EVP_MD_size() et EVP_MD_CTX_size() renvoient la taille d’un condensé de message lorsqu’il est fourni à une structure EVP_MD ou EVP_MD_CTX, c’est-à-dire la taille de l’empreinte numérique.
EVP_MD_block_size() et EVP_MD_CTX_block_size() renvoient la taille de bloc du condensé de message lorsqu’il est fourni à une structure EVP_MD ou EVP_MD_CTX.
EVP_MD_type() et EVP_MD_CTX_type() renvoient le NID de OBJECT IDENTIFIER représentant le condensé de message indiqué lorsqu’il est fourni à une structure EVP_MD. Par exemple, EVP_MD_type(EVP_sha1() renvoie NID_sha1. Cette fonction est généralement utilisée pour définir les OID ASN1.
EVP_MD_CTX_md() renvoie la structure EVP_MD correspondant à celle fournie : EVP_MD_CTX.
EVP_MD_pkey_type() renvoie le NID de la clef publique signant l’algorithme associé avec ce condensé de message. Par exemple, EVP_sha1() est associée avec RSA, et renverra NID_sha1WithRSAEncryption. Puisque les condensés de message et les algorithmes ne sont plus liés, cette fonction n’est plus conservée que pour des raisons de compatibilité.
EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_sha224(), EVP_sha256(), EVP_sha384(), EVP_sha512(), EVP_mdc2() et EVP_ripemd160() renvoient des structures EVP_MD pour leurs algorithmes respectifs : MD2, MD5, SHA, SHA1, SHA224, SHA256, SHA384, SHA512, MDC2 ou RIPEMD160.
EVP_dss() et EVP_dss1() renvoient des structures EVP_MD pour leurs algorithmes de hachage SHA et SHA1 en utilisant DSS (DSA) comme algorithme de signature. Remarque : il n’est nul besoin d’utiliser ces pseudo-condensés de message dans OpenSSL 1.0.0 ou postérieur ; ces fonctions ne sont plus conservées que pour des raisons de compatibilité.
EVP_md_null() est un condensé de message « null » sans aucun effet : c’est-à-dire la valeur renvoyée est de longueur zéro.
EVP_get_digestbyname(), EVP_get_digestbynid() et EVP_get_digestbyobj() renvoient une structure EVP_MD lorsque sont fournis un nom d’algorithme de hachage, un NID ou une structure ASN1_OBJECT, respectivement. La table du hachage doit être initialisée en utilisant, par exemple, OpenSSL_add_all_digests() pour que ces fonctions agissent.
VALEURS DE RETOUR
EVP_DigestInit_ex(), EVP_DigestUpdate() et EVP_DigestFinal_ex() renvoient 1 en cas de réussite et 0 en cas d’échec.EVP_MD_CTX_copy_ex() renvoie 1 en cas de réussite et 0 en cas d’échec.
EVP_MD_type(), EVP_MD_pkey_type() et EVP_MD_type() renvoient le NID du OBJECT IDENTIFIER correspondant ou NID_undef si absent.
EVP_MD_size(), EVP_MD_block_size(), EVP_MD_CTX_size() et EVP_MD_CTX_block_size() renvoient les tailles de condensé de message ou de bloc en octet.
EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_dss(), EVP_dss1(), EVP_mdc2() et EVP_ripemd160() renvoient des pointeurs vers les structures EVP_MD correspondantes.
EVP_get_digestbyname(), EVP_get_digestbynid() et EVP_get_digestbyobj() renvoient soit une structure EVP_MD ou NULL en cas d’erreur.
NOTES
L’interface EVP pour les condensés de message devrait presque toujours être utilisée de préférence aux interfaces de bas niveau. Cela est ainsi parce que le code devient évident pour l’algorithme de hachage utilisé et bien plus souple.Les nouvelles applications devraient utiliser les algorithmes de hachage SHA2 tels que SHA256. Les autres algorithmes de hachage sont encore communément utilisés.
Pour la plupart des applications, le paramètre impl pour EVP_DigestInit_ex() doit être défini à NULL pour utiliser l’implémentation par défaut de condensé de message.
Les fonctions EVP_DigestInit(), EVP_DigestFinal() et EVP_MD_CTX_copy() sont obsolètes mais sont conservées pour compatibilité avec le code existant. Les nouvelles applications devraient utiliser EVP_DigestInit_ex(), EVP_DigestFinal_ex() et EVP_MD_CTX_copy_ex() car elles peuvent, de manière efficace, utiliser de nouveau un contexte de condensé de message au lieu de l’initialiser et le nettoyer à chaque appel, et permettent aux implémentations non installées de l’être.
Dans OpenSSL 0.9.7 et postérieur, si un contexte de condensé de message n’est pas nettoyé après son utilisation, une fuite de mémoire se produira.
L’allocation de mémoire pour des structures EVP_MD_CTX est courant, par exemple :
EVP_MD_CTX mctx; EVP_MD_CTX_init(&mctx);
Cela conduira à des problèmes de compatibilité si la taille de la structure EVP_MD_CTX change (cela ne peut arriver que lors d’une nouvelle mise à jour majeure d’OpenSSL). Les applications souhaitant éviter ce problème doivent plutôt utiliser EVP_MD_CTX_create() :
EVP_MD_CTX *mctx; mctx = EVP_MD_CTX_create();
EXEMPLE
Cet exemple hache les données « Message de test » et « Hello World », en utilisant le nom d’algorithme de hachage fourni sur la ligne de commande.
#include <stdio.h>
#include <openssl/evp.h>
main(int argc, char *argv[])
{
EVP_MD_CTX *mdctx;
const EVP_MD *md;
char mess1[] = "Message de test\n";
char mess2[] = "Hello World\n";
unsigned char md_value[EVP_MAX_MD_SIZE];
int md_len, i;
OpenSSL_add_all_digests();
if(!argv[1]) {
printf("Usage : mdtest digestname\n");
B<exit>(1);
}
md = EVP_get_digestbyname(argv[1]);
if(!md) {
printf("Algorithme de hachage inconnu %s\n", argv[1]);
B<exit>(1);
}
mdctx = EVP_MD_CTX_create();
EVP_DigestInit_ex(mdctx, md, NULL);
EVP_DigestUpdate(mdctx, mess1, strlen(mess1));
EVP_DigestUpdate(mdctx, mess2, strlen(mess2));
EVP_DigestFinal_ex(mdctx, md_value, &md_len);
EVP_MD_CTX_destroy(mdctx);
printf("Digest is: ");
for(i = 0; i < md_len; i++)
printf("%02x", md_value[i]);
printf("\n");
/* Exécuter ceci avant de quitter. */
EVP_cleanup();
exit(0);
}
HISTORIQUE
EVP_DigestInit(), EVP_DigestUpdate() et EVP_DigestFinal() sont disponibles dans toutes les versions de SSLeay et OpenSSL.EVP_MD_CTX_init(), EVP_MD_CTX_create(), EVP_MD_CTX_copy_ex(), EVP_MD_CTX_cleanup(), EVP_MD_CTX_destroy(), EVP_DigestInit_ex() et EVP_DigestFinal_ex() ont été ajoutées dans OpenSSL 0.9.7.
EVP_md_null(), EVP_md2(), EVP_md5(), EVP_sha(), EVP_sha1(), EVP_dss(), EVP_dss1(), EVP_mdc2() et EVP_ripemd160() ont été modifiées pour renvoyer correctement const EVP_MD * dans OpenSSL 0.9.7.
Le problème de lien entre les algorithmes de condensé de message et de signature a été corrigé dans OpenSSL 1.0 et postérieur, et maintenant EVP_sha1() peut être utilisée avec RSA et DSA ; EVP_dss1() n’est plus nécessaire.
OpenSSL 1.0 et postérieurs n’intègrent pas l’algorithme de hachage MD2 dans leur configuration par défaut à cause de ses problèmes de faiblesse de sécurité.
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.