mirror of
https://codeberg.org/kiss-community/repo
synced 2024-08-21 13:46:17 +00:00
123 lines
4.9 KiB
Groff
123 lines
4.9 KiB
Groff
.\" generated by cd2nroff 0.1 from CURLOPT_HTTPAUTH.md
|
|
.TH CURLOPT_HTTPAUTH 3 "2024-06-01" libcurl
|
|
.SH NAME
|
|
CURLOPT_HTTPAUTH \- HTTP server authentication methods to try
|
|
.SH SYNOPSIS
|
|
.nf
|
|
#include <curl/curl.h>
|
|
|
|
CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPAUTH, long bitmask);
|
|
.fi
|
|
.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
|
|
first queries the host to see which authentication methods it supports and
|
|
then picks the best one you allow it to use. For some methods, this induces 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 username and password over the network in plain text, easily captured by
|
|
others.
|
|
.IP CURLAUTH_DIGEST
|
|
HTTP Digest authentication. Digest authentication is defined in RFC 2617 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 RFC 2617 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 uses a special "quirk" that IE is known to have used before version 7
|
|
and that some servers require the client to use.
|
|
.IP CURLAUTH_BEARER
|
|
HTTP Bearer token authentication, used primarily in OAuth 2.0 protocol.
|
|
|
|
You can set the Bearer token to use with \fICURLOPT_XOAUTH2_BEARER(3)\fP.
|
|
.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 or GnuTLS support for this
|
|
option to work, or build libcurl on Windows with SSPI support.
|
|
.IP CURLAUTH_NTLM_WB
|
|
Support for this is removed since libcurl 8.8.0.
|
|
|
|
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 \fB/usr/bin/ntlm_auth\fP.
|
|
|
|
Note that libcurl forks when necessary to run the winbind application and kill
|
|
it when complete, calling \fBwaitpid()\fP to await its exit when done. On POSIX
|
|
operating systems, killing the process causes 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 automatically selects 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 automatically selects 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 unrestricted auth and if not, only that
|
|
single auth algorithm is acceptable.
|
|
.IP CURLAUTH_AWS_SIGV4
|
|
provides AWS V4 signature authentication on HTTPS header
|
|
see \fICURLOPT_AWS_SIGV4(3)\fP.
|
|
.SH DEFAULT
|
|
CURLAUTH_BASIC
|
|
.SH PROTOCOLS
|
|
HTTP
|
|
.SH EXAMPLE
|
|
.nf
|
|
int main(void)
|
|
{
|
|
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, (long)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
|
|
|
|
CURLAUTH_BEARER was added in 7.61.0
|
|
|
|
CURLAUTH_AWS_SIGV4 was added in 7.74.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_PASSWORD (3),
|
|
.BR CURLOPT_PROXYAUTH (3),
|
|
.BR CURLOPT_USERNAME (3)
|