diff --git a/docs/libcurl/curl_version_info.md b/docs/libcurl/curl_version_info.md index be626b6ec..9fc764e18 100644 --- a/docs/libcurl/curl_version_info.md +++ b/docs/libcurl/curl_version_info.md @@ -129,9 +129,9 @@ associated bits. names of the features that libcurl supports. The array is terminated by a NULL entry. See the list of features names below. -*ssl_version* is an ASCII string for the TLS library name + version -used. If libcurl has no SSL support, this is NULL. For example "Schannel", -&"Secure Transport" or "OpenSSL/1.1.0g". +*ssl_version* is an ASCII string for the TLS library name + version used. If +libcurl has no SSL support, this is NULL. For example "Schannel", "Secure +Transport" or "OpenSSL/1.1.0g". *ssl_version_num* is always 0. diff --git a/docs/libcurl/libcurl-security.md b/docs/libcurl/libcurl-security.md index aa1a980ef..09d63f4a8 100644 --- a/docs/libcurl/libcurl-security.md +++ b/docs/libcurl/libcurl-security.md @@ -44,7 +44,7 @@ this. # .netrc -&.netrc is a pretty handy file/feature that allows you to login quickly and +.netrc is a pretty handy file/feature that allows you to login quickly and automatically to frequently visited sites. The file contains passwords in clear text and is a real security risk. In some cases, your .netrc is also stored in a home directory that is NFS mounted or used on another network diff --git a/docs/libcurl/libcurl-share.md b/docs/libcurl/libcurl-share.md index 0106eb592..e244b9726 100644 --- a/docs/libcurl/libcurl-share.md +++ b/docs/libcurl/libcurl-share.md @@ -27,8 +27,7 @@ All functions in the share interface are prefixed with curl_share. # OBJECTIVES -The share interface was added to enable sharing of data between curl -&"handles". +The share interface was added to enable sharing of data between curl handles. # ONE SET OF DATA - MANY TRANSFERS diff --git a/docs/libcurl/libcurl-tutorial.md b/docs/libcurl/libcurl-tutorial.md index 1491d317a..2bf5f0547 100644 --- a/docs/libcurl/libcurl-tutorial.md +++ b/docs/libcurl/libcurl-tutorial.md @@ -64,13 +64,15 @@ libcurl can be built and customized in many ways. One of the things that varies from different libraries and builds is the support for SSL-based transfers, like HTTPS and FTPS. If a supported SSL library was detected properly at build-time, libcurl is built with SSL support. To figure out if an -installed libcurl has been built with SSL support enabled, use &'curl-config' +installed libcurl has been built with SSL support enabled, use *curl-config* like this: + ~~~c $ curl-config --feature ~~~ -And if SSL is supported, the keyword *SSL* is written to stdout, possibly -together with a other features that could be either on or off on for different + +If SSL is supported, the keyword *SSL* is written to stdout, possibly together +with a other features that could be either on or off on for different libcurls. See also the "Features libcurl Provides" further down. @@ -227,30 +229,32 @@ program. Therefore, if you use the default callback and pass in an open file handle with CURLOPT_WRITEDATA(3), libcurl crashes. You should avoid this to make your program run fine virtually everywhere. -(CURLOPT_WRITEDATA(3) was formerly known as *CURLOPT_FILE*. Both -names still work and do the same thing). +(CURLOPT_WRITEDATA(3) was formerly known as *CURLOPT_FILE*. Both names still +work and do the same thing). If you are using libcurl as a win32 DLL, you MUST use the -CURLOPT_WRITEFUNCTION(3) if you set CURLOPT_WRITEDATA(3) - or -experience crashes. +CURLOPT_WRITEFUNCTION(3) if you set CURLOPT_WRITEDATA(3) - or experience +crashes. There are of course many more options you can set, and we get back to a few of them later. Let's instead continue to the actual transfer: + ~~~c success = curl_easy_perform(handle); ~~~ -curl_easy_perform(3) connects to the remote site, does the necessary -commands and performs the transfer. Whenever it receives data, it calls the -callback function we previously set. The function may get one byte at a time, -or it may get many kilobytes at once. libcurl delivers as much as possible as -often as possible. Your callback function should return the number of bytes it -&"took care of". If that is not the same amount of bytes that was passed to -it, libcurl aborts the operation and returns with an error code. + +curl_easy_perform(3) connects to the remote site, does the necessary commands +and performs the transfer. Whenever it receives data, it calls the callback +function we previously set. The function may get one byte at a time, or it may +get many kilobytes at once. libcurl delivers as much as possible as often as +possible. Your callback function should return the number of bytes it "took +care of". If that is not the same amount of bytes that was passed to it, +libcurl aborts the operation and returns with an error code. When the transfer is complete, the function returns a return code that informs you if it succeeded in its mission or not. If a return code is not enough for -you, you can use the CURLOPT_ERRORBUFFER(3) to point libcurl to a buffer -of yours where it stores a human readable error message as well. +you, you can use the CURLOPT_ERRORBUFFER(3) to point libcurl to a buffer of +yours where it stores a human readable error message as well. If you then want to transfer another file, the handle is ready to be used again. It is even preferred and encouraged that you reuse an existing handle @@ -363,30 +367,36 @@ libcurl also provides options to set various passwords. The user name and password as shown embedded in the URL can instead get set with the CURLOPT_USERPWD(3) option. The argument passed to libcurl should be a char * to a string in the format "user:password". In a manner like this: + ~~~c curl_easy_setopt(handle, CURLOPT_USERPWD, "myname:thesecret"); ~~~ + Another case where name and password might be needed at times, is for those users who need to authenticate themselves to a proxy they use. libcurl offers -another option for this, the CURLOPT_PROXYUSERPWD(3). It is used quite -similar to the CURLOPT_USERPWD(3) option like this: +another option for this, the CURLOPT_PROXYUSERPWD(3). It is used quite similar +to the CURLOPT_USERPWD(3) option like this: + ~~~c curl_easy_setopt(handle, CURLOPT_PROXYUSERPWD, "myname:thesecret"); ~~~ + There is a long time Unix "standard" way of storing FTP user names and passwords, namely in the $HOME/.netrc file (on Windows, libcurl also checks -the *%USERPROFILE% environment* variable if *%HOME%* is unset, and -tries "_netrc" as name). The file should be made private so that only the user -may read it (see also the "Security Considerations" chapter), as it might -contain the password in plain text. libcurl has the ability to use this file -to figure out what set of user name and password to use for a particular -host. As an extension to the normal functionality, libcurl also supports this -file for non-FTP protocols such as HTTP. To make curl use this file, use the +the *%USERPROFILE% environment* variable if *%HOME%* is unset, and tries +"_netrc" as name). The file should be made private so that only the user may +read it (see also the "Security Considerations" chapter), as it might contain +the password in plain text. libcurl has the ability to use this file to figure +out what set of user name and password to use for a particular host. As an +extension to the normal functionality, libcurl also supports this file for +non-FTP protocols such as HTTP. To make curl use this file, use the CURLOPT_NETRC(3) option: + ~~~c curl_easy_setopt(handle, CURLOPT_NETRC, 1L); ~~~ -And a basic example of how such a .netrc file may look like: + +A basic example of how such a .netrc file may look like: ~~~c machine myhost.mydomain.com @@ -414,25 +424,32 @@ method is called 'Basic', which is sending the name and password in clear-text in the HTTP request, base64-encoded. This is insecure. At the time of this writing, libcurl can be built to use: Basic, Digest, NTLM, -Negotiate (SPNEGO). You can tell libcurl which one to use -with CURLOPT_HTTPAUTH(3) as in: +Negotiate (SPNEGO). You can tell libcurl which one to use with +CURLOPT_HTTPAUTH(3) as in: + ~~~c curl_easy_setopt(handle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST); + ~~~ -And when you send authentication to a proxy, you can also set authentication -type the same way but instead with CURLOPT_PROXYAUTH(3): + +When you send authentication to a proxy, you can also set authentication type +the same way but instead with CURLOPT_PROXYAUTH(3): + ~~~c curl_easy_setopt(handle, CURLOPT_PROXYAUTH, CURLAUTH_NTLM); ~~~ + Both these options allow you to set multiple types (by ORing them together), to make libcurl pick the most secure one out of the types the server/proxy claims to support. This method does however add a round-trip since libcurl must first ask the server what it supports: + ~~~c curl_easy_setopt(handle, CURLOPT_HTTPAUTH, CURLAUTH_DIGEST|CURLAUTH_BASIC); ~~~ -For convenience, you can use the *CURLAUTH_ANY* define (instead of a list -with specific types) which allows libcurl to use whatever method it wants. + +For convenience, you can use the *CURLAUTH_ANY* define (instead of a list with +specific types) which allows libcurl to use whatever method it wants. When asking for multiple types, libcurl picks the available one it considers "best" in its own internal order of preference. @@ -842,7 +859,7 @@ it defaults to assuming an HTTP proxy): libcurl automatically checks and uses a set of environment variables to know what proxies to use for certain protocols. The names of the variables are following an old tradition and are built up as "[protocol]_proxy" (note the -lower casing). Which makes the variable &'http_proxy' checked for a name of a +lower casing). Which makes the variable 'http_proxy' checked for a name of a proxy to use when the input URL is HTTP. Following the same rule, the variable named 'ftp_proxy' is checked for FTP URLs. Again, the proxies are always HTTP proxies, the different names of the variables simply allows different HTTP @@ -855,10 +872,9 @@ which port the proxy operates. If not specified, the internal default port number is used and that is most likely not the one you would like it to be. There are two special environment variables. 'all_proxy' is what sets proxy -for any URL in case the protocol specific variable was not set, and -&'no_proxy' defines a list of hosts that should not use a proxy even though a -variable may say so. If 'no_proxy' is a plain asterisk ("*") it matches all -hosts. +for any URL in case the protocol specific variable was not set, and 'no_proxy' +defines a list of hosts that should not use a proxy even though a variable may +say so. If 'no_proxy' is a plain asterisk ("*") it matches all hosts. To explicitly disable libcurl's checking for and using the proxy environment variables, set the proxy name to "" - an empty string - with @@ -984,11 +1000,11 @@ anything but default. ## Accept -&"*/*". +"*/*" ## Expect -When doing POST requests, libcurl sets this header to &"100-continue" to ask +When doing POST requests, libcurl sets this header to "100-continue" to ask the server for an "OK" message before it proceeds with sending the data part of the post. If the posted data amount is deemed "small", libcurl does not use this header. @@ -1038,9 +1054,9 @@ curl_easy_perform(handle); /* transfer http */ curl_slist_free_all(headers); /* free the header list */ ~~~ -&... and if you think some of the internally generated headers, such as -Accept: or Host: do not contain the data you want them to contain, you can -replace them by simply setting them too: +... and if you think some of the internally generated headers, such as Accept: +or Host: do not contain the data you want them to contain, you can replace +them by simply setting them too: ~~~c headers = curl_slist_append(headers, "Accept: Agent-007"); @@ -1051,7 +1067,7 @@ headers = curl_slist_append(headers, "Host: munged.host.line"); If you replace an existing header with one with no contents, you prevent the header from being sent. For instance, if you want to completely prevent the -&"Accept:" header from being sent, you can disable it with code similar to +"Accept:" header from being sent, you can disable it with code similar to this: headers = curl_slist_append(headers, "Accept:"); @@ -1310,7 +1326,7 @@ The headers are passed to the callback function one by one, and you can depend on that fact. It makes it easier for you to add custom header parsers etc. -&"Headers" for FTP transfers equal all the FTP server responses. They are not +"Headers" for FTP transfers equal all the FTP server responses. They are not actually true headers, but in this case we pretend they are! ;-) # Post Transfer Information diff --git a/docs/libcurl/libcurl-url.md b/docs/libcurl/libcurl-url.md index e1469d08f..a2948001a 100644 --- a/docs/libcurl/libcurl-url.md +++ b/docs/libcurl/libcurl-url.md @@ -142,12 +142,14 @@ The appended string can of course also get URL encoded on add, and if asked to URL encode, the encoding process skips the '=' character. For example, append "candy=N&N" to what we already have, and URL encode it to deal with the ampersand in the data: + ~~~c rc = curl_url_set(urlp, CURLUPART_QUERY, "candy=N&N", CURLU_APPENDQUERY | CURLU_URLENCODE); ~~~ Now the URL looks like + ~~~c https://example.com/?shoes=2&hat=1&candy=N%26N ~~~ diff --git a/docs/libcurl/opts/CURLINFO_CERTINFO.md b/docs/libcurl/opts/CURLINFO_CERTINFO.md index 46f28375b..d9cbc9306 100644 --- a/docs/libcurl/opts/CURLINFO_CERTINFO.md +++ b/docs/libcurl/opts/CURLINFO_CERTINFO.md @@ -37,10 +37,10 @@ struct curl_certinfo { ~~~ The *certinfo* struct member is an array of linked lists of certificate -information. The *num_of_certs* struct member is the number of -certificates which is the number of elements in the array. Each certificate's -list has items with textual information in the format "name:content" such as -&"Subject:Foo", "Issuer:Bar", etc. The items in each list varies depending on +information. The *num_of_certs* struct member is the number of certificates +which is the number of elements in the array. Each certificate's list has +items with textual information in the format "name:content" such as +"Subject:Foo", "Issuer:Bar", etc. The items in each list varies depending on the SSL backend and the certificate. # PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.md b/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.md index 922d23795..a6ddf2f7a 100644 --- a/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.md +++ b/docs/libcurl/opts/CURLOPT_FTPSSLAUTH.md @@ -24,7 +24,7 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_FTPSSLAUTH, long order); # DESCRIPTION Pass a long using one of the values from below, to alter how libcurl issues -&"AUTH TLS" or "AUTH SSL" when FTP over SSL is activated. This is only +"AUTH TLS" or "AUTH SSL" when FTP over SSL is activated. This is only interesting if CURLOPT_USE_SSL(3) is also set. Possible *order* values: diff --git a/docs/libcurl/opts/CURLOPT_HSTS.md b/docs/libcurl/opts/CURLOPT_HSTS.md index 107cfd909..83379f270 100644 --- a/docs/libcurl/opts/CURLOPT_HSTS.md +++ b/docs/libcurl/opts/CURLOPT_HSTS.md @@ -48,7 +48,7 @@ an entry valid for all subdomains to the name as well or only for the exact name. [stamp] is the time (in UTC) when the entry expires and it uses the format -&"YYYYMMDD HH:MM:SS". +"YYYYMMDD HH:MM:SS". Lines starting with "#" are treated as comments and are ignored. There is currently no length or size limit. diff --git a/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.md b/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.md index c1d50ad13..e138a3cd9 100644 --- a/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.md +++ b/docs/libcurl/opts/CURLOPT_RTSP_STREAM_URI.md @@ -30,16 +30,16 @@ stream using this option. If unset, libcurl defaults to operating on generic server options by passing '*' in the place of the RTSP Stream URI. This option is distinct from CURLOPT_URL(3). When working with RTSP, the CURLOPT_RTSP_STREAM_URI(3) indicates what URL to send to the server in the -request header while the CURLOPT_URL(3) indicates where to make the -connection to. (e.g. the CURLOPT_URL(3) for the above examples might be set -to *rtsp://foo/twister* +request header while the CURLOPT_URL(3) indicates where to make the connection +to. (e.g. the CURLOPT_URL(3) for the above examples might be set to +*rtsp://foo/twister* The application does not have to keep the string around after setting this option. # DEFAULT -&'*' +"*" # PROTOCOLS diff --git a/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md b/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md index 8a2023ea4..b3f114109 100644 --- a/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md +++ b/docs/libcurl/opts/CURLOPT_SSLKEYTYPE.md @@ -28,9 +28,9 @@ Pass a pointer to a null-terminated string as parameter. The string should be the format of your private key. Supported formats are "PEM", "DER" and "ENG". The format "ENG" enables you to load the private key from a crypto engine. In -this case CURLOPT_SSLKEY(3) is used as an identifier passed to the -engine. You have to set the crypto engine with CURLOPT_SSLENGINE(3). -&"DER" format key file currently does not work because of a bug in OpenSSL. +this case CURLOPT_SSLKEY(3) is used as an identifier passed to the engine. You +have to set the crypto engine with CURLOPT_SSLENGINE(3). "DER" format key file +currently does not work because of a bug in OpenSSL. The application does not have to keep the string around after setting this option. diff --git a/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md b/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md index 2d7c32da2..c96c93f3e 100644 --- a/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md +++ b/docs/libcurl/opts/CURLOPT_SSL_CIPHER_LIST.md @@ -29,25 +29,25 @@ CURLcode curl_easy_setopt(CURL *handle, CURLOPT_SSL_CIPHER_LIST, char *list); Pass a char pointer, pointing to a null-terminated string holding the list of ciphers to use for the SSL connection. The list must be syntactically correct, it consists of one or more cipher strings separated by colons. Commas or -spaces are also acceptable separators but colons are normally used, &!, &- and -&+ can be used as operators. +spaces are also acceptable separators but colons are normally used, !, - and ++ can be used as operators. For OpenSSL and GnuTLS valid examples of cipher lists include **RC4-SHA**, -**SHA1+DES**, **TLSv1** and **DEFAULT**. The default list is normally -set when you compile OpenSSL. +**SHA1+DES**, **TLSv1** and **DEFAULT**. The default list is normally set when +you compile OpenSSL. For WolfSSL, valid examples of cipher lists include **ECDHE-RSA-RC4-SHA**, **AES256-SHA:AES256-SHA256**, etc. For BearSSL, valid examples of cipher lists include -**ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256**, or when using IANA names +**ECDHE-RSA-CHACHA20-POLY1305:ECDHE-RSA-AES128-GCM-SHA256**, or when using +IANA names **TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256:TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256**, -etc. -With BearSSL you do not add/remove ciphers. If one uses this option then all -known ciphers are disabled and only those passed in are enabled. +etc. With BearSSL you do not add/remove ciphers. If one uses this option then +all known ciphers are disabled and only those passed in are enabled. -For Schannel, you can use this option to set algorithms but not specific cipher -suites. Refer to the ciphers lists document for algorithms. +For Schannel, you can use this option to set algorithms but not specific +cipher suites. Refer to the ciphers lists document for algorithms. Find more details about cipher lists on this URL: