docs/libcurl/libcurl-security.3

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