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.

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.
    • 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 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:

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 kompresi
  • deflate(): Untuk melakukan operasi kompresi pada potongan data
  • deflateEnd(): 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.