docs/libcurl/opts/CURLOPT_SSL_VERIFYHOST.3

   1 .\" **************************************************************************
   2 .\" *                                  _   _ ____  _
   3 .\" *  Project                     ___| | | |  _ \| |
   4 .\" *                             / __| | | | |_) | |
   5 .\" *                            | (__| |_| |  _ <| |___
   6 .\" *                             \___|\___/|_| \_\_____|
   7 .\" *
   8 .\" * Copyright (C) 1998 - 2015, Daniel Stenberg, <daniel@haxx.se>, et al.
   9 .\" *
  10 .\" * This software is licensed as described in the file COPYING, which
  11 .\" * you should have received as part of this distribution. The terms
  12 .\" * are also available at http://curl.haxx.se/docs/copyright.html.
  13 .\" *
  14 .\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
  15 .\" * copies of the Software, and permit persons to whom the Software is
  16 .\" * furnished to do so, under the terms of the COPYING file.
  17 .\" *
  18 .\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
  19 .\" * KIND, either express or implied.
  20 .\" *
  21 .\" **************************************************************************
  22 .\"
  23 .TH CURLOPT_SSL_VERIFYHOST 3 "17 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options"
  24 .SH NAME
  25 CURLOPT_SSL_VERIFYHOST \- verify the certificate's name against host
  26 .SH SYNOPSIS
  27 #include <curl/curl.h>
  28
  29 CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_VERIFYHOST, long verify);
  30 .SH DESCRIPTION
  31 Pass a long as parameter specifying what to \fIverify\fP.
  32
  33 This option determines whether libcurl verifies that the server cert is for
  34 the server it is known as.
  35
  36 When negotiating TLS and SSL connections, the server sends a certificate
  37 indicating its identity.
  38
  39 When \fICURLOPT_SSL_VERIFYHOST(3)\fP is 2, that certificate must indicate that
  40 the server is the server to which you meant to connect, or the connection
  41 fails. Simply put, it means it has to have the same name in the certificate as
  42 is in the URL you operate against.
  43
  44 Curl considers the server the intended one when the Common Name field or a
  45 Subject Alternate Name field in the certificate matches the host name in the
  46 URL to which you told Curl to connect.
  47
  48 When the \fIverify\fP value is 1, \fIcurl_easy_setopt\fP will return an error
  49 and the option value will not be changed.  It was previously (in 7.28.0 and
  50 earlier) a debug option of some sorts, but it is no longer supported due to
  51 frequently leading to programmer mistakes. Future versions will stop returning
  52 an error for 1 and just treat 1 and 2 the same.
  53
  54 When the \fIverify\fP value is 0, the connection succeeds regardless of the
  55 names in the certificate. Use that ability with caution!
  56
  57 The default value for this option is 2.
  58
  59 This option controls checking the server's certificate's claimed identity.
  60 The server could be lying.  To control lying, see
  61 \fICURLOPT_SSL_VERIFYPEER(3)\fP.  If libcurl is built against NSS and
  62 \fICURLOPT_SSL_VERIFYPEER(3)\fP is zero, \fICURLOPT_SSL_VERIFYHOST(3)\fP is
  63 also set to zero and cannot be overridden.
  64 .SH DEFAULT
  65 2
  66 .SH PROTOCOLS
  67 All TLS based protocols: HTTPS, FTPS, IMAPS, POP3, SMTPS etc.
  68 .SH EXAMPLE
  69 .nf
  70 CURL *curl = curl_easy_init();
  71 if(curl) {
  72   curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
  73
  74   /* Set the default value: strict name check please */
  75   curl_easy_setopt(curl, CURLOPT_SSL_VERIFYHOST, 2L);
  76
  77   curl_easy_perform(curl);
  78 }
  79 .fi
  80 .SH AVAILABILITY
  81 If built TLS enabled.
  82 .SH RETURN VALUE
  83 Returns CURLE_OK if TLS is supported, and CURLE_UNKNOWN_OPTION if not.
  84
  85 If 1 is set as argument, \fICURLE_BAD_FUNCTION_ARGUMENT\fP is returned.
  86 .SH "SEE ALSO"
  87 .BR CURLOPT_SSL_VERIFYPEER "(3), " CURLOPT_CAINFO "(3), "