Sandboxed API'yi Kullanmaya Başlama

Bu sayfada, Sandboxed API (SAPI) ile kendi korumalı C/C++ kitaplığınızı nasıl oluşturacağınız açıklanmaktadır. Üstbilgi dosyalarındaki örnekler ve kod dokümanlarıyla birlikte kılavuz olarak kullanın.

Derleme Bağımlılıkları

Sisteme aşağıdaki bağımlılıklar yüklenmelidir:

  • UTS, IPC, kullanıcı, PID ve ağ ad alanlarını destekleyen Linux çekirdeği
  • Linux kullanıcı alanı API başlıkları
  • Kodunuzu derlemek için: GCC 6 (7 veya daha yeni bir sürüm tercih edilir) ya da Clang 7 (veya daha yeni bir sürüm)
  • Başlık dosyalarını otomatik olarak oluşturmak için: Clang Python Bindings
  • Python 3.5 veya sonraki sürümler
  • Bazel 2.2.0 veya CMake 3.12 ya da sonraki bir sürüm.
    • Yalnızca CMake: GNU Make veya libcap kitaplığı üst bilgilerinin bir sürümü ve Ninja gibi bir derleme aracı (önerilir).

Bazel'i kullanma

Bazel, önerilen derleme sistemidir ve entegrasyonu en kolay olanıdır.

Dokümanlarımızda Clang derleyicisi kullanılmaktadır. Belirli bir araç zincirine (ör. derleyici, bağlayıcı vb.) ihtiyacınız varsa varsayılan derleyici araç zincirini değiştirme hakkında bilgi edinmek için Bazel dokümanlarına bakın.

Debian 10 (Buster)

Derleme bağımlılıklarını yüklemek için:

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

Gerekli çekirdek seçenekleri:

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

Derleme bağımlılıklarını yüklemek için:

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

CMake kullanma

CMake, Ninja veya Make gibi derleme araçları için proje dosyaları oluşturan popüler bir açık kaynaklı meta derleme sistemidir.

Debian 10 (Buster)

Derleme bağımlılıklarını yüklemek için:

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

Gerekli çekirdek seçenekleri:

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

Derleme bağımlılıklarını yüklemek için:

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

Geliştirme Süreci

Bir C/C++ kitaplığını korumalı alana almak için projenizle ilgili iki öğe hazırlamanız gerekir:

Sandbox2 örneklerinden zlib'i biliyor olabilirsiniz. Burada, zpipe.c adlı tam bir program korumalı alana alınmıştır. Aşağıdaki adımlarda, zlib kitaplığını korumalı alana almak ve Sandboxed Library'yi kullanmak için SAPI'yi nasıl kullanacağınızı öğreneceksiniz.

1. Hangi işlevlerin gerekli olduğuna karar verme

zlib ana makine koduna (main_zlib.cc) baktığınızda aracın işlevinin, stdin'den veri okumak ve EOF işaretçisi okunana kadar verileri sıkıştırmak için zlib'in deflate() işlevini kullanmak olduğunu görebilirsiniz. Program, toplamda zlib'den üç işlev kullanır:

  • deflateInit_(): Sıkıştırma için başlatmak üzere
  • deflate(): Veri parçasında sıkıştırma işlemini gerçekleştirmek için
  • deflateEnd(): Sıkıştırmayı sonlandırmak ve dinamik olarak ayrılan veri yapılarını serbest bırakmak için

Gerçek hayattaki bir örnekte C/C++ kitaplığını inceler ve hangi işlevlerin gerekli olduğuna karar verirsiniz. Olası bir strateji, ana makine koduyla başlayıp kitaplığı korumalı alan dışında kullanmaktır. Ardından, ikinci bir adımda, Sandboxed Library'yi oluşturabilir ve Host Code'u, korumalı alan işlevi çağrılarını kullanacak şekilde uyarlayabilirsiniz.

2. sapi_library Build Rule'u yazma

Koruma alanına alınmış zlib kitaplığından gereken üç zlib işlevini belirledikten sonra, BUILD dosyasında derleme kuralını tanımlayabilirsiniz. sapi_library derleme kuralıyla ilgili dokümanları Derleme Kuralları sayfasında bulabilirsiniz.

Aşağıdaki kod snippet'inde, zlib SAPI örneği için sapi_library tanımı gösterilmektedir. lib özelliği kullanıldığında Bazel'e zlib kitaplığı için WORKSPACE dosyasını araması talimatı verilir.

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

Sonuç olarak, korumalı alan zlib kitaplığı oluşturulur. Çıkış, ana makine koduna dahil edilebilen ve RPC çağrıları aracılığıyla korumalı alan kitaplığıyla iletişim kurmak için kullanılabilen SAPI nesnesidir. Bu örnekte kullanılan Sandbox Politikası, varsayılan politikadır.

3. Toplantı kodunu yazma veya değiştirme

Artık oluşturulan SAPI kitaplığını ana makine koduna dahil etme zamanı.

Sandbox oluşturma

sapi::Sandbox sandbox(sapi::zlib::zlib_sapi_embed_create()); kullanarak bir sandbox nesnesi oluşturun.

SAPI nesnesini oluşturmak ve böylece korumalı alan işlevlerini kullanıma sunmak için sapi::zlib::ZlibApi api(&sandbox); öğesini kullanın.

SAPI Türlerini Kullanma

SAPI Türleri, bazen normal C türleri çalışmadığı için SAPI'nin sağladığı C++ sınıfları biçimindeki özel türlerdir.

Bir SAPI türünün ilk kullanımı, strm bildiriminde görülebilir. Burada bir SAPI yapısı kullanılır: sapi::v::Struct<sapi::zlib::z_stream> strm;

Şablon türü (sapi::zlib::z_stream), derleme kuralı tarafından otomatik olarak oluşturulan kodun iyi bir örneğidir.

Daha fazla bilgi için Değişkenler sayfasına göz atın.

API çağrıları yapma

defalteInit_, deflate veya deflateEnd numaralarını aramak için SAPI Object'i kullanın. "Değiştirme" yaklaşımını kullanmaya karar verirseniz işlev parametrelerinin beklenen değerlerle eşleştiğinden emin olmanız gerekir.

zlib example içindeki her çağrıya ilişkin bir örnek:

  • 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 İşlemlerini Kullanma

SAPI, ana makine kodunu korumalı alan kitaplığından ayırır ve arayana sorunlu veri işleme isteklerini yeniden başlatma veya iptal etme olanağı tanır. SAPI İşlemi bir adım daha ileri giderek başarısız olan işlemleri otomatik olarak tekrar eder.

Daha fazla bilgi için SAPI İşlemleri Sayfası'na göz atın.

Örnekler

Örnekler bölümünde, SAPI ekibi tarafından hazırlanmış birkaç kitaplık bulabilirsiniz.