| 1 |
.\" ************************************************************************** |
| 2 |
.\" * _ _ ____ _ |
| 3 |
.\" * Project ___| | | | _ \| | |
| 4 |
.\" * / __| | | | |_) | | |
| 5 |
.\" * | (__| |_| | _ <| |___ |
| 6 |
.\" * \___|\___/|_| \_\_____| |
| 7 |
.\" * |
| 8 |
.\" * Copyright (C) 1998 - 2019, Daniel Stenberg, <[email protected]>, et al. |
| 9 |
.\" * |
| 10 |
.\" * This software is licensed as described in the file COPYING, which |
| 11 |
.\" * you should have received as part of this distribution. The terms |
| 12 |
.\" * are also available at https://curl.haxx.se/docs/copyright.html. |
| 13 |
.\" * |
| 14 |
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell |
| 15 |
.\" * copies of the Software, and permit persons to whom the Software is |
| 16 |
.\" * furnished to do so, under the terms of the COPYING file. |
| 17 |
.\" * |
| 18 |
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY |
| 19 |
.\" * KIND, either express or implied. |
| 20 |
.\" * |
| 21 |
.\" ************************************************************************** |
| 22 |
.\" |
| 23 |
.TH libcurl-security 3 "13 Feb 2018" "libcurl" "libcurl security" |
| 24 |
.SH NAME |
| 25 |
libcurl-security \- security considerations when using libcurl |
| 26 |
.SH "Security" |
| 27 |
The libcurl project takes security seriously. The library is written with |
| 28 |
caution and precautions are taken to mitigate many kinds of risks encountered |
| 29 |
while operating with potentially malicious servers on the Internet. It is a |
| 30 |
powerful library, however, which allows application writers to make trade-offs |
| 31 |
between ease of writing and exposure to potential risky operations. If used |
| 32 |
the right way, you can use libcurl to transfer data pretty safely. |
| 33 |
|
| 34 |
Many applications are used in closed networks where users and servers can |
| 35 |
(possibly) be trusted, but many others are used on arbitrary servers and are |
| 36 |
fed input from potentially untrusted users. Following is a discussion about |
| 37 |
some risks in the ways in which applications commonly use libcurl and |
| 38 |
potential mitigations of those risks. It is by no means comprehensive, but |
| 39 |
shows classes of attacks that robust applications should consider. The Common |
| 40 |
Weakness Enumeration project at https://cwe.mitre.org/ is a good reference for |
| 41 |
many of these and similar types of weaknesses of which application writers |
| 42 |
should be aware. |
| 43 |
.SH "Command Lines" |
| 44 |
If you use a command line tool (such as curl) that uses libcurl, and you give |
| 45 |
options to the tool on the command line those options can very likely get read |
| 46 |
by other users of your system when they use 'ps' or other tools to list |
| 47 |
currently running processes. |
| 48 |
|
| 49 |
To avoid these problems, never feed sensitive things to programs using command |
| 50 |
line options. Write them to a protected file and use the \-K option to avoid |
| 51 |
this. |
| 52 |
.SH ".netrc" |
| 53 |
\&.netrc is a pretty handy file/feature that allows you to login quickly and |
| 54 |
automatically to frequently visited sites. The file contains passwords in |
| 55 |
clear text and is a real security risk. In some cases, your .netrc is also |
| 56 |
stored in a home directory that is NFS mounted or used on another network |
| 57 |
based file system, so the clear text password will fly through your network |
| 58 |
every time anyone reads that file! |
| 59 |
|
| 60 |
For applications that enable .netrc use, a user who manage to set the right |
| 61 |
URL might then be possible to pass on passwords. |
| 62 |
|
| 63 |
To avoid these problems, don't use .netrc files and never store passwords in |
| 64 |
plain text anywhere. |
| 65 |
.SH "Clear Text Passwords" |
| 66 |
Many of the protocols libcurl supports send name and password unencrypted as |
| 67 |
clear text (HTTP Basic authentication, FTP, TELNET etc). It is very easy for |
| 68 |
anyone on your network or a network nearby yours to just fire up a network |
| 69 |
analyzer tool and eavesdrop on your passwords. Don't let the fact that HTTP |
| 70 |
Basic uses base64 encoded passwords fool you. They may not look readable at a |
| 71 |
first glance, but they very easily "deciphered" by anyone within seconds. |
| 72 |
|
| 73 |
To avoid this problem, use an authentication mechanism or other protocol that |
| 74 |
doesn't let snoopers see your password: Digest, CRAM-MD5, Kerberos, SPNEGO or |
| 75 |
NTLM authentication. Or even better: use authenticated protocols that protect |
| 76 |
the entire connection and everything sent over it. |
| 77 |
.SH "Un-authenticated Connections" |
| 78 |
Protocols that don't have any form of cryptographic authentication cannot |
| 79 |
with any certainty know that they communicate with the right remote server. |
| 80 |
|
| 81 |
If your application is using a fixed scheme or fixed host name, it is not safe |
| 82 |
as long as the connection is un-authenticated. There can be a |
| 83 |
man-in-the-middle or in fact the whole server might have been replaced by an |
| 84 |
evil actor. |
| 85 |
|
| 86 |
Un-authenticated protocols are unsafe. The data that comes back to curl may |
| 87 |
have been injected by an attacker. The data that curl sends might be modified |
| 88 |
before it reaches the intended server. If it even reaches the intended server |
| 89 |
at all. |
| 90 |
|
| 91 |
Remedies: |
| 92 |
.IP "Restrict operations to authenticated transfers" |
| 93 |
Ie use authenticated protocols protected with HTTPS or SSH. |
| 94 |
.IP "Make sure the server's certificate etc is verified" |
| 95 |
Never ever switch off certificate verification. |
| 96 |
.SH "Redirects" |
| 97 |
The \fICURLOPT_FOLLOWLOCATION(3)\fP option automatically follows HTTP |
| 98 |
redirects sent by a remote server. These redirects can refer to any kind of |
| 99 |
URL, not just HTTP. libcurl restricts the protocols allowed to be used in |
| 100 |
redirects for security reasons: only HTTP, HTTPS, FTP and FTPS are |
| 101 |
enabled by default. Applications may opt to restrict that set further. |
| 102 |
|
| 103 |
A redirect to a file: URL would cause the libcurl to read (or write) arbitrary |
| 104 |
files from the local filesystem. If the application returns the data back to |
| 105 |
the user (as would happen in some kinds of CGI scripts), an attacker could |
| 106 |
leverage this to read otherwise forbidden data (e.g. |
| 107 |
file://localhost/etc/passwd). |
| 108 |
|
| 109 |
If authentication credentials are stored in the ~/.netrc file, or Kerberos |
| 110 |
is in use, any other URL type (not just file:) that requires |
| 111 |
authentication is also at risk. A redirect such as |
| 112 |
ftp://some-internal-server/private-file would then return data even when |
| 113 |
the server is password protected. |
| 114 |
|
| 115 |
In the same way, if an unencrypted SSH private key has been configured for the |
| 116 |
user running the libcurl application, SCP: or SFTP: URLs could access password |
| 117 |
or private-key protected resources, |
| 118 |
e.g. sftp://user@some-internal-server/etc/passwd |
| 119 |
|
| 120 |
The \fICURLOPT_REDIR_PROTOCOLS(3)\fP and \fICURLOPT_NETRC(3)\fP options can be |
| 121 |
used to mitigate against this kind of attack. |
| 122 |
|
| 123 |
A redirect can also specify a location available only on the machine running |
| 124 |
libcurl, including servers hidden behind a firewall from the attacker. |
| 125 |
e.g. http://127.0.0.1/ or http://intranet/delete-stuff.cgi?delete=all or |
| 126 |
tftp://bootp-server/pc-config-data |
| 127 |
|
| 128 |
Applications can mitigate against this by disabling |
| 129 |
\fICURLOPT_FOLLOWLOCATION(3)\fP and handling redirects itself, sanitizing URLs |
| 130 |
as necessary. Alternately, an app could leave \fICURLOPT_FOLLOWLOCATION(3)\fP |
| 131 |
enabled but set \fICURLOPT_REDIR_PROTOCOLS(3)\fP and install a |
| 132 |
\fICURLOPT_OPENSOCKETFUNCTION(3)\fP callback function in which addresses are |
| 133 |
sanitized before use. |
| 134 |
.SH "Local Resources" |
| 135 |
A user who can control the DNS server of a domain being passed in within a URL |
| 136 |
can change the address of the host to a local, private address which a |
| 137 |
server-side libcurl-using application could then use. e.g. the innocuous URL |
| 138 |
http://fuzzybunnies.example.com/ could actually resolve to the IP address of a |
| 139 |
server behind a firewall, such as 127.0.0.1 or 10.1.2.3. Applications can |
| 140 |
mitigate against this by setting a \fICURLOPT_OPENSOCKETFUNCTION(3)\fP and |
| 141 |
checking the address before a connection. |
| 142 |
|
| 143 |
All the malicious scenarios regarding redirected URLs apply just as well to |
| 144 |
non-redirected URLs, if the user is allowed to specify an arbitrary URL that |
| 145 |
could point to a private resource. For example, a web app providing a |
| 146 |
translation service might happily translate file://localhost/etc/passwd and |
| 147 |
display the result. Applications can mitigate against this with the |
| 148 |
\fICURLOPT_PROTOCOLS(3)\fP option as well as by similar mitigation techniques |
| 149 |
for redirections. |
| 150 |
|
| 151 |
A malicious FTP server could in response to the PASV command return an IP |
| 152 |
address and port number for a server local to the app running libcurl but |
| 153 |
behind a firewall. Applications can mitigate against this by using the |
| 154 |
\fICURLOPT_FTP_SKIP_PASV_IP(3)\fP option or \fICURLOPT_FTPPORT(3)\fP. |
| 155 |
|
| 156 |
Local servers sometimes assume local access comes from friends and trusted |
| 157 |
users. An application that expects http://example.com/file_to_read that and |
| 158 |
instead gets http://192.168.0.1/my_router_config might print a file that would |
| 159 |
otherwise be protected by the firewall. |
| 160 |
|
| 161 |
Allowing your application to connect to local hosts, be it the same machine |
| 162 |
that runs the application or a machine on the same local network, might be |
| 163 |
possible to exploit by an attacker who then perhaps can "port-scan" the |
| 164 |
particular hosts - depending on how the application and servers acts. |
| 165 |
.SH "IPv6 Addresses" |
| 166 |
libcurl will normally handle IPv6 addresses transparently and just as easily |
| 167 |
as IPv4 addresses. That means that a sanitizing function that filters out |
| 168 |
addresses like 127.0.0.1 isn't sufficient--the equivalent IPv6 addresses ::1, |
| 169 |
::, 0:00::0:1, ::127.0.0.1 and ::ffff:7f00:1 supplied somehow by an attacker |
| 170 |
would all bypass a naive filter and could allow access to undesired local |
| 171 |
resources. IPv6 also has special address blocks like link-local and |
| 172 |
site-local that generally shouldn't be accessed by a server-side libcurl-using |
| 173 |
application. A poorly-configured firewall installed in a data center, |
| 174 |
organization or server may also be configured to limit IPv4 connections but |
| 175 |
leave IPv6 connections wide open. In some cases, setting |
| 176 |
\fICURLOPT_IPRESOLVE(3)\fP to CURL_IPRESOLVE_V4 can be used to limit resolved |
| 177 |
addresses to IPv4 only and bypass these issues. |
| 178 |
.SH Uploads |
| 179 |
When uploading, a redirect can cause a local (or remote) file to be |
| 180 |
overwritten. Applications must not allow any unsanitized URL to be passed in |
| 181 |
for uploads. Also, \fICURLOPT_FOLLOWLOCATION(3)\fP should not be used on |
| 182 |
uploads. Instead, the applications should consider handling redirects itself, |
| 183 |
sanitizing each URL first. |
| 184 |
.SH Authentication |
| 185 |
Use of \fICURLOPT_UNRESTRICTED_AUTH(3)\fP could cause authentication |
| 186 |
information to be sent to an unknown second server. Applications can mitigate |
| 187 |
against this by disabling \fICURLOPT_FOLLOWLOCATION(3)\fP and handling |
| 188 |
redirects itself, sanitizing where necessary. |
| 189 |
|
| 190 |
Use of the CURLAUTH_ANY option to \fICURLOPT_HTTPAUTH(3)\fP could result in |
| 191 |
user name and password being sent in clear text to an HTTP server. Instead, |
| 192 |
use CURLAUTH_ANYSAFE which ensures that the password is encrypted over the |
| 193 |
network, or else fail the request. |
| 194 |
|
| 195 |
Use of the CURLUSESSL_TRY option to \fICURLOPT_USE_SSL(3)\fP could result in |
| 196 |
user name and password being sent in clear text to an FTP server. Instead, |
| 197 |
use CURLUSESSL_CONTROL to ensure that an encrypted connection is used or else |
| 198 |
fail the request. |
| 199 |
.SH Cookies |
| 200 |
If cookies are enabled and cached, then a user could craft a URL which |
| 201 |
performs some malicious action to a site whose authentication is already |
| 202 |
stored in a cookie. e.g. http://mail.example.com/delete-stuff.cgi?delete=all |
| 203 |
Applications can mitigate against this by disabling cookies or clearing them |
| 204 |
between requests. |
| 205 |
.SH "Dangerous SCP URLs" |
| 206 |
SCP URLs can contain raw commands within the scp: URL, which is a side effect |
| 207 |
of how the SCP protocol is designed. e.g. |
| 208 |
|
| 209 |
scp://user:pass@host/a;date >/tmp/test; |
| 210 |
|
| 211 |
Applications must not allow unsanitized SCP: URLs to be passed in for |
| 212 |
downloads. |
| 213 |
.SH "file://" |
| 214 |
By default curl and libcurl support file:// URLs. Such a URL is always an |
| 215 |
access, or attempted access, to a local resource. If your application wants to |
| 216 |
avoid that, keep control of what URLs to use and/or prevent curl/libcurl from |
| 217 |
using the protocol. |
| 218 |
|
| 219 |
By default, libcurl prohibits redirects to file:// URLs. |
| 220 |
.SH "What if the user can set the URL" |
| 221 |
Applications may find it tempting to let users set the URL that it can work |
| 222 |
on. That's probably fine, but opens up for mischief and trickery that you as |
| 223 |
an application author may want to address or take precautions against. |
| 224 |
|
| 225 |
If your curl-using script allow a custom URL do you also, perhaps |
| 226 |
unintentionally, allow the user to pass other options to the curl command line |
| 227 |
if creative use of special characters are applied? |
| 228 |
|
| 229 |
If the user can set the URL, the user can also specify the scheme part to |
| 230 |
other protocols that you didn't intend for users to use and perhaps didn't |
| 231 |
consider. curl supports over 20 different URL schemes. "http://" might be what |
| 232 |
you thought, "ftp://" or "imap://" might be what the user gives your |
| 233 |
application. Also, cross-protocol operations might be done by using a |
| 234 |
particular scheme in the URL but point to a server doing a different protocol |
| 235 |
on a non-standard port. |
| 236 |
|
| 237 |
Remedies: |
| 238 |
.IP "Use --proto" |
| 239 |
curl command lines can use \fI--proto\fP to limit what URL schemes it accepts |
| 240 |
.IP "Use CURLOPT_PROTOCOLS" |
| 241 |
libcurl programs can use \fICURLOPT_PROTOCOLS(3)\fP to limit what URL schemes it accepts |
| 242 |
.IP "consider not allowing the user to set the full URL" |
| 243 |
Maybe just let the user provide data for parts of it? Or maybe filter input to |
| 244 |
only allow specific choices? |
| 245 |
.SH "RFC 3986 vs WHATWG URL" |
| 246 |
curl supports URLs mostly according to how they are defined in RFC 3986, and |
| 247 |
has done so since the beginning. |
| 248 |
|
| 249 |
Web browsers mostly adhere to the WHATWG URL Specification. |
| 250 |
|
| 251 |
This deviance makes some URLs copied between browsers (or returned over HTTP |
| 252 |
for redirection) and curl not work the same way. This can mislead users into |
| 253 |
getting the wrong thing, connecting to the wrong host or otherwise not work |
| 254 |
identically. |
| 255 |
.SH "FTP uses two connections" |
| 256 |
When performing an FTP transfer, two TCP connections are used: one for setting |
| 257 |
up the transfer and one for the actual data. |
| 258 |
|
| 259 |
FTP is not only un-authenticated, but the setting up of the second transfer is |
| 260 |
also a weak spot. The second connection to use for data, is either setup with |
| 261 |
the PORT/EPRT command that makes the server connect back to the client on the |
| 262 |
given IP+PORT, or with PASV/EPSV that makes the server setup a port to listen |
| 263 |
to and tells the client to connect to a given IP+PORT. |
| 264 |
|
| 265 |
Again, un-authenticated means that the connection might be meddled with by a |
| 266 |
man-in-the-middle or that there's a malicious server pretending to be the |
| 267 |
right one. |
| 268 |
|
| 269 |
A malicious FTP server can respond to PASV commands with the IP+PORT of a |
| 270 |
totally different machine. Perhaps even a third party host, and when there are |
| 271 |
many clients trying to connect to that third party, it could create a |
| 272 |
Distributed Denial-Of-Service attack out of it! If the client makes an upload |
| 273 |
operation, it can make the client send the data to another site. If the |
| 274 |
attacker can affect what data the client uploads, it can be made to work as a |
| 275 |
HTTP request and then the client could be made to issue HTTP requests to third |
| 276 |
party hosts. |
| 277 |
|
| 278 |
An attacker that manages to control curl's command line options can tell curl |
| 279 |
to send an FTP PORT command to ask the server to connect to a third party host |
| 280 |
instead of back to curl. |
| 281 |
|
| 282 |
The fact that FTP uses two connections makes it vulnerable in a way that is |
| 283 |
hard to avoid. |
| 284 |
.SH "Denial of Service" |
| 285 |
A malicious server could cause libcurl to effectively hang by sending data |
| 286 |
very slowly, or even no data at all but just keeping the TCP connection open. |
| 287 |
This could effectively result in a denial-of-service attack. The |
| 288 |
\fICURLOPT_TIMEOUT(3)\fP and/or \fICURLOPT_LOW_SPEED_LIMIT(3)\fP options can |
| 289 |
be used to mitigate against this. |
| 290 |
|
| 291 |
A malicious server could cause libcurl to download an infinite amount of data, |
| 292 |
potentially causing all of memory or disk to be filled. Setting the |
| 293 |
\fICURLOPT_MAXFILESIZE_LARGE(3)\fP option is not sufficient to guard against |
| 294 |
this. Instead, applications should monitor the amount of data received within |
| 295 |
the write or progress callback and abort once the limit is reached. |
| 296 |
|
| 297 |
A malicious HTTP server could cause an infinite redirection loop, causing a |
| 298 |
denial-of-service. This can be mitigated by using the |
| 299 |
\fICURLOPT_MAXREDIRS(3)\fP option. |
| 300 |
.SH "Arbitrary Headers" |
| 301 |
User-supplied data must be sanitized when used in options like |
| 302 |
\fICURLOPT_USERAGENT(3)\fP, \fICURLOPT_HTTPHEADER(3)\fP, |
| 303 |
\fICURLOPT_POSTFIELDS(3)\fP and others that are used to generate structured |
| 304 |
data. Characters like embedded carriage returns or ampersands could allow the |
| 305 |
user to create additional headers or fields that could cause malicious |
| 306 |
transactions. |
| 307 |
.SH "Server-supplied Names" |
| 308 |
A server can supply data which the application may, in some cases, use as a |
| 309 |
file name. The curl command-line tool does this with |
| 310 |
\fI--remote-header-name\fP, using the Content-disposition: header to generate |
| 311 |
a file name. An application could also use \fICURLINFO_EFFECTIVE_URL(3)\fP to |
| 312 |
generate a file name from a server-supplied redirect URL. Special care must be |
| 313 |
taken to sanitize such names to avoid the possibility of a malicious server |
| 314 |
supplying one like "/etc/passwd", "\\autoexec.bat", "prn:" or even ".bashrc". |
| 315 |
.SH "Server Certificates" |
| 316 |
A secure application should never use the \fICURLOPT_SSL_VERIFYPEER(3)\fP |
| 317 |
option to disable certificate validation. There are numerous attacks that are |
| 318 |
enabled by applications that fail to properly validate server TLS/SSL |
| 319 |
certificates, thus enabling a malicious server to spoof a legitimate |
| 320 |
one. HTTPS without validated certificates is potentially as insecure as a |
| 321 |
plain HTTP connection. |
| 322 |
.SH "Report Security Problems" |
| 323 |
Should you detect or just suspect a security problem in libcurl or curl, |
| 324 |
contact the project curl security team immediately. See |
| 325 |
https://curl.haxx.se/dev/secprocess.html for details. |
| 326 |
.SH "Showing What You Do" |
| 327 |
Relatedly, be aware that in situations when you have problems with libcurl and |
| 328 |
ask someone for help, everything you reveal in order to get best possible help |
| 329 |
might also impose certain security related risks. Host names, user names, |
| 330 |
paths, operating system specifics, etc. (not to mention passwords of course) |
| 331 |
may in fact be used by intruders to gain additional information of a potential |
| 332 |
target. |
| 333 |
|
| 334 |
Be sure to limit access to application logs if they could hold private or |
| 335 |
security-related data. Besides the obvious candidates like user names and |
| 336 |
passwords, things like URLs, cookies or even file names could also hold |
| 337 |
sensitive data. |
| 338 |
|
| 339 |
To avoid this problem, you must of course use your common sense. Often, you |
| 340 |
can just edit out the sensitive data or just search/replace your true |
| 341 |
information with faked data. |