Return to CURLOPT_HTTPAUTH.3 CVS log

Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / curl / docs / libcurl / opts

Annotation of embedaddon/curl/docs/libcurl/opts/CURLOPT_HTTPAUTH.3, revision 1.1.1.1

1.1       misho       1: .\" **************************************************************************
                      2: .\" *                                  _   _ ____  _
                      3: .\" *  Project                     ___| | | |  _ \| |
                      4: .\" *                             / __| | | | |_) | |
                      5: .\" *                            | (__| |_| |  _ <| |___
                      6: .\" *                             \___|\___/|_| \_\_____|
                      7: .\" *
                      8: .\" * Copyright (C) 1998 - 2018, 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.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_HTTPAUTH 3 "June 15, 2018" "libcurl 7.70.0" "curl_easy_setopt options"
                     24: 
                     25: .SH NAME
                     26: CURLOPT_HTTPAUTH \- set HTTP server authentication methods to try
                     27: .SH SYNOPSIS
                     28: .nf
                     29: #include <curl/curl.h>
                     30: 
                     31: CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPAUTH, long bitmask);
                     32: .SH DESCRIPTION
                     33: Pass a long as parameter, which is set to a bitmask, to tell libcurl which
                     34: authentication method(s) you want it to use speaking to the remote server.
                     35: 
                     36: The available bits are listed below. If more than one bit is set, libcurl will
                     37: first query the site to see which authentication methods it supports and then
                     38: pick the best one you allow it to use. For some methods, this will induce an
                     39: extra network round-trip. Set the actual name and password with the
                     40: \fICURLOPT_USERPWD(3)\fP option or with the \fICURLOPT_USERNAME(3)\fP and the
                     41: \fICURLOPT_PASSWORD(3)\fP options.
                     42: 
                     43: For authentication with a proxy, see \fICURLOPT_PROXYAUTH(3)\fP.
                     44: 
                     45: .IP CURLAUTH_BASIC
                     46: HTTP Basic authentication. This is the default choice, and the only method
                     47: that is in wide-spread use and supported virtually everywhere. This sends
                     48: the user name and password over the network in plain text, easily captured by
                     49: others.
                     50: .IP CURLAUTH_DIGEST
                     51: HTTP Digest authentication.  Digest authentication is defined in RFC2617 and
                     52: is a more secure way to do authentication over public networks than the
                     53: regular old-fashioned Basic method.
                     54: .IP CURLAUTH_DIGEST_IE
                     55: HTTP Digest authentication with an IE flavor.  Digest authentication is
                     56: defined in RFC2617 and is a more secure way to do authentication over public
                     57: networks than the regular old-fashioned Basic method. The IE flavor is simply
                     58: that libcurl will use a special "quirk" that IE is known to have used before
                     59: version 7 and that some servers require the client to use.
                     60: .IP CURLAUTH_BEARER
                     61: HTTP Bearer token authentication, used primarily in OAuth 2.0 protocol.
                     62: 
                     63: You can set the Bearer token to use with \fICURLOPT_XOAUTH2_BEARER(3)\fP.
                     64: .IP CURLAUTH_NEGOTIATE
                     65: HTTP Negotiate (SPNEGO) authentication. Negotiate authentication is defined
                     66: in RFC 4559 and is the most secure way to perform authentication over HTTP.
                     67: 
                     68: You need to build libcurl with a suitable GSS-API library or SSPI on Windows
                     69: for this to work.
                     70: .IP CURLAUTH_NTLM
                     71: HTTP NTLM authentication. A proprietary protocol invented and used by
                     72: Microsoft. It uses a challenge-response and hash concept similar to Digest, to
                     73: prevent the password from being eavesdropped.
                     74: 
                     75: You need to build libcurl with either OpenSSL, GnuTLS or NSS support for this
                     76: option to work, or build libcurl on Windows with SSPI support.
                     77: .IP CURLAUTH_NTLM_WB
                     78: NTLM delegating to winbind helper. Authentication is performed by a separate
                     79: binary application that is executed when needed. The name of the application
                     80: is specified at compile time but is typically /usr/bin/ntlm_auth
                     81: 
                     82: Note that libcurl will fork when necessary to run the winbind application and
                     83: kill it when complete, calling waitpid() to await its exit when done. On POSIX
                     84: operating systems, killing the process will cause a SIGCHLD signal to be
                     85: raised (regardless of whether \fICURLOPT_NOSIGNAL(3)\fP is set), which must be
                     86: handled intelligently by the application. In particular, the application must
                     87: not unconditionally call wait() in its SIGCHLD signal handler to avoid being
                     88: subject to a race condition.  This behavior is subject to change in future
                     89: versions of libcurl.
                     90: .IP CURLAUTH_ANY
                     91: This is a convenience macro that sets all bits and thus makes libcurl pick any
                     92: it finds suitable. libcurl will automatically select the one it finds most
                     93: secure.
                     94: .IP CURLAUTH_ANYSAFE
                     95: This is a convenience macro that sets all bits except Basic and thus makes
                     96: libcurl pick any it finds suitable. libcurl will automatically select the one
                     97: it finds most secure.
                     98: .IP CURLAUTH_ONLY
                     99: This is a meta symbol. OR this value together with a single specific auth
                    100: value to force libcurl to probe for un-restricted auth and if not, only that
                    101: single auth algorithm is acceptable.
                    102: .SH DEFAULT
                    103: CURLAUTH_BASIC
                    104: .SH PROTOCOLS
                    105: HTTP
                    106: .SH EXAMPLE
                    107: .nf
                    108: CURL *curl = curl_easy_init();
                    109: if(curl) {
                    110:   CURLcode ret;
                    111:   curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
                    112:   /* allow whatever auth the server speaks */
                    113:   curl_easy_setopt(curl, CURLOPT_HTTPAUTH, CURLAUTH_ANY);
                    114:   curl_easy_setopt(curl, CURLOPT_USERPWD, "james:bond");
                    115:   ret = curl_easy_perform(curl);
                    116: }
                    117: .fi
                    118: .SH AVAILABILITY
                    119: Option Added in 7.10.6.
                    120: 
                    121: CURLAUTH_DIGEST_IE was added in 7.19.3
                    122: 
                    123: CURLAUTH_ONLY was added in 7.21.3
                    124: 
                    125: CURLAUTH_NTLM_WB was added in 7.22.0
                    126: 
                    127: CURLAUTH_BEARER was added in 7.61.0
                    128: .SH RETURN VALUE
                    129: Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
                    130: CURLE_NOT_BUILT_IN if the bitmask specified no supported authentication
                    131: methods.
                    132: .SH "SEE ALSO"
                    133: .BR CURLOPT_PROXYAUTH "(3), " CURLOPT_USERPWD "(3), "