サンドボックス化された 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 の例では、プログラム全体（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 属性を使用して、 WORKSPACE ファイル で zlib ライブラリを検索するように Bazel に指示します。

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++ クラスの形式の特殊な タイプです。通常の C タイプでは機能しない場合があるため、SAPI によって提供されます。

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

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

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

API 呼び出しを行う

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

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

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

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

詳細については、SAPI トランザクション のページをご覧ください。

例

例では、Examples SAPI チームによってすでに準備されているいくつかの ライブラリを確認できます。