mirror of
https://github.com/moparisthebest/curl
synced 2024-11-18 07:25:14 -05:00
127 lines
5.5 KiB
Groff
127 lines
5.5 KiB
Groff
.\" **************************************************************************
|
|
.\" * _ _ ____ _
|
|
.\" * Project ___| | | | _ \| |
|
|
.\" * / __| | | | |_) | |
|
|
.\" * | (__| |_| | _ <| |___
|
|
.\" * \___|\___/|_| \_\_____|
|
|
.\" *
|
|
.\" * Copyright (C) 1998 - 2017, Daniel Stenberg, <daniel@haxx.se>, et al.
|
|
.\" *
|
|
.\" * This software is licensed as described in the file COPYING, which
|
|
.\" * you should have received as part of this distribution. The terms
|
|
.\" * are also available at https://curl.haxx.se/docs/copyright.html.
|
|
.\" *
|
|
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
|
|
.\" * copies of the Software, and permit persons to whom the Software is
|
|
.\" * furnished to do so, under the terms of the COPYING file.
|
|
.\" *
|
|
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
|
|
.\" * KIND, either express or implied.
|
|
.\" *
|
|
.\" **************************************************************************
|
|
.\"
|
|
.TH CURLOPT_HTTPAUTH 3 "2 Aug 2014" "libcurl 7.38.0" "curl_easy_setopt options"
|
|
.SH NAME
|
|
CURLOPT_HTTPAUTH \- set HTTP server authentication methods to try
|
|
.SH SYNOPSIS
|
|
.nf
|
|
#include <curl/curl.h>
|
|
|
|
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPAUTH, long bitmask);
|
|
.SH DESCRIPTION
|
|
Pass a long as parameter, which is set to a bitmask, to tell libcurl which
|
|
authentication method(s) you want it to use speaking to the remote server.
|
|
|
|
The available bits are listed below. If more than one bit is set, libcurl will
|
|
first query the site to see which authentication methods it supports and then
|
|
pick the best one you allow it to use. For some methods, this will induce an
|
|
extra network round-trip. Set the actual name and password with the
|
|
\fICURLOPT_USERPWD(3)\fP option or with the \fICURLOPT_USERNAME(3)\fP and the
|
|
\fICURLOPT_PASSWORD(3)\fP options.
|
|
|
|
For authentication with a proxy, see \fICURLOPT_PROXYAUTH(3)\fP.
|
|
|
|
.IP CURLAUTH_BASIC
|
|
HTTP Basic authentication. This is the default choice, and the only method
|
|
that is in wide-spread use and supported virtually everywhere. This sends
|
|
the user name and password over the network in plain text, easily captured by
|
|
others.
|
|
.IP CURLAUTH_DIGEST
|
|
HTTP Digest authentication. Digest authentication is defined in RFC2617 and
|
|
is a more secure way to do authentication over public networks than the
|
|
regular old-fashioned Basic method.
|
|
.IP CURLAUTH_DIGEST_IE
|
|
HTTP Digest authentication with an IE flavor. Digest authentication is
|
|
defined in RFC2617 and is a more secure way to do authentication over public
|
|
networks than the regular old-fashioned Basic method. The IE flavor is simply
|
|
that libcurl will use a special "quirk" that IE is known to have used before
|
|
version 7 and that some servers require the client to use.
|
|
.IP CURLAUTH_NEGOTIATE
|
|
HTTP Negotiate (SPNEGO) authentication. Negotiate authentication is defined
|
|
in RFC 4559 and is the most secure way to perform authentication over HTTP.
|
|
|
|
You need to build libcurl with a suitable GSS-API library or SSPI on Windows
|
|
for this to work.
|
|
.IP CURLAUTH_NTLM
|
|
HTTP NTLM authentication. A proprietary protocol invented and used by
|
|
Microsoft. It uses a challenge-response and hash concept similar to Digest, to
|
|
prevent the password from being eavesdropped.
|
|
|
|
You need to build libcurl with either OpenSSL, GnuTLS or NSS support for this
|
|
option to work, or build libcurl on Windows with SSPI support.
|
|
.IP CURLAUTH_NTLM_WB
|
|
NTLM delegating to winbind helper. Authentication is performed by a separate
|
|
binary application that is executed when needed. The name of the application
|
|
is specified at compile time but is typically /usr/bin/ntlm_auth
|
|
|
|
Note that libcurl will fork when necessary to run the winbind application and
|
|
kill it when complete, calling waitpid() to await its exit when done. On POSIX
|
|
operating systems, killing the process will cause a SIGCHLD signal to be
|
|
raised (regardless of whether \fICURLOPT_NOSIGNAL(3)\fP is set), which must be
|
|
handled intelligently by the application. In particular, the application must
|
|
not unconditionally call wait() in its SIGCHLD signal handler to avoid being
|
|
subject to a race condition. This behavior is subject to change in future
|
|
versions of libcurl.
|
|
.IP CURLAUTH_ANY
|
|
This is a convenience macro that sets all bits and thus makes libcurl pick any
|
|
it finds suitable. libcurl will automatically select the one it finds most
|
|
secure.
|
|
.IP CURLAUTH_ANYSAFE
|
|
This is a convenience macro that sets all bits except Basic and thus makes
|
|
libcurl pick any it finds suitable. libcurl will automatically select the one
|
|
it finds most secure.
|
|
.IP CURLAUTH_ONLY
|
|
This is a meta symbol. OR this value together with a single specific auth
|
|
value to force libcurl to probe for un-restricted auth and if not, only that
|
|
single auth algorithm is acceptable.
|
|
.SH DEFAULT
|
|
CURLAUTH_BASIC
|
|
.SH PROTOCOLS
|
|
HTTP
|
|
.SH EXAMPLE
|
|
.nf
|
|
CURL *curl = curl_easy_init();
|
|
if(curl) {
|
|
CURLcode ret;
|
|
curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/");
|
|
/* allow whatever auth the server speaks */
|
|
curl_easy_setopt(curl, CURLOPT_HTTPAUTH, CURLAUTH_ANY);
|
|
curl_easy_setopt(curl, CURLOPT_USERPWD, "james:bond");
|
|
ret = curl_easy_perform(curl);
|
|
}
|
|
.fi
|
|
.SH AVAILABILITY
|
|
Option Added in 7.10.6.
|
|
|
|
CURLAUTH_DIGEST_IE was added in 7.19.3
|
|
|
|
CURLAUTH_ONLY was added in 7.21.3
|
|
|
|
CURLAUTH_NTLM_WB was added in 7.22.0
|
|
.SH RETURN VALUE
|
|
Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or
|
|
CURLE_NOT_BUILT_IN if the bitmask specified no supported authentication
|
|
methods.
|
|
.SH "SEE ALSO"
|
|
.BR CURLOPT_PROXYAUTH "(3), " CURLOPT_USERPWD "(3), "
|