#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é
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
Dss-Parms telle que définie dans la
RFC2459.
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 :
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
rwflag
est à 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 :
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 */
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 :
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é.
FORMAT DE CHIFFREMENT PEM
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 :
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.
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.
