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 des fichiers CSE de manière programmatique, ainsi que comment les télécharger et les déchiffrer à 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 :

  • Particulier : pour vous authentifier en tant que particulier, utilisez le flux OAuth afin d'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 la délégation au niveau du domaine (DWD). Utilisez les points de terminaison /privilegedwrap et /privilegedunwrap 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 de 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 envoyées à votre KACLS. Ce jeton est obligatoire pour permettre à votre application d'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 l'authentification auprès de l'API Drive et de votre IdP. Exemples :

  • Éléments secrets du fournisseur d'identité, tels qu'un fichier de code secret du 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, comme les identifiants enregistrés

Vous devez veiller à stocker tous ces identifiants de manière sécurisée.

Limites et quotas

Les fichiers chiffrés côté client sont soumis aux limites et quotas standards de Drive. 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 attend le 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 tout au 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 primitive AEAD (Authenticated Encryption with Associated Data) de la bibliothèque Google Tink avec un type de clé AES-GCM, en utilisant l'index du bloc et un indicateur de bloc final comme données associées. Pour obtenir un exemple de code qui utilise l'API Drive et qui 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 en local, 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 Files:generateCseToken de l'API Drive. 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 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 en fonction de la structure du fichier chiffré.

Calculer le hachage de la clé de ressource de calcul

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 obtenu en base64.

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

Encapsuler la clé de chiffrement

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

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

Importer dans Drive

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

  • id : ID unique du fichier 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 :

Exemple Open Source

Pour une démonstration pratique du processus de chiffrement et d'importation, consultez la démonstration Open Source. Cela 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 et les métadonnées chiffrés depuis Google Drive, demander la clé de chiffrement des données en texte brut à votre KACLS et déchiffrer le fichier en local.

Récupérer les métadonnées et le contenu chiffré d'un 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 le DEK encapsulé (WDEK) et le JWT contenant les informations KACLS.

Développer la clé de chiffrement

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

Déchiffrer les données en local

  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 en fonction de la structure du fichier chiffré.

Exemple Open Source

Pour une démonstration pratique du processus de téléchargement et de décryptage, consultez la démonstration Open Source. Cela 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îneront des erreurs lors du déchiffrement des fichiers côté client. Une validation approfondie est essentielle avant d'utiliser votre propre implémentation.

Pour que le contenu importé dans Google Drive avec le CSE fonctionne correctement, il doit être correctement chiffré et contenir les métadonnées appropriées. Vous êtes responsable de la validité et de la 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 obtenu 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 montre 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 en forme de cadenas 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 les données, ce qui permet d'isoler les problèmes liés à votre logique de chiffrement ou d'encapsulation de clé. Incluez les fichiers de Mon Drive et des Drive partagés.

Démo Open Source

Le package Open Source Drive CSE Upload 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 d'examiner le code de démonstration avant de créer votre propre intégration CSE.