7c749dc1ce43213e564aa268d79487fd25b18215 - third_party/rust-mirrors/quiche

commit	7c749dc1ce43213e564aa268d79487fd25b18215	[log] [tgz]
author	Alessandro Ghedini <alessandro@ghedini.me>	Wed Oct 09 14:09:53 2019 +0100
committer	Alessandro Ghedini <alessandro@ghedini.me>	Wed Oct 09 15:23:49 2019 +0100
tree	d58b13662723fe6de926dcfd3d8bea9c7cd941ea
parent	3978a900609a048111ec20d9c700bbd66fc38c88 [diff]

deps: update BoringSSL submodule

* 2019-01-09 Test CRYPTO_gcm128_tag in gcm_test.cc.
* 2019-01-15 Fix SSL_R_TOO_MUCH_READ_EARLY_DATA.
* 2019-01-11 Add ABI tests for GCM.
* 2019-01-16 Revert "Fix protos_len size in SSL_set_alpn_protos and SSL_CTX_set_alpn_protos"
* 2019-01-08 Mark some unmarked array sizes in curve25519.c.
* 2019-01-15 Don't look for libunwind if cross-compiling.
* 2019-01-08 Switch to new fiat pipeline.
* 2019-01-21 Rename Fiat include files to end in .h
* 2019-01-21 Add SSL_OP_NO_RENEGOTIATION
* 2019-01-16 Simplify HRSS mod3 circuits.
* 2018-11-27 Add test of assembly code dispatch.
* 2019-01-21 HRSS: flatten sample distribution.
* 2019-01-12 Fix undefined pointer casts in SHA-512 code.
* 2019-01-21 Add an option to build with UBSan.
* 2019-01-21 Fix signed left-shifts in curve25519.c.
* 2019-01-21 Don't pass NULL,0 to qsort.
* 2019-01-22 Avoid unwind tests on libc functions.
* 2019-01-22 Remove union from |SHA512_CTX|.
* 2019-01-22 Add a RelWithAsserts build configuration.
* 2019-01-16 Update comments around JDK11 workaround.
* 2019-01-23 Make 256-bit ciphers a preference for CECPQ2, not a requirement.
* 2019-01-23 Tweak some slightly fragile tests.
* 2019-01-09 Add a constant-time pshufb-based GHASH implementation.
* 2018-07-17 Implement server support for delegated credentials.
* 2019-01-25 Add some Node compatibility functions.
* 2019-01-25 Add a very roundabout EC keygen API.
* 2019-01-26 Add ABI testing for 32-bit x86.
* 2018-12-31 Better document RSAZ and tidy up types.
* 2019-01-26 Add RSAZ ABI tests.
* 2019-01-28 Test and fix an ABI issue with small parameters.
* 2019-01-28 Avoid SCT/OCSP extensions in SH on {Omit|Empty}Extensions
* 2019-01-29 Remove infra/config folder in master branch.
* 2019-01-30 Enforce key usage for RSA keys in TLS 1.2.
* 2019-01-30 Add instructions for debugging on Android with gdb.
* 2019-01-30 perlasm/x86_64-xlate.pl: refine symbol recognition in .xdata.
* 2019-01-12 Don't use bsaes over vpaes for CTR-DRBG.
* 2019-02-01 runner: Don't generate an RSA key on startup.
* 2019-02-03 Tolerate spaces when parsing .type directives.
* 2019-02-02 Implement unwind testing for Windows.
* 2019-02-03 Fix the order of Windows unwind codes.
* 2019-01-07 Implement ABI testing for ARM.
* 2019-02-04 Fix ABI error in bn_mul_mont on aarch64.
* 2019-02-01 Implement ABI testing for aarch64.
* 2019-01-29 Enable all curves (inc CECPQ2) during fuzzing.
* 2019-01-29 Remove separate default group list for servers.
* 2019-02-07 Remove stray semicolons.
* 2019-02-08 Hyperlink DOI to preferred resolver
* 2019-01-28 sync EVP_get_cipherbyname with EVP_do_all_sorted
* 2019-01-28 Add ABI tests for x86_64-mont5.pl.
* 2019-02-10 Add ABI tests for aesni-gcm-x86_64.pl.
* 2019-02-10 Patch out unused aesni-x86_64 functions.
* 2019-02-06 Unwind RDRAND functions correctly on Windows.
* 2019-02-10 Use Windows symbol APIs in the unwind tester.
* 2019-02-12 Update delegated credentials to draft-03
* 2019-02-02 Always define GHASH.
* 2019-02-02 Remove stray prototype.
* 2019-02-02 Patch XTS out of ARMv7 bsaes too.
* 2019-02-09 Remove non-STRICT_ALIGNMENT code from xts.c.
* 2019-02-09 Remove STRICT_ALIGNMENT code from modes.
* 2019-02-20 Add go 1.11 to go.mod.
* 2019-02-20 Fix x86_64-xlate.pl comment regex.
* 2019-02-21 Add compiled python files to .gitignore.
* 2019-02-21 Clear out a bunch of -Wextra-semi warnings.
* 2019-02-21 Add uint64_t support in CBS and CBB.
* 2019-02-10 Avoid double-dispatch with AES_* vs aes_nohw_*.
* 2019-02-10 Enable vpaes for AES_* functions.
* 2019-02-22 Set VPAES flags in x86-64 code.
* 2019-02-22 Appease GCC's uninitialized value warning.
* 2019-02-10 Add an option to configure bssl speed chunk size.
* 2019-02-26 Fix bsaes-armv7.pl getting disabled by accident.
* 2019-02-26 Remove __ARM_ARCH__ guard on gcm_*_v8.
* 2019-02-27 Add a reference for Linux ARM ABI.
* 2019-02-24 Update *_set_cert_cb documentation regarding resumption
* 2019-03-01 Don't pull abi_test.cc into non-GTest targets.
* 2019-03-01 Also include abi_test.cc in ssl_test_files.
* 2019-02-24 Add a 32-bit SSSE3 GHASH implementation.
* 2019-03-04 Handle NULL public key in |EC_KEY_set_public_key|.
* 2019-03-04 silence unused variable warnings when using OPENSSL_clear_free
* 2019-02-25 Check in vpaes-armv8.pl from OpenSSL unused and unmodified.
* 2019-02-25 Enable vpaes for aarch64, with CTR optimizations.
* 2019-03-03 modes/asm/ghash-armv4.pl: address "infixes are deprecated" warnings.
* 2019-02-26 Tell ASan about the OPENSSL_malloc prefix.
* 2019-03-02 Prefer vpaes over bsaes in AES-GCM-SIV and AES-CCM.
* 2019-03-05 Remove SSL_get_structure_sizes.
* 2019-03-07 Correct outdated comments
* 2019-03-06 Support three-argument instructions on x86-64.
* 2019-03-10 Make vpaes-armv8.pl compatible with XOM.
* 2019-03-13 Implement sk_find manually.
* 2019-01-09 Patch out the aes_nohw fallback in bsaes_ctr32_encrypt_blocks.
* 2019-01-12 Patch out the aes_nohw fallback in bsaes_cbc_encrypt.
* 2019-03-09 Adapt gcm_*_neon to aarch64.
* 2019-03-02 Drop some unused bsaes to aes_nohw dependencies.
* 2019-03-14 Remove d2i_ASN1_UINTEGER.
* 2019-03-14 Harden the lower level parts of crypto/asn1 against overflows.
* 2019-03-14 Reject long inputs in c2i_ASN1_INTEGER.
* 2019-03-15 Save a temporary in BN_mod_exp_mont's w=1 case.
* 2019-03-14 Rewrite BN_CTX.
* 2019-03-20 Add 16384 to the default bssl speed sizes.
* 2019-03-19 Add an optimized x86_64 vpaes ctr128_f and remove bsaes.
* 2019-03-21 Unwind the large_inputs hint in aes_ctr_set_key.
* 2019-03-23 Update ImplDispatchTest for bsaes-x86_64 removal.
* 2019-03-25 Support get versions with get_{min,max}_proto_version for context
* 2019-04-01 nit: Update references to draft-ietf-tls-subcerts.
* 2019-04-03 Update SDE to 8.35.0-2019-03-11.
* 2019-04-03 Update other build tools.
* 2019-04-04 Rename 'md' output parameter to 'out' and add bounds.
* 2019-04-09 Update third_party/googletest.
* 2019-04-09 Handle CBB_cleanup on child CBBs more gracefully.
* 2019-04-10 Test AES-GCM-SIV with OPENSSL_SMALL.
* 2019-04-10 Add missing nonce_len check to aead_aes_gcm_siv_asm_open.
* 2019-04-10 Check key sizes in AES_set_*_key.
* 2019-04-15 Fix EVP_CIPHER_CTX_copy for AES-GCM.
* 2019-04-15 Test copying an EVP_MD_CTX.
* 2019-04-15 Fix and test EVP_PKEY_CTX copying.
* 2019-04-12 Output a ClientHello during handoff.
* 2019-04-16 Give ENGINE_free a return value.
* 2019-04-16 Add X509_CHECK_FLAG_NEVER_CHECK_SUBJECT.
* 2019-04-16 Silently ignore X509_CHECK_FLAG_ALWAYS_CHECK_SUBJECT.
* 2019-04-17 Disable the common name fallback on *any* SAN list.
* 2019-04-18 Make X509_verify_cert_error_string thread-safe.
* 2019-04-16 Require certificates under name constraints use SANs.
* 2019-04-18 Predeclare enums in base.h
* 2019-02-21 Hold off flushing NewSessionTicket until write.
* 2019-04-12 Handle errors from close in perlasm scripts.
* 2019-04-25 Check for x18 usage in aarch64 assembly.
* 2019-03-28 Convert the rest of ssl_test to GTest.
* 2019-03-29 Compute the delegated credentials length prefix with CBB.
* 2019-03-30 Convert a few more things from int to bool.
* 2019-03-30 Check for errors when setting up X509_STORE_CTX.
* 2019-04-27 Fix up EVP_DigestSign implementation for Ed25519.
* 2019-04-27 Add a compatibility EVP_DigestFinalXOF function.
* 2019-04-30 Remove stray underscores.
* 2019-04-27 Add functions for "raw" EVP_PKEY serializations.
* 2019-05-01 Fix spelling in comments.
* 2019-05-03 Use weak symbols only on supported platforms
* 2019-05-04 Remove implicit -on-resume for -expect-early-data-accept.
* 2019-05-04 Add SSL_get_early_data_reason.
* 2019-05-04 Enforce the ticket_age parameter for 0-RTT.
* 2019-05-04 Rename remnants of ticket_early_data_info.
* 2019-05-04 clang-format Flag arrays in test_config.cc.
* 2019-05-04 Make expect/expected flag and variable names match.
* 2019-05-07 Reject obviously invalid DSA parameters during signing.
* 2019-05-06 Save and restore errors when ignoring ssl_send_alert result.
* 2019-05-07 Add an option to skip crypto_test_data.cc in GN too.
* 2019-05-14 tool: fix speed tests.
* 2019-03-06 Add support for SIKE/p503 post-quantum KEM
* 2019-05-16 Define p503 with crypto_word_t, not uint64_t.
* 2019-05-16 Remove no-op casts around tt1.
* 2019-05-16 Fix the last casts in third_party/sike.
* 2019-05-20 Update generate_build_files.py for SIKE.
* 2019-05-20 Sync aesp8-ppc.pl with upstream.
* 2019-05-20 Make EVP_PKEY_keygen work for Ed25519.
* 2019-05-20 Support PKCS#8 blobs using PBES2 with HMAC-SHA256.
* 2019-05-20 Support PKCS#12 KeyBags.
* 2019-05-20 Align PKCS12_parse closer to OpenSSL.
* 2019-05-08 Always store early data tickets.
* 2019-05-23 Disable RDRAND on AMD chips before Zen.
* 2019-05-24 Convert ecdsa_p224_key.pem to PKCS#8.
* 2019-03-11 Integrate SIKE with TLS key exchange.
* 2019-05-28 delocate: translate uleb128 and sleb128 directives
* 2019-05-29 delocate: add test for .file handling.
* 2019-05-09 Add FIPS shared mode.
* 2019-05-30 Split ec_point_mul_scalar into two operations.
* 2019-05-30 Split EC_METHOD.mul into two operations.
* 2019-05-30 Fix filename in comment.
* 2019-05-30 Fix various mistakes in ec_GFp_nistp_recode_scalar_bits comment.
* 2019-05-30 Handle fips_shared_support.c getting built in other builds.
* 2019-06-03 bcm: don't forget to cleanup HMAC_CTX.
* 2019-06-03 Fix name clash in test structures
* 2019-06-05 Fix various typos.
* 2019-06-05 Eliminate some superfluous conditions in SIKE Go code.
* 2019-06-06 Replace addc64,subc64,mul64 in SIKE Go code with functions from math/bits
* 2019-06-12 Set a minimum CMake version of 3.0.
* 2019-06-13 Update build tools.
* 2019-06-06 Discuss the doubling case in windowed Booth representation.
* 2019-06-04 Add AES-KWP
* 2019-06-14 Split p224-64.c multiplication functions in three.
* 2019-06-14 Avoid leaking intermediate states in point doubling special case.
* 2019-06-17 Add a value barrier to constant-time selects.
* 2019-06-19 Fix runner tests with Go 1.13.
* 2019-06-11 Add an API to record use of delegated credential
* 2019-06-24 Clarify language about default SSL_CTX session ticket key behavior.
* 2019-06-25 Emit empty signerInfos in PKCS#7 bundles.
* 2019-06-25 Factor out TLS cipher selection to ssl_choose_tls_cipher.
* 2019-07-01 Move fipstools/ to util/fipstools/cavp
* 2019-07-08 Add android_sdk checkout
* 2019-07-08 Support key wrap with padding in CAVP.
* 2019-07-08 Remove android_tools checkout
* 2019-07-10 Add SipHash-2-4.
* 2019-06-28 Implements SIKE/p434
* 2019-07-09 Add initial draft of ACVP tool.
* 2019-07-16 Fix shim error message endings.
* 2019-07-16 Add post-quantum experiment signal extension.
* 2019-07-19 Rename SIKE's params.c.
* 2019-07-19 Prefix all the SIKE symbols.
* 2019-07-19 Align TLS 1.3 cipher suite names with OpenSSL.
* 2019-07-19 Name cipher suite tests in runner by IETF names.
* 2019-07-19 Move the PQ-experiment signal to SSL_CTX.
* 2019-07-19 Only bypass the signature verification itself in fuzzer mode.
* 2019-07-20 Make SSL_get_servername work in the early callback.
* 2019-07-20 Make EVP_PKEY_bits return 253 for Ed25519.
* 2019-07-20 Add EVP_PKEY support for X25519.
* 2019-07-21 Remove SSL_export_early_keying_material.
* 2019-07-21 Trim some more per-connection memory.
* 2019-07-21 Make alert_dispatch into a bool.
* 2019-07-29 Add some project links to README.md.
* 2019-07-30 Add EVP_PKEY_base_id.
* 2019-07-29 Move CCM fragments out of the FIPS module.
* 2019-07-31 Fix misspelled TODO.
* 2019-08-01 acvp: add support for AES-ECB and AES-CBC.
* 2019-07-01 Fix typo in valgrind constant-time annotations.
* 2019-08-07 Add assembly support for -fsanitize=hwaddress tagged globals.
* 2019-08-08 Workaround Clang bug on POWER.
* 2019-08-08 Fix POWER build with OPENSSL_NO_ASM.
* 2019-08-08 Fix paths in break-tests.sh.
* 2019-08-08 Update TODO to note that Clang git doesn't have the POWER bug.
* 2019-08-09 Add missing ".text" to Windows code for dummy_chacha20_poly1305_asm
* 2019-07-25 Add a QUIC test for HelloRetryRequest.
* 2019-08-13 Add an android-cmake option to generate_build_files.py
* 2019-08-15 Remove stale TODO.
* 2019-08-15 Introduce libcrypto_bcm_sources for Android.
* 2019-08-16 Check the second ClientHello's PSK binder on resumption.
* 2019-08-16 Switch tls13_enc.cc to spans.
* 2019-08-16 Switch another low-level function to spans.
* 2019-08-16 Use spans for the various TLS 1.3 secrets.
* 2019-08-21 Fold SSL_want constants into SSL_get_error constants.
* 2019-08-21 Add a function to convert SSL_ERROR_* values to strings.
* 2019-08-20 acvp: allow passing custom subprocess I/O.
* 2019-08-21 Require getrandom in Android FIPS builds.
* 2019-08-20 Align 0-RTT and resumption state machines slightly
* 2019-08-21 Add self-test suppression flag file for Android FIPS builds.
* 2019-08-26 Add Fallthru support for clang 10.
* 2019-08-22 Make |EVP_CIPHER_CTX_reset| return one.
* 2019-08-26 Limit __attribute__ ((fallthrough)) to Clang >= 5.
* 2019-08-26 Add OPENSSL_FALLTHROUGH to a few files.
* 2019-08-22 Have some more fun with spans.
* 2019-08-15 Add initial support for 0-RTT with QUIC.
* 2019-08-21 Clear *out in ReadHandshakeData's empty case.
* 2019-08-21 Move the config->async check into RetryAsync.
* 2019-09-03 Fix cross-compile of Android on Windows.
* 2019-04-10 Support compilation via emscripten
* 2019-09-06 Revert "Fix VS build when assembler is enabled"
* 2019-09-10 Const-correct EC_KEY_set_public_key_affine_coordinates.
* 2019-09-12 Only write self test flag files if an environment variable is set.
* 2019-08-31 Add benchmarks for AES block operations.
* 2019-08-31 Correct comments for x86_64 _vpaes_encrypt_core_2x.
* 2019-03-22 Add vpaes-armv7.pl and replace non-parallel modes.
* 2019-05-05 Add NEON vpaes-to-bsaes key converters.
* 2019-05-19 Use vpaes + conversion to setup CBC decrypt on NEON.
* 2019-08-25 Use a mix of bsaes and vpaes for CTR on NEON.
* 2019-09-13 Use ScopedEVP_AEAD_CTX in ImplDispatchTest.AEAD_AES_GCM.
* 2019-09-07 Update build tools.
* 2019-09-07 Use the Go 1.13 standard library ed25519.
* 2019-09-14 Parse explicit EC curves more strictly.
* 2019-08-30 Add AES-256 CFB to libdecrepit.
* 2019-09-13 Add AES-192-GCM support to EVP_AEAD.
* 2019-09-16 Fix vpaes-armv7.pl in ARM mode.
* 2019-09-16 Trigger a build on the ARM mode builder.
* 2019-09-18 Replace BIO_printf with ASN1_STRING_print in GENERAL_NAME_print
* 2019-09-18 Add XOF compilation compatibility flags
* 2019-09-18 Add |SSL_CIPHER_get_value| to get the IANA number of a cipher suite.
* 2019-09-17 Don't allow SGC EKUs for server certificates.
* 2019-09-19 Disable RDRAND on AMD family 0x17, models 0x70–0x7f.
* 2019-09-19 Disable unwind tests in FIPS mode.
* 2019-09-20 Add page protection logic to BCM self test.
* 2019-09-24 Ignore build32 and build64 subdirectories.
* 2019-09-23 Update INSTANTIATE_TEST_SUITE_P calls missing first argument.
* 2019-09-19 Opportunistically read entropy from the OS in FIPS mode.
* 2019-09-25 Only attempt to mprotect FIPS module for AArch64.
* 2019-09-26 Bound the number of API calls in ssl_ctx_api.cc.
* 2019-09-26 Make the dispatch tests opt-in.
* 2019-09-26 Mark ssl_early_data_reason_t values stable.
* 2019-09-29 fix build with armv6  Error: .size expression for _vpaes_decrypt_consts does not evaluate to a constant
* 2019-09-14 Be consistent about Miller-Rabin vs Rabin-Miller.
* 2019-09-14 Test some Euler pseudoprimes.
* 2019-09-14 Test some known large primes.
* 2019-09-14 Assert that BN_CTX_end is actually called.
* 2019-09-14 Style nit.
* 2019-09-30 Move #include of "internal.h", which defines |OPENSSL_URANDOM|.
* 2019-08-30 Use getentropy on macOS 10.12 and later.
* 2019-09-30 Switch to using SHA-256 for FIPS integrity check on Android.
* 2019-10-01 Use a smaller hex digest in FIPS flag files when SHA-256 used.
* 2019-10-02 Use a pointer to module_hash in boringssl_fips_self_test() args.
* 2019-10-02 Set -Wno-vla.
* 2019-10-01 tool: add -json flag to |speed|
* 2019-05-15 Add an option for explicit renegotiations.
* 2019-10-03 -Wno-vla -> -Wvla
* 2019-10-03 Add .note.GNU-stack at the source level.
* 2019-10-04 Fixed quic_method lookup in TLS 1.3 server side handshake.
* 2019-09-16 Add GrowableArray<T> to ssl/internal.h.
* 2019-10-08 Switch cert_compression_algs to GrowableArray.

2 files changed

tree: d58b13662723fe6de926dcfd3d8bea9c7cd941ea

README.md

quiche

quiche is an implementation of the QUIC transport protocol and HTTP/3 as specified by the IETF. It provides a low level API for processing QUIC packets and handling connection state. The application is responsible for providing I/O (e.g. sockets handling) as well as an event loop with support for timers.

A live QUIC server based on quiche is available at https://quic.tech:4433/ to be used for experimentation.

For more information on how quiche came about and some insights into its design you can read a post on Cloudflare's (where this library is used in production) blog that goes into some more detail.

Getting Started

Connection setup

The first step in establishing a QUIC connection using quiche is creating a configuration object:

let config = quiche::Config::new(quiche::PROTOCOL_VERSION)?;

This is shared among multiple connections and can be used to configure a QUIC endpoint.

On the client-side the connect() utility function can be used to create a new connection, while accept() is for servers:

// Client connection.
let conn = quiche::connect(Some(&server_name), &scid, &mut config)?;

// Server connection.
let conn = quiche::accept(&scid, None, &mut config)?;

Handling incoming packets

Using the connection's recv() method the application can process incoming packets that belong to that connection from the network:

loop {
    let read = socket.recv(&mut buf).unwrap();

    let read = match conn.recv(&mut buf[..read]) {
        Ok(v) => v,

        Err(quiche::Error::Done) => {
            // Done reading.
            break;
        },

        Err(e) => {
            // An error occurred, handle it.
            break;
        },
    };
}

Generating outgoing packets

Outgoing packet are generated using the connection's send() method instead:

loop {
    let write = match conn.send(&mut out) {
        Ok(v) => v,

        Err(quiche::Error::Done) => {
            // Done writing.
            break;
        },

        Err(e) => {
            // An error occurred, handle it.
            break;
        },
    };

    socket.send(&out[..write]).unwrap();
}

When packets are sent, the application is responsible for maintaining a timer to react to time-based connection events. The timer expiration can be obtained using the connection's timeout() method.

let timeout = conn.timeout();

The application is responsible for providing a timer implementation, which can be specific to the operating system or networking framework used. When a timer expires, the connection's on_timeout() method should be called, after which additional packets might need to be sent on the network:

// Timeout expired, handle it.
conn.on_timeout();

// Send more packets as needed after timeout.
loop {
    let write = match conn.send(&mut out) {
        Ok(v) => v,

        Err(quiche::Error::Done) => {
            // Done writing.
            break;
        },

        Err(e) => {
            // An error occurred, handle it.
            break;
        },
    };

    socket.send(&out[..write]).unwrap();
}

Sending and receiving stream data

After some back and forth, the connection will complete its handshake and will be ready for sending or receiving application data.

Data can be sent on a stream by using the stream_send() method:

if conn.is_established() {
    // Handshake completed, send some data on stream 0.
    conn.stream_send(0, b"hello", true)?;
}

The application can check whether there are any readable streams by using the connection's readable() method, which returns an iterator over all the streams that have outstanding data to read.

The stream_recv() method can then be used to retrieve the application data from the readable stream:

if conn.is_established() {
    // Iterate over readable streams.
    for stream_id in conn.readable() {
        // Stream is readable, read until there's no more data.
        while let Ok((read, fin)) = conn.stream_recv(stream_id, &mut buf) {
            println!("Got {} bytes on stream {}", read, stream_id);
        }
    }
}

HTTP/3

The quiche HTTP/3 module provides a high level API for sending and receiving HTTP requests and responses on top of the QUIC transport protocol.

Have a look at the examples/ directory for more complete examples on how to use the quiche API, including examples on how to use quiche in C/C++ applications (see below for more information).

Calling quiche from C/C++

quiche exposes a thin C API on top of the Rust API that can be used to more easily integrate quiche into C/C++ applications (as well as in other languages that allow calling C APIs via some form of FFI). The C API follows the same design of the Rust one, modulo the constraints imposed by the C language itself.

When running cargo build, a static library called libquiche.a will be built automatically alongside the Rust one. This is fully stand-alone and can be linked directly into C/C++ applications.

Building

quiche requires Rust 1.38 or later to build. The latest stable Rust release can be installed using rustup.

Once the Rust build environment is setup, the quiche source code can be fetched using git:

 $ git clone --recursive https://github.com/cloudflare/quiche

and then built using cargo:

 $ cargo build --examples

cargo can also be used to run the testsuite:

 $ cargo test

Note that BoringSSL, which is used to implement QUIC's cryptographic handshake based on TLS, needs to be built and linked to quiche. This is done automatically when building quiche using cargo, but requires the cmake and go commands to be available during the build process.

In alternative you can use your own custom build of BoringSSL by configuring the BoringSSL directory with the QUICHE_BSSL_PATH environment variable:

 $ QUICHE_BSSL_PATH="/path/to/boringssl" cargo build --examples

Building for Android

To build quiche for Android, you need the following:

Install Android NDK (13b or higher), using Android Studio or directly.
Set ANDROID_NDK_HOME environment variable to NDK path, e.g. using bash:

 $ export ANDROID_NDK_HOME=/usr/local/share/android-ndk

Install the Rust toolchain for Android architectures:

 $ rustup target add aarch64-linux-android arm-linux-androideabi armv7-linux-androideabi i686-linux-android

Then, to prepare the cross-compiling toolchain, run the following command:

 $ tools/setup_android.sh

It will create a standalone toolchain for arm64/arm/x86 architectures under the $TOOLCHAIN_DIR/arch directory. If you didn't set TOOLCHAIN_DIR environment variable, the current directory will be used. Note that the minimum API level is 21 for all target architectures.

After it run successfully, run the following script to build libquiche:

 $ tools/build_android.sh

It will build binaries for aarch64, armv7 and i686. You can pass parameters to this script for cargo build. For example if you want to build a release binary with verbose logs, do the following:

 $ tools/build_android.sh --release -vv

Building for iOS

To build quiche for iOS, you need the following:

Install Xcode command-line tools. You can install them with Xcode or with the following command:

 $ xcode-select --install

Install the Rust toolchain for iOS architectures:

 $ rustup target add aarch64-apple-ios armv7-apple-ios armv7s-apple-ios x86_64-apple-ios i386-apple-ios

Install cargo-lipo:

 $ cargo install cargo-lipo

To build libquiche, run the following command:

 $ cargo lipo

 $ cargo lipo --release

Copyright

See COPYING for the license.