Administra archivos con encriptación del cliente con la API de Drive

La encriptación del cliente (CSE) garantiza que tus datos se encripten antes de llegar a los servidores de Drive, lo que te brinda control sobre ellos. En esta guía, se explica el proceso para encriptar y subir, así como descargar y desencriptar, archivos de CSE de forma programática con la API de Drive. También se abordan los enfoques recomendados para probar y validar tu implementación.

Antes de comenzar

Antes de administrar archivos encriptados, configura tu dominio de Google Workspace con la siguiente lista de tareas:

Autenticación y autorización

Para interactuar con la API de Drive y tus KACLS, debes elegir un método de autenticación. Esta elección afecta la forma en que interactúas con ambos servicios:

Para obtener más detalles sobre cómo crear credenciales, consulta la guía Crea credenciales de acceso.

Autenticación del IdP del dominio

Para autenticarte con tu IdP, debes configurar un ID de cliente de OAuth y descargar su archivo de secreto de cliente. Tu aplicación debe obtener un token de autenticación de tu IdP para autenticar las solicitudes a tu KACLS. Este token es necesario para permitir que tu aplicación acceda a la clave de encriptación de datos.

Cómo administrar credenciales de forma segura

Tu aplicación controla las credenciales sensibles para la autenticación en la API de Drive y tu IdP. Estos incluyen los siguientes:

  • Material secreto del IdP, como un archivo de secreto del cliente
  • Material secreto de Google, como un archivo service-account-private-key-file
  • Material secreto almacenado por la app, como las credenciales guardadas

Debes asegurarte de que todas estas credenciales se almacenen de forma segura.

Límites y cuotas

Los archivos con encriptación del cliente están sujetos a los límites y las cuotas estándar de Drive. Ten en cuenta los límites de las unidades compartidas, los límites generales de archivos y carpetas y cómo administrar tu cuota. Además, tu herramienta de importación debe controlar los límites de frecuencia de tu servicio de listas de control de acceso a claves (KACLS) y tu proveedor de identidad (IdP).

Estructura de archivos encriptados

Drive espera el siguiente formato de archivo con encriptación del cliente para las cargas y descargas.

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

Encabezado mágico

Un encabezado mágico (también conocido como firma de archivo o número mágico) es una secuencia de bytes constante que se coloca al principio de un archivo para identificar de forma única su formato. El archivo debe comenzar con los bytes 0x99 0x5E 0xCC 0x5E.

Fragmentos encriptados

El archivo se debe dividir en fragmentos de 2 MiB. Cada fragmento se encripta con la primitiva de encriptación autenticada con datos asociados (AEAD) de la biblioteca Google Tink con un tipo de clave AES-GCM, utilizando el índice del fragmento y una marca de fragmento final como los datos asociados. Para ver un ejemplo de código que usa la API de Drive y cumple con esta especificación, consulta la demostración de código abierto.

Cómo encriptar y subir un archivo

Para subir un archivo de CSE, tu aplicación debe autenticarse, solicitar un token de CSE, encriptar el contenido del archivo de forma local, encapsular la clave de encriptación y, por último, subir el contenido encriptado y los metadatos a Google Drive.

Obtén un token de CSE

Llama al método Files:generateCseToken de la API de Drive para solicitar un token de CSE de Google Drive. Asegúrate de no incluir el parámetro de búsqueda fileId en la solicitud. Para crear el archivo en una carpeta específica, incluye el parámetro de consulta parent con el ID de la carpeta. Si se omite parent, el archivo se crea en la carpeta raíz de Mi unidad del usuario. La respuesta incluye un ID de archivo único para la carga y un token de autorización JWT, que se requiere para el paso de ajuste de claves.

Encripta datos de forma local

  1. Usa Google Tink para generar una clave de encriptación de datos (DEK) única para el archivo.
  2. Encripta el contenido del archivo según la estructura del archivo encriptado.

Procesa el hash de la clave de recurso de procesamiento

Para calcular el hash de la clave del recurso, haz lo siguiente:

  1. Extrae resource_name y perimeter_id del token de autorización jwt que se recibió de generateCseToken. Si falta perimeter_id, usa una cadena vacía.
  2. Calcula HMAC-SHA256 con la DEK de texto simple como clave y la cadena ResourceKeyDigest:my_resource_name:my_perimeter_id como los datos que se firmarán.
  3. Codifica en Base64 el hash resultante.

Para obtener más detalles, consulta Hash de clave de recurso.

Une la clave de encriptación

Para proteger la DEK, encripta (envuelve) con tu KACLS externa.

  1. Llama al extremo adecuado:
  2. Pasa la DEK de texto sin formato, el token de autenticación de tu IdP, el token de autorización de Google (si es necesario), el resource_name del JWT y un reason.
  3. Recibe la DEK unida (WDEK) del KACLS.

Subir a Drive

Usa el extremo files.create de la API de Drive para realizar una carga de archivos estándar del BLOB del archivo encriptado. Configura los siguientes campos en los metadatos del archivo:

  • id: Es el ID de archivo único que se recibió de la respuesta de generateCseToken.
  • mimeType: application/vnd.google-gsuite.encrypted; content="application/octet-stream".
    • El parámetro content se puede establecer en el tipo de MIME del archivo original.
  • clientEncryptionDetails:
    • encryptionState: "encrypted".
    • decryptionMetadata:
      • wrappedKey: Es la DEK unida (WDEK) que se recibió del KACLS.
      • kaclsId: Es el ID de KACLS que se recibió de la respuesta de generateCseToken.
      • keyFormat: "tinkAesGcmKey".
      • aes256GcmChunkSize: "default".
      • encryptionResourceKeyHash: Es el hash calculado en Compute Resource Key Hash.

Ejemplo de código abierto

Para obtener una demostración práctica del proceso de encriptación y carga, consulta la demostración de código abierto. Esto proporciona una solución funcional y puede servir como referencia valiosa.

Cómo descargar y desencriptar un archivo

Para descargar un archivo de CSE, se debe recuperar el contenido y los metadatos encriptados de Google Drive, solicitar la DEK de texto simple a tu KACLS y desencriptar el archivo de forma local.

Recupera metadatos y contenido encriptado de archivos

Llama al método Files:get de la API de Drive para recuperar los metadatos y el contenido del archivo. El campo clientEncryptionDetails contiene el DecryptionMetadata que incluye la DEK envuelta (WDEK) y el JWT que contiene la información de KACLS.

Desajusta la clave de encriptación

  1. Llama al extremo adecuado:
  2. Pasa la WDEK, el token de autenticación del IdP, el token de autorización de Google (si es necesario), el resource_name y un reason.
  3. Recibe la DEK de texto simple del KACLS.

Cómo desencriptar datos de forma local

  1. Inicializa el cifrado con la DEK de texto sin formato que se recibió del KACLS.
  2. Omite los bytes mágicos iniciales y descifra el contenido restante según la estructura del archivo encriptado.

Ejemplo de código abierto

Para obtener una demostración práctica del proceso de descarga y desencriptación, consulta la demostración de código abierto. Esto proporciona una solución funcional y puede servir como referencia valiosa.

Valida los archivos importados

Como Google no tiene acceso a las claves de encriptación, no puede desencriptar ni validar tus archivos del lado del servidor. Los errores de implementación durante las fases de encriptación local o de encapsulamiento de claves generarán errores cuando se desencripten archivos del cliente. Es fundamental realizar una validación exhaustiva antes de utilizar tu propia implementación.

Para que el contenido de los CSE de Google Drive subido funcione correctamente, debe estar encriptado de forma adecuada y contener los metadatos correctos. Eres responsable de garantizar que el contenido sea válido y se pueda desencriptar.

Realiza pruebas de encriptación y desencriptación de ida y vuelta

Para validar tu implementación, es fundamental que pruebes el flujo de extremo a extremo. Esto implica tomar un conjunto de archivos de prueba, encriptarlos con tu lógica local, subirlos a Drive con la API y, luego, descargarlos y desencriptarlos. Después de descifrar el contenido, compara el resultado con los archivos originales para asegurarte de que sean idénticos. Este proceso ayuda a detectar cualquier problema en la encriptación, el envoltorio de claves o el manejo de metadatos. La demostración de código abierto muestra cómo puedes implementar un proceso de validación de este tipo en tu propia aplicación.

Verificación aleatoria con Google Drive

Verifica que los archivos subidos incluyan un ícono de candado en el cliente web de Drive. Descarga manualmente una pequeña cantidad de archivos subidos para verificar que funcionen según lo previsto. Esta verificación usa la implementación de CSE de Google para intentar la desencriptación, lo que ayuda a aislar problemas en la lógica de encriptación o de ajuste de claves. Incluir archivos de Mi unidad y de unidades compartidas

Demostración de código abierto

El paquete de código abierto Drive CSE Upload proporciona una biblioteca de Python y un ejemplo de línea de comandos completos y funcionales que implementan los flujos de carga y descarga de CSE que se describen en esta guía. Se recomienda revisar el código de demostración antes de compilar tu propia integración del CSE.