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);
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 il est supposé que
*px contient une structure
X509 valable et une tentative est faite pour la réutiliser. 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, la mémoire
sera allouée 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.
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.
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.
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).
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.