*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->Tru64 Unix man pages -> SSL_CTX_set_verify_depth (3)              
Title
Content
Arch
Section
 

SSL_CTX_set_verify(3)

Contents


NAME    [Toc]    [Back]

       SSL_CTX_set_verify,    SSL_set_verify,    SSL_CTX_set_verify_depth,
 SSL_set_verify_depth  -  Set  peer  certificate
       verification parameters

SYNOPSIS    [Toc]    [Back]

       #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 depth ); void SSL_set_verify_depth(
               SSL *s,
               int depth ); int verify_callback(
               int preverify_ok,
               X509_STORE_CTX *x509_ctx );

DESCRIPTION    [Toc]    [Back]

       The  SSL_CTX_set_verify()  function  sets the verification
       flags for ctx to be mode and  specifies  the  verify_callback()
  function  to  be  used. If no callback function is
       specified, the NULL pointer can be used  for  verify_callback().


       The  SSL_set_verify() function sets the verification flags
       for ssl to be mode  and  specifies  the  verify_callback()
       function to be used. If no callback function is specified,
       the NULL pointer can be  used  for  verify_callback().  In
       this  last  case verify_callback set specifically for this
       ssl remains. If no special callback was set,  the  default
       callback  for the underlying ctx that was valid at the the
       time ssl was created with the SSL_new() function is  used.

       The  SSL_CTX_set_verify_depth()  function sets the maximum
       depth for the certificate chain verification that will  be
       allowed for ctx.

       The SSL_set_verify_depth() function sets the maximum depth
       for  the  certificate  chain  verification  that  will  be
       allowed for ssl.

NOTES    [Toc]    [Back]

       The  verification  of  certificates can be controlled by a
       set of logically or'ed mode flags: Server mode: the server
       will  not send a client certificate request to the client,
       so the client will not send a certificate.

              Client mode: if not using an anonymous  cipher  (by
              default  disabled), the server will send a certificate
 which will be checked. The result of the  certificate
  verification process can be checked after
              the  TLS/SSL  handshake  using   the   SSL_get_verify_result()
  function.  The handshake will be continued
  regardless  of  the  verification   result.
              Server  mode: the server sends a client certificate
              request to the client. The certificate returned (if
              any) is checked. If the        verification process
              fails,  the  TLS/SSL   handshake   is   immediately
              terminated  with  an  alert  message containing the
              reason for  the         verification  failure.  The
              behavior   can  be  controlled  by  the  additional
              SSL_VERIFY_FAIL_IF_NO_PEER_CERT    and     SSL_VERIFY_CLIENT_ONCE
 flags.

              Client mode: the server certificate is verified. If
              the verification process fails, the  TLS/SSL  handshake
    is    immediately   terminated   with   an
              alert message containing the reason for the verification
 failure.  If no        server certificate is
              sent, because an anonymous cipher is used, SSL_VERIFY_PEER
  is ignored Server mode: if the client did
              not return a certificate, the TLS/SSL handshake  is
              immediately  terminated  with  a  handshake failure
              alert.  This  flag  must  be  used  together   with
              SSL_VERIFY_PEER.

              Client  mode:  ignored  Server mode: only request a
              client certificate on  the  initial  TLS/SSL  handshake.
 Do not ask for a client certificate again in
              case of a renegotiation. This  flag  must  be  used
              together with SSL_VERIFY_PEER.

              Client mode: ignored

       Either  SSL_VERIFY_NONE  or SSL_VERIFY_PEER must be set at
       any time.

       The actual  verification  procedure  is  performed  either
       using the built-in verification procedure or using another
       application provided verification function  set  with  the
       SSL_CTX_set_cert_verify_callback() function. The following
       descriptions apply in the case of the built-in  procedure.
       An  application  provided procedure also has access to the
       verify depth information and the  verify_callback()  function,
  but the way this information is used may be different.


       The SSL_CTX_set_verify_depth() and  SSL_set_verify_depth()
       functions  set the limit up to which depth certificates in
       a chain are used during the verification procedure. If the
       certificate chain is longer than allowed, the certificates
       above the limit are ignored. Error messages are  generated
       as if these certificates would not be present. Most likely
       a  X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY  will   be
       issued. The depth count is level 0:peer certificate, level
       1: CA certificate, level 2: higher level  CA  certificate,
       and  so on. Setting the maximum depth to 2 allows the levels
 0, 1, and 2. The default depth limit  is  9,  allowing
       for the peer certificate and additional 9 CA certificates.

       The verify_callback() function  is  used  to  control  the
       behavior  when the SSL_VERIFY_PEER flag is set. It must be
       supplied by the application and  receives  two  arguments:
       preverify_ok  indicates,  whether  the verification of the
       certificate in question was passed (preverify_ok=1) or not
       (preverify_ok=0).  The  x509_ctx  is a pointer to the complete
 context used for the certificate chain verification.

       The certificate chain is checked starting with the deepest
       nesting level (the root CA certificate) and worked  upward
       to  the  peer's  certificate. At each level signatures and
       issuer attributes are  checked.  Whenever  a  verification
       error  is  found,  the error number is stored in x509_ctx.
       The verify_callback()  function  is  called  with  preverify_ok=0.
  By  applying  X509_CTX_store_*  functions, verify_callback
 can locate the certificate  in  question  and
       perform  additional steps. If no error is found for a certificate,
 verify_callback() is called with  preverify_ok=1
       before advancing to the next level.

       The  return value of verify_callback() controls the strategy
 of the further verification process.  If  verify_callback()
 returns 0, the verification process stops with verification
 failed state. If SSL_VERIFY_PEER is set, a verification
 failure alert is sent to the peer and the TLS/SSL
       handshake terminates. If verify_callback() returns 1,  the
       verification  process  is  continued. If verify_callback()
       always returns 1, the TLS/SSL handshake will never be terminated
 because of this application experiencing a verification
  failure.   The  calling  process   can,   however,
       retrieve  the  error  code  of the last verification error
       using SSL_get_verify_result() or by  maintaining  its  own
       error storage managed by verify_callback().

       If no verify_callback() is specified, the default callback
       will be used. Its return value  is  identical  to  preverify_ok,
  so  that  any verification failure will lead to a
       termination of the TLS/SSL handshake with  an  alert  message,
 if SSL_VERIFY_PEER is set.

RESTRICTIONS    [Toc]    [Back]

       In  client  mode,  it  is not checked whether the SSL_VERIFY_PEER
 flag is set, but whether SSL_VERIFY_NONE  is  not
       set. This can lead to unexpected behavior, if the SSL_VERIFY_PEER
 and SSL_VERIFY_NONE are not used as required (one
       or the other must be set at any time).

       The   certificate   verification   depth   set   with  the
       SSL[_CTX]_verify_depth() function stops  the  verification
       at  a  certain  depth.  The error message produced will be
       that  of  an  incomplete   certificate   chain   and   not
       X509_V_ERR_CERT_CHAIN_TOO_LONG as may be expected.

RETURN VALUES    [Toc]    [Back]

       The SSL*_set_verify*() functions do not provide diagnostic
       information.

EXAMPLES    [Toc]    [Back]

       The following code sequence is  an  example  of  the  verify_callback()
  function  that  will  always  continue the
       TLS/SSL handshake regardless of verification failure.  The
       callback  realizes  a  verification  depth limit with more
       informational output.

       All verification errors are printed. Information about the
       certificate  chain  are printed on request. The example is
       realized for a server that allows, but not require, client
       certificates.

       The  example  makes  use of the ex_data technique to store
       application data into or retrieve  application  data  from
       the    SSL    structure    (see   SSL_get_ex_new_index(3),
       SSL_get_ex_data_X509(3), _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);

           /*
            *  Retrieve  the pointer to the SSL of the connection
       currently treated
            * and the application specific data stored  into  the
       SSL object.
            */
           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);

           /*
            * Catch a too long certificate chain. The depth limit
       set using
            * SSL_CTX_set_verify_depth() is  by  purpose  set  to
       "limit+1" so
            * that whenever the "depth>verify_depth" condition is
       met, we
            * have violated the limit and want to log this  error
       condition.
            *  We  must  do  it  here, because the CHAIN_TOO_LONG
       error would not
            * be found explicitly; only errors introduced by cutting
 off the
            * additional certificates would be logged.
            */
           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);
           }

           /*
            *  At  this point, err contains the last verification
       error. We can use
            * it for something special
            */
           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);

        /*
         * Let the verify_callback catch the  verify_depth  error
       so that we get
         * an appropriate error in the logfile.
         */
        SSL_CTX_set_verify_depth(verify_depth + 1);

        /*
         *  Set  up the SSL specific data into "mydata" and store
       it into th SSL
         * structure.
         */
        mydata.verify_depth = verify_depth; ...
        SSL_set_ex_data(ssl, mydata_index, &mydata);

        ...
        SSL_accept(ssl);   /* check of success left out for clarity
 */
        if (peer = SSL_get_peer_certificate(ssl))
        {
          if (SSL_get_verify_result(ssl) == X509_V_OK)
          {
            /* The client sent a certificate which verified OK */
          }
        }

SEE ALSO    [Toc]    [Back]

      
      
       Functions: ssl(3), SSL_new(3), SSL_CTX_get_verify_mode(3),
       SSL_get_verify_result(3),        SSL_CTX_load_verify_locations(3),                     SSL_get_peer_certificate(3),
       SSL_CTX_set_cert_verify_cb(3),     SSL_get_ex_data_X509(3)
       _STORE_CTX_idx(3), SSL_get_ex_new_index(3)



                                            SSL_CTX_set_verify(3)
[ Back ]
 Similar pages
Name OS Title
SSL_CTX_set_cert_verify_callback OpenBSD set peer certificate verification procedure
SSL_CTX_set_cert_verify_cb Tru64 Set peer certificate verification procedure
SSL_get_verify_result OpenBSD get result of peer certificate verification
SSL_get_verify_result Tru64 Get result of peer certificate verification
SSL_CTX_set_cert_verify_callback NetBSD set peer certificate verification procedure
SSL_get_verify_result NetBSD get result of peer certificate verification
SSL_set_verify_result NetBSD override result of peer certificate verification
SSL_set_verify_result OpenBSD override result of peer certificate verification
SSL_set_verify_result Tru64 Override result of peer certificate verification
SSL_get_peer_certificate NetBSD get the X509 certificate of the peer
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service