הסבר על ממשק ה-Sandbox

ממשק ה-API של ארגז החול (SAPI) מבוסס על פרויקט Sandbox2 המבוסס והמוכר. בדף הזה מוסבר על ארכיטקטורת העיצוב של SAPI ועל מושגים מרכזיים.

סקירה כללית

‫SAPI נועד לספק למפתחים כלים להכנת ספריות C/C++‎ לארגון בסביבת ארגז חול, וגם את ממשקי ה-API שנדרשים לתקשורת עם הגרסה של ספריות C/C++‎ שמאורגנת בסביבת ארגז חול.

בתרשים הזה מוצגת הארכיטקטורה של ספריית C/C++ ב-SAPI sandboxed:

בנוסף, SAPI מספקת פרימיטיבים לסנכרון זיכרון ידני ואוטומטי (מבוסס על מאפייני מצביעים בהתאמה אישית) (מערכים, מבנים) בין ספריות SAPI לבין קוד המארח.

לבסוף, API ברמה גבוהה של Transactions מאפשר מעקב אחרי ספריות SAPI והפעלה מחדש שלהן אם הן נכשלות (לדוגמה, בגלל הפרות אבטחה, קריסות או ניצול יתר של משאבים).

Sandbox2

פרויקט הקוד הפתוח Sandbox2 פותח ומתוחזק על ידי מהנדסי אבטחה של Google, והוא טכנולוגיית הארגז חול העיקרית שבה נעשה שימוש ב-SAPI. ‫Sandbox2 מכיל שלושה רכיבים עיקריים: Sandbox Policy,‏ Executor ו-Sandboxee.

מדיניות בנושא ארגז חול

מדיניות ארגז החול מגדירה את סביבת ההפעלה המוגבלת של הספרייה בארגז החול. הדבר מושג באמצעות הבהרה של אילו קריאות למערכת אפשר להפעיל. ‫SAPI משתמש באותו מנגנון כמו Sandbox2. מידע נוסף על תכנון והגדרה של מדיניות ארגז חול זמין בקטע בנושא מדיניות ארגז חול ובדף תחילת העבודה עם Sandbox2.

‫SAPI משתמש במדיניות ברירת מחדל, אבל אפשר גם להשתמש במדיניות ייעודית לארגז חול. כדי לעשות את זה, צריך להגדיר אותה בקובץ כותרת sandbox.h ולהעביר אותה כארגומנט בכלל הבנייה sapi_library.

ספרייה מבודדת

זוהי ספריית C/C++ בארגז חול שתופעל בסביבת ארגז החול המוגבלת שמסופקת על ידי Sandbox2. בסופו של דבר, Sandboxed Library חושפת את הפונקציונליות הנדרשת שאפשר להשתמש בה ב-Host Code.

הספרייה Sandboxed בנויה באמצעות כלל הבנייה sapi_library, שבו אפשר לציין מדיניות מותאמת אישית של ארגז חול שמגדירה את סביבת ההרצה המוגבלת. יכול להיות שתצטרכו לכתוב קוד wrapper או קוד stub (ראו libcurl), אבל לא מצופה מכם לשנות את קוד המקור של ספריית C/C++ בזמן ההכנה של גרסת SAPI.

אובייקט SAPI ו-RPC Stub

אובייקט SAPI הוא אובייקט C++‎ שחושף את ה-API של הספרייה המבודדת. היא מעבירה קריאות מקוד המארח אל RPC Stub, שמוטמע בספריית SAPI יחד עם ספריית Sandboxed.

שני הרכיבים האלה נוצרים באופן אוטומטי על ידי מערכת ה-build באמצעות sapi_library() כלל ה-build. ‫SAPI תומך בשתי מערכות בנייה: Bazel של Google ו-CMake.

קוד המארח

קוד המארח הוא מה שמיישם את הלוגיקה שמסופקת על ידי ספריית SAPI. היא צורכת את הגרסה הלא-ארגזית של ספריית C/C++. לכן, קוד המארח קורא לפונקציות שמיוצאות על ידי ספריית ה-SAPI, מעביר נתונים לארגז החול ומקבל ממנו נתונים.

צריך להתאים את קוד המארח לשימוש בספריית SAPI. בעיקר, אי אפשר לקרוא לפונקציות של הספרייה כי היא נמצאת בתהליך נפרד של ארגז חול. לכן, SAPI מספקת כלים שיוצרים אובייקט SAPI שמייצג קריאות לספריית SAPI.

מושגים

כללי Build של Bazel

פרויקט SAPI מספק שני כללי build של Bazel להפעלת ארגז חול לספריית C/C++‎:

• ‫sapi_library() – יוצר את כל הפלטים שנדרשים כדי להכניס את ספריית C/C++ לארגז חול כ-Sandboxee של Sandbox2. אפשר להשתמש בפלט של ה-build כתלות בכלל cc_binary() שמשמש ליצירת קובץ בינארי של קוד המארח.
• ‫sapi_interface() – יוצר באופן אוטומטי את הכותרת שאפשר לכלול בקובץ הבינארי של קוד המארח.

הסבר מפורט יותר על כללי בנייה זמין במאמר כללי בנייה.

משתנים

‫SAPI מספק מספר סוגים מיוחדים, שנקראים SAPI Types, שאנחנו ממליצים להשתמש בהם ב-Host Code. הסיבה העיקרית לצורך בסוגי SAPI היא התהליך, ולכן הזיכרון, הבידוד בין קוד המארח לבין הספרייה בסביבת ארגז חול.

הסבר מפורט יותר על הנושא הזה וסקירה כללית של כמה סוגי SAPI נפוצים זמינים במאמר משתנים.

עסקאות

כפי שהוסבר למעלה, כל קריאה ל-API של ספרייה עם ארגז חול מועברת דרך שכבת RPC. כדי לטפל בכשל בשכבה הזו, צריך להטמיע טיפול מתאים בשגיאות. מודול SAPI Transaction מספק את המנגנון הדרוש כדי לוודא שכל הקריאות לספרייה מבודדת הושלמו ללא בעיות ברמת ה-RPC, או שהן מוחזרות עם שגיאה רלוונטית.

הסבר מפורט יותר בנושא הזה זמין במאמר עסקאות.

תחילת העבודה

במאמר תחילת העבודה עם Sandboxed API מוסבר איך להגדיר את הפרויקט הראשון שלכם ב-Sandboxed API.