SYNOPSIS

#include <openssl/ssl.h>

void SSL_CTX_set_verify(SSL_CTX *ctx, int mode,
                         int (*verify_callback)(int, X509_STORE_CTX *));
 void SSL_set_verify(SSL *s, int mode,
                     int (*verify_callback)(int, X509_STORE_CTX *));
 void SSL_CTX_set_verify_depth(SSL_CTX *ctx,int profondeur);
 void SSL_set_verify_depth(SSL *s, int profondeur);

int verify_callback(int preverify_ok, X509_STORE_CTX *x509_ctx);

DESCRIPTION

SSL_CTX_set_verify() définit les attributs de vérification pour ctx à mode et précise la fonction verify_callback à utiliser. Si aucune fonction de rappel n’est précisée, le pointeur NULL peut être utilisé pour verify_callback.

SSL_CTX_set_verify() définit les attributs de vérification pour ssl à mode et précise la fonction verify_callback à utiliser. Si aucune fonction de rappel n’est précisée, le pointeur NULL peut être utilisé pour verify_callback. Dans ce cas, le dernier verify_callback défini précisément pour ce ssl est conservé. Si aucun rappel n’était défini auparavant, le rappel par défaut pour le ctx sous-jacent, et qui était valable au moment où ssl a été créé avec SSL_new(3), est utilisé.

SSL_CTX_set_verify_depth() définit la profondeur maximale pour la vérification de chaîne de certificats qui sera autorisée pour ctx (consultez la section BOGUES).

SSL_CTX_set_verify_depth() définit la profondeur maximale pour la vérification de chaîne de certificats qui sera autorisée pour ssl (consultez la section BOGUES).

NOTES

La vérification des certificats peut être contrôlée par une suite d’opérations « ou » logiques d’attributs mode.

SSL_VERIFY_NONE

Mode serveur : le serveur n’enverra pas de demande de certificat client au client, aussi le client n’enverra pas de certificat.

Mode client : s’il n’utilise pas un algorithme de chiffrement anonyme (fonctionnement par défaut), le serveur enverra un certificat qui sera contrôlé. Le résultat du processus de vérification de certificat peut être contrôlé après l’initiation de connexion TLS/SSL en utilisant la fonction SSL_get_verify_result(3). L’initiation de connexion peut continuer indépendamment de la vérification du résultat.

SSL_VERIFY_PEER

Mode serveur : le serveur demande un certificat au client. Le certificat renvoyé (le cas échéant) est vérifié. Si la vérification échoue, l’initiation de connexion TLS/SSl se termine immédiatement avec un message d’alerte contenant le pourquoi de l’échec de vérification. Le comportement peut être contrôlé par les attributs additionnels SSL_VERIFY_FAIL_IF_NO_PEER_CERT et SSL_VERIFY_CLIENT_ONCE.

Mode client : le certificat du serveur est vérifié. Si la vérification échoue, l’initiation de connexion TLS/SSL se termine immédiatement avec un message d’alerte contenant le pourquoi de l’échec de vérification. Si aucun certificat de serveur est envoyé, à cause de l’utilisation d’un algorithme de chiffrement anonyme, SSL_VERIFY_PEER est ignoré.

SSL_VERIFY_FAIL_IF_NO_PEER_CERT

Mode serveur : si le client ne renvoie pas de certificat, l’initialisation de connexion TSL/SSL se termine immédiatement avec un message « handshake failure » (échec d’initialisation). Cet attribut doit être utilisé de concert avec SSL_VERIFY_PEER.

Mode client : mode ignoré.

SSL_VERIFY_CLIENT_ONCE

Mode serveur : requête uniquement d’un certificat de client lors de la première initiation de connexion TLS/SSL. Une nouvelle demande ne doit pas être faite dans le cas d’une renégociation. Cet attribut doit être utilisé de concert avec SSL_VERIFY_PEER.

Mode client : mode ignoré.

Un seul des attributs mode SSL_VERIFY_NONE et SSL_VERIFY_PEER doit être activé à tout moment.

La véritable procédure de vérification est réalisée en utilisant la procédure de vérification interne ou une autre application fournissant une fonction de vérification définie avec SSL_CTX_set_cert_verify_callback(3). Les descriptions suivantes s’appliquent dans le cas d’une procédure interne. Une procédure fournie par une application a aussi accès à l’information de profondeur de vérification et à la fonction verify_callback(), mais la façon dont l’information est utilisée peut être différente.

SSL_CTX_set_verify_depth() et SSL_set_verify_depth() définissent la limite supérieure de profondeur jusqu’à laquelle les certificats dans une chaîne sont utilisés pendant la procédure de vérification. Si la chaîne de certificats est plus grande que celle autorisée, les certificats après la limite sont ignorés. Les messages d’erreur ne tiennent pas compte des certificats au-dessus la limite, plus vraisemblablement un X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY sera émis. Le compte d’erreurs est « level 0:peer certificate », « level 1: CA certificate ,> « level 2: higher level CA certificate », etc. Définir la profondeur maximale à 2 autorise les niveaux 0, 1 et 2. La limite de profondeur par défaut est 100, permettant le certificat du pair plus 100 certificats de CA.

La fonction verify_callback est utilisée pour contrôler le fonctionnement lorsque l’attribut SSL_VERIFY_PEER flag est activé. Il doit être fourni par l’application et reçoit deux arguments : preverify_ok indique si la vérification du certificat est demandée (preverify_ok=1) ou non (preverify_ok=0). x509_ctx est un pointeur vers le contexte complet utilisé par la vérification de la chaîne de certificats.

La chaîne de certificats est vérifiée en commençant par le niveau d’emboitement le plus profond (le certificat de CA racine) et progresse jusqu’au certificat de pair. À chaque niveau, les signatures et les certificats d’émetteur sont contrôlés. À chaque fois qu’une erreur de vérification est trouvée, le numéro d’erreur est stocké dans x509_ctx et verify_callback est appelé avec preverify_ok=0. En utilisant les fonctions X509_CTX_store_*, verify_callback peut trouver le certificat en question et réaliser les étapes additionnelles (consultez EXEMPLES). Si aucune erreur n’est trouvée pour un certificat, verify_callback est appelé avec preverify_ok=1 avant accéder au prochain niveau.

La valeur de retour de verify_callback détermine la stratégie de la procédure de vérification suivante. Si verify_callback renvoie 0, la procédure de vérification s’arrête avec un état « échec de vérification ». Si SSL_VERIFY_PEER est activé, un message d’échec de vérification est envoyé au pair et la connexion TLS/SSL s’arrête. Si verify_callback renvoie 1, la procédure continue. Si verify_callback renvoie toujours 1, l’initialisation de connexion TLS/SSL ne sera pas achevée en ce qui concerne les erreurs de connexion et la connexion sera établie. Le processus demandeur peut cependant retrouver le code d’erreur de la dernière vérification en utilisant SSL_get_verify_result(3) ou en entretenant son propre stockage d’erreurs géré par verify_callback.

Si aucun verify_callback n’est indiqué, le rappel par défaut sera utilisé. Sa valeur de retour est identique à preverify_ok, aussi toute erreur de vérification conduira à une fin de la connexion TLS/SSL, avec un message d’alerte si SSL_VERIFY_PEER est activé.

VALEURS DE RETOUR

Les fonctions SSL*_set_verify*() ne fournissent pas d’information de diagnostic.

EXEMPLES

Le code suivant réalise un exemple de la fonction verify_callback qui continuera toujours l’initiation de connexion TLS/SSL indépendamment d’erreur de vérification, si voulu. Le rappel réalise une vérification avec limite de profondeur et avec le maximum d’informations.

Toutes les erreurs de vérification sont affichées ; l’information sur la chaîne de certificats est affichée sur demande. Cet exemple concerne un serveur qui autorise mais ne demande pas de certificat client.

Cet exemple utilise la technique « ex_data » pour stocker les données d’application dans la structure SSL ou les retrouver à partir de cette structure (consultez SSL_get_ex_new_index(3), SSL_get_ex_data_X509_STORE_CTX_idx(3)).

 ...
 typedef struct {
   int verbose_mode;
   int verify_depth;
   int always_continue;
 } mydata_t;
 int mydata_index;
 ...
 static int verify_callback(int preverify_ok, X509_STORE_CTX *ctx)
 {
    char    buf[256];
    X509   *err_cert;
    int     err, depth;
    SSL    *ssl;
    mydata_t *mydata;
    err_cert = X509_STORE_CTX_get_current_cert(ctx);
    err = X509_STORE_CTX_get_error(ctx);
    depth = X509_STORE_CTX_get_error_depth(ctx);
    /*
     * Extraire le pointeur vers l’objet SSL de la connexion
     * actuellement traitée et les données spécifiques à
     * l’application stockées dans cet objet.
     */
    ssl = X509_STORE_CTX_get_ex_data(ctx,
                            SSL_get_ex_data_X509_STORE_CTX_idx());
    mydata = SSL_get_ex_data(ssl, mydata_index);
    X509_NAME_oneline(X509_get_subject_name(err_cert), buf, 256);
    /*
     * Chaîne de certificats trop longue. La profondeur limite définie
     * par SSL_CTX_set_verify_depth() est en principe « limit+1 » aussi
     * si la condition « depth>verify_depth » est satisfaite, la limite
     * est dépassée et la journalisation de cette erreur doit être
     * faite. Cela doit être fait ici parce que l’erreur CHAIN_TOO_LONG
     * ne peut être trouvée explicitement ; les seules erreurs
     * introduites par des certificats additionnels sont journalisées.
     */
    if (depth > mydata->verify_depth) {
        preverify_ok = 0;
        err = X509_V_ERR_CERT_CHAIN_TOO_LONG;
        X509_STORE_CTX_set_error(ctx, err);
    } 
    if (!preverify_ok) {
        printf("verify error:num=%d:%s:depth=%d:%s\n", err,
                 X509_verify_cert_error_string(err), depth, buf);
    }
    else if (mydata->verbose_mode)
    {
        printf("depth=%d:%s\n", depth, buf);
    }
    /*
     * À ce moment, err contient la dernière erreur de vérification.
     * Ce peut être utilisé pour un but particulier
     */
    if (!preverify_ok && (err == X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT))
    {
      X509_NAME_oneline(X509_get_issuer_name(ctx->current_cert),
                        buf, 256);
      printf("issuer= %s\n", buf);
    }
    if (mydata->always_continue)
      return 1;
    else
      return preverify_ok;
 }
 ...
 mydata_t mydata;
 ...
 mydata_index = SSL_get_ex_new_index(0, "mydata index",
                                     NULL, NULL, NULL);
 ...
 SSL_CTX_set_verify(ctx, SSL_VERIFY_PEER|SSL_VERIFY_CLIENT_ONCE,
                    verify_callback);
 /*
  * Permettre à verify_callback de capturer l’erreur de verify_depth
  * pour obtenir une erreur appropriée dans le journal.
  */
 SSL_CTX_set_verify_depth(verify_depth + 1);
 /*
  * Définir les données spécifiques au SSL dans « mydata » et les
  * stocker dans la structure SSL.
  */
 mydata.verify_depth = verify_depth; ...
 SSL_set_ex_data(ssl, mydata_index, &mydata);
                                             
 ...
 SSL_accept(ssl);    /* Vérification d’une réussite omise pour clarté */
 if (peer = SSL_get_peer_certificate(ssl))
 {
   if (SSL_get_verify_result(ssl) == X509_V_OK)
   {
     /* Le client a envoyé un certificat valable */
   }
 }

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.