Mulai Menggunakan API dengan Sandbox

Di halaman ini, Anda akan mempelajari cara membuat library C/C++ dengan sandbox Anda sendiri menggunakan Sandboxed API (SAPI). Gunakan sebagai panduan bersama dengan contoh dan dokumentasi kode di file header.

Membangun Dependensi

Dependensi berikut harus diinstal di sistem:

  • Kernel Linux dengan dukungan untuk UTS, IPC, pengguna, PID, dan namespace jaringan
  • Header API ruang pengguna Linux
  • Untuk mengompilasi kode Anda: GCC 6 (lebih disarankan versi 7 atau yang lebih tinggi) atau Clang 7 (atau yang lebih tinggi)
  • Untuk membuat file header secara otomatis: Binding Python Clang
  • 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 dokumentasi Bazel untuk mengetahui 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 build meta open source populer yang membuat 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 melakukan sandbox pada library C/C++, Anda harus menyiapkan dua item untuk project:

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

1. Menentukan fungsi mana yang diperlukan

Jika Anda 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 melakukan inisialisasi 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 memutuskan fungsi mana yang diperlukan. Salah satu strategi yang mungkin adalah memulai dengan Kode Host dan menggunakan library tanpa sandbox. Kemudian, pada langkah kedua, Anda dapat membuat Sandboxed Library dan menyesuaikan Kode Host untuk menggunakan panggilan fungsi yang di-sandbox.

2. Menulis 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 Build Rules.

Cuplikan kode di bawah ini menunjukkan definisi sapi_library untuk contoh zlib SAPI. Dengan menggunakan atribut lib, Bazel diinstruksikan 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 yang di-sandbox dihasilkan. Outputnya adalah Objek SAPI yang dapat disertakan dalam Kode Host dan digunakan untuk berkomunikasi dengan library sandbox melalui panggilan RPC. Kebijakan Sandbox yang digunakan dalam contoh ini adalah kebijakan default.

3. Menulis atau Mengubah Kode Host

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

Buat 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 dengan demikian membuat fungsi 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, dengan menggunakan SAPI Struct: sapi::v::Struct<sapi::zlib::z_stream> strm;

Jenis template (sapi::zlib::z_stream) adalah contoh bagus kode 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 Anda memutuskan untuk menggunakan pendekatan 'change', Anda harus memastikan bahwa parameter fungsi cocok dengan nilai yang diharapkan.

Contoh setiap panggilan di 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 Sandboxed Library dan memberikan kemampuan kepada pemanggil untuk memulai ulang atau membatalkan permintaan pemrosesan data yang bermasalah. Transaksi SAPI melangkah lebih jauh dan otomatis mengulangi proses yang gagal.

Lihat Halaman Transaksi SAPI untuk mengetahui detail selengkapnya.

Contoh

Di bagian Contoh, Anda dapat menemukan beberapa pustaka yang sudah disiapkan oleh tim SAPI.