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), "
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>