Quản lý tệp được mã hoá phía máy khách bằng API Drive

Tính năng mã hoá phía máy khách (CSE) đảm bảo rằng dữ liệu của bạn được mã hoá trước khi đến máy chủ Drive, giúp bạn kiểm soát dữ liệu của mình. Hướng dẫn này sẽ hướng dẫn bạn quy trình mã hoá và tải lên theo phương thức lập trình, cũng như tải xuống và giải mã các tệp Mã hoá phía máy khách (CSE) bằng API Drive. Tài liệu này cũng đề cập đến các phương pháp được đề xuất để kiểm thử và xác thực việc triển khai của bạn.

Trước khi bắt đầu

Trước khi quản lý các tệp được mã hoá, hãy thiết lập miền Google Workspace của bạn theo danh sách kiểm tra sau:

Xác thực và uỷ quyền

Để tương tác với API Drive và KACLS, bạn phải chọn một phương thức xác thực. Lựa chọn này ảnh hưởng đến cách bạn tương tác với cả hai dịch vụ:

  • Cá nhân: Để xác thực với tư cách là cá nhân, hãy sử dụng quy trình OAuth để thay mặt người dùng đó hành động. Sử dụng các điểm cuối /wrap và /unwrap tiêu chuẩn, đồng thời cung cấp mã uỷ quyền của Google cho người dùng đó.
  • Quản trị viên: Để mạo danh người dùng khác trong miền, hãy sử dụng tài khoản dịch vụ có quyền uỷ quyền trên toàn miền (DWD). Sử dụng các điểm cuối /privilegedwrap và /privilegedunwrap mà không cần mã thông báo uỷ quyền của Google.

Để biết thêm thông tin về cách tạo thông tin đăng nhập, hãy xem hướng dẫn Tạo thông tin đăng nhập để truy cập.

Xác thực IdP miền

Để xác thực bằng IdP, bạn phải định cấu hình mã ứng dụng OAuth và tải tệp khoá bí mật của ứng dụng khách xuống. Ứng dụng của bạn phải lấy mã thông báo xác thực từ IdP để xác thực các yêu cầu đối với KACLS. Bạn phải có mã thông báo này để cho phép ứng dụng của bạn truy cập vào Khoá mã hoá dữ liệu.

Xử lý thông tin đăng nhập một cách an toàn

Ứng dụng của bạn xử lý thông tin đăng nhập nhạy cảm để xác thực với API Drive và IdP của bạn. Trong đó có:

  • Tài liệu bí mật từ IdP, chẳng hạn như client-secret-file
  • Tài liệu bí mật của Google, chẳng hạn như tệp khoá riêng tư của tài khoản dịch vụ
  • Tài liệu bí mật do ứng dụng lưu trữ, chẳng hạn như thông tin đăng nhập đã lưu

Bạn phải đảm bảo rằng tất cả thông tin đăng nhập này đều được lưu trữ an toàn.

Hạn mức và hạn ngạch

Các tệp được mã hoá phía máy khách phải tuân theo hạn mức và giới hạn tiêu chuẩn của Drive. Lưu ý về giới hạn của bộ nhớ dùng chung, giới hạn chung về tệp và thư mục, cũng như cách quản lý hạn mức. Ngoài ra, công cụ nhập của bạn phải xử lý hạn mức từ Dịch vụ danh sách kiểm soát quyền truy cập khoá (KACLS) và Nhà cung cấp dịch vụ danh tính (IdP).

Cấu trúc tệp đã mã hoá

Drive yêu cầu định dạng tệp được mã hoá phía máy khách sau đây cho các hoạt động tải lên và tải xuống.

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

Tiêu đề thần kỳ

Tiêu đề đặc biệt (còn gọi là chữ ký tệp hoặc số đặc biệt) là một chuỗi byte cố định được đặt ngay đầu tệp để xác định duy nhất định dạng của tệp. Tệp phải bắt đầu bằng các byte 0x99 0x5E 0xCC 0x5E.

Các khối được mã hoá

Tệp phải được chia thành các khối 2 MiB. Mỗi khối được mã hoá bằng phương thức gốc Mã hoá đã xác thực với dữ liệu liên kết (AEAD) của thư viện Google Tink với loại khoá AES-GCM, sử dụng chỉ mục khối và cờ khối cuối cùng làm Dữ liệu liên kết. Để xem ví dụ về mã sử dụng API Drive và tuân thủ quy cách này, hãy xem bản minh hoạ mã nguồn mở.

Mã hoá rồi tải tệp lên

Để tải tệp Mã hoá phía máy khách (CSE) lên, ứng dụng của bạn phải xác thực, yêu cầu mã thông báo CSE, mã hoá nội dung tệp cục bộ, bao bọc khoá mã hoá và cuối cùng là tải nội dung và siêu dữ liệu đã mã hoá lên Google Drive.

Lấy mã thông báo CSE

Yêu cầu mã thông báo CSE từ Google Drive bằng cách gọi phương thức Drive API Files:generateCseToken. Đảm bảo rằng bạn không thêm tham số truy vấn fileId vào yêu cầu. Để tạo tệp trong một thư mục cụ thể, hãy thêm tham số truy vấn parent cùng với mã thư mục. Nếu bạn bỏ qua parent, tệp sẽ được tạo trong thư mục gốc Drive của tôi của người dùng. Phản hồi này bao gồm một mã tệp duy nhất cho quá trình tải lên và một mã uỷ quyền JWT. Mã này là bắt buộc đối với bước bao bọc khoá.

Mã hoá dữ liệu cục bộ

  1. Sử dụng Google Tink để tạo một Khoá mã hoá dữ liệu (DEK) duy nhất cho tệp.
  2. Mã hoá nội dung tệp theo cấu trúc tệp được mã hoá.

Tính toán hàm băm khoá tài nguyên

Cách tính hàm băm khoá tài nguyên:

  1. Trích xuất resource_name và perimeter_id từ mã thông báo uỷ quyền jwt nhận được từ generateCseToken. Nếu thiếu perimeter_id, hãy sử dụng một chuỗi trống.
  2. Tính toán HMAC-SHA256 bằng cách sử dụng DEK văn bản thuần tuý làm khoá và chuỗi ResourceKeyDigest:my_resource_name:my_perimeter_id làm dữ liệu để ký.
  3. Mã hoá hàm băm thu được bằng Base64.

Để biết thêm thông tin chi tiết, hãy xem phần Băm khoá tài nguyên.

Bọc khoá mã hoá

Để bảo vệ DEK, hãy mã hoá (bao bọc) DEK bằng KACLS bên ngoài của bạn.

  1. Gọi điểm cuối thích hợp:
  2. Truyền DEK văn bản thuần tuý, mã xác thực IdP, mã uỷ quyền của Google (nếu cần), resource_name từ JWT và reason.
  3. Nhận DEK được bao bọc (WDEK) từ KACLS.

Tải lên Drive

Sử dụng điểm cuối files.create của API Drive để thực hiện một thao tác tải tệp lên tiêu chuẩn cho blob tệp đã mã hoá. Đặt các trường sau trong siêu dữ liệu của tệp:

  • id: Mã nhận dạng tệp duy nhất nhận được từ phản hồi generateCseToken.
  • mimeType: application/vnd.google-gsuite.encrypted; content="application/octet-stream".
    • Bạn có thể đặt tham số content thành loại MIME của tệp gốc.
  • clientEncryptionDetails:
    • encryptionState: "encrypted".
    • decryptionMetadata:
      • wrappedKey: DEK được bao bọc (WDEK) nhận được từ KACLS.
      • kaclsId: Mã nhận dạng KACLS nhận được từ phản hồi generateCseToken.
      • keyFormat: "tinkAesGcmKey".
      • aes256GcmChunkSize: "default".
      • encryptionResourceKeyHash: Hàm băm được tính trong Tính toán hàm băm khoá tài nguyên.

Ví dụ về nguồn mở

Để xem bản minh hoạ thực tế về quy trình mã hoá và tải lên, hãy tham khảo bản minh hoạ mã nguồn mở. Điều này cung cấp một giải pháp hoạt động và có thể đóng vai trò là một tài liệu tham khảo có giá trị.

Tải xuống và giải mã tệp

Để tải một tệp CSE xuống, bạn cần truy xuất nội dung và siêu dữ liệu đã mã hoá từ Google Drive, yêu cầu DEK văn bản thuần tuý từ KACLS và giải mã tệp cục bộ.

Truy xuất siêu dữ liệu tệp và nội dung đã mã hoá

Gọi phương thức Files:get của API Drive để truy xuất siêu dữ liệu và nội dung của tệp. clientEncryptionDetails chứa DecryptionMetadata, bao gồm DEK được bao bọc (WDEK) và JWT chứa thông tin KACLS.

Giải mã khoá mã hoá

  1. Gọi điểm cuối thích hợp:
  2. Truyền WDEK, mã thông báo xác thực IdP, mã thông báo uỷ quyền của Google (nếu cần), resource_name và reason.
  3. Nhận DEK văn bản thuần tuý từ KACLS.

Giải mã dữ liệu cục bộ

  1. Khởi tạo thuật toán mật mã bằng DEK văn bản thuần tuý nhận được từ KACLS.
  2. Bỏ qua các byte ban đầu và giải mã nội dung còn lại theo cấu trúc tệp được mã hoá.

Ví dụ về nguồn mở

Để xem quy trình tải xuống và giải mã trong thực tế, hãy tham khảo bản minh hoạ nguồn mở. Điều này cung cấp một giải pháp hoạt động và có thể đóng vai trò là một tài liệu tham khảo có giá trị.

Xác thực tệp đã nhập

Vì không có quyền truy cập vào khoá mã hoá, nên Google không thể giải mã và xác thực các tệp của bạn ở phía máy chủ. Lỗi triển khai trong giai đoạn mã hoá cục bộ hoặc gói khoá sẽ dẫn đến lỗi khi giải mã tệp phía máy khách. Việc xác thực kỹ lưỡng là rất quan trọng trước khi bạn sử dụng quy trình triển khai của riêng mình.

Để nội dung CSE trên Google Drive mà bạn tải lên hoạt động đúng cách, nội dung đó phải được mã hoá đúng cách và chứa siêu dữ liệu chính xác. Bạn chịu trách nhiệm đảm bảo rằng nội dung hợp lệ và có thể giải mã.

Thực hiện các kiểm thử mã hoá và giải mã khứ hồi

Để xác thực quá trình triển khai, bạn cần phải kiểm thử quy trình từ đầu đến cuối. Việc này bao gồm việc lấy một nhóm tệp kiểm thử, mã hoá các tệp đó bằng logic cục bộ, tải các tệp đó lên Drive bằng API, sau đó tải xuống và giải mã các tệp đó. Sau khi giải mã, hãy so sánh nội dung thu được với các tệp gốc để đảm bảo chúng giống hệt nhau. Quy trình này giúp phát hiện mọi vấn đề trong quá trình mã hoá, bao bọc khoá hoặc xử lý siêu dữ liệu. Bản minh hoạ nguồn mở cho thấy cách bạn có thể triển khai quy trình xác thực như vậy trong ứng dụng của riêng mình.

Kiểm tra ngẫu nhiên bằng Google Drive

Kiểm tra để đảm bảo rằng các tệp được tải lên có biểu tượng khoá trong ứng dụng Drive trên web. Tải một số ít tệp đã tải lên xuống theo cách thủ công để xác minh rằng các tệp đó hoạt động như dự kiến. Quy trình kiểm tra này sử dụng chế độ triển khai CSE của Google để thử giải mã, giúp cô lập các vấn đề trong logic mã hoá hoặc bao bọc khoá của bạn. Bao gồm các tệp trong cả Drive của tôi và Bộ nhớ dùng chung.

Bản minh hoạ nguồn mở

Gói Tải lên CSE trên Drive mã nguồn mở cung cấp một thư viện Python hoàn chỉnh, hoạt động và ví dụ về dòng lệnh triển khai các quy trình tải lên và tải xuống CSE được mô tả trong hướng dẫn này. Bạn nên xem lại mã minh hoạ trước khi tạo chế độ tích hợp CSE của riêng mình.