---Curl Corporation
\bmanpages[^./;=&{:-]:man pages
\bmanpage[^si./;=&{:-]:man page
+favour:favor
Creative people have written bindings or interfaces for various environments
and programming languages. Using one of these allows you to take advantage of
-curl powers from within your favourite language or system.
+curl powers from within your favorite language or system.
This is a list of all known interfaces as of this writing.
wolfSSL (curl 8.10.0+) and mbedTLS (3.6.0+, curl 8.10.0+).
The list of cipher suites that can be used for the `--tls13-ciphers` option:
+
```
TLS_AES_128_GCM_SHA256
TLS_AES_256_GCM_SHA384
Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS)) of cipher suites,
which are (mostly) supported by all SSL backends, that can be used for the
`--ciphers` option:
+
```
ECDHE-ECDSA-AES128-GCM-SHA256
ECDHE-RSA-AES128-GCM-SHA256
ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305 \
https://example.com/
```
+
Restrict ciphers to `aes128-gcm` and `chacha20`. Works with OpenSSL, LibreSSL,
mbedTLS and wolfSSL.
--tls13-ciphers TLS_AES_128_GCM_SHA256:TLS_CHACHA20_POLY1305_SHA256 \
https://example.com/
```
+
Restrict to only TLS 1.3 with `aes128-gcm` and `chacha20` ciphers. Works with
OpenSSL, LibreSSL, mbedTLS, wolfSSL and Schannel.
ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305 \
https://example.com/
```
+
Restrict TLS 1.2 ciphers to `aes128-gcm` and `chacha20`, use default TLS 1.3
ciphers (if TLS 1.3 is available). Works with OpenSSL, LibreSSL, BoringSSL,
mbedTLS and wolfSSL.
--ciphers '-CIPHER_ALL:+AES-128-GCM:+CHACHA20-POLY1305' \
https://example.com/
```
+
Restrict ciphers to `aes128-gcm` and `chacha20` in GnuTLS.
```sh
--ciphers 'NORMAL:-VERS-ALL:+TLS1.3:-AES-256-GCM' \
https://example.com/
```
+
Restrict to only TLS 1.3 without the `aes256-gcm` cipher.
```sh
--ciphers 'NORMAL:-VERS-ALL:+TLS1.2:-CIPHER_ALL:+CAMELLIA-128-GCM' \
https://example.com/
```
+
Restrict to only TLS 1.2 with the `CAMELLIA-128-GCM` cipher.
## Further reading
+
- [OpenSSL cipher suite names documentation](https://docs.openssl.org/master/man1/openssl-ciphers/#cipher-suite-names)
- [wolfSSL cipher support documentation](https://www.wolfssl.com/documentation/manuals/wolfssl/chapter04.html#cipher-support)
- [mbedTLS cipher suites reference](https://mbed-tls.readthedocs.io/projects/api/en/development/api/file/ssl__ciphersuites_8h/)
There are some known issues with the ECH implementation in wolfSSL:
- The main issue is that the client currently handles HelloRetryRequest
- incorrectly. [HRR issue](https://github.com/wolfSSL/wolfssl/issues/6802).)
+ incorrectly. [HRR issue](https://github.com/wolfSSL/wolfssl/issues/6802).)
The HRR issue means that the client does not work for
[this ECH test web site](https://tls-ech.dev/) and any other similarly
configured sites.
```sh
cd $HOME/code/curl/
-./src/curl -vvv --insecure --connect-to foo.example.com:8443:localhost:8443 --ech ecl:AD7+DQA6uwAgACBix2B78sX+EQhEbxMspDOc8Z3xVS5aQpYP0Cxpc2AWPAAEAAEAAQALZXhhbXBsZS5jb20AAA==
+./src/curl -vvv --insecure --connect-to foo.example.com:8443:localhost:8443 --ech ecl:AD7+DQA6uwAgACBix2B78sX+EQhEbxMspDOc8Z3xVS5aQpYP0Cxpc2AWPAAEAAEAAQALZXhhbXBsZS5jb20AAA==
```
### Automated use of ``retry_configs`` not supported so far...
- `--disable-libcurl-option` (--libcurl C code generation support)
- `--disable-manual` (--manual built-in documentation)
- `--disable-mime` (MIME API)
-- `--disable-netrc` (.netrc file)
+- `--disable-netrc` (.netrc file)
- `--disable-progress-meter` (graphical progress meter in library)
- `--disable-proxy` (HTTP and SOCKS proxies)
- `--disable-socketpair` (socketpair for asynchronous name resolving)
-- `--disable-threaded-resolver` (threaded name resolver)
+- `--disable-threaded-resolver` (threaded name resolver)
- `--disable-tls-srp` (Secure Remote Password authentication for TLS)
- `--disable-unix-sockets` (Unix sockets)
- `--disable-verbose` (eliminates debugging strings and error code strings)
-->
# IPFS
+
For an overview about IPFS, visit the [IPFS project site](https://ipfs.tech/).
In IPFS there are two protocols. IPFS and IPNS (their workings are explained
The IPFS integration in curl hides this gateway logic for you. Instead of
providing a full URL to a file on IPFS like this:
-```
+```sh
curl http://127.0.0.1:8080/ipfs/bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi
```
You can provide it with the IPFS protocol instead:
-```
+```sh
curl ipfs://bafybeigagd5nmnn2iys2f3doro7ydrevyr2mzarwidgadawmamiteydbzi
```
Its basic read/write functions have a similar signature and return code
handling as many internal curl read and write ones.
-```
+```c
ssize_t Curl_bufq_write(struct bufq *q, const unsigned char *buf, size_t len, CURLcode *err);
- returns the length written into `q` or -1 on error.
To pass data into a `bufq` without an extra copy, read callbacks can be used.
-```
+```c
typedef ssize_t Curl_bufq_reader(void *reader_ctx, unsigned char *buf, size_t len,
CURLcode *err);
The analog mechanism for write out buffer data is:
-```
+```c
typedef ssize_t Curl_bufq_writer(void *writer_ctx, const unsigned char *buf, size_t len,
CURLcode *err);
It is possible to get access to the memory of data stored in a `bufq` with:
-```
+```c
bool Curl_bufq_peek(const struct bufq *q, const unsigned char **pbuf, size_t *plen);
```
Instead of reading `bufq` data, one may simply skip it:
-```
+```c
void Curl_bufq_skip(struct bufq *q, size_t amount);
```
`bufq` is initialized and freed similar to the `dynbuf` module. Code using
`bufq` holds a `struct bufq` somewhere. Before it uses it, it invokes:
-```
+```c
void Curl_bufq_init(struct bufq *q, size_t chunk_size, size_t max_chunks);
```
The user of the `bufq` has the responsibility to call:
-```
+```c
void Curl_bufq_free(struct bufq *q);
```
+
to free all resources held by `q`. It is possible to reset a `bufq` to empty via:
-```
+```c
void Curl_bufq_reset(struct bufq *q);
```
A `struct bufc_pool` may be used to create chunks for a `bufq` and keep spare
ones around. It is initialized and used via:
-```
+```c
void Curl_bufcp_init(struct bufc_pool *pool, size_t chunk_size, size_t spare_max);
void Curl_bufq_initp(struct bufq *q, struct bufc_pool *pool, size_t max_chunks, int opts);
more data to send for a transfer. If no specific reader has been installed yet,
the default one that uses `CURLOPT_READFUNCTION` is added. The prototype is
-```
+```c
CURLcode Curl_client_read(struct Curl_easy *data, char *buf, size_t blen,
size_t *nread, bool *eos);
```
The definition of a reader is:
-```
+```c
struct Curl_crtype {
const char *name; /* writer name. */
CURLcode (*do_init)(struct Curl_easy *data, struct Curl_creader *writer);
is created, it gets the `phase` property in which it operates. Reader phases
are defined like:
-```
+```c
typedef enum {
CURL_CR_NET, /* data send to the network (connection filters) */
CURL_CR_TRANSFER_ENCODE, /* add transfer-encodings */
forward this data via `Curl_client_write()` to the application. The exact
prototype of this function is:
-```
+```c
CURLcode Curl_client_write(struct Curl_easy *data, int type, const char *buf, size_t blen);
```
The `type` argument specifies what the bytes in `buf` actually are.
The following bits are defined:
-```
+```c
#define CLIENTWRITE_BODY (1 << 0) /* non-meta information, BODY */
#define CLIENTWRITE_INFO (1 << 1) /* meta information, not a HEADER */
#define CLIENTWRITE_HEADER (1 << 2) /* meta information, HEADER */
client writers can be chained to process the bytes written through them. The
definition is:
-```
+```c
struct Curl_cwtype {
const char *name;
CURLcode (*do_init)(struct Curl_easy *data,
one property it gets is the `phase` in which it operates. Writer phases are
defined like:
-```
+```c
typedef enum {
CURL_CW_RAW, /* raw data written, before any decoding */
CURL_CW_TRANSFER_DECODE, /* remove transfer-encodings */
Each filter does in principle the following:
-```
+```c
static CURLcode myfilter_cf_connect(struct Curl_cfilter *cf,
struct Curl_easy *data,
bool *done)
The memory footprint of a filter is relatively small:
-```
+```c
struct Curl_cfilter {
const struct Curl_cftype *cft; /* the type providing implementation */
struct Curl_cfilter *next; /* next filter in chain */
filter, once it is connected, just passes the calls through. Those filters
implementations look like this:
-```
+```c
ssize_t Curl_cf_def_send(struct Curl_cfilter *cf, struct Curl_easy *data,
const void *buf, size_t len, CURLcode *err)
{
return cf->next->cft->do_send(cf->next, data, buf, len, err);
}
```
+
The `recv` implementation is equivalent.
## Filter Types
`--trace-config` argument. For example, in order to get more detailed tracing
of an HTTP/2 request, invoke curl with:
-```
+```sh
> curl -v --trace-config ids,time,http/2 https://curl.se/
```
A typical invocation for measuring performance of HTTP/2 downloads would be:
-```
+```sh
curl> python3 tests/http/scorecard.py -d h2
```
Help for all command line options are available via:
-```
+```sh
curl> python3 tests/http/scorecard.py -h
```
For example, to run downloads of a 1 MB resource only, 100 times with at max 6
parallel transfers, use:
-```
+```sh
curl> python3 tests/http/scorecard.py -d --download-sizes=1mb --download-count=100 --download-parallel=6 h2
```
project or set the environment variable `FLAMEGRAPH` to the location of your
clone. Then run scorecard with the `--flame` option, like
-```
+```sh
curl> FLAMEGRAPH=/Users/sei/projects/FlameGraph python3 tests/http/scorecard.py \
-r --request-count=50000 --request-parallels=100 --samples=1 --flame h2
```
CURLIOE_LAST /* never use */
} curlioerr;
-typedef enum {
+typedef enum {
CURLIOCMD_NOP, /* no operation */
CURLIOCMD_RESTARTREAD, /* restart the read stream from start */
CURLIOCMD_LAST /* never use */
~~~c
#include <curl/curl.h>
-typedef enum {
+typedef enum {
CURLSOCKTYPE_IPCXN, /* socket created for a specific IP connection */
} curlsocktype;
~~~c
#include <curl/curl.h>
-typedef enum {
+typedef enum {
CURLSOCKTYPE_IPCXN, /* socket created for a specific IP connection */
CURLSOCKTYPE_ACCEPT, /* socket created by accept() call */
CURLSOCKTYPE_LAST /* never use */
`pytest` from there or from the top level curl checkout and it finds all
tests.
-```
+```sh
curl> pytest test/http
platform darwin -- Python 3.9.15, pytest-6.2.0, py-1.10.0, pluggy-0.13.1
rootdir: /Users/sei/projects/curl
be something resembling a python test or just a string that needs to match
test cases in their names.
-```
+```sh
curl/tests/http> pytest -vv -k test_01_02
```
use. If you want to run a test with a particular protocol only, use a command
line like:
-```
+```sh
curl/tests/http> pytest -k "test_02_06 and h2"
```
Test cases can be repeated, with the `pytest-repeat` module (`pip install
pytest-repeat`). Like in:
-```
+```sh
curl/tests/http> pytest -k "test_02_06 and h2" --count=100
```
which then runs this test case a hundred times. In case of flaky tests, you
can make pytest stop on the first one with:
-```
+```sh
curl/tests/http> pytest -k "test_02_06 and h2" --count=100 --maxfail=1
```
output. If you specify `-v` three times, the `curl` command is started with
`--trace`:
-```
+```sh
curl/tests/http> pytest -vvv -k "test_02_06 and h2" --count=100 --maxfail=1
```
#endif
-/* pickoneauth() selects the most favourable authentication method from the
+/* pickoneauth() selects the most favorable authentication method from the
* ones available and the ones we want.
*
* return TRUE if one was picked
projects / thirdparty / curl.git / commitdiff
