Provided by: manpages-fr-extra_20151231_all 
NOM
d2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio, i2d_X509_fp - Fonctions d'encodage et
décodage X509
SYNOPSIS
#include <openssl/x509.h>
X509 *d2i_X509(X509 **px, const unsigned char **in, int len);
int i2d_X509(X509 *x, unsigned char **out);
X509 *d2i_X509_bio(BIO *bp, X509 **x);
X509 *d2i_X509_fp(FILE *fp, X509 **x);
int i2d_X509_bio(BIO *bp, X509 *x);
int i2d_X509_fp(FILE *fp, X509 *x);
int i2d_re_X509_tbs(X509 *x, unsigned char **out);
DESCRIPTION
Les routines d'encodage et décodage X509 encodent et analysent une structure X509, qui représente un
certificat X509.
d2i_X509() essaye de décoder len octets à *in. En cas de réussite, un pointeur vers la structure X509 est
renvoyé. Si une erreur survient, alors NULL est renvoyé. Si px n'est pas NULL, alors la structure
renvoyée est écrite en *px. Si *px n'est pas NULL, alors *px est supposé contenir une structure X509
valable et une tentative est faite pour la réutiliser. Cette fonctionnalité de « réutilisation » est
présente pour compatibilité historique mais son utilisation est fortement découragée (consultez BOGUES
ci-dessous, et la discussion dans la section VALEURS DE RETOUR).
Si l'appel a réussi, *in est incrémenté à l'octet qui suit les données analysées.
i2d_X509() encode la structure pointée par x au format DER. Si out n'est pas NULL, les données encodées
en DER sont écrites dans le tampon à *out, et il est incrémenté pour pointer après les données qui
viennent d'être écrites. Si la valeur de retour est négative, une erreur est survenue, sinon la taille
des données encodées est renvoyée.
Depuis OpenSSL 0.9.7, si *out est NULL, une allocation de mémoire sera faite pour un tampon et les
données encodées y seront écrites. Dans ce cas, *out n'est pas incrémenté et il pointe au début des
données qui viennent d'être écrites.
d2i_X509_bio() est similaire à d2i_X509(), à la différence qu'elle essaye d'analyser les données du BIO
bp.
d2i_X509_fp() est similaire à d2i_X509(), à la différence qu'elle essaye d'analyser les données du
pointeur FILE fp.
i2d_X509_bio() est similaire à i2d_X509(), à la différence qu'elle écrit l'encodage de la structure x
dans le BIO bp et renvoie 1 en cas de réussite et 0 en cas d'échec.
i2d_X509_fp() est similaire à i2d_X509(), à la différence qu'elle écrit l'encodage de la structure x dans
le pointeur FILE fp et renvoie 1 en cas de réussite et 0 en cas d'échec.
i2d_re_X509_tbs() est similaire à i2d_X509() à part qu’elle n’encode que la portion TBSCertificate du
certificat.
NOTES
Les lettres i et d, dans par exemple i2d_X509, signifient « interne » (c'est-à-dire une structure C
interne) et « DER ». Ainsi, i2d_X509 convertit de l'interne en DER. Le « re » dans i2d_re_X509_tbs()
indique le « réencodage », et assure qu’un encodage frais est créé si l’objet a été modifié après
création (consultez la section BOGUES).
Les fonctions peuvent aussi comprendre les formes BER.
La structure X509 vraiment passée à i2d_X509() doit être une structure X509 peuplée valable. Elle ne peut
pas être simplement alimentée par une structure vide comme celle renvoyée par X509_new().
Les données encodées sont en forme binaire et peuvent contenir des zéros embarqués. Ainsi tous les
pointeurs FILE ou BIO devraient être ouverts en mode binaire. Les fonctions comme strlen() ne renverront
pas la taille adéquate de structure encodée.
Les façons d'incrémenter *in et *out après l'opération peuvent piéger les imprudents. Consulter la
section AVERTISSEMENTS qui indique quelques erreurs habituelles.
Le comportement de l'incrément automatique sert à refléter une utilisation typique des fonctions ASN1 :
après qu'une structure soit encodée ou décodée, une autre sera traitée à sa suite.
EXEMPLES
Allouer et encoder l'encodage DER d'une structure X509 :
int len;
unsigned char *buf, *p;
len = i2d_X509(x, NULL);
buf = OPENSSL_malloc(len);
if (buf == NULL)
/* erreur */
p = buf;
i2d_X509(x, &p);
À partir d'OpenSSL 0.9.7, cela peut être simplifié en :
int len;
unsigned char *buf;
buf = NULL;
len = i2d_X509(x, &buf);
if (len < 0)
/* erreur */
Essayer de décoder un tampon :
X509 *x;
unsigned char *buf, *p;
int len;
/* Quelque chose pour définir buf et len */
p = buf;
x = d2i_X509(NULL, &p, len);
if (x == NULL)
/* Quelques erreurs */
Technique alternative :
X509 *x;
unsigned char *buf, *p;
int len;
/* Quelque chose pour définir buf et len */
p = buf;
x = NULL;
if(!d2i_X509(&x, &p, len))
/* Quelques erreurs */
AVERTISSEMENTS
L'utilisation d'une variable temporaire est obligatoire. Une erreur habituelle est d'essayer d'utiliser
un tampon directement comme ceci :
int len;
unsigned char *buf;
len = i2d_X509(x, NULL);
buf = OPENSSL_malloc(len);
if (buf == NULL)
/* erreur */
i2d_X509(x, &buf);
/* Autres choses… */
OPENSSL_free(buf);
Ce code aura pour résultat un buf contenant apparemment n'importe quoi parce qu'il a été incrémenté après
l'appel pour pointer après les données qui viennent d'être écrites. Ainsi buf ne contiendra plus le
pointeur alloué par OPENSSL_malloc() et l'appel suivant de OPENSSL_malloc() pourrait sans doute planter.
La fonctionnalité d'allocation automatique (configurant buf à NULL) ne fonctionne qu'à partir
d'OpenSSL 0.9.7. Essayer de l'utiliser avec des versions précédentes provoquera typiquement une violation
de segmentation.
Un autre piège à éviter est la mauvaise utilisation de l'argument xp de d2i_X509() :
X509 *x;
if (!d2i_X509(&x, &p, len))
/* Quelques erreurs */
Cela plantera probablement quelque part dans d2i_X509(). La raison à cela et que la variable x est
désinitialisée et qu'il y aura une tentative d'interpréter sa valeur (incorrecte) comme une structure
X509, provoquant typiquement une violation de segmentation. Si x est définie à NULL d'abord, alors ça
n'arrivera pas.
BOGUES
Dans certaines version d'OpenSSL, le comportement de « réutilisation » de d2i_X509(), quand *px est
correct, est cassé et certaines parties de la structure réutilisée pourraient persister si elles ne sont
pas présentes dans la nouvelle. Par conséquent, l'utilisation de ce comportement de « réutilisation » est
fortement déconseillée.
i2d_X509() ne renverra pas d'erreur dans plusieurs versions d'OpenSSL : si des champs obligatoires ne
sont pas initialisés à cause d'une erreur de programmation, alors la structure encodée pourrait contenir
des données incorrectes ou omettre les champs complètement et ne sera pas analysée par d2i_X509(). Cela
pourrait être corrigé plus tard, de telle sorte que le code ne devrait pas supposer pas que i2d_X509()
réussira toujours.
L’encodage de la portion TBSCertificate d’un certificat est mise en cache dans la structure X509 interne
pour améliorer les performances d’encodage et s’assurer que les signatures de certificat sont vérifiées
correctement dans certains certificats avec des encodages (non DER) cassés.
Toutes les fonctions qui encodent une structure X509 comme i2d_X509(), i2d_X509_fp() ou i2d_X509_bio()
pourraient renvoyer un encodage dépassé si la structure X509 a été modifiée après désérialisation ou
sérialisation précédente.
Si, après modification, l’objet X509 est signé de nouveau avec X509_sign(), l’encodage est
automatiquement renouvelé. Sinon, l’encodage de la portion TBSCertificate de X509 peut être renouvelé en
appelant i2d_re_X509_tbs() directement.
VALEURS DE RETOUR
d2i_X509(), d2i_X509_bio() et d2i_X509_fp() renvoient une structure X509 valable en cas de réussite et
NULL en cas d'erreur. Le code d'erreur peut être obtenu à l'aide de ERR_get_error(3). Si la
fonctionnalité de « réutilisation » a été utilisée avec une structure X509 valable, passée par px,
l’objet n’est pas libéré en cas d’erreur mais pourrait être dans un état potentiellement incorrect ou
incohérent.
i2d_X509() renvoie le nombre d'octets encodés ou une valeur négative en cas d'erreur. Le code d'erreur
peut être obtenu à l'aide de ERR_get_error(3).
i2d_X509_bio() et i2d_X509_fp() renvoient 1 en cas de réussite et 0 en cas d'erreur. Le code d'erreur
peut être obtenu à l'aide de ERR_get_error(3).
VOIR AUSSI
ERR_get_error(3)
HISTORIQUE
d2i_X509, i2d_X509, d2i_X509_bio, d2i_X509_fp, i2d_X509_bio et i2d_X509_fp sont disponibles dans toutes
les versions de SSLeay et OpenSSL.
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.
1.0.2a 1.0.2c 2015-12-31 fr::crypto::d2i_X509(3SSL)