SYNOPSIS

#include <openssl/ssl.h>

long SSL_CTX_set_options(SSL_CTX *ctx, long options);
 long SSL_set_options(SSL *ssl, long options);

long SSL_CTX_clear_options(SSL_CTX *ctx, long options);
 long SSL_clear_options(SSL *ssl, long options);

long SSL_CTX_get_options(SSL_CTX *ctx);
 long SSL_get_options(SSL *ssl);

long SSL_get_secure_renegotiation_support(SSL *ssl);

DESCRIPTION

Note : toutes ces fonctions sont implémentées en utilisant des macros.

SSL_CTX_set_options() ajoute les options, définies à l’aide d’un masquage dans options, à ctx. Les options déjà définies ne sont pas effacées !

SSL_set_options() ajoute les options, définies à l’aide d’un masquage dans options, à ctx. Les options déjà définies ne sont pas effacées !

SSL_CTX_clear_options() efface les options, définies à l’aide d’un masquage dans options, de ctx.

SSL_clear_options() efface les options, définies à l’aide d’un masquage dans options, de ssl.

SSL_CTX_get_options() renvoie les options définies pour ctx.

SSL_get_options() renvoie les options définies pour ssl.

SSL_get_secure_renegotiation_support() signale si le pair gère les renégociations sécurisées.

NOTES

Le comportement de la bibliothèque SSL peut être modifié en réglant plusieurs options. Les options sont codées comme des masquages et peuvent être associées avec une opération logique ou (|).

SSL_CTX_set_options() et SSL_set_options() affectent le comportement de protocole (externe) de la bibliothèque SSL. Le comportement (interne) de l’API peut être changé en utilisant les fonctions similaires SSL_CTX_set_mode(3) et SSL_set_mode().

Pendant une initialisation de connexion, les réglages d’options de l’objet SSL sont utilisés. Quand un nouvel objet SSL est créé à partir d’un contexte en utilisant SSL_new(), les réglages d’option sont copiés. Les modifications à ctx n’agissent sur les objets SSL déjà créés. SSL_clear() ne modifie pas les réglages.

Les options suivantes de palliatif de bogue sont disponibles :

SSL_OP_MICROSOFT_SESS_ID_BUG

www.microsoft.com — avec SSLv2, si une réutilisation de l’identifiant de session est faite, l’identifiant transmis dans le message quand le serveur a terminé est différent de celui décidé pour SSLv2.

SSL_OP_NETSCAPE_CHALLENGE_BUG

Netscape-Commerce/1.12, avec SSLv2, accepte une demande d’accès en 32 octets mais il semble seulement utiliser 16 octets lors de la production de la clef de chiffrement. Utiliser 16 octets est correct, mais 32 octets le serait aussi. D’après les spécifications SSLv3, 32 octets devraient être utilisés lors d’une demande dans le mode de compatibilité SSLv2/v3, mais comme mentionné ci-dessus, cela casse le serveur et 16 octets est la méthode à utiliser.

SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG

Comme dans OpenSSL 0.9.8q et 1.0.0c, cette option n’a pas d’effet.

SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG

...

SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER

...

SSL_OP_SAFARI_ECDHE_ECDSA_BUG

Ne choisissez pas les signatures ECDHE-ECDSA si le client apparait être Safari sur OS X. OS X 10.8..10.8.3 ne prennent plus en charge les signatures ECDHE-ECDSA.

SSL_OP_SSLEAY_080_CLIENT_DH_BUG

...

SSL_OP_TLS_D5_BUG

...

SSL_OP_TLS_BLOCK_PADDING_BUG

...

SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS

Désactiver les contre-mesures sur une vulnérabilité du protocole SSL 3.0/TLS 1.0 affectant les chiffrements CBC, qui ne peut être gérée par quelques implémentations cassées de SSL. Cette option n’a aucun effet sur les connexions utilisant d’autres signatures.

SSL_OP_TLSEXT_PADDING

Ajouter une extension d’emplissage pour garantir que la taille de ClientHello ne soit jamais comprise entre 256 et 512 octets. Cela est nécessaire comme palliatif pour quelques implémentations.

SSL_OP_ALL

Tous les palliatifs pour les bogues ci-dessus.

Utiliser SSL_OP_ALL est généralement sans danger pour activer les options de palliatif de bogue si la compatibilité avec quelques implémentations légèrement non conformes est désirée.

Les options modificatrices suivantes sont disponibles.

SSL_OP_TLS_ROLLBACK_BUG

Désactiver la détection de la variante attaque par annulation.

Pendant l’échange de clefs, le client doit envoyer la même information sur les niveaux acceptables de protocole SSL/TLS comme pendant le premier hello. Certains clients enfreignent cette règle en s’adaptant à la réponse du serveur. (Exemple : le client envoie un hello SSLv2 et accepte jusqu’à SSLv3.1=TLSv1, le serveur comprend jusqu’à SSLv3. Dans ce cas, le client doit encore utiliser la même annonce SSLv3.1=TLSv1. Certains clients se rabattent sur SSLv3 en accord avec la réponse du serveur et enfreignent la variante protection contre annulation.)

SSL_OP_SINGLE_DH_USE

Toujours créer une nouvelle clef lors de l’utilisation de paramètres DH temporaires ou éphémères (consultez SSL_CTX_set_tmp_dh_callback(3)). Cette option doit être utilisée en prévention des attaques par petits sous-groupes, si les paramètres DH n’étaient pas créés avec des nombres premiers « forts » (par exemple lors de l’utilisation de paramètres DSA, consultez dhparam(1)). Si des nombres premiers « forts » sont utilisés, créer une nouvelle clef DH à chaque initialisation de connexion n’est pas strictement nécessaire mais recommandé. SSL_OP_SINGLE_DH_USE devrait par conséquent être activé chaque fois que des paramètres temporaires ou éphémères sont utilisés.

SSL_OP_EPHEMERAL_RSA

Cette option n’est plus effective, elle est ignorée.

SSL_OP_CIPHER_SERVER_PREFERENCE

Lors du choix d’une signature, utiliser les préférences du serveur plutôt que celles du client. Sans ce réglage, le serveur SSL suivra toujours les préférences du client. Avec ce réglage, le serveur SSLv3/TLSv1 choisira de suivre ses propres préférences. À cause de la différence de protocole, pour SSLv2 le serveur enverra sa liste de préférences au client et celui-ci choisira.

SSL_OP_PKCS1_CHECK_1

...

SSL_OP_PKCS1_CHECK_2

...

SSL_OP_NETSCAPE_CA_DN_BUG

Si une connexion Netscape est acceptée, demande un certificat client, possède un CA non auto-signé n’ayant pas son CA dans Netscape, et que le navigateur a un certificat, cela provoquera un plantage ou un blocage. Valable pour 3.x et 4.xbeta.

SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG

...

SSL_OP_NO_SSLv2

Ne pas utiliser le protocole SSLv2.

SSL_OP_NO_SSLv3

Ne pas utiliser le protocole SSLv3.

SSL_OP_NO_TLSv1

Ne pas utiliser le protocole TLSv1.

SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION

Lors d’une renégociation par un serveur, toujours démarrer une nouvelle session (c’est-à-dire, une requête de reprise de session est seulement acceptée au cours de l’initiation initiale de connexion). Cette option n’est pas nécessaire pour les clients.

SSL_OP_NO_TICKET

Normalement les clients et serveurs, où c’est possible, font usage de certificats RFC4507bis de manière transparente pour la reprise d’une session sans état.

Si cette option est activée, cette fonctionnalité est désactivée et les certificats ne seront pas utilisés par les clients ou serveurs.

SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION

Autoriser les anciennes renégociations non sécurisées entre OpenSSL et les clients ou serveurs non protégés. Consultez la section RENÉGOCIATION SÉCURISÉE pour plus de détails.

SSL_OP_LEGACY_SERVER_CONNECT

Autoriser les anciennes renégociations non sécurisées entre OpenSSL et les serveurs non protégés uniquement. Cette option est actuellement établie par défaut. Consultez la section RENÉGOCIATION SÉCURISÉE pour plus de détails.

RENÉGOCIATION SÉCURISÉE

OpenSSL 0.9.8m et ses versions postérieures essayent d’utiliser les renégociations sécurisées comme décrites dans la RFC5746. Cela contre l’attaque par préfixe décrite entre autres dans CVE-2009-3555.

Le protocole SSLv2, déprécié et couramment transgressé, ne gère absolument pas les renégociations ; son usage est très fortement déconseillé.

Cette attaque est de grande portée et les développeurs d’application devrait en tenir compte. Dans la description qui suit, une implémentation gérant une renégociation sécurisée est qualifiée de protégée. Un serveur ne prenant pas en charge les renégociations sécurisées est qualifié de non protégé.

Les sections suivantes décrivent les opérations permises par les implémentations de renégociation sécurisée.

Client et serveur protégés

Les connexions et renégociations sont toujours autorisées par les implémentations d’OpenSSL.

Client non protégé et serveur OpenSSL protégé

La connexion initiale réussit mais la renégociation du client est refusée par le serveur avec un message d’avertissement no_renegotiation si TLS v1.0 utilisé, ou un message fatal handshake_failure si c’est SSL v3.0.

Si le serveur OpenSSL protégé essaie de renégocier, un message fatal handshake_failure est envoyé. Cela est dû à l’ignorance par le serveur de la nature non protégée du client.

Si l’option SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION est validée, alors la renégociation réussira toujours.

Remarque : un bogue dans les clients OpenSSL antérieurs à 0.9.8m (aucun d’entre eux n’est protégé) conduira à un blocage de la connexion si un message no_renegotiation est reçu. Les versions 0.9.8m et ultérieures d’OpenSSL considéreront un message no_renegotiation comme fatal et répondront par un message fatal handshake_failure. C’est parce qu’actuellement l’API d’OpenSSL n’a aucun moyen d’indiquer à une application qu’un essai est refusé.

Client OpenSSL protégé et serveur non protégé.

Si l’option SSL_OP_LEGACY_SERVER_CONNECT ou SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION est établie, les connexions et les renégociations entre les clients OpenSSL et les serveurs non protégés réussiront. Si aucune option n’est établie, alors les connexions initiales vers les serveurs non protégés échoueront.

L’option SSL_OP_LEGACY_SERVER_CONNECT est actuellement établie par défaut même si elle a des implications sur la sécurité : sans quoi il serait impossible de se connecter sur des serveurs non protégés (c’est-à-dire initialement tous) et cela n’est clairement pas acceptable. La renégociation est autorisée parce que cela n’ajoute aucun problème de sécurité : pendant une attaque, les clients ne voient de toute façon aucune renégociation.

Comme de plus en plus de serveurs deviennent protégés, l’option SSL_OP_LEGACY_SERVER_CONNECT ne sera pas active par défaut dans une future version de OpenSSL.

Les applications clientes d’OpenSSL voulant être sûres de se connecter à des serveurs non protégés devrait toujours activer SSL_OP_LEGACY_SERVER_CONNECT.

Les applications clientes d’OpenSSL voulant être sûres de ne pas se connecter à des serveurs non protégés (et donc éviter tout problème de sécurité) devraient toujours désactiver SSL_OP_LEGACY_SERVER_CONNECT en utilisant SSL_CTX_clear_options() ou SSL_clear_options().

La différence entre les options SSL_OP_LEGACY_SERVER_CONNECT et SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION est que SSL_OP_LEGACY_SERVER_CONNECT autorise les connections initiales et renégociation sécurisée entre des clients OpenSSL et seulement des serveurs non protégés, quand SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION autorise des connexions initiales et renégociation sécurisée entre OpenSSL et des clients ou serveurs non protégés.

VALEURS DE RETOUR

SSL_CTX_set_options() et SSL_set_options() renvoient les nouveaux masquages d’options après l’ajout d’options.

SSL_CTX_clear_options() et SSL_clear_options() renvoient les nouveaux masquages d’options après effacement d’options.

SSL_CTX_get_options() et SSL_get_options() renvoient l’actuel masquage.

SSL_get_secure_renegotiation_support() renvoie 1 si le pair prend en charge les renégociations sécurisées et 0 dans le cas contraire.

HISTORIQUE

SSL_OP_CIPHER_SERVER_PREFERENCE et SSL_OP_NO_SESSION_RESUMPTION_ON_RENEGOTIATION ont été ajoutées dans OpenSSL 0.9.7.

SSL_OP_TLS_ROLLBACK_BUG a été ajoutée dans OpenSSL 0.9.6 et était automatiquement activée avec SSL_OP_ALL. À partir de 0.9.7, elle n’est plus incluse dans SSL_OP_ALL et doit être clairement indiquée.

SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS a été ajoutée dans OpenSSL 0.9.6e. Les versions jusqu’à OpenSSL 0.9.6c n’incluent pas de contre-mesure qui puisse être désactivée avec cette option (dans OpenSSL 0.9.6d, elle était toujours active).

SSL_CTX_clear_options() et SSL_clear_options() ont été ajoutées la première fois dans OpenSSL 0.9.8m.

SSL_OP_ALLOW_UNSAFE_LEGACY_RENEGOTIATION, SSL_OP_LEGACY_SERVER_CONNECT et la fonction SSL_get_secure_renegotiation_support() ont été ajoutées la première fois dans OpenSSL 0.9.8m.

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.