ניהול קבצים שהוצפנו מצד הלקוח באמצעות Drive API

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

לפני שמתחילים

לפני שמנהלים קבצים מוצפנים, צריך להגדיר את דומיין Google Workspace באמצעות רשימת המשימות הבאה:

אימות והרשאה

כדי ליצור אינטראקציה עם Drive API ועם KACLS, צריך לבחור שיטת אימות. הבחירה הזו משפיעה על אופן האינטראקציה שלכם עם שני השירותים:

  • משתמש יחיד: כדי לבצע אימות כמשתמש יחיד, צריך להשתמש בתהליך OAuth כדי לפעול בשם המשתמש. משתמשים בנקודות הקצה הרגילות /wrap ו-/unwrap ומספקים את טוקן ההרשאה של Google עבור המשתמש הזה.
  • אדמין: כדי להתחזות למשתמשים אחרים בדומיין, צריך להשתמש בחשבון שירות עם הענקת גישה ברמת הדומיין (DWD). אפשר להשתמש בנקודות הקצה /privilegedwrap ו-/privilegedunwrap בלי אסימון הרשאה של Google.

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

אימות באמצעות ספק זהויות (IdP) של הדומיין

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

טיפול מאובטח בפרטי הכניסה

האפליקציה שלכם מטפלת בפרטי כניסה רגישים לצורך אימות ב-Drive API וב-IdP שלכם. למשל:

  • חומר סודי מ-IdP, כמו קובץ סוד לקוח
  • חומר סודי מ-Google, כמו קובץ מפתח פרטי של חשבון שירות
  • חומר סודי שמאוחסן באפליקציה, כמו פרטי כניסה שמורים

חשוב לוודא שכל פרטי הכניסה האלה מאוחסנים בצורה מאובטחת.

מגבלות ומכסות

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

מבנה של קובץ מוצפן

‫Drive מצפה לפורמט הקובץ הבא שהוצפן בצד הלקוח להעלאות ולהורדות.

+-------------------+
| Magic header      |
+-------------------+
| Encrypted Chunk 1 |
+-------------------+
| Encrypted Chunk 2 |
+-------------------+
| ...               |
+-------------------+
| Encrypted Chunk N |
+-------------------+

כותרת קסם

כותרת קסם (נקראת גם חתימת קובץ או מספר קסם) היא רצף קבוע של בייטים שמוצב בתחילת הקובץ כדי לזהות באופן ייחודי את הפורמט שלו. הקובץ חייב להתחיל בבייטים 0x99 0x5E 0xCC 0x5E.

חלקים מוצפנים

צריך לפצל את הקובץ לחלקים של 2MiB. כל נתח מוצפן באמצעות פרימיטיב של הצפנה מאומתת עם נתונים משויכים (AEAD) של ספריית Google Tink עם סוג מפתח AES-GCM, באמצעות אינדקס הנתח ודגל הנתח הסופי כנתונים המשויכים. דוגמת קוד שמשתמשת ב-Drive API ועומדת בדרישות האלה מופיעה בהדגמה בקוד פתוח.

הצפנה והעלאה של קובץ

כדי להעלות קובץ CSE, האפליקציה צריכה לעבור אימות, לבקש אסימון CSE, להצפין את תוכן הקובץ באופן מקומי, לעטוף את מפתח ההצפנה ולבסוף להעלות את התוכן המוצפן ואת המטא-נתונים ל-Google Drive.

קבלת טוקן CSE

שולחים בקשה לאסימון CSE מ-Google Drive על ידי הפעלת ה-method ‏Files:generateCseToken של Drive API. חשוב לוודא שלא כוללים את פרמטר השאילתה fileId בבקשה. כדי ליצור את הקובץ בתיקייה ספציפית, צריך לכלול את פרמטר השאילתה parent עם מזהה התיקייה. אם לא מציינים את parent, הקובץ נוצר בתיקיית הבסיס 'האחסון שלי' של המשתמש. התגובה כוללת מזהה קובץ ייחודי להעלאה ואסימון הרשאה מסוג JWT, שנדרש לשלב של עטיפת המפתח.

הצפנת נתונים באופן מקומי

  1. משתמשים ב-Google Tink כדי ליצור מפתח ייחודי להצפנת נתונים (DEK) עבור הקובץ.
  2. מצפינים את תוכן הקובץ בהתאם למבנה של קובץ מוצפן.

חישוב הגיבוב (hash) של מפתח משאב מחשוב

כדי לחשב את הגיבוב של מפתח המשאב:

  1. מחלקים את טוקן ההרשאה jwt שמתקבל מ-generateCseToken ל-resource_name ול-perimeter_id. אם perimeter_id חסר, צריך להשתמש במחרוזת ריקה.
  2. מחשבים HMAC-SHA256 באמצעות מפתח ה-DEK בטקסט לא מוצפן כמפתח והמחרוזת ResourceKeyDigest:my_resource_name:my_perimeter_id כנתונים לחתימה.
  3. מקודדים את הגיבוב (hash) שמתקבל בקידוד Base64.

פרטים נוספים זמינים במאמר גיבוב (Hash) של מפתח משאב.

עטיפת מפתח ההצפנה

כדי להגן על מפתח ה-DEK, מצפינים אותו (עוטפים אותו) באמצעות KACL חיצוניים.

  1. מתקשרים לנקודת הקצה המתאימה:
  2. מעבירים את מפתח ה-DEK בטקסט לא מוצפן, את אסימון האימות של ספק הזהויות, את אסימון ההרשאה של Google (אם נדרש), את resource_name מ-JWT ואת reason.
  3. מקבלים את מפתח ההצפנה העטוף (WDEK) מ-KACLS.

העלאה ל-Drive

משתמשים בנקודת הקצה (endpoint) של Drive API‏ files.create כדי לבצע העלאה רגילה של קובץ של ה-blob של הקובץ המוצפן. מגדירים את השדות הבאים במטא-נתונים של הקובץ:

  • ‫id: המזהה הייחודי של הקובץ שהתקבל מהתגובה של generateCseToken.
  • mimeType: application/vnd.google-gsuite.encrypted; content="application/octet-stream".
    • אפשר להגדיר את הפרמטר content לסוג ה-MIME של הקובץ המקורי.
  • clientEncryptionDetails:
    • encryptionState: "encrypted".
    • decryptionMetadata:
      • ‫wrappedKey: מפתח ה-DEK העטוף (WDEK) שהתקבל מ-KACLS.
      • ‫kaclsId: המזהה של KACLS שהתקבל מהתגובה generateCseToken.
      • keyFormat: "tinkAesGcmKey".
      • aes256GcmChunkSize: "default".
      • ‫encryptionResourceKeyHash: הגיבוב שחושב בחישוב הגיבוב של מפתח משאב.

דוגמה לקוד פתוח

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

הורדה ופענוח של קובץ

כדי להוריד קובץ CSE, צריך לאחזר את התוכן המוצפן ואת המטא-נתונים מ-Google Drive, לשלוח בקשה למפתח DEK בטקסט לא מוצפן מ-KACLS ולפענח את הקובץ באופן מקומי.

אחזור מטא-נתונים של קובץ ותוכן מוצפן

קוראים לשיטה Files:get של Drive API כדי לאחזר את המטא-נתונים והתוכן של הקובץ. השדה clientEncryptionDetails מכיל את DecryptionMetadata, שכולל את ה-DEK העטוף (WDEK) ואת ה-JWT שמכיל את המידע של KACLS.

פענוח מפתח ההצפנה

  1. מתקשרים לנקודת הקצה המתאימה:
  2. מעבירים את מפתח ה-WDEK, את אסימון האימות של ספק הזהויות, את אסימון ההרשאה של Google (אם נדרש), את resource_name ואת reason.
  3. מקבלים את מפתח ה-DEK בטקסט לא מוצפן מ-KACLS.

פענוח נתונים באופן מקומי

  1. מאתחלים את הצופן באמצעות מפתח ה-DEK בטקסט פשוט שהתקבל מ-KACLS.
  2. מדלגים על בייטי הקסם הראשוניים ומפענחים את התוכן שנותר בהתאם למבנה הקובץ המוצפן.

דוגמה לקוד פתוח

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

אימות קבצים מיובאים

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

כדי שתוכן CSE שהועלה ל-Google Drive יפעל בצורה תקינה, הוא צריך להיות מוצפן בצורה נכונה ולהכיל את המטא-נתונים הנכונים. אתם אחראים לוודא שהתוכן תקין ושאפשר לפענח אותו.

ביצוע בדיקות הצפנה ופענוח של נתונים

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

בדיקה מדגמית באמצעות Google Drive

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

הדגמה של קוד פתוח

חבילת Drive CSE Upload בקוד פתוח מספקת ספריית Python מלאה ופעילה ודוגמה לשורת פקודה שמיישמת את תהליכי ההעלאה וההורדה של CSE שמתוארים במדריך הזה. מומלץ מאוד לבדוק את קוד ההדגמה לפני שיוצרים שילוב משלכם של CSE.