NOM¶
PEM, PEM_read_bio_PrivateKey, PEM_read_PrivateKey, PEM_write_bio_PrivateKey,
PEM_write_PrivateKey, PEM_write_bio_PKCS8PrivateKey,
PEM_write_PKCS8PrivateKey, PEM_write_bio_PKCS8PrivateKey_nid,
PEM_write_PKCS8PrivateKey_nid, PEM_read_bio_PUBKEY, PEM_read_PUBKEY,
PEM_write_bio_PUBKEY, PEM_write_PUBKEY, PEM_read_bio_RSAPrivateKey,
PEM_read_RSAPrivateKey, PEM_write_bio_RSAPrivateKey, PEM_write_RSAPrivateKey,
PEM_read_bio_RSAPublicKey, PEM_read_RSAPublicKey, PEM_write_bio_RSAPublicKey,
PEM_write_RSAPublicKey, PEM_read_bio_RSA_PUBKEY, PEM_read_RSA_PUBKEY,
PEM_write_bio_RSA_PUBKEY, PEM_write_RSA_PUBKEY, PEM_read_bio_DSAPrivateKey,
PEM_read_DSAPrivateKey, PEM_write_bio_DSAPrivateKey, PEM_write_DSAPrivateKey,
PEM_read_bio_DSA_PUBKEY, PEM_read_DSA_PUBKEY, PEM_write_bio_DSA_PUBKEY,
PEM_write_DSA_PUBKEY, PEM_read_bio_DSAparams, PEM_read_DSAparams,
PEM_write_bio_DSAparams, PEM_write_DSAparams, PEM_read_bio_DHparams,
PEM_read_DHparams, PEM_write_bio_DHparams, PEM_write_DHparams,
PEM_read_bio_X509, PEM_read_X509, PEM_write_bio_X509, PEM_write_X509,
PEM_read_bio_X509_AUX, PEM_read_X509_AUX, PEM_write_bio_X509_AUX,
PEM_write_X509_AUX, PEM_read_bio_X509_REQ, PEM_read_X509_REQ,
PEM_write_bio_X509_REQ, PEM_write_X509_REQ, PEM_write_bio_X509_REQ_NEW,
PEM_write_X509_REQ_NEW, PEM_read_bio_X509_CRL, PEM_read_X509_CRL,
PEM_write_bio_X509_CRL, PEM_write_X509_CRL, PEM_read_bio_PKCS7,
PEM_read_PKCS7, PEM_write_bio_PKCS7, PEM_write_PKCS7,
PEM_read_bio_NETSCAPE_CERT_SEQUENCE, PEM_read_NETSCAPE_CERT_SEQUENCE,
PEM_write_bio_NETSCAPE_CERT_SEQUENCE, PEM_write_NETSCAPE_CERT_SEQUENCE -
routines PEM
SYNOPSIS¶
#include <openssl/pem.h>
EVP_PKEY *PEM_read_bio_PrivateKey(BIO *bp, EVP_PKEY **x,
pem_password_cb *cb, void *u);
EVP_PKEY *PEM_read_PrivateKey(FILE *fp, EVP_PKEY **x,
pem_password_cb *cb, void *u);
int PEM_write_bio_PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
unsigned char *kstr, int klen,
pem_password_cb *cb, void *u);
int PEM_write_PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
unsigned char *kstr, int klen,
pem_password_cb *cb, void *u);
int PEM_write_bio_PKCS8PrivateKey(BIO *bp, EVP_PKEY *x, const EVP_CIPHER *enc,
char *kstr, int klen,
pem_password_cb *cb, void *u);
int PEM_write_PKCS8PrivateKey(FILE *fp, EVP_PKEY *x, const EVP_CIPHER *enc,
char *kstr, int klen,
pem_password_cb *cb, void *u);
int PEM_write_bio_PKCS8PrivateKey_nid(BIO *bp, EVP_PKEY *x, int nid,
char *kstr, int klen,
pem_password_cb *cb, void *u);
int PEM_write_PKCS8PrivateKey_nid(FILE *fp, EVP_PKEY *x, int nid,
char *kstr, int klen,
pem_password_cb *cb, void *u);
EVP_PKEY *PEM_read_bio_PUBKEY(BIO *bp, EVP_PKEY **x,
pem_password_cb *cb, void *u);
EVP_PKEY *PEM_read_PUBKEY(FILE *fp, EVP_PKEY **x,
pem_password_cb *cb, void *u);
int PEM_write_bio_PUBKEY(BIO *bp, EVP_PKEY *x);
int PEM_write_PUBKEY(FILE *fp, EVP_PKEY *x);
RSA *PEM_read_bio_RSAPrivateKey(BIO *bp, RSA **x,
pem_password_cb *cb, void *u);
RSA *PEM_read_RSAPrivateKey(FILE *fp, RSA **x,
pem_password_cb *cb, void *u);
int PEM_write_bio_RSAPrivateKey(BIO *bp, RSA *x, const EVP_CIPHER *enc,
unsigned char *kstr, int klen,
pem_password_cb *cb, void *u);
int PEM_write_RSAPrivateKey(FILE *fp, RSA *x, const EVP_CIPHER *enc,
unsigned char *kstr, int klen,
pem_password_cb *cb, void *u);
RSA *PEM_read_bio_RSAPublicKey(BIO *bp, RSA **x,
pem_password_cb *cb, void *u);
RSA *PEM_read_RSAPublicKey(FILE *fp, RSA **x,
pem_password_cb *cb, void *u);
int PEM_write_bio_RSAPublicKey(BIO *bp, RSA *x);
int PEM_write_RSAPublicKey(FILE *fp, RSA *x);
RSA *PEM_read_bio_RSA_PUBKEY(BIO *bp, RSA **x,
pem_password_cb *cb, void *u);
RSA *PEM_read_RSA_PUBKEY(FILE *fp, RSA **x,
pem_password_cb *cb, void *u);
int PEM_write_bio_RSA_PUBKEY(BIO *bp, RSA *x);
int PEM_write_RSA_PUBKEY(FILE *fp, RSA *x);
DSA *PEM_read_bio_DSAPrivateKey(BIO *bp, DSA **x,
pem_password_cb *cb, void *u);
DSA *PEM_read_DSAPrivateKey(FILE *fp, DSA **x,
pem_password_cb *cb, void *u);
int PEM_write_bio_DSAPrivateKey(BIO *bp, DSA *x, const EVP_CIPHER *enc,
unsigned char *kstr, int klen,
pem_password_cb *cb, void *u);
int PEM_write_DSAPrivateKey(FILE *fp, DSA *x, const EVP_CIPHER *enc,
unsigned char *kstr, int klen,
pem_password_cb *cb, void *u);
DSA *PEM_read_bio_DSA_PUBKEY(BIO *bp, DSA **x,
pem_password_cb *cb, void *u);
DSA *PEM_read_DSA_PUBKEY(FILE *fp, DSA **x,
pem_password_cb *cb, void *u);
int PEM_write_bio_DSA_PUBKEY(BIO *bp, DSA *x);
int PEM_write_DSA_PUBKEY(FILE *fp, DSA *x);
DSA *PEM_read_bio_DSAparams(BIO *bp, DSA **x, pem_password_cb *cb, void *u);
DSA *PEM_read_DSAparams(FILE *fp, DSA **x, pem_password_cb *cb, void *u);
int PEM_write_bio_DSAparams(BIO *bp, DSA *x);
int PEM_write_DSAparams(FILE *fp, DSA *x);
DH *PEM_read_bio_DHparams(BIO *bp, DH **x, pem_password_cb *cb, void *u);
DH *PEM_read_DHparams(FILE *fp, DH **x, pem_password_cb *cb, void *u);
int PEM_write_bio_DHparams(BIO *bp, DH *x);
int PEM_write_DHparams(FILE *fp, DH *x);
X509 *PEM_read_bio_X509(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
X509 *PEM_read_X509(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
int PEM_write_bio_X509(BIO *bp, X509 *x);
int PEM_write_X509(FILE *fp, X509 *x);
X509 *PEM_read_bio_X509_AUX(BIO *bp, X509 **x, pem_password_cb *cb, void *u);
X509 *PEM_read_X509_AUX(FILE *fp, X509 **x, pem_password_cb *cb, void *u);
int PEM_write_bio_X509_AUX(BIO *bp, X509 *x);
int PEM_write_X509_AUX(FILE *fp, X509 *x);
X509_REQ *PEM_read_bio_X509_REQ(BIO *bp, X509_REQ **x,
pem_password_cb *cb, void *u);
X509_REQ *PEM_read_X509_REQ(FILE *fp, X509_REQ **x,
pem_password_cb *cb, void *u);
int PEM_write_bio_X509_REQ(BIO *bp, X509_REQ *x);
int PEM_write_X509_REQ(FILE *fp, X509_REQ *x);
int PEM_write_bio_X509_REQ_NEW(BIO *bp, X509_REQ *x);
int PEM_write_X509_REQ_NEW(FILE *fp, X509_REQ *x);
X509_CRL *PEM_read_bio_X509_CRL(BIO *bp, X509_CRL **x,
pem_password_cb *cb, void *u);
X509_CRL *PEM_read_X509_CRL(FILE *fp, X509_CRL **x,
pem_password_cb *cb, void *u);
int PEM_write_bio_X509_CRL(BIO *bp, X509_CRL *x);
int PEM_write_X509_CRL(FILE *fp, X509_CRL *x);
PKCS7 *PEM_read_bio_PKCS7(BIO *bp, PKCS7 **x, pem_password_cb *cb, void *u);
PKCS7 *PEM_read_PKCS7(FILE *fp, PKCS7 **x, pem_password_cb *cb, void *u);
int PEM_write_bio_PKCS7(BIO *bp, PKCS7 *x);
int PEM_write_PKCS7(FILE *fp, PKCS7 *x);
NETSCAPE_CERT_SEQUENCE *PEM_read_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp,
NETSCAPE_CERT_SEQUENCE **x,
pem_password_cb *cb, void *u);
NETSCAPE_CERT_SEQUENCE *PEM_read_NETSCAPE_CERT_SEQUENCE(FILE *fp,
NETSCAPE_CERT_SEQUENCE **x,
pem_password_cb *cb, void *u);
int PEM_write_bio_NETSCAPE_CERT_SEQUENCE(BIO *bp, NETSCAPE_CERT_SEQUENCE *x);
int PEM_write_NETSCAPE_CERT_SEQUENCE(FILE *fp, NETSCAPE_CERT_SEQUENCE *x);
DESCRIPTION¶
Les fonctions PEM lisent ou écrivent des structures au format PEM. En ce
sens, le format PEM est simplement des données chiffrées en
base64 entourées de lignes d'en-tête.
Pour plus de détails sur la signification des arguments, voir la partie
ARGUMENTS DES FONCTIONS PEM.
Chaque opération possède 4 fonctions qui lui sont
associées. Pour clarifier le terme « fonctions
foobar » sera utilisé pour faire collectivement
référence aux fonctions
PEM_read_bio_foobar(),
PEM_read_foobar(),
PEM_write_bio_foobar() et
PEM_write_foobar()
La fonction
PrivateKey lit et écrit une clé privée
dans le format PEM en utilisant une structure EVP_PKEY. Les routines
d'écriture utilisent une clé privée au format
« traditionnel » et peuvent gérer les
clés privées RSA et DSA. Les fonctions de lecture peuvent aussi
gérer de façon transparente les clés chiffrées et
déchiffrées au format PKCS#8.
PEM_write_bio_PKCS8PrivateKey() et
PEM_write_PKCS8PrivateKey()
écrivent une clé privée dans une structure EVP_PKEY dans
le format PKCS#8 EncryptedPrivateKeyInfo en utilisant un algorithme de mot de
passe basé sur PKCS#5 v2.0. L'argument
cipher
spécifie l'algorithme de chiffrement à utiliser :
contrairement à toutes les autres routines PEM, le chiffrement est
appliqué au niveau du PKCS#8 et pas dans les en-têtes PEM. Si
cipher est NULL alors il n'y aura pas de chiffrement utilisé et
une structure PKCS#8 PrivateKeyInfo sera utilisée.
PEM_write_bio_PKCS8PrivateKey_nid() et
PEM_write_PKCS8PrivateKey_nid() écrivent aussi une clé
privée comme PKCS#8 EncryptedPrivateKeyInfo cependant elles utilisent
les algorithmes de chiffrement KCS#5 v1.5 ou PKCS#12 à la place.
L'algorithme à utiliser dans le paramètre
nid doit
être le NID de l'IDENTIFIANT DE L'OBJET (voir la section NOTES).
Les fonctions
PUBKEY traitent une clé publique en utilisant une
structure EVP_PKEY. La clé publique est chiffrée comme une
structure SubjectPublicKeyInfo.
Les fonctions
RSAPrivateKey traitent une clé RSA privée en
utilisant une structure RSA. Elles gèrent le même format que les
fonctions
PrivateKey mais une erreur se produit si la clé
privée n'est pas une clé RSA.
Les fonctions
RSAPublicKey traitent une clé RSA publique en
utilisant une structure RSA. La clé publique est chiffrée en
utilisant une structure PKCS#1 RSAPublicKey
Les fonctions
RSA_PUBKEY traitent aussi une clé publique en
utilisant une structure RSA. Mais la clé publique est chiffrée
en utilisant une structure SubjectPublicKeyInfo et une erreur se produit si la
clé publique n'est pas une clé RSA.
Les fonctions
DSAPrivateKey traitent une clé DSA privée en
utilisant une structure DSA. Elles gèrent les mêmes formats que
les fonctions
PrivateKey mais une erreur se produit si la clé
privée n'est pas une clé DSA.
Les fonctions
DSA_PUBKEY traitent une clé publique DSA en
utilisant une structure DSA. La clé publique est chiffrée en
utilisant une structure SubjectPublicKeyInfo et une erreur se produit si la
clé publique n'est pas une clé DSA.
Les fonctions
DSAparams traitent les paramètres DSA en utilisant
une structure DSA. Les paramètres sont chiffrés en utilisant une
structure foobar.
Les fonctions
DHparams traitent les paramètres DH en utilisant une
structure DH. Les paramètres sont chiffrés en utilisant une
structure PKCS#3 DHparameter
Les fonctions
X509 traitent un certificat X509 en utilisant une structure
X509. Elles traitent aussi les certificats X509 certifiés mais les
paramètres de réglages sont ignorés.
Les fonctions
X509_AUX traitent un certificat X509 certifié en
utilisant une structure X509.
Les fonctions
X509_REQ et
X509_REQ_NEW traitent une requête
de certificat PKCS#10 en utilisant une structure X509_REQ. La fonction
d'écriture
X509_REQ utilise
CERTIFICATE REQUEST dans
l'en-tête alors que les fonctions
X509_REQ_NEW utilisent
NEW
CERTIFICATE REQUEST (comme requis par des CA). Les fonctions de lecture
X509_REQ peuvent gérer les deux formes, il n'y a donc pas de
fonctions de lecture
X509_REQ_NEW.
Les fonctions
X509_CRL traitent un CRL X509 en utilisant une structure
X509_CRL.
Les fonctions
PKCS7 traitent un PKCS#7 ContentInfo en utilisant une
structure PKCS7.
Les fonctions
NETSCAPE_CERT_SEQUENCE traitent une séquence de
certificats Netscape en utilisant une structure NETSCAPE_CERT_SEQUENCE.
ARGUMENTS DES FONCTIONS PEM¶
Les fonctions PEM ont beaucoup d'arguments en commun.
Les paramètres
bp (si présents) spécifient le BIO
dans lequel il faut lire ou écrire.
Le paramètre de FILE
fp (si présent) spécifie le
pointeur de FILE dans lequel il faut lire ou écrire.
Les fonctions de lecture PEM prennent toutes un argument
TYPE **x et
renvoient toutes un pointeur
TYPE *, où
TYPE est une
structure quelconque que la fonction utilise. Si
x est NULL, alors le
paramètre est ignoré. Si
x n'est pas NULL mais
*x
est NULL, alors la structure renvoyée sera écrite dans
*x. Si ni
x et
*x ne sont NULL, alors une tentative de
réutilisation de la structure sera faite (mais voir la partie BOGUES et
EXEMPLES). Quelle que soit la valeur de
x, un pointeur vers une
structure est toujours renvoyé (ou NULL en cas d'erreur).
Les fonctions PEM qui utilisent des clés privées prennent un
paramètre
enc qui spécifie l'algorithme de chiffrement
à utiliser, le chiffrement est fait au niveau du PEM. Si ce
paramètre est mis à NULL, alors la clé privée est
écrite de façon non chiffrée.
L'argument
cb est le rappel à utiliser pour les requêtes
pour le mot de passe utilisé pour chiffrer les structures PEM (que des
clés privées normalement).
Pour les routines d'écritures PEM, si le paramètre
kstr
n'est pas NULL, alors
klen octets à
kstr sont
utilisés comme mot de passe et
cb est ignoré.
Si les paramètres
cb sont initialisés à NULL et que
le paramètre
u n'est pas NULL, alors le paramètre
u n'est pas correctement interprété comme une
chaîne de caractère terminée par un null à
utiliser comme mot de passe. Si
cb et
u sont NULL, alors la
routine de retour est utilisée, ce qui affiche
généralement une demande d'entrée de texte pour le mot de
passe sur le terminal courant et sans affichage de l'entrée.
Le rappel du mot de passe par défaut n'est parfois pas approprié
(par exemple dans une application à interface graphique), une
alternative peut donc être fournie. La routine de retour de fonction a
la forme suivante :
int cb(char *buf, int size, int rwflag, void *u);
buf est le tampon d'écriture dans lequel sera écrit le mot
de passe.
size est la taille maximale du mot de passe
(c'est-à-dire la taille du tampon).
rwflag est un drapeau qui
est mis à 0 lors d'une lecture et à 1 lors d'une
écriture. Une routine typique demandera à l'utilisateur de
vérifier le mot de passe (par exemple pour le demander deux fois) si
rwflagest à 1. Le paramètre
u a la même
valeur que le paramètre
u passé à la routine PEM.
Il autorise l'application à passer des données arbitraires
à la rétroaction (par exemple un gestionnaire de fenêtres
dans une application à interface graphique). La rétroaction
doit renvoyer le nombre de caractères dans le mot de passe ou 0
en cas d'erreur.
EXEMPLES¶
Bien que les routines PEM prennent plusieurs arguments, dans presque toutes
leurs applications ceux-ci sont mis à 0 ou NULL.
Lire un certificat dans le format PEM à partir d'un BIO :
X509 *x;
x = PEM_read_bio_X509(bp, NULL, 0, NULL);
if (x == NULL)
{
/* Erreur */
}
Méthodes alternatives :
X509 *x = NULL;
if (!PEM_read_bio_X509(bp, &x, 0, NULL))
{
/* Erreur */
}
Écrire un certificat dans un BIO :
if (!PEM_write_bio_X509(bp, x))
{
/* Erreur */
}
Écrire une clé non chiffrée dans un pointeur FILE :
if (!PEM_write_PrivateKey(fp, key, NULL, NULL, 0, 0, NULL))
{
/* Erreur */
}
Écrire une clé privée (en utilisant le format traditionnel)
dans un BIO en utilisant un chiffrement Triple-DES, le mot de passe est
requis :
if (!PEM_write_bio_PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, NULL))
{
/* Erreur */
}
Écrire une clé privée (en utilisant le format PKCS#8) dans
un BIO en utilisant le chiffrement Triple-DES, en utilisant le mot de passe
« hello » :
if (!PEM_write_bio_PKCS8PrivateKey(bp, key, EVP_des_ede3_cbc(), NULL, 0, 0, "hello"))
{
/* Erreur */
}
Lire une clé privée d'un BIO en utilisant le mot de passe
« hello » :
key = PEM_read_bio_PrivateKey(bp, NULL, 0, "hello");
if (key == NULL)
{
/* Erreur */
}
Lire une clé privée d'un BIO en utilisant le rappel de phrase
secrète :
key = PEM_read_bio_PrivateKey(bp, NULL, pass_cb, "My Private Key");
if (key == NULL)
{
/* Erreur */
}
Squelette de rappel de phrase secrète :
int pass_cb(char *buf, int size, int rwflag, void *u);
{
int len;
char *tmp;
/* On ferait probablement autre chose si 'rwflag' était à 1 */
printf("Enter pass phrase for \"%s\"\n", u);
/* obtenir la phrase chiffrée, longueur 'len' dans 'tmp' */
tmp = "hello";
len = strlen(tmp);
if (len <= 0) return 0;
/* if too long, truncate */
if (len > size) len = size;
memcpy(buf, tmp, len);
return len;
}
NOTES¶
Les anciennes routines d'écriture
PrivateKey sont gardées
pour raisons de comptabilité. Les nouvelles applications doivent
écrire de nouvelles clés privées en utilisant les
routines
PEM_write_bio_PKCS8PrivateKey() ou
PEM_write_PKCS8PrivateKey() car elles sont plus
sécurisées (elles utilisent un compteur d'itération sur
2048 alors que les routines traditionnelles utilisent un compteur de 1) sauf
si la compatibilité avec les anciennes versions d'OpenSSL est
importante.
Les routines de lecture
PrivateKey peuvent être utilisées
dans toutes les applications car elles manipulent tous les formats de
façon transparente.
Un cas récurrent de problèmes est la tentative d'utilisation des
routines PEM de la façon suivante :
X509 *x;
PEM_read_bio_X509(bp, &x, 0, NULL);
cela est un bogue car une tentative de réutilisation des données
à
x sera faite alors que c'est un pointeur qui n'est pas
initialisé.
Cette vieille routine
PrivateKey utilise une méthode non standard
de chiffrement.
La clé privée (ou toute autre donnée) prend la forme
suivante :
-----DÉBUT CLÉ PRIVÉE RSA-----
Proc-Type: 4,ENCRYPTED
DEK-Info: DES-EDE3-CBC,3F17F5316E2BAC89
...données encodées en base64...
-----FIN CLÉ PRIVÉE RSA-----
La ligne qui commence DEK-Info contient deux virgules séparées par
des morceaux d'information : le nom de l'algorithme de chiffrement
comme utilisé par
EVP_get_cipherbyname() et un
salt de
8 octets chiffré comme un ensemble de valeurs
hexadécimales.
Après ce sont les données chiffrées en base64.
La clé de chiffrement est déterminée en utilisant
EVP_Bytestokey(), en utilisant
salt et un compteur
d'itération de 1. Le IV utilisé est la valeur de
salt et
*pas* le IV renvoyé par
EVP_Bytestokey().
BOGUES¶
Les routines de lecture PEM, dans certaines versions d'OpenSSL, n'utiliseront
pas correctement les structures existantes. De ce fait, ce qui suit :
PEM_read_bio_X509(bp, &x, 0, NULL);
où
x contient déjà un certificat valable, risque de
ne pas fonctionner, alors que :
X509_free(x);
x = PEM_read_bio_X509(bp, NULL, 0, NULL);
est garanti de fonctionner.
CODES DE RETOUR¶
Les routines de lectures renvoient soit un pointeur vers la structure read ou
NULL si une erreur s'est produite.
La routine d'écriture renvoie 1 en cas de succès et 0 en cas
d'échec.
VOIR AUSSI¶
EVP_get_cipherbyname(3),
EVP_BytesToKey(3)
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.