Mulai Menggunakan API dengan Sandbox

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.

Membuat Dependensi

Dependensi berikut harus diinstal di sistem:

  • Kernel Linux dengan dukungan untuk namespace UTS, IPC, pengguna, PID, dan jaringan
  • Header API ruang pengguna Linux
  • Untuk mengompilasi kode Anda: GCC 6 (sebaiknya versi 7 atau yang lebih baru) atau Clang 7 (atau yang lebih baru)
  • Untuk membuat 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 baru.
    • Khusus CMake: GNU Make atau versi header library libcap dan alat build seperti Ninja (direkomendasikan).

Menggunakan Bazel

Bazel adalah sistem build yang direkomendasikan dan paling mudah diintegrasikan.

Dokumentasi kami menggunakan compiler Clang. Jika Anda memerlukan toolchain tertentu (misalnya, compiler, linker, dll.), lihat Bazel dokumentasi untuk informasi tentang cara mengubah toolchain compiler default.

Debian 10 (Buster)

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 meta build open source populer yang menghasilkan file project untuk alat build seperti Ninja atau Make.

Debian 10 (Buster)

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 membuat sandbox library C/C++, Anda harus menyiapkan dua item untuk project Anda:

Anda mungkin sudah familiar dengan zlib dari contoh Sandbox2 di sini, seluruh program (zpipe.c) telah dibuat sandbox. Pada langkah-langkah berikut, Anda akan mempelajari cara menggunakan SAPI untuk membuat sandbox library zlib dan menggunakan Library Sandbox.

1. Tentukan 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 zlib's deflate() untuk mengompresi data hingga penanda EOF dibaca. Secara total, program ini menggunakan tiga fungsi dari zlib:

  • deflateInit_(): Untuk menginisialisasi kompresi
  • deflate(): Untuk melakukan operasi kompresi pada potongan data
  • deflateEnd(): Untuk mengakhiri kompresi dan membebaskan struktur data yang dialokasikan secara dinamis

Dalam contoh kehidupan nyata, Anda akan meninjau library C/C++ dan menentukan fungsi yang diperlukan. Salah satu strategi yang mungkin adalah memulai dengan Kode Host dan menggunakan library yang tidak di-sandbox. Kemudian, pada langkah kedua, Anda dapat membuat Library Sandbox dan mengadaptasi Kode Host untuk menggunakan panggilan fungsi sandbox.

2. Tulis Aturan Build sapi_library

Setelah mengidentifikasi tiga fungsi zlib yang diperlukan dari library zlib 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 diperintahkan untuk mencari 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 sandbox dibuat. Outputnya adalah Objek SAPI yang dapat disertakan ke dalam Kode Host dan digunakan untuk berkomunikasi dengan library sandbox melalui panggilan RPC. Kebijakan Sandbox yang digunakan dalam contoh ini adalah kebijakan default.

3. Tulis atau Ubah Kode Host

Sekarang saatnya menggabungkan Library SAPI yang dihasilkan ke dalam Kode Host.

Membuat 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 sehingga fungsi sandbox dapat digunakan.

Menggunakan Jenis SAPI

Jenis SAPI adalah jenis khusus dalam bentuk class C++ yang disediakan SAPI karena terkadang jenis C reguler 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 kode yang baik yang dibuat secara otomatis oleh aturan build.

Lihat halaman Variabel untuk mengetahui detail selengkapnya.

Melakukan Panggilan API

Untuk melakukan panggilan ke defalteInit_, deflate, atau deflateEnd, gunakan Objek SAPI. Jika memutuskan untuk menggunakan pendekatan 'ubah', Anda harus memastikan bahwa parameter fungsi cocok dengan nilai yang diharapkan.

Contoh setiap panggilan dalam contoh zlib example:

  • 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 selangkah lebih maju dan otomatis mengulang proses yang gagal.

Lihat Halaman Transaksi SAPI untuk mengetahui detail selengkapnya.

Contoh

Di bagian Contoh, Anda dapat menemukan beberapa library yang telah disiapkan oleh tim SAPI.