CURLOPT_SSL_OPTIONS.3 4.2 KB

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394
  1. .\" **************************************************************************
  2. .\" * _ _ ____ _
  3. .\" * Project ___| | | | _ \| |
  4. .\" * / __| | | | |_) | |
  5. .\" * | (__| |_| | _ <| |___
  6. .\" * \___|\___/|_| \_\_____|
  7. .\" *
  8. .\" * Copyright (C) 1998 - 2021, 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 https://curl.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_OPTIONS 3 "19 Jun 2014" "libcurl 7.37.0" "curl_easy_setopt options"
  24. .SH NAME
  25. CURLOPT_SSL_OPTIONS \- SSL behavior options
  26. .SH SYNOPSIS
  27. .nf
  28. #include <curl/curl.h>
  29. CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_OPTIONS, long bitmask);
  30. .fi
  31. .SH DESCRIPTION
  32. Pass a long with a bitmask to tell libcurl about specific SSL
  33. behaviors. Available bits:
  34. .IP CURLSSLOPT_ALLOW_BEAST
  35. Tells libcurl to not attempt to use any workarounds for a security flaw in the
  36. SSL3 and TLS1.0 protocols. If this option is not used or this bit is set to 0,
  37. the SSL layer libcurl uses may use a work-around for this flaw although it
  38. might cause interoperability problems with some (older) SSL
  39. implementations. WARNING: avoiding this work-around lessens the security, and
  40. by setting this option to 1 you ask for exactly that. This option is only
  41. supported for Secure Transport, NSS and OpenSSL.
  42. .IP CURLSSLOPT_NO_REVOKE
  43. Tells libcurl to disable certificate revocation checks for those SSL backends
  44. where such behavior is present. This option is only supported for Schannel
  45. (the native Windows SSL library), with an exception in the case of Windows'
  46. Untrusted Publishers block list which it seems cannot be bypassed. (Added in
  47. 7.44.0)
  48. .IP CURLSSLOPT_NO_PARTIALCHAIN
  49. Tells libcurl to not accept "partial" certificate chains, which it otherwise
  50. does by default. This option is only supported for OpenSSL and will fail the
  51. certificate verification if the chain ends with an intermediate certificate
  52. and not with a root cert. (Added in 7.68.0)
  53. .IP CURLSSLOPT_REVOKE_BEST_EFFORT
  54. Tells libcurl to ignore certificate revocation checks in case of missing or
  55. offline distribution points for those SSL backends where such behavior is
  56. present. This option is only supported for Schannel (the native Windows SSL
  57. library). If combined with \fICURLSSLOPT_NO_REVOKE\fP, the latter takes
  58. precedence. (Added in 7.70.0)
  59. .IP CURLSSLOPT_NATIVE_CA
  60. Tell libcurl to use the operating system's native CA store for certificate
  61. verification. Works only on Windows when built to use OpenSSL. This option is
  62. experimental and behavior is subject to change.
  63. (Added in 7.71.0)
  64. .IP CURLSSLOPT_AUTO_CLIENT_CERT
  65. Tell libcurl to automatically locate and use a client certificate for
  66. authentication, when requested by the server. This option is only supported
  67. for Schannel (the native Windows SSL library). Prior to 7.77.0 this was the
  68. default behavior in libcurl with Schannel. Since the server can request any
  69. certificate that supports client authentication in the OS certificate store it
  70. could be a privacy violation and unexpected.
  71. (Added in 7.77.0)
  72. .SH DEFAULT
  73. 0
  74. .SH PROTOCOLS
  75. All TLS-based protocols
  76. .SH EXAMPLE
  77. .nf
  78. CURL *curl = curl_easy_init();
  79. if(curl) {
  80. curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
  81. /* weaken TLS only for use with silly servers */
  82. curl_easy_setopt(curl, CURLOPT_SSL_OPTIONS, CURLSSLOPT_ALLOW_BEAST |
  83. CURLSSLOPT_NO_REVOKE);
  84. ret = curl_easy_perform(curl);
  85. curl_easy_cleanup(curl);
  86. }
  87. .fi
  88. .SH AVAILABILITY
  89. Added in 7.25.0
  90. .SH RETURN VALUE
  91. Returns CURLE_OK if the option is supported, and CURLE_UNKNOWN_OPTION if not.
  92. .SH "SEE ALSO"
  93. .BR CURLOPT_SSLVERSION "(3), " CURLOPT_SSL_CIPHER_LIST "(3), "