Di halaman ini, Anda akan mempelajari cara membuat library C/C++ sandbox Anda sendiri dengan Sandboxed API (SAPI). Gunakan sebagai panduan bersama dengan contoh dan dokumentasi kode di file header.
Dependensi Build
Dependensi berikut harus diinstal pada sistem:
- Kernel Linux dengan dukungan untuk namespace jaringan, IPC, pengguna, PID, dan jaringan
- Header API userspace Linux
- Untuk mengompilasi kode: GCC 6 (versi 7 atau yang lebih tinggi lebih disukai) atau Clang 7 (atau yang lebih tinggi)
- Untuk pembuatan file header secara otomatis: Clang Python Bindings
- Python 3.5 atau yang lebih baru
- Bazel versi 2.2.0 atau CMake versi 3.12 atau yang lebih tinggi.
Menggunakan Bazel
Bazel adalah sistem build yang direkomendasikan dan paling mudah diintegrasikan.
Dokumentasi kami menggunakan compiler Clang. Jika Anda memerlukan toolchain khusus (mis. compiler, penaut, dll.), lihat dokumentasi Bazel untuk mendapatkan informasi tentang cara mengubah toolchain compiler default.
Debian 10 (Perusak)
Untuk menginstal dependensi build:
echo "deb http://storage.googleapis.com/bazel-apt stable jdk1.8" | \ sudo tee /etc/apt/sources.list.d/bazel.list
wget -qO - https://bazel.build/bazel-release.pub.gpg | sudo apt-key add -
sudo apt-get update
sudo apt-get install -qy build-essential linux-libc-dev bazel python3 \ python3-pip libclang-dev
pip3 install clang
Gentoo
Opsi kernel yang diperlukan:
General setup --->
-*- Namespaces support
[*] UTS namespace
[*] IPC namespace
[*] User namespace (EXPERIMENTAL)
[*] PID Namespaces
[*] Network namespace
Untuk menginstal dependensi build:
emerge dev-util/bazel dev-python/typing dev-python/clang-python
Menggunakan CMake
CMake adalah sistem build meta open source populer yang menghasilkan file project untuk alat build seperti Ninja atau Make.
Debian 10 (Perusak)
Untuk menginstal dependensi build:
sudo apt-get install -qy build-essential linux-libc-dev cmake ninja-build \ python3 python3-pip libclang-dev libcap-dev
pip3 install absl-py clang
Gentoo
Opsi kernel yang diperlukan:
General setup --->
-*- Namespaces support
[*] UTS namespace
[*] IPC namespace
[*] User namespace (EXPERIMENTAL)
[*] PID Namespaces
[*] Network namespace
Untuk menginstal dependensi build:
emerge sys-kernel/linux-headers dev-util/cmake dev-util/ninja \
dev-python/clang-python
Proses Pengembangan
Untuk melakukan sandbox library C/C++, Anda harus menyiapkan dua item untuk project:
- Library dengan Sandbox
- Kode Host yang akan menggunakan fungsi yang diekspos oleh Library dengan Sandbox. SAPI akan membuat Objek SAPI dan RPC Stub secara otomatis untuk Anda selama proses build.
Anda mungkin sudah mengenal zlib dari contoh Sandbox2 di sini, bahwa seluruh program (zpipe.c) di-sandbox. Pada langkah berikut, Anda akan mempelajari cara menggunakan SAPI untuk melakukan sandbox library zlib dan memanfaatkan Library dengan Sandbox.
1. Menentukan fungsi yang diperlukan
Jika melihat kode host zlib (main_zlib.cc), Anda dapat melihat bahwa fungsi alat ini adalah membaca data dari stdin dan menggunakan fungsi deflate()
zlib untuk mengompresi data hingga penanda EOF
dibaca. Secara total, program ini menggunakan tiga fungsi dari zlib:
deflateInit_()
: Untuk menginisialisasi kompresideflate()
: Untuk melakukan operasi kompresi pada potongan datadeflateEnd()
: Untuk mengakhiri kompresi dan membebaskan struktur data yang dialokasikan secara dinamis
Dalam contoh nyata, Anda akan meninjau library C/C++ dan memutuskan fungsi mana yang diperlukan. Strategi yang dapat digunakan adalah memulai dengan Kode Host dan menggunakan library di luar sandbox. Kemudian, pada langkah kedua, Anda dapat membuat Library dengan Sandbox dan menyesuaikan Kode Host untuk menggunakan panggilan fungsi dengan sandbox.
2. Menulis Aturan Build sapi_library
Setelah mengidentifikasi tiga fungsi zlib yang diperlukan dari library zlib dengan sandbox, Anda dapat menentukan aturan build dalam file BUILD. Dokumentasi untuk aturan build sapi_library
dapat ditemukan di halaman Aturan Build.
Cuplikan kode di bawah ini menunjukkan definisi sapi_library
untuk contoh SAPI zlib. Dengan menggunakan atribut lib
, Bazel diminta untuk melihat library zlib di file WORKSPACE.
sapi_library(
name = "zlib-sapi",
srcs = [],
hdrs = [],
functions = [
"deflateInit_",
"deflate",
"deflateEnd",
],
lib = "@net_zlib//:zlib",
lib_name = "Zlib",
namespace = "sapi::zlib",
)
Hasilnya adalah library zlib dengan sandbox akan dibuat. Outputnya adalah Objek SAPI yang dapat disertakan ke dalam Kode Host dan digunakan untuk berkomunikasi dengan library dalam sandbox melalui panggilan RPC. Kebijakan Sandbox yang digunakan dalam contoh ini adalah kebijakan default.
3. Menulis atau Mengubah Kode Host
Sekarang saatnya menyertakan Library SAPI yang dihasilkan ke dalam Kode Host.
Menciptakan Sandbox
Gunakan sapi::Sandbox sandbox(sapi::zlib::zlib_sapi_embed_create());
untuk membuat objek sandbox.
Gunakan sapi::zlib::ZlibApi api(&sandbox);
untuk membuat instance Objek SAPI dan membuat fungsi dengan sandbox tersedia untuk digunakan.
Menggunakan Jenis SAPI
Jenis SAPI adalah jenis khusus dalam bentuk class C++ yang disediakan SAPI karena terkadang jenis C biasa tidak akan berfungsi.
Penggunaan pertama jenis SAPI dapat diamati dalam deklarasi strm
, tempat Struct SAPI digunakan: sapi::v::Struct<sapi::zlib::z_stream> strm;
Jenis template (sapi::zlib::z_stream
) adalah contoh bagus kode yang otomatis dibuat oleh aturan build.
Lihat halaman Variabel untuk mengetahui detail selengkapnya.
Lakukan Panggilan API
Untuk melakukan panggilan ke defalteInit_
, deflate
, atau deflateEnd
, gunakan Objek SAPI. Jika memutuskan untuk menggunakan pendekatan 'change', Anda harus memastikan parameter fungsi cocok dengan nilai yang diharapkan.
Contoh setiap panggilan dalam contoh zlib:
api.deflateInit_(strm.PtrBoth(), Z_DEFAULT_COMPRESSION, version.PtrBefore(), sizeof(sapi::zlib::z_stream));
api.deflate(strm.PtrBoth(), flush);
api.deflateEnd(strm.PtrBoth()).IgnoreError();
Menggunakan Transaksi SAPI
SAPI mengisolasi Kode Host dari Library Sandbox dan memberikan kemampuan kepada pemanggil untuk memulai ulang atau membatalkan permintaan pemrosesan data yang bermasalah. Transaksi SAPI berjalan selangkah lebih maju dan secara otomatis mengulangi proses yang gagal.
Lihat Halaman Transaksi SAAPI untuk mengetahui detail selengkapnya.
Contoh
Pada Examples, Anda dapat menemukan beberapa library, yang sudah disiapkan oleh tim SAPI.