サンドボックス化された API のスタートガイド

このページでは、Sandboxed API（SAPI）を使用して独自のサンドボックス化された C/C++ ライブラリを作成する方法について説明します。ヘッダー ファイルの例やコード ドキュメントと合わせて、ガイドとして使用してください。

ビルド依存関係

システムに次の依存関係をインストールする必要があります。

  • UTS、IPC、ユーザー、PID、ネットワーク名前空間をサポートする Linux カーネル
  • Linux ユーザースペース API ヘッダー
  • コードをコンパイルするには: GCC 6（バージョン 7 以降が推奨）または Clang 7（以降）
  • ヘッダー ファイルの自動生成: Clang Python バインディング
  • Python 3.5 以降
  • Bazel バージョン 2.2.0 または CMake バージョン 3.12 以降。
    • CMake のみ: GNU Make または libcap ライブラリ ヘッダーのバージョンと、Ninja などのビルドツール（推奨）。

Bazel の使用

Bazel は推奨されるビルドシステムであり、最も簡単に統合できます。

このドキュメントでは、Clang コンパイラを使用しています。特定のツールチェーン（コンパイラ、リンカーなど）が必要な場合は、Bazel ドキュメントを参照して、デフォルトのコンパイラ ツールチェーンを変更する方法を確認してください。

Debian 10（Buster）

ビルドの依存関係をインストールするには:

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

必要なカーネル オプション:

General setup  --->
-*- Namespaces support
[*]   UTS namespace
[*]   IPC namespace
[*]   User namespace (EXPERIMENTAL)
[*]   PID Namespaces
[*]   Network namespace

ビルドの依存関係をインストールするには:

emerge dev-util/bazel dev-python/typing dev-python/clang-python

CMake を使用する

CMake は、Ninja や Make などのビルドツール用のプロジェクト ファイルを生成する、一般的なオープンソースのメタビルド システムです。

Debian 10（Buster）

ビルドの依存関係をインストールするには:

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

必要なカーネル オプション:

General setup  --->
-*- Namespaces support
[*]   UTS namespace
[*]   IPC namespace
[*]   User namespace (EXPERIMENTAL)
[*]   PID Namespaces
[*]   Network namespace

ビルドの依存関係をインストールするには:

emerge sys-kernel/linux-headers dev-util/cmake dev-util/ninja \
dev-python/clang-python

開発プロセス

C/C++ ライブラリをサンドボックス化するには、プロジェクト用に次の 2 つのアイテムを準備する必要があります。

Sandbox2 の例の zlib をご存知の方もいらっしゃるかもしれませんが、ここではプログラム全体（zpipe.c）がサンドボックス化されています。次の手順では、SAPI を使用して zlib ライブラリをサンドボックス化し、サンドボックス化されたライブラリを利用する方法について説明します。

1. 必要な関数を決定する

zlib ホストコード（main_zlib.cc）を見ると、このツールの機能は stdin からデータを読み取り、zlib の deflate() 関数を使用して EOF マーカーが読み取られるまでデータを圧縮することであることがわかります。このプログラムでは、zlib の 3 つの関数を使用します。

  • deflateInit_(): 圧縮用に初期化する
  • deflate(): データチャンクに対して圧縮オペレーションを実行する
  • deflateEnd(): 圧縮を終了し、動的に割り当てられたデータ構造を解放する

実際の例では、C/C++ ライブラリを確認して、必要な関数を決定します。考えられる戦略は、ホストコードから始めて、ライブラリをサンドボックス化せずに使用することです。次に、2 番目のステップで、サンドボックス化されたライブラリを生成し、サンドボックス化された関数呼び出しを使用するようにホストコードを適応させます。

2. sapi_library ビルドルールを記述する

サンドボックス化された zlib ライブラリから必要な 3 つの zlib 関数を特定したら、BUILD ファイルでビルドルールを定義できます。sapi_library ビルドルールのドキュメントについては、ビルドルールのページをご覧ください。

次のコード スニペットは、zlib SAPI の例の sapi_library 定義を示しています。lib 属性を使用すると、Bazel は WORKSPACE ファイルで zlib ライブラリを探すように指示されます。

sapi_library(
    name = "zlib-sapi",
    srcs = [],
    hdrs = [],
    functions = [
        "deflateInit_",
        "deflate",
        "deflateEnd",
    ],
    lib = "@net_zlib//:zlib",
    lib_name = "Zlib",
    namespace = "sapi::zlib",
)

結果として、サンドボックス化された zlib ライブラリが生成されます。出力は SAPI オブジェクトです。このオブジェクトはホストコードに含めることができ、RPC 呼び出しを介してサンドボックス化されたライブラリとの通信に使用できます。この例で使用されているサンドボックス ポリシーはデフォルトのポリシーです。

3. ホストコードを記述または変更する

生成された SAPI ライブラリをホストコードに組み込む手順は次のとおりです。

サンドボックスを作成する

sapi::Sandbox sandbox(sapi::zlib::zlib_sapi_embed_create()); を使用して、サンドボックス オブジェクトを作成します。

sapi::zlib::ZlibApi api(&sandbox); を使用して SAPI オブジェクトをインスタンス化し、サンドボックス化された関数を使用できるようにします。

SAPI タイプを使用する

SAPI 型は、通常の C 型が機能しない場合があるため、SAPI が提供する C++ クラスの形式の特殊な型です。

SAPI 型の最初の使用は、SAPI 構造体が使用されている strm の宣言で確認できます。sapi::v::Struct<sapi::zlib::z_stream> strm;

テンプレート タイプ（sapi::zlib::z_stream）は、ビルドルールによって自動的に生成されるコードの好例です。

詳細については、変数ページをご覧ください。

API 呼び出しを行う

defalteInit_、deflate、deflateEnd のいずれかに呼び出しを行うには、SAPI オブジェクトを使用します。「変更」アプローチを使用する場合は、関数パラメータが想定される値と一致していることを確認する必要があります。

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();

SAPI トランザクションの使用

SAPI は、ホストコードをサンドボックス化されたライブラリから分離し、呼び出し元に問題のあるデータ処理リクエストを再開または中止する機能を提供します。SAPI トランザクションは、さらに一歩進んで、失敗したプロセスを自動的に繰り返します。

詳しくは、SAPI トランザクション ページをご覧ください。

例

[Examples] には、SAPI チームがすでに用意したライブラリがいくつかあります。