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