1--- 2c: Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al. 3SPDX-License-Identifier: curl 4Title: CURLOPT_HTTPAUTH 5Section: 3 6Source: libcurl 7Protocol: 8 - HTTP 9See-also: 10 - CURLOPT_PASSWORD (3) 11 - CURLOPT_PROXYAUTH (3) 12 - CURLOPT_USERNAME (3) 13--- 14 15# NAME 16 17CURLOPT_HTTPAUTH - HTTP server authentication methods to try 18 19# SYNOPSIS 20 21~~~c 22#include <curl/curl.h> 23 24CURLcode curl_easy_setopt(CURL *handle, CURLOPT_HTTPAUTH, long bitmask); 25~~~ 26 27# DESCRIPTION 28 29Pass a long as parameter, which is set to a bitmask, to tell libcurl which 30authentication method(s) you want it to use speaking to the remote server. 31 32The available bits are listed below. If more than one bit is set, libcurl 33first queries the host to see which authentication methods it supports and 34then picks the best one you allow it to use. For some methods, this induces an 35extra network round-trip. Set the actual name and password with the 36CURLOPT_USERPWD(3) option or with the CURLOPT_USERNAME(3) and the 37CURLOPT_PASSWORD(3) options. 38 39For authentication with a proxy, see CURLOPT_PROXYAUTH(3). 40 41## CURLAUTH_BASIC 42 43HTTP Basic authentication. This is the default choice, and the only method 44that is in wide-spread use and supported virtually everywhere. This sends 45the username and password over the network in plain text, easily captured by 46others. 47 48## CURLAUTH_DIGEST 49 50HTTP Digest authentication. Digest authentication is defined in RFC 2617 and 51is a more secure way to do authentication over public networks than the 52regular old-fashioned Basic method. 53 54## CURLAUTH_DIGEST_IE 55 56HTTP Digest authentication with an IE flavor. Digest authentication is defined 57in RFC 2617 and is a more secure way to do authentication over public networks 58than the regular old-fashioned Basic method. The IE flavor is simply that 59libcurl uses a special "quirk" that IE is known to have used before version 7 60and that some servers require the client to use. 61 62## CURLAUTH_BEARER 63 64HTTP Bearer token authentication, used primarily in OAuth 2.0 protocol. 65 66You can set the Bearer token to use with CURLOPT_XOAUTH2_BEARER(3). 67 68## CURLAUTH_NEGOTIATE 69 70HTTP Negotiate (SPNEGO) authentication. Negotiate authentication is defined 71in RFC 4559 and is the most secure way to perform authentication over HTTP. 72 73You need to build libcurl with a suitable GSS-API library or SSPI on Windows 74for this to work. 75 76## CURLAUTH_NTLM 77 78HTTP NTLM authentication. A proprietary protocol invented and used by 79Microsoft. It uses a challenge-response and hash concept similar to Digest, to 80prevent the password from being eavesdropped. 81 82You need to build libcurl with either OpenSSL or GnuTLS support for this 83option to work, or build libcurl on Windows with SSPI support. 84 85## CURLAUTH_NTLM_WB 86 87Support for this is removed since libcurl 8.8.0. 88 89NTLM delegating to winbind helper. Authentication is performed by a separate 90binary application that is executed when needed. The name of the application 91is specified at compile time but is typically **/usr/bin/ntlm_auth**. 92 93Note that libcurl forks when necessary to run the winbind application and kill 94it when complete, calling **waitpid()** to await its exit when done. On POSIX 95operating systems, killing the process causes a SIGCHLD signal to be raised 96(regardless of whether CURLOPT_NOSIGNAL(3) is set), which must be handled 97intelligently by the application. In particular, the application must not 98unconditionally call wait() in its SIGCHLD signal handler to avoid being 99subject to a race condition. This behavior is subject to change in future 100versions of libcurl. 101 102## CURLAUTH_ANY 103 104This is a convenience macro that sets all bits and thus makes libcurl pick any 105it finds suitable. libcurl automatically selects the one it finds most secure. 106 107## CURLAUTH_ANYSAFE 108 109This is a convenience macro that sets all bits except Basic and thus makes 110libcurl pick any it finds suitable. libcurl automatically selects the one it 111finds most secure. 112 113## CURLAUTH_ONLY 114 115This is a meta symbol. OR this value together with a single specific auth 116value to force libcurl to probe for unrestricted auth and if not, only that 117single auth algorithm is acceptable. 118 119## CURLAUTH_AWS_SIGV4 120 121provides AWS V4 signature authentication on HTTPS header 122see CURLOPT_AWS_SIGV4(3). 123 124# DEFAULT 125 126CURLAUTH_BASIC 127 128# EXAMPLE 129 130~~~c 131int main(void) 132{ 133 CURL *curl = curl_easy_init(); 134 if(curl) { 135 CURLcode ret; 136 curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/"); 137 /* allow whatever auth the server speaks */ 138 curl_easy_setopt(curl, CURLOPT_HTTPAUTH, (long)CURLAUTH_ANY); 139 curl_easy_setopt(curl, CURLOPT_USERPWD, "james:bond"); 140 ret = curl_easy_perform(curl); 141 } 142} 143~~~ 144 145# AVAILABILITY 146 147Option Added in 7.10.6. 148 149CURLAUTH_DIGEST_IE was added in 7.19.3 150 151CURLAUTH_ONLY was added in 7.21.3 152 153CURLAUTH_NTLM_WB was added in 7.22.0 154 155CURLAUTH_BEARER was added in 7.61.0 156 157CURLAUTH_AWS_SIGV4 was added in 7.74.0 158 159# RETURN VALUE 160 161Returns CURLE_OK if the option is supported, CURLE_UNKNOWN_OPTION if not, or 162CURLE_NOT_BUILT_IN if the bitmask specified no supported authentication 163methods. 164
