SYNOPSIS

#include <openssl/ssl.h>

void SSL_CTX_set_tmp_dh_callback(SSL_CTX *ctx,
            DH *(*tmp_dh_callback)(SSL *ssl, int is_export,
                                   int taille_clef);
 long SSL_CTX_set_tmp_dh(SSL_CTX *ctx, DH *dh);

void SSL_set_tmp_dh_callback(SSL *ctx,
            DH *(*tmp_dh_callback)(SSL *ssl, int is_export,
                                   int taille_clef));
 long SSL_set_tmp_dh(SSL *ssl, DH *dh)

DESCRIPTION

SSL_CTX_set_tmp_dh_callback() définit la fonction de rappel à utiliser pour ctx lorsqu’un paramètre DH est nécessaire pour tmp_dh_callback. Tous les objets ssl créés à partir de ctx héritent du rappel.

SSL_CTX_set_tmp_dh() définit les paramètres DH à utiliser à dh. Tous les objets ssl créés à partir de ctx héritent de la clef.

SSL_set_tmp_dh_callback() définit le rappel seulement pour ssl.

SSL_set_tmp_dh() définit les paramètres seulement pour ssl.

Ces fonctions sont applicables aux serveurs SSL/TLS uniquement.

NOTES

Lors de l’utilisation d’un algorithme de chiffrement avec authentification RSA, un échange de clefs éphémères DH peut survenir. Les algorithmes avec clefs DSA utilisent toujours des clefs éphémères DH. Dans ces cas, les données de session sont négociées en utilisant une clef éphémère/temporaire DH et la clef fournie et authentifiée par la chaîne de certificats est utilisée uniquement pour la signature. Les algorithmes anonymes (sans serveur permanent de clefs) utilisent aussi les clefs éphémères DH.

L’usage de clef éphémère DH rend la confidentialité persistante, car la connexion ne peut être déchiffrée que lorsque la clef DH est connue. En créant une clef DH éphémère uniquement pendant la durée de la mise en œuvre du serveur, un attaquant ne peut absolument pas déchiffrer des sessions terminées même s’il se procure une clef conforme (certifiée), puisque la clef n’a été utilisée que pour la signature.

Pour réaliser l’échange de clefs DH, le serveur doit utiliser un ensemble DH (paramètres DH) et créer une clef DH. Durant la négociation, le serveur générera toujours une nouvelle clef DH si les paramètres DH sont fournis à l’aide du rappel ou si l’option SSL_OP_SINGLE_DH_USE de SSL_CTX_set_options(3) est définie (ou les deux). Le serveur créera immédiatement une clef DH si les paramètres DH sont fournis à l’aide de SSL_CTX_set_tmp_dh() et que SSL_OP_SINGLE_DH_USE n’est pas définie. Dans ce cas, une clef peut être créée lors d’une initialisation et n’être jamais nécessaire, quoique d’un autre coté, le temps de calcul pendant la négociation est économisé.

Si des nombres premiers « forts » sont utilisés pour générer les paramètres DH, créer une nouvelle clef n’est pas strictement nécessaire à chaque initialisation de connexion mais cela améliore la confidentialité persistante. Si l’utilisation de nombres premiers « forts » n’est pas sûre, SSL_OP_SINGLE_DH_USE doit être utilisée pour empêcher les attaques par sous-groupes. L’utilisation de SSL_OP_SINGLE_DH_USE a toujours des incidences sur le temps de calcul nécessaire à la négociation, mais ce n’est pas très important et les créateurs ou utilisateurs devraient toujours activer cette option. Cette option est nécessaire pour mettre en œuvre une confidentialité persistante parfaite (PFS).

Comme le temps pour générer les paramètres DH est extrêmement long, les applications ne devraient pas les créer à la volée mais les fournir. Ces paramètres DH peuvent être réutilisés puisque la clef effective est fraichement créée durant la négociation. Le risque de la réutilisation est qu’un attaquant pourrait se focaliser sur un groupe DH très souvent utilisé. Les applications devraient donc créer leurs propres paramètres DH durant le processus d’installation en utilisant la fonction d’OpenSSL dhparam(1). Cette fonction garantit que des nombres premiers « forts » sont utilisés.

Les fichiers dh2048.pem et dh4096.pem dans le répertoire « apps » de l’actuelle distribution d’OpenSSL contiennent les paramètres DH « SKIP », ceux-ci utilisant des nombres premiers sûrs, et, d’une manière vérifiable, générés de manière pseudo-aléatoire. Ces fichiers peuvent être convertis en code C avec l’option -C de la fonction dhparam(1). La création de paramètres DH personnalisés lors de l’installation devrait toujours être préférée pour arrêter un attaquant se focalisant sur un groupe fréquemment utilisé. Les fichiers dh1024.pem et dh512.pem contiennent de vieux paramètres et ne doivent pas être utilisés.

Une application peut soit indiquer les paramètres DH, soit les fournir avec une fonction de rappel.

Les précédentes versions de rappel utilisaient les paramètres is_export et keylength pour contrôler la création de paramètres pour les suites de chiffrement destinées à l’export ou non. Les serveurs d’aujourd’hui qui ne prennent pas en charge les suites de chiffrement destinées à l’export serait avisés de soit utiliser SSL_CTX_set_tmp_dh() avec SSL_OP_SINGLE_DH_USE, soit utiliser le rappel en ignorant keylength et is_export, et en fournissant simplement au moins des paramètres 2048 bits dans le rappel.

EXEMPLES

Définition des paramètres DH avec une longueur de clef de 2048 bits. (La gestion des erreurs est délaissée).

 Création des paramètres en ligne de commande :
 $ openssl dhparam -out dh_param_2048.pem 2048
 Code pour établir les paramètres durant l’initialisation du serveur :
 ...
 SSL_CTX ctx = SSL_CTX_new();
 ...
 /* Définitions des paramètres DH éphémères. */
 DH *dh_2048 = NULL;
 FILE *fich_param;
 fich_param = fopen("dh_param_2048.pem", "r");
 if (fich_param) {
   dh_2048 = PEM_read_DHparams(fich_param, NULL, NULL, NULL);
   fclose(fich_param);
 } else {
   /* Error. */
 }
 if (dh_2048 == NULL) {
  /* Error. */
 }
 if (SSL_CTX_set_tmp_dh(ctx, dh_2048) != 1) {
   /* Error. */
 }
 SSL_CTX_set_options(ctx, SSL_OP_SINGLE_DH_USE);
 ...

VALEURS DE RETOUR

SSL_CTX_set_tmp_dh_callback() et SSL_set_tmp_dh_callback() ne renvoient pas d’information de diagnostic.

SSL_CTX_set_tmp_dh() et SSL_set_tmp_dh() renvoient 1 en cas de réussite 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.