1---
2c: Copyright (C) Daniel Stenberg, <daniel.se>, et al.
3SPDX-License-Identifier: curl
4Title: CURLOPT_USERPWD
5Section: 3
6Source: libcurl
7See-also:
8  - CURLOPT_PASSWORD (3)
9  - CURLOPT_PROXYUSERPWD (3)
10  - CURLOPT_USERNAME (3)
11---
12
13# NAME
14
15CURLOPT_USERPWD - user name and password to use in authentication
16
17# SYNOPSIS
18
19~~~c
20#include <curl/curl.h>
21
22CURLcode curl_easy_setopt(CURL *handle, CURLOPT_USERPWD, char *userpwd);
23~~~
24
25# DESCRIPTION
26
27Pass a char pointer as parameter, pointing to a null-terminated login details
28string for the connection. The format of which is: [user name]:[password].
29
30When using Kerberos V5 authentication with a Windows based server, you should
31specify the user name part with the domain name in order for the server to
32successfully obtain a Kerberos Ticket. If you do not then the initial part of
33the authentication handshake may fail.
34
35When using NTLM, the user name can be specified simply as the user name
36without the domain name should the server be part of a single domain and
37forest.
38
39To specify the domain name use either Down-Level Logon Name or UPN (User
40Principal Name) formats. For example **EXAMPLE\user** and **user@example.com**
41respectively.
42
43Some HTTP servers (on Windows) support inclusion of the domain for Basic
44authentication as well.
45
46When using HTTP and CURLOPT_FOLLOWLOCATION(3), libcurl might perform several
47requests to possibly different hosts. libcurl only sends this user and
48password information to hosts using the initial hostname (unless
49CURLOPT_UNRESTRICTED_AUTH(3) is set), so if libcurl follows redirects to other
50hosts, it does not send the user and password to those. This is enforced to
51prevent accidental information leakage.
52
53Use CURLOPT_HTTPAUTH(3) to specify the authentication method for HTTP
54based connections or CURLOPT_LOGIN_OPTIONS(3) to control IMAP, POP3 and
55SMTP options.
56
57The user and password strings are not URL decoded, so there is no way to send
58in a user name containing a colon using this option. Use
59CURLOPT_USERNAME(3) for that, or include it in the URL.
60
61The application does not have to keep the string around after setting this
62option.
63
64# DEFAULT
65
66NULL
67
68# PROTOCOLS
69
70Most
71
72# EXAMPLE
73
74~~~c
75int main(void)
76{
77  CURL *curl = curl_easy_init();
78  if(curl) {
79    CURLcode res;
80    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com/foo.bin");
81
82    curl_easy_setopt(curl, CURLOPT_USERPWD, "clark:kent");
83
84    res = curl_easy_perform(curl);
85
86    curl_easy_cleanup(curl);
87  }
88}
89~~~
90
91# AVAILABILITY
92
93Always
94
95# RETURN VALUE
96
97Returns CURLE_OK on success or
98CURLE_OUT_OF_MEMORY if there was insufficient heap space.
99