dbcf0fb5f0
* fix: lazily initialize safeStorage async encryptor
The SafeStorage constructor previously registered a browser observer that
called os_crypt_async()->GetInstance() on app-ready. Because ESM named
imports (import { x } from 'electron') eagerly evaluate all electron
module getters, simply importing electron in an ESM entrypoint would
construct SafeStorage and touch the OS keychain on app-ready, even when
safeStorage was never used.
This showed up as a macOS CI hang: the esm-spec import-meta fixture
triggers a keychain access prompt that blocks the test runner until
timeout.
Now the async encryptor is requested lazily on the first call to
encryptStringAsync, decryptStringAsync, or isAsyncEncryptionAvailable.
isAsyncEncryptionAvailable now returns a Promise that resolves once
initialization completes, matching what the docs already stated.
* chore: lint
* fix: add HandleScope in OnOsCryptReady for pending operations
OnOsCryptReady fires asynchronously from a posted task without an active
V8 HandleScope. Previously this was harmless because eager init meant the
pending queues were always empty when it fired. With lazy init, operations
queue up first, then the callback processes them and needs to create V8
handles (Buffer::Copy, Dictionary::CreateEmpty, Promise::Resolve).
7.0 KiB
safeStorage
Allows access to simple encryption and decryption of strings for storage on the local machine.
Process: Main
This module adds extra protection to data being stored on disk by using OS-provided cryptography systems. Current security semantics for each platform are outlined below.
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: Encryption keys are stored for your app in Keychain Access in a way that prevents other applications from loading them without user override. Therefore, content is protected from other users and other apps running in the same userspace.
- Windows: Encryption keys are generated 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". Therefore, content is protected from other users on the same machine, but not from other apps running in the same userspace.
- 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,kwallet6andgnome-libsecret, but more may be available in future versions of Electron. As such, the security semantics of content protected via thesafeStorageAPI 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
safeStorageAPI will be unprotected as they are encrypted via hardcoded plaintext password. You can detect when this happens whensafeStorage.getSelectedStorageBackend()returnsbasic_text.
- Note that not all Linux setups have an available secret store. If no secret store is available, items stored in using the
Note that on macOS, access to the system Keychain is required and these calls can block the current thread to collect user input. The same is true for Linux, if a password management tool is available.
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).
Events
The safeStorage module emits the following events:
Methods
The safeStorage module has the following methods:
safeStorage.isEncryptionAvailable()
Returns boolean - Whether encryption is available.
On Linux, returns true if the app has emitted the ready event and the secret key is available.
On MacOS, returns true if Keychain is available.
On Windows, returns true once the app has emitted the ready event.
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)
plainTextstring
Returns Buffer - An array of bytes representing the encrypted string.
This function will throw an error if encryption fails.
safeStorage.decryptString(encrypted)
encryptedBuffer
Returns string - the decrypted string. Decrypts the encrypted buffer
obtained with safeStorage.encryptString back into a string.
safeStorage.encryptStringAsync(plainText)
plainTextstring
Returns Promise<Buffer> - An array of bytes representing the encrypted string.
safeStorage.decryptStringAsync(encrypted)
encryptedBuffer
Returns Promise<Object> - Resolve with an object containing the following:
shouldReEncryptboolean - 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. Iftrue, you should calldecryptStringAsyncagain to receive the new decrypted string.resultstring - the decrypted string.
safeStorage.setUsePlainTextEncryption(usePlainText)
usePlainTextboolean
This function on Linux will force the module to use an in memory password for creating symmetric key that is used for encrypt/decrypt functions when a valid OS password manager cannot be determined for the current active desktop environment. This function is a no-op on Windows and 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 isX-Cinnamon,Deepin,GNOME,Pantheon,XFCE,UKUI,unityor if the following command line flag is provided--password-store="gnome-libsecret".kwallet- When the desktop session iskde4or if the following command line flag is provided--password-store="kwallet".kwallet5- When the desktop session iskde5or if the following command line flag is provided--password-store="kwallet5".kwallet6- When the desktop session iskde6or if the following command line flag is provided--password-store="kwallet6".unknown- When the function is called before app has emitted thereadyevent.