Gérer les fichiers chiffrés côté client avec l'API Drive

Le chiffrement côté client (CSE) garantit que vos données sont chiffrées avant d'atteindre les serveurs Drive, ce qui vous permet de les contrôler. Ce guide vous explique comment chiffrer et importer, ainsi que télécharger et déchiffrer de manière programmatique des fichiers CSE à l'aide de l'API Drive. Il aborde également les approches recommandées pour tester et valider votre implémentation.

Avant de commencer

Avant de gérer des fichiers chiffrés, configurez votre domaine Google Workspace à l'aide de la checklist suivante :

Authentification et autorisation

Pour interagir avec l'API Drive et votre KACLS, vous devez choisir une méthode d'authentification. Ce choix affecte la façon dont vous interagissez avec les deux services :

  • Individuel : pour vous authentifier en tant qu'individu, utilisez le OAuth pour agir au nom de cet utilisateur. Utilisez les points de terminaison standards /wrap et /unwrap, et fournissez le jeton d'autorisation Google pour cet utilisateur.
  • Administrateur : pour emprunter l'identité d'autres utilisateurs du domaine, utilisez un compte de service avec délégation au niveau du domaine (DWD). Utilisez les /privilegedwrap et /privilegedunwrap points de terminaison, sans jeton d'autorisation Google.

Pour en savoir plus sur la création d'identifiants, consultez le guide Créer des identifiants d'accès.

Authentification IdP du domaine

Pour vous authentifier auprès de votre IdP, vous devez configurer un ID client OAuth et télécharger son fichier de code secret client. Votre application doit obtenir un jeton d'authentification auprès de votre IdP pour authentifier les requêtes adressées à votre KACLS. Ce jeton est nécessaire pour autoriser votre application à accéder à la clé de chiffrement des données.

Gérer les identifiants de manière sécurisée

Votre application gère les identifiants sensibles pour s'authentifier auprès de l'API Drive et de votre IdP. En voici quelques exemples :

  • Matériel secret de l'IdP, tel qu'un fichier de code secret client
  • Matériel secret de Google, tel qu'un fichier de clé privée de compte de service
  • Matériel secret stocké par l'application, tel que des identifiants enregistrés

Vous devez vous assurer que tous ces identifiants sont stockés de manière sécurisée.

Limites et quotas

Les fichiers chiffrés côté client sont soumis aux limites et quotas Drive standards. Tenez compte des limites des Drive partagés, des limites générales applicables aux fichiers et aux dossiers, et de la façon de gérer votre quota. De plus, votre outil d'importation doit gérer les limites de débit de votre service de liste de contrôle d'accès aux clés (KACLS) et de votre fournisseur d'identité (IdP).

Structure des fichiers chiffrés

Drive s'attend au format de fichier chiffré côté client suivant pour les importations et les téléchargements.

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

En-tête magique

Un en-tête magique (également appelé signature de fichier ou nombre magique) est une séquence d'octets constante placée au tout début d'un fichier pour identifier de manière unique son format. Le fichier doit commencer par les octets 0x99 0x5E 0xCC 0x5E.

Blocs chiffrés

Le fichier doit être divisé en blocs de 2 Mio. Chaque bloc est chiffré à l'aide de la bibliothèque Google Tink et de sa primitive AEAD (Authenticated Encryption with Associated Data, chiffrement authentifié avec données associées) avec un type de clé AES-GCM, en utilisant l'index de bloc et un indicateur de bloc final comme données associées. Pour obtenir un exemple de code qui utilise l'API Drive et est conforme à cette spécification, consultez la démonstration Open Source.

Chiffrer et importer un fichier

Pour importer un fichier CSE, votre application doit s'authentifier, demander un jeton CSE, chiffrer le contenu du fichier localement, encapsuler la clé de chiffrement, puis importer le contenu chiffré et les métadonnées dans Google Drive.

Obtenir un jeton CSE

Demandez un jeton CSE à Google Drive en appelant la méthode de l'API Drive Files:generateCseToken. Assurez-vous de ne pas inclure le paramètre de requête fileId dans la requête. Pour créer le fichier dans un dossier spécifique, incluez le paramètre de requête parent avec l'ID du dossier. Si parent est omis, le fichier est créé dans le dossier racine "Mon Drive" de l'utilisateur. La réponse inclut un ID de fichier unique pour l'importation et un jeton d'autorisation JWT, qui est requis pour l'étape d'encapsulation de la clé.

Chiffrer les données localement

  1. Utilisez Google Tink pour générer une clé de chiffrement des données (DEK) unique pour le fichier.
  2. Chiffrez le contenu du fichier conformément à la structure du fichier chiffré.

Calculer le hachage de la clé de ressource

Pour calculer le hachage de la clé de ressource :

  1. Extrayez resource_name et perimeter_id du jeton d'autorisation jwt reçu de generateCseToken. Si perimeter_id est manquant, utilisez une chaîne vide.
  2. Calculez HMAC-SHA256 en utilisant la DEK en texte brut comme clé et la chaîne ResourceKeyDigest:my_resource_name:my_perimeter_id comme données à signer.
  3. Encodez le hachage résultant en base64.

Pour en savoir plus, consultez la section Clé de ressource Hachage.

Encapsuler la clé de chiffrement

Pour protéger la DEK, chiffrez-la (encapsulez-la) à l'aide de votre KACLS externe.

  1. Appelez le point de terminaison approprié :
  2. Transmettez la DEK en texte brut, votre jeton d'authentification IdP, le jeton d'autorisation Google (si nécessaire), le resource_name du JWT et un reason.
  3. Recevez la DEK encapsulée (WDEK) du KACLS.

Importer dans Drive

Utilisez le point de terminaison de l'API Drive files.create pour effectuer une importation de fichier standard du blob de fichier chiffré. Définissez les champs suivants dans les métadonnées du fichier :

  • id : ID de fichier unique reçu de la réponse generateCseToken.
  • mimeType: application/vnd.google-gsuite.encrypted; content="application/octet-stream".
    • Le paramètre content peut être défini sur le type MIME du fichier d'origine.
  • clientEncryptionDetails:
    • encryptionState: "encrypted".
    • decryptionMetadata:
      • wrappedKey : DEK encapsulée (WDEK) reçue du KACLS.
      • kaclsId: ID KACLS reçu de la réponse generateCseToken.
      • keyFormat: "tinkAesGcmKey".
      • aes256GcmChunkSize: "default".
      • encryptionResourceKeyHash : hachage calculé dans Calculer le hachage de la clé de ressource.

Exemple Open Source

Pour une démonstration pratique du processus de chiffrement et d'importation, consultez la démonstration Open Source. Elle fournit une solution fonctionnelle et peut servir de référence utile.

Télécharger et déchiffrer un fichier

Pour télécharger un fichier CSE, vous devez récupérer le contenu chiffré et les métadonnées de Google Drive, demander la DEK en texte brut à votre KACLS et déchiffrer le fichier localement.

Récupérer les métadonnées et le contenu chiffré du fichier

Appelez la méthode Files:get de l'API Drive pour récupérer les métadonnées et le contenu du fichier. clientEncryptionDetails contient DecryptionMetadata, qui inclut la DEK encapsulée (WDEK) et le JWT contenant les informations KACLS.

Désencapsuler la clé de chiffrement

  1. Appelez le point de terminaison approprié :
  2. Transmettez la WDEK, votre jeton d'authentification IdP, le jeton d'autorisation Google (si nécessaire), le resource_name et un reason.
  3. Recevez la DEK en texte brut du KACLS.

Déchiffrer les données localement

  1. Initialisez le chiffrement à l'aide de la DEK en texte brut reçue du KACLS.
  2. Ignorez les octets magiques initiaux et déchiffrez le contenu restant conformément à la structure du fichier chiffré.

Exemple Open Source

Pour une démonstration pratique du processus de téléchargement et de déchiffrement, consultez la démonstration Open Source. Elle fournit une solution fonctionnelle et peut servir de référence utile.

Valider les fichiers importés

Comme Google n'a pas accès aux clés de chiffrement, il ne peut pas déchiffrer ni valider vos fichiers côté serveur. Les erreurs d'implémentation lors des phases de chiffrement local ou d'encapsulation de clé entraînent des erreurs lors du déchiffrement côté client des fichiers. Une validation approfondie est essentielle avant d'utiliser votre propre implémentation.

Pour que le contenu CSE importé dans Google Drive fonctionne correctement, il doit être correctement chiffré et contenir les métadonnées appropriées. Vous êtes responsable de la validité et du déchiffrement du contenu.

Effectuer des tests de chiffrement et de déchiffrement aller-retour

Pour valider votre implémentation, il est essentiel de tester le flux de bout en bout. Cela implique de prendre un ensemble de fichiers de test, de les chiffrer à l'aide de votre logique locale, de les importer dans Drive à l'aide de l'API, puis de les télécharger et de les déchiffrer. Après le déchiffrement, comparez le contenu résultant avec les fichiers d'origine pour vous assurer qu'ils sont identiques. Ce processus permet de détecter tout problème lié au chiffrement, à l'encapsulation de clé ou à la gestion des métadonnées. La démonstration Open Source explique comment implémenter un tel processus de validation dans votre propre application.

Vérification ponctuelle avec Google Drive

Vérifiez que les fichiers importés incluent une icône de verrou dans le client Web Drive. Téléchargez manuellement un petit nombre de fichiers importés pour vérifier qu'ils fonctionnent comme prévu. Cette vérification utilise l'implémentation CSE de Google pour tenter de déchiffrer, ce qui permet d'isoler les problèmes liés à votre logique de chiffrement ou d'encapsulation de clé. Incluez des fichiers de Mon Drive et de Drive partagés.

Démonstration Open Source

Le package d'importation Drive CSE Upload Open Source fournit une bibliothèque Python complète et fonctionnelle, ainsi qu'un exemple de ligne de commande qui implémente les flux d'importation et de téléchargement CSE décrits dans ce guide. Nous vous recommandons vivement de consulter le code de démonstration avant de créer votre propre intégration CSE.