Управляйте зашифрованными на стороне клиента файлами с помощью API Google Диска.

Шифрование на стороне клиента (CSE) гарантирует, что ваши данные будут зашифрованы до того, как достигнут серверов Google Drive, предоставляя вам контроль над вашими данными. Это руководство описывает процесс программного шифрования и загрузки, а также скачивания и расшифровки файлов CSE с использованием API Google Drive. В нем также рассматриваются рекомендуемые подходы к тестированию и проверке вашей реализации.

Прежде чем начать

Прежде чем работать с зашифрованными файлами, настройте домен Google Workspace, используя следующий контрольный список:

• Настройте шифрование на стороне клиента (CSE) для вашего домена.

• Настройте своего поставщика идентификационных данных (IdP) .

• Убедитесь, что ваша служба списков контроля доступа по ключу (KACLS) поддерживает конечные точки /wrap , /unwrap , /privilegedwrap , /privilegedunwrap и /digest .

• Создайте проект в консоли Google Cloud и включите API Google Drive .

Аутентификация и авторизация

Для взаимодействия с API Google Drive и вашими KACLS необходимо выбрать метод аутентификации. Этот выбор влияет на то, как вы будете взаимодействовать с обеими службами:

• Для аутентификации в качестве физического лица используйте поток OAuth , действующий от имени этого пользователя. Используйте стандартные конечные точки /wrap и /unwrap и предоставьте токен авторизации Google для этого пользователя.
• Администратор: Чтобы выдавать себя за других пользователей в домене, используйте учетную запись службы с делегированием полномочий в масштабе домена (DWD). Используйте конечные точки /privilegedwrap и /privilegedunwrap без токена авторизации Google.

Внимание: если учетная запись службы используется без делегирования полномочий в масштабах домена, созданные файлы добавляются на диск учетной записи службы, а не на диск конкретного пользователя, что делает эти файлы недоступными для пользователей.

Дополнительные сведения о создании учетных данных см. в руководстве по созданию учетных данных доступа .

Аутентификация поставщика идентификации домена

Для аутентификации с вашим поставщиком идентификации (IdP) необходимо настроить идентификатор клиента OAuth и загрузить файл секретного ключа клиента. Ваше приложение должно получить токен аутентификации от вашего IdP для аутентификации запросов к вашим KACLS. Этот токен необходим для предоставления вашему приложению доступа к ключу шифрования данных .

Обеспечьте безопасную обработку учетных данных.

Ваше приложение обрабатывает конфиденциальные учетные данные для аутентификации в API Google Drive и вашем поставщике идентификации (IdP). К ним относятся:

• Секретные материалы от поставщика идентификации, такие как файл с секретной информацией клиента.
• Секретные материалы от Google, такие как файл закрытого ключа учетной записи службы.
• Секретные данные, хранящиеся в приложении, такие как сохраненные учетные данные.

Вы должны обеспечить безопасное хранение всех этих учетных данных.

Ограничения и квоты

На файлы, зашифрованные на стороне клиента, распространяются стандартные ограничения и квоты Google Диска. Обратите внимание на ограничения общего доступа к дискам , общие ограничения на файлы и папки , а также на то, как управлять своей квотой . Кроме того, ваш инструмент импорта должен учитывать ограничения скорости, установленные вашей службой списков контроля доступа по ключу (KACLS) и вашим поставщиком идентификационных данных (IdP).

Структура зашифрованного файла

Для загрузки и скачивания Google Drive ожидает следующий формат файлов, зашифрованных на стороне клиента.

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

Волшебный заголовок

Магический заголовок (также известный как сигнатура файла или магическое число) — это постоянная последовательность байтов, размещаемая в самом начале файла для уникальной идентификации его формата. Файл должен начинаться с байтов 0x99 0x5E 0xCC 0x5E .

Зашифрованные фрагменты

Файл необходимо разбить на фрагменты размером 2 МиБ. Каждый фрагмент шифруется с использованием примитива Authenticated Encryption with Associated Data (AEAD) из библиотеки Google Tink с ключом типа AES-GCM, используя индекс фрагмента и флаг конечного фрагмента в качестве ассоциированных данных. Пример кода, использующего API Google Drive и соответствующего данной спецификации, см. в демонстрационном примере с открытым исходным кодом .

Предупреждение: Google Drive не сможет расшифровать файлы с неправильной структурой на стороне клиента. Рекомендуемые методы тестирования см. в разделе «Методы проверки» .

Зашифровать и загрузить файл

Для загрузки файла CSE ваше приложение должно пройти аутентификацию, запросить токен CSE, зашифровать содержимое файла локально, упаковать ключ шифрования и, наконец, загрузить зашифрованное содержимое и метаданные в Google Диск.

Получите токен CSE

Запросите токен CSE у Google Drive, вызвав метод Files:generateCseToken API Drive. Убедитесь, что вы не включаете параметр запроса fileId в запрос. Чтобы создать файл в определенной папке, включите параметр запроса parent с идентификатором папки. Если parent опущен, файл будет создан в корневой папке «Мой диск» пользователя. В ответе будет содержаться уникальный идентификатор файла для загрузки и токен авторизации JWT, необходимый для этапа обертывания ключа.

Шифрование данных локально

1. Используйте Google Tink для генерации уникального ключа шифрования данных (DEK) для файла.
2. Зашифруйте содержимое файла в соответствии со структурой зашифрованного файла .

Хэш ключа вычислительного ресурса

Для вычисления хеша ключа ресурса:

1. Извлеките resource_name и perimeter_id из токена авторизации jwt , полученного от generateCseToken . Если perimeter_id отсутствует, используйте пустую строку.
2. Вычислите HMAC-SHA256, используя открытый текст DEK в качестве ключа и строку ResourceKeyDigest:my_resource_name:my_perimeter_id в качестве данных для подписи.
3. Закодируйте полученный хеш в формате Base64.

Для получения более подробной информации см. Хэш ключа ресурса .

Оберните ключ шифрования

Для защиты DEK зашифруйте (упакуйте) его с помощью внешних KACLS.

1. Вызовите соответствующую конечную точку:
   • Индивидуальный: /wrap
   • Администратор: /privilegedwrap
2. Передайте открытый DEK, токен аутентификации вашего поставщика идентификации (IdP), токен авторизации Google (если требуется), resource_name из JWT и reason .
3. Получите упакованный DEK (WDEK) от KACLS.

Загрузить на Диск

Используйте конечную точку files.create API Google Drive для стандартной загрузки зашифрованного файла. Задайте следующие поля в метаданных файла:

• 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 .

Примечание: Для некоторых полей требуется кодирование base64. Подробности см. в документации по API Google Drive.

Пример с открытым исходным кодом

Для практической демонстрации процесса шифрования и загрузки обратитесь к демонстрационному проекту с открытым исходным кодом . Он предоставляет работающее решение и может служить ценным справочным материалом.

Скачать и расшифровать файл

Для загрузки файла CSE необходимо получить зашифрованное содержимое и метаданные с Google Drive, запросить открытый текст DEK у вашего KACLS и расшифровать файл локально.

Получение метаданных файла и зашифрованного содержимого.

Вызовите метод Files:get API Google Drive, чтобы получить метаданные и содержимое файла. Объект clientEncryptionDetails содержит DecryptionMetadata , включающую Wrapped DEK (WDEK) и JWT, содержащий информацию KACLS.

Расшифруйте ключ шифрования

1. Вызовите соответствующую конечную точку:
   • Индивидуальный: /unwrap
   • Администратор: /privilegedunwrap
2. Передайте WDEK, токен аутентификации вашего поставщика идентификации (IdP), токен авторизации Google (если требуется), resource_name ) и reason ).
3. Получите открытый текст DEK от KACLS.

Расшифровать данные локально

1. Инициализируйте шифр, используя открытый текст DEK, полученный от KACLS.
2. Пропустите начальные «магические байты» и расшифруйте оставшееся содержимое в соответствии со структурой зашифрованного файла .

Пример с открытым исходным кодом

Для практической демонстрации процесса загрузки и расшифровки обратитесь к демонстрационному проекту с открытым исходным кодом . Он предоставляет работающее решение и может служить ценным справочным материалом.

Проверьте импортированные файлы

Поскольку у Google нет доступа к ключам шифрования, компания не может расшифровать и проверить ваши файлы на стороне сервера. Ошибки реализации на этапах локального шифрования или упаковки ключей приведут к ошибкам при расшифровке файлов на стороне клиента. Тщательная проверка крайне важна перед использованием собственной реализации.

Для корректной работы загруженного контента Google Drive CSE необходимо, чтобы он был должным образом зашифрован и содержал корректные метаданные. Вы несете ответственность за обеспечение достоверности контента и возможности его расшифровки.

Выполните тесты шифрования и дешифрования в обоих направлениях.

Для проверки вашей реализации крайне важно протестировать весь процесс от начала до конца. Это включает в себя создание набора тестовых файлов, их шифрование с использованием вашей локальной логики, загрузку на Google Диск с помощью API, а затем скачивание и расшифровку. После расшифровки сравните полученное содержимое с исходными файлами, чтобы убедиться в их идентичности. Этот процесс помогает выявить любые проблемы в шифровании, упаковке ключей или обработке метаданных. Демонстрационный пример с открытым исходным кодом показывает, как вы можете реализовать подобный процесс проверки в своем собственном приложении.

Выборочная проверка с помощью Google Drive

Убедитесь, что загруженные файлы содержат значок замка в веб-клиенте Google Диска. Вручную загрузите небольшое количество загруженных файлов, чтобы убедиться, что они работают должным образом. Эта проверка использует реализацию CSE от Google для попытки расшифровки, что помогает выявить проблемы в вашей логике шифрования или обертывания ключа. Включите файлы как из «Моего диска» , так и из общих дисков .

Внимание: Не удаляйте исходные файлы, пока полностью не убедитесь, что импортированные версии CSE подлежат расшифровке.

Демонстрация с открытым исходным кодом

Пакет Drive CSE Upload с открытым исходным кодом предоставляет полную, работающую библиотеку Python и пример командной строки, реализующие процессы загрузки и скачивания CSE, описанные в этом руководстве. Настоятельно рекомендуется ознакомиться с демонстрационным кодом, прежде чем создавать собственную интеграцию с CSE.