הצפנה מצד הלקוח (CSE) מבטיחה שהנתונים שלכם מוצפנים לפני שהם מגיעים לשרתי Drive, וכך אתם יכולים לשלוט בנתונים. במדריך הזה מוסבר איך להצפין ולהעלות קבצים ב-CSE באופן פרוגרמטי, וגם איך להוריד ולפענח אותם באמצעות Drive API. הוא כולל גם גישות מומלצות לבדיקה ולאימות של ההטמעה.
לפני שמתחילים
לפני שמנהלים קבצים מוצפנים, צריך להגדיר את דומיין Google Workspace באמצעות רשימת המשימות הבאה:
מגדירים הצפנה מצד הלקוח (CSE) לדומיין.
מגדירים את ספק הזהויות (IdP).
מוודאים ששירות רשימת בקרת הגישה למפתחות (KACLS) תומך בנקודות הקצה
/wrap,/unwrap,/privilegedwrap,/privilegedunwrapו-/digest.יוצרים פרויקט במסוף Google Cloud ומפעילים את Drive API.
אימות והרשאה
כדי ליצור אינטראקציה עם Drive API ועם KACL, צריך לבחור שיטת אימות. הבחירה הזו משפיעה על אופן האינטראקציה שלכם עם שני השירותים:
- משתמש יחיד: כדי לבצע אימות כמשתמש יחיד, צריך להשתמש בתהליך OAuth כדי לפעול בשם המשתמש. משתמשים בנקודות הקצה הרגילות
/wrapו-/unwrapומספקים את טוקן ההרשאה של Google עבור המשתמש הזה. - אדמין: כדי להתחזות למשתמשים אחרים בדומיין, צריך להשתמש בחשבון שירות עם הענקת גישה ברמת הדומיין (DWD). אפשר להשתמש בנקודות הקצה
/privilegedwrapו-/privilegedunwrapבלי אסימון הרשאה של Google.
פרטים נוספים על יצירת פרטי כניסה זמינים במדריך יצירת פרטי כניסה לגישה.
אימות באמצעות ספק זהויות (IdP) של הדומיין
כדי לבצע אימות באמצעות ספק הזהויות, צריך להגדיר מזהה לקוח ב-OAuth ולהוריד את קובץ סוד הלקוח שלו. האפליקציה שלכם צריכה לקבל טוקן אימות מספק הזהויות כדי לאמת בקשות ל-KACLS. הטוקן הזה נדרש כדי לאפשר לאפליקציה שלך גישה למפתח הצפנת הנתונים.
טיפול מאובטח בפרטי הכניסה
האפליקציה שלכם מטפלת בפרטי כניסה רגישים לצורך אימות ב-Drive API וב-IdP. למשל:
- חומר סודי מספק הזהויות, כמו קובץ סוד לקוח
- חומר סודי מ-Google, כמו קובץ מפתח פרטי של חשבון שירות
- חומר סודי שמאוחסן באפליקציה, כמו פרטי כניסה שמורים
חשוב לוודא שכל פרטי הכניסה האלה מאוחסנים בצורה מאובטחת.
מגבלות ומכסות
קבצים שמוצפנים מצד הלקוח כפופים למגבלות ולמכסות הרגילות של Drive. חשוב להכיר את המגבלות על אחסון שיתופי, את המגבלות הכלליות על קבצים ותיקיות ואת ההוראות לניהול המכסה. בנוסף, כלי הייבוא צריך לטפל במגבלות קצב מהשירות של רשימת המפתחות של בקרת הגישה (KACLS) ומספק הזהויות (IdP).
מבנה של קובץ מוצפן
ב-Drive מצפים לפורמט הקובץ הבא שהוצפן בצד הלקוח להעלאות ולהורדות.
+-------------------+
| Magic header |
+-------------------+
| Encrypted Chunk 1 |
+-------------------+
| Encrypted Chunk 2 |
+-------------------+
| ... |
+-------------------+
| Encrypted Chunk N |
+-------------------+
כותרת קסם
כותרת קסם (נקראת גם חתימת קובץ או מספר קסם) היא רצף קבוע של בייטים שמוצב בתחילת הקובץ כדי לזהות באופן ייחודי את הפורמט שלו. הקובץ חייב להתחיל בבייטים 0x99 0x5E 0xCC 0x5E.
חלקים מוצפנים
צריך לפצל את הקובץ לחלקים של 2MiB. כל מקטע מוצפן באמצעות הפרימיטיב של Google Tink להצפנה מאומתת עם נתונים משויכים (AEAD) עם סוג מפתח AES-GCM, תוך שימוש באינדקס המקטע ובדגל המקטע הסופי כנתונים המשויכים. דוגמה לקוד שמשתמש ב-Drive API ועומד בדרישות המפרט הזה מופיעה בהדגמה בקוד פתוח.
הצפנה והעלאה של קובץ
כדי להעלות קובץ CSE, האפליקציה צריכה לעבור אימות, לבקש טוקן CSE, להצפין את תוכן הקובץ באופן מקומי, לעטוף את מפתח ההצפנה ולבסוף להעלות את התוכן המוצפן ואת המטא-נתונים ל-Google Drive.
קבלת טוקן CSE
שולחים בקשה לאסימון CSE מ-Google Drive על ידי הפעלת ה-method Files:generateCseToken של Drive API. חשוב לוודא שלא כוללים את פרמטר השאילתה fileId בבקשה. כדי ליצור את הקובץ בתיקייה ספציפית, צריך לכלול את פרמטר השאילתה parent עם מזהה התיקייה. אם לא מציינים את parent, הקובץ נוצר בתיקיית הבסיס של המשתמש ב'האחסון שלי'. התגובה כוללת מזהה קובץ ייחודי להעלאה ואסימון הרשאה מסוג JWT, שנדרש לשלב של עטיפת המפתח.
הצפנת נתונים באופן מקומי
- משתמשים ב-Google Tink כדי ליצור מפתח ייחודי להצפנת נתונים (DEK) עבור הקובץ.
- מצפינים את תוכן הקובץ בהתאם למבנה של קובץ מוצפן.
חישוב הגיבוב (hash) של מפתח משאב מחשוב
כדי לחשב את הגיבוב של מפתח המשאב:
- מחלקים את אסימון ההרשאה
jwtשמתקבל מ-generateCseTokenל-resource_nameול-perimeter_id. אםperimeter_idחסר, צריך להשתמש במחרוזת ריקה. - מחשבים HMAC-SHA256 באמצעות ה-DEK של הטקסט ללא הצפנה כמפתח והמחרוזת
ResourceKeyDigest:my_resource_name:my_perimeter_idכנתונים לחתימה. - מקודדים את הגיבוב (hash) שמתקבל בקידוד Base64.
פרטים נוספים זמינים במאמר גיבוב (Hash) של מפתח משאב.
עטיפת מפתח ההצפנה
כדי להגן על מפתח ה-DEK, מצפינים אותו (עוטפים אותו) באמצעות רשימות ה-KACL החיצוניות.
- מתקשרים לנקודת הקצה המתאימה:
- אנשים פרטיים:
/wrap - אדמין:
/privilegedwrap
- אנשים פרטיים:
- מעבירים את מפתח ה-DEK בטקסט לא מוצפן, את אסימון האימות של ספק הזהויות, את אסימון ההרשאה של Google (אם נדרש), את
resource_nameמ-JWT ואתreason. - מקבלים את מפתח ההצפנה העטוף (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: הגיבוב שחושב ב-Compute Resource Key Hash.
-
דוגמה לקוד פתוח
כדי לראות הדגמה מעשית של תהליך ההצפנה וההעלאה, אפשר לעיין בהדגמה של קוד פתוח. הפתרון הזה עובד ויכול לשמש כהפניה שימושית.
הורדה ופענוח של קובץ
כדי להוריד קובץ CSE, צריך לאחזר את התוכן המוצפן ואת המטא-נתונים מ-Google Drive, לשלוח בקשה למפתח DEK בטקסט לא מוצפן מ-KACLS ולפענח את הקובץ באופן מקומי.
אחזור מטא-נתונים של קבצים ותוכן מוצפן
קוראים לשיטה Drive API
Files:get כדי לאחזר את המטא-נתונים והתוכן של הקובץ. השדה clientEncryptionDetails מכיל את DecryptionMetadata, שכולל את מפתח ה-DEK המוצפן (WDEK) ואת ה-JWT שמכיל את פרטי ה-KACLS.
פענוח מפתח ההצפנה
- מתקשרים לנקודת הקצה המתאימה:
- אנשים פרטיים:
/unwrap - אדמין:
/privilegedunwrap
- אנשים פרטיים:
- מעבירים את מפתח ה-WDEK, את אסימון האימות של ספק הזהויות, את אסימון ההרשאה של Google (אם נדרש), את
resource_nameואתreason. - לקבל את מפתח ה-DEK בטקסט לא מוצפן מ-KACLS.
פענוח נתונים באופן מקומי
- מאתחלים את ההצפנה באמצעות מפתח ה-DEK בטקסט לא מוצפן שהתקבל מ-KACLS.
- מדלגים על בייטי הקסם הראשוניים ומפענחים את התוכן שנותר בהתאם למבנה הקובץ המוצפן.
דוגמה לקוד פתוח
כדי לראות הדגמה מעשית של תהליך ההורדה והפענוח, אפשר לעיין בהדגמה של קוד פתוח. הפתרון הזה עובד ויכול לשמש כהפניה שימושית.
אימות קבצים מיובאים
ל-Google אין גישה למפתחות ההצפנה, ולכן היא לא יכולה לפענח ולאמת את הקבצים שלכם בצד השרת. שגיאות בהטמעה במהלך שלבי ההצפנה המקומית או עטיפת המפתח יגרמו לשגיאות במהלך פענוח הקבצים בצד הלקוח. חשוב לבצע אימות יסודי לפני שמשתמשים בהטמעה שלכם.
כדי שתוכן שמוצפן באמצעות CSE ב-Google Drive יפעל בצורה תקינה, הוא צריך להיות מוצפן בצורה נכונה ולהכיל את המטא-נתונים הנכונים. אתם אחראים לוודא שהתוכן תקין ושאפשר לפענח אותו.
ביצוע בדיקות הצפנה ופענוח של נתונים
כדי לוודא שההטמעה תקינה, חשוב לבדוק את התהליך מקצה לקצה. התהליך כולל לקיחת קבוצה של קבצים לבדיקה, הצפנה שלהם באמצעות הלוגיקה המקומית, העלאה שלהם ל-Drive באמצעות ה-API, ואז הורדה ופענוח שלהם. אחרי הפענוח, משווים את התוכן שמתקבל לקבצים המקוריים כדי לוודא שהם זהים. התהליך הזה עוזר לזהות בעיות בהצפנה, בהצפנת המפתח או בטיפול במטא-נתונים. הדמו של קוד פתוח מדגים איך אפשר להטמיע תהליך אימות כזה באפליקציה שלכם.
בדיקה מדגמית באמצעות Google Drive
מוודאים שהקבצים שהועלו כוללים סמל של מנעול בלקוח האינטרנט של Drive. מורידים באופן ידני מספר קטן של קבצים שהועלו כדי לוודא שהם פועלים כמצופה. בבדיקה הזו נעשה ניסיון לפענוח באמצעות הטמעת ה-CSE של Google, כדי לבודד בעיות בהצפנה או בלוגיקה של עטיפת המפתח. לכלול קבצים מהאחסון שלי ומתיקיות אחסון שיתופי.
הדגמה של קוד פתוח
חבילת Drive CSE Upload בקוד פתוח מספקת ספריית Python מלאה ופעילה ודוגמה לשורת פקודה שמיישמת את תהליכי ההעלאה וההורדה של CSE שמתוארים במדריך הזה. מומלץ מאוד לבדוק את קוד ההדגמה לפני שיוצרים שילוב משלכם של CSE.