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