Aller au contenu principal

safeStorage

Permet d'accéder à des cryptage et décryptage simples de chaînes de caractères pour le stockage sur la machine locale.

Process: Main

Ce module ajoute une protection supplémentaire aux données stockées sur disque en utilisant des systèmes de cryptographie fournis par le système d'exploitation. La sémantique de sécurité actuelle pour chaque plate-forme est décrite ci-dessous.

[!NOTE] We recommend using the asynchronous API (encryptStringAsync/decryptStringAsync) over the synchronous API. The async API is non-blocking, supports key rotation, and handles temporary unavailability gracefully. The synchronous API may be deprecated in a future version of Electron.

Platform-Specific Key Providers​

Synchronous API​

  • macOS : les clés de chiffrement sont stockées pour votre application selon Keychain Access de manière à empêcher d’autres applications de les charger sans outrepasser les droits de l’utilisateur. Par conséquent, le contenu est protégé contre d’autres utilisateurs et d’autres applications fonctionnant dans le même espace utilisateur.
  • Windows : les clés de chiffrement sont générées via DPAPI. As per the Windows documentation: "Typically, only a user with the same logon credential as the user who encrypted the data can typically decrypt the data". Par conséquent, le contenu est protégé contre d'éventuels autres utilisateurs sur la même machine, mais pas des autres applications fonctionnant dans le même espace utilisateur.
  • Linux: Encryption keys are generated and stored in a secret store that varies depending on your window manager and system setup. Options currently supported are kwallet, kwallet5, kwallet6 and gnome-libsecret, but more may be available in future versions of Electron. As such, the security semantics of content protected via the safeStorage API vary between window managers and secret stores.
    • Note that not all Linux setups have an available secret store. If no secret store is available, items stored in using the safeStorage API will be unprotected as they are encrypted via hardcoded plaintext password. You can detect when this happens when safeStorage.getSelectedStorageBackend() returns basic_text.

Note that on macOS, access to the system Keychain is required and these calls can block the current thread to collect user input. Il en va de même pour Linux, si un outil de gestion des mots de passe est disponible.

Asynchronous API​

The asynchronous API uses pluggable key providers that vary by platform:

  • macOS: Encryption keys are stored and retrieved from Keychain Access. This provides the same security model as the synchronous API, protecting content from other users and other apps running in the same userspace.
  • Windows: Encryption keys are protected via DPAPI. This provides the same security model as the synchronous API, protecting content from other users on the same machine but not from other apps running in the same userspace.
  • Linux: Multiple key providers may be available depending on the desktop environment:
    • org.freedesktop.portal.Secret: Uses the Portal Secret D-Bus interface to retrieve application-specific secrets. This is the preferred provider for sandboxed environments like Flatpak.
    • Secret Service API: Uses the freedesktop.org Secret Service API (e.g., GNOME Keyring) for key storage.
    • A fallback provider is used for environments without a secret service available.

Unlike the synchronous API, these operations are non-blocking and support additional features like key rotation (indicated by shouldReEncrypt) and temporary unavailability handling (indicated by isTemporarilyUnavailable).

Événements​

Le module safeStorage émet les événements suivants :

Méthodes​

Le module safeStorage possède les méthodes suivantes :

safeStorage.isEncryptionAvailable()​

Retourne boolean - Indique si le cryptage est disponible.

Sous Linux, retourne vrai si l'application a émis l'événement ready et que la clé secrète est disponible. Sur MacOS, retourne true si Keychain est disponible. Sous Windows, renvoie true une fois que l’application a émis l’événement ready .

safeStorage.isAsyncEncryptionAvailable()​

Returns Promise<boolean> - Resolves with whether encryption is available for asynchronous safeStorage operations.

The asynchronous encryptor is initialized lazily the first time this method, encryptStringAsync, or decryptStringAsync is called after the app is ready. The returned promise resolves once initialization completes.

safeStorage.encryptString(plainText)​

  • plainText string

Retourne Buffer - Un tableau d'octets représentant la chaîne chiffrée.

Cette fonction déclenchera une erreur en cas d'échec du cryptage.

safeStorage.decryptString(encrypted)​

  • encrypted Buffer

Retourne string - la chaîne décryptée. Décrypte dans une chaîne le tampon crypté obtenu avec safeStorage.encryptString.

safeStorage.encryptStringAsync(plainText)​

  • plainText string

Retourne Promise<Buffer> - Un tableau d'octets représentant la chaîne chiffrée.

safeStorage.decryptStringAsync(encrypted)​

  • encrypted Buffer

Retourne Promise<Object> - Se résout avec un objet contenant les éléments suivants :

  • shouldReEncrypt boolean - whether data that has just been returned from the decrypt operation should be re-encrypted, as the key has been rotated or a new key is available that provides a different security level. If true, you should call decryptStringAsync again to receive the new decrypted string.
  • result string - the decrypted string.

safeStorage.setUsePlainTextEncryption(usePlainText)​

  • usePlainText boolean

Cette fonction sur Linux forcera le module à utiliser un mot de passe en mémoire pour créer une clé symétrique utilisée pour crypter/décrypter les fonctions lorsqu’un manager de mot de passe OS valide ne peut être déterminé pour l’environnement de bureau actif actuel. Cette fonction est un non-op sur Windows et MacOS.

safeStorage.getSelectedStorageBackend() Linux​

Returns string - User friendly name of the password manager selected on Linux.

This function will return one of the following values:

  • basic_text - When the desktop environment is not recognised or if the following command line flag is provided --password-store="basic".
  • gnome_libsecret - When the desktop environment is X-Cinnamon, Deepin, GNOME, Pantheon, XFCE, UKUI, unity or if the following command line flag is provided --password-store="gnome-libsecret".
  • kwallet - When the desktop session is kde4 or if the following command line flag is provided --password-store="kwallet".
  • kwallet5 - When the desktop session is kde5 or if the following command line flag is provided --password-store="kwallet5".
  • kwallet6 - When the desktop session is kde6 or if the following command line flag is provided --password-store="kwallet6".
  • unknown - When the function is called before app has emitted the ready event.