quiche
0.22.0
Quiche adalah implementasi dari protokol transportasi quic dan HTTP/3 sebagaimana ditentukan oleh IETF. Ini memberikan API tingkat rendah untuk memproses paket quic dan menangani status koneksi. Aplikasi ini bertanggung jawab untuk menyediakan I/O (misalnya penanganan soket) serta loop acara dengan dukungan untuk pengatur waktu.
Untuk informasi lebih lanjut tentang bagaimana quiche muncul dan beberapa wawasan tentang desainnya, Anda dapat membaca posting di blog Cloudflare yang masuk ke beberapa detail lebih lanjut.
Dukungan HTTP/3 Quiche Powers Powers Cloudflare Edge Network. Situs web CloudFlare-quic.com dapat digunakan untuk pengujian dan eksperimen.
Resolver DNS Android menggunakan Quiche untuk mengimplementasikan DNS melalui HTTP/3.
Quiche dapat diintegrasikan ke dalam curl untuk memberikan dukungan untuk HTTP/3.
Quiche dapat diintegrasikan ke dalam Nginx menggunakan tambalan tidak resmi untuk memberikan dukungan untuk HTTP/3.
Sebelum menyelam ke API quiche, berikut adalah beberapa contoh tentang cara menggunakan alat quiche yang disediakan sebagai bagian dari peti quiche-apps.
Setelah mengkloning proyek sesuai dengan perintah yang disebutkan di bagian bangunan, klien dapat dijalankan sebagai berikut:
$ kargo run-Bin quiche-client-https://cloudflare-quic.com/
Sedangkan server dapat dijalankan sebagai berikut:
$ kargo run-bin quiche-server---cert Apps/src/bin/cert.crt --key apps/src/bin/cert.key
(Perhatikan bahwa sertifikat yang disediakan ditandatangani sendiri dan tidak boleh digunakan dalam produksi)
Gunakan bendera baris perintah --help untuk mendapatkan deskripsi yang lebih rinci dari opsi masing-masing alat.
Langkah pertama dalam membuat koneksi quic menggunakan quiche adalah membuat objek Config :
Biarkan mut config = quiche :: config :: new (quiche :: protocol_version) ?; config.set_application_protos (& [b "example-proto"]); // konfigurasi tambahan khusus untuk aplikasi dan penggunaan case ...
Objek Config mengontrol aspek -aspek penting dari koneksi quic seperti versi quic, ID ALPN, kontrol aliran, kontrol kemacetan, batas waktu idle dan properti atau fitur lainnya.
QUIC adalah protokol transport tujuan umum dan ada beberapa properti konfigurasi di mana tidak ada nilai default yang masuk akal. Misalnya, jumlah aliran bersamaan yang diizinkan dari jenis tertentu tergantung pada aplikasi yang menjalankan quic, dan masalah spesifik kasus penggunaan lainnya.
Quiche default beberapa properti ke nol, aplikasi kemungkinan besar perlu mengatur ini ke sesuatu yang lain untuk memenuhi kebutuhan mereka menggunakan yang berikut:
set_initial_max_streams_bidi()
set_initial_max_streams_uni()
set_initial_max_data()
set_initial_max_stream_data_bidi_local()
set_initial_max_stream_data_bidi_remote()
set_initial_max_stream_data_uni()
Config juga memegang konfigurasi TLS. Ini dapat diubah oleh mutator pada objek yang ada, atau dengan membangun konteks TLS secara manual dan membuat konfigurasi menggunakan with_boring_ssl_ctx_builder() .
Objek konfigurasi dapat dibagikan di antara beberapa koneksi.
Di sisi klien, fungsi utilitas connect() dapat digunakan untuk membuat koneksi baru, saat accept() adalah untuk server:
// Koneksi klien. & mut config)?;
Menggunakan metode recv() koneksi aplikasi dapat memproses paket yang masuk yang termasuk dalam koneksi itu dari jaringan:
let to = socket.local_addr (). unwrap (); loop {let (baca, dari) = socket.recv_from (& mut buf) .unwrap (); let recv_info = quiche :: recvinfo {from, to}; biarkan baca = kecocokan conn.recv (& mut buf [.. baca], recv_info) {ok (v) => v, err (e) => {// kesalahan terjadi, menangani it.break;},};} Paket keluar dihasilkan menggunakan metode send() koneksi sebagai gantinya:
loop {let (write, send_info) = match conn.send (& mut out) {ok (v) => v, err (quiche :: error :: done) => {// selesai write.break;}, err (err (err (err e) => {// Terjadi kesalahan, menangani it.break;},}; socket.send_to (& out [.. tulis], & send_info.to) .unwrap ();} Ketika paket dikirim, aplikasi bertanggung jawab untuk mempertahankan timer untuk bereaksi terhadap peristiwa koneksi berbasis waktu. Eksirasi timer dapat diperoleh dengan menggunakan metode timeout() .
Biarkan timeout = conn.timeout ();
Aplikasi ini bertanggung jawab untuk menyediakan implementasi timer, yang dapat spesifik untuk sistem operasi atau kerangka kerja jaringan yang digunakan. Ketika timer kedaluwarsa, metode koneksi on_timeout() harus dipanggil, setelah itu paket tambahan mungkin perlu dikirim di jaringan:
// Timeout kedaluwarsa, tangani itu.conn.on_timeout (); // Kirim lebih banyak paket sesuai kebutuhan setelah timeout.loop {let (write, send_info) = match conn.send (& mut out) {ok (v) => v, Err (quiche :: error :: done) => {// selesai write.break;}, err (e) => {// terjadi kesalahan, pegangan it.break;},}; socket.send_to (& out [.. write], & send_info.to) .unwrap ();}Direkomendasikan agar aplikasi pengiriman paket keluar dari paket keluar untuk menghindari membuat semburan paket yang dapat menyebabkan kemacetan jangka pendek dan kerugian dalam jaringan.
Quiche memaparkan petunjuk mondar -mandir untuk paket keluar melalui bidang [ at ] dari struktur [ SendInfo ] yang dikembalikan dengan metode send() . Bidang ini mewakili waktu ketika paket tertentu harus dikirim ke jaringan.
Aplikasi dapat menggunakan petunjuk ini dengan secara artifisial menunda pengiriman paket melalui mekanisme spesifik platform (seperti opsi soket SO_TXTIME di Linux), atau metode khusus (misalnya dengan menggunakan timer ruang-pengguna).
Setelah beberapa bolak -balik, koneksi akan menyelesaikan jabat tangannya dan akan siap untuk mengirim atau menerima data aplikasi.
Data dapat dikirim pada aliran dengan menggunakan metode stream_send() :
jika conn.is_establish () {// jabat tangan selesai, kirim beberapa data pada aliran 0.conn.stream_send (0, b "halo", true) ?;} Aplikasi dapat memeriksa apakah ada aliran yang dapat dibaca dengan menggunakan metode koneksi readable() , yang mengembalikan iterator di atas semua aliran yang memiliki data yang luar biasa untuk dibaca.
Metode stream_recv() kemudian dapat digunakan untuk mengambil data aplikasi dari aliran yang dapat dibaca:
jika conn.is_establish () {// iterate over readable streams.for stream_id di conn.readable () {// stream dapat dibaca, baca sampai tidak ada data lagi. (stream_id, & mut buf) {println! ("got {} byte pada stream {}", baca, stream_id);}}Modul Quiche HTTP/3 menyediakan API tingkat tinggi untuk mengirim dan menerima permintaan dan tanggapan HTTP di atas protokol transportasi quic.
Lihatlah direktori [quiche/contoh/] untuk contoh yang lebih lengkap tentang cara menggunakan API quiche, termasuk contoh tentang cara menggunakan quiche dalam aplikasi C/C ++ (lihat di bawah untuk informasi lebih lanjut).
Quiche memperlihatkan API C tipis di atas API karat yang dapat digunakan untuk lebih mudah mengintegrasikan quiche ke dalam aplikasi C/C ++ (serta dalam bahasa lain yang memungkinkan panggilan C API melalui beberapa bentuk FFI). API C mengikuti desain yang sama dari karat, modulo kendala yang dikenakan oleh bahasa C itu sendiri.
Saat menjalankan cargo build , perpustakaan statis bernama libquiche.a akan dibangun secara otomatis di samping yang karat. Ini sepenuhnya berdiri sendiri dan dapat dihubungkan langsung ke aplikasi C/C ++.
Perhatikan bahwa untuk mengaktifkan FFI API, fitur ffi harus diaktifkan (dinonaktifkan secara default), dengan memberikan --features ffi ke cargo .
Quiche membutuhkan karat 1.67 atau lebih baru untuk membangun. Rilis karat stabil terbaru dapat dipasang menggunakan RustUp.
Setelah lingkungan build karat diatur, kode sumber quiche dapat diambil menggunakan git:
$ git clone --recursive https://github.com/cloudflare/quiche
dan kemudian dibangun menggunakan kargo:
$ kargo build -contoh
Kargo juga dapat digunakan untuk menjalankan testsuite:
$ tes kargo
Perhatikan bahwa BoringsSL, yang digunakan untuk mengimplementasikan jabat tangan kriptografi Quic berdasarkan TLS, perlu dibangun dan ditautkan ke Quiche. Ini dilakukan secara otomatis saat membangun quiche menggunakan kargo, tetapi mengharuskan perintah cmake tersedia selama proses pembangunan. Di jendela Anda juga membutuhkan NASM. Dokumentasi BoringsSL resmi memiliki detail lebih lanjut.
Sebagai alternatif Anda dapat menggunakan build kustom boringssl Anda sendiri dengan mengonfigurasi direktori boringssl dengan variabel lingkungan QUICHE_BSSL_PATH :
$ Quiche_bssl_path = "/path/to/boringssl" Build -Extelpath
Atau Anda dapat menggunakan OpenSSL/QUICTLS. Untuk mengaktifkan quiche untuk menggunakan vendor ini, fitur openssl dapat ditambahkan ke daftar --feature . Ketahuilah bahwa 0-RTT tidak didukung jika vendor ini digunakan.
Membangun quiche untuk Android (NDK Versi 19 atau lebih tinggi, 21 disarankan), dapat dilakukan dengan menggunakan kargo-NDK (v2.0 atau lebih baru).
Pertama, Android NDK perlu diinstal, baik menggunakan Android Studio atau secara langsung, dan variabel lingkungan ANDROID_NDK_HOME perlu diatur ke jalur instalasi NDK, misalnya:
$ Ekspor android_ndk_home =/usr/local/share/android-ndk
Kemudian rust toolchain untuk arsitektur Android yang dibutuhkan dapat diinstal sebagai berikut:
$ rustup Target Tambahkan aarch64-linux-android armv7-linux-androidabi i686-linux-android x86_64-linux-android
Perhatikan bahwa tingkat API minimum adalah 21 untuk semua arsitektur target.
Cargo-NDK (v2.0 atau lebih baru) juga perlu diinstal:
$ kargo pasang kargo-ndk
Akhirnya perpustakaan quiche dapat dibangun menggunakan prosedur berikut. Perhatikan bahwa opsi -t <architecture> dan -p <NDK version> opsi wajib.
$ kargo ndk -t arm64 -v8a -p 21 -build --features ffi
Lihat build_android_ndk19.sh untuk informasi lebih lanjut.
Untuk membangun quiche untuk iOS, Anda membutuhkan yang berikut:
Instal Alat Baris Perintah XCODE. Anda dapat menginstalnya dengan Xcode atau dengan perintah berikut:
$ xcode-select --install
Instal Rust Toolchain untuk Arsitektur IOS:
$ rustup target tambahkan aarch64-apple-ios x86_64-apple-ios
Instal cargo-lipo :
$ kargo pasang kargo-lipo
Untuk membangun libquiche, jalankan perintah berikut:
$ kargo lipo -fitur ffi
atau
$ kargo lipo --fitur ffi -rilis
IOS Build diuji dalam Xcode 10.1 dan Xcode 11.2.
Untuk membangun gambar Docker, cukup jalankan perintah berikut:
$ Make Docker-Build
Anda dapat menemukan gambar quiche docker pada repositori Docker Hub berikut:
Cloudflare/quiche
Cloudflare/quiche-qns
Tag latest akan diperbarui setiap kali pembaruan cabang quiche master.
Cloudflare/quiche
Menyediakan server dan klien yang diinstal di/usr/lokal/bin.
Cloudflare/quiche-qns
Memberikan skrip untuk menguji quiche dalam pelari quic-interop.
Hak Cipta (C) 2018-2019, Cloudflare, Inc.
Lihat Menyalin Lisensi.
