github/electron
1
1
Fork 0
mirror of https://github.com/electron/electron.git synced 2026-02-19 03:14:51 -05:00
Code Issues Packages Projects Releases Wiki Activity

feat: introduce os_crypt_async in safeStorage (#49054)

Browse Source 
* feat: support Freedesktop Secret Service OSCrypt client

Refs https://issues.chromium.org/issues/40086962
Refs https://issues.chromium.org/issues/447372315

* chore: rework to async interface

* refactor: allow customizing freedesktop config

* docs: add more async impl info

* refactor: reject when temporarily unavailable

* chore: feedback from review

* chore: push_back => emplace_back
This commit is contained in:
Shelley Vohr
2026-02-15 19:54:50 +01:00
committed by GitHub
parent dcdbb0397e
commit eb29568e45
19 changed files with 970 additions and 875 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
docs/api/cookies.md
View File

@@ -107,7 +107,7 @@ the response.
cookie and will not be retained between sessions.
* `sameSite` string (optional) - The [Same Site](https://developer.mozilla.org/en-US/docs/Web/HTTP/Cookies#SameSite_cookies) policy to apply to this cookie. Can be `unspecified`, `no_restriction`, `lax` or `strict`. Default is `lax`.
Returns `Promise<void>` - A promise which resolves when the cookie has been set
Returns `Promise<void>` - A promise which resolves when the cookie has been set.
Sets a cookie with `details`.
@@ -116,16 +116,16 @@ Sets a cookie with `details`.
* `url` string - The URL associated with the cookie.
* `name` string - The name of cookie to remove.
Returns `Promise<void>` - A promise which resolves when the cookie has been removed
Returns `Promise<void>` - A promise which resolves when the cookie has been removed.
Removes the cookies matching `url` and `name`
Removes the cookies matching `url` and `name`.
#### `cookies.flushStore()`
Returns `Promise<void>` - A promise which resolves when the cookie store has been flushed
Returns `Promise<void>` - A promise which resolves when the cookie store has been flushed.
Writes any unwritten cookies data to disk
Writes any unwritten cookies data to disk.
Cookies written by any method will not be written to disk immediately, but will be written every 30 seconds or 512 operations
Cookies written by any method will not be written to disk immediately, but will be written every 30 seconds or 512 operations.
Calling this method can cause the cookie to be written to disk immediately.

55
docs/api/safe-storage.md
View File

@@ -7,21 +7,44 @@ Process: [Main](../glossary.md#main-process)
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](https://support.apple.com/en-ca/guide/keychain-access/kyca1083/mac) 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](https://learn.microsoft.com/en-us/windows/win32/api/dpapi/nf-dpapi-cryptprotectdata).
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
* **Windows**: Encryption keys are generated via [DPAPI](https://learn.microsoft.com/en-us/windows/win32/api/dpapi/nf-dpapi-cryptprotectdata). 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`, `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 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 Mac, access to the system Keychain is required and
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](https://developer.apple.com/documentation/security/keychain-items). 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](https://learn.microsoft.com/en-us/windows/win32/api/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`](https://flatpak.github.io/xdg-desktop-portal/docs/doc-org.freedesktop.portal.Secret.html): 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](https://specifications.freedesktop.org/secret-service/latest/): 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:
@@ -34,6 +57,10 @@ On Linux, returns true if the app has emitted the `ready` event and the secret k
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>` - Whether encryption is available for asynchronous safeStorage operations.
### `safeStorage.encryptString(plainText)`
* `plainText` string
@@ -49,7 +76,21 @@ This function will throw an error if encryption fails.
Returns `string` - the decrypted string. Decrypts the encrypted buffer
obtained with `safeStorage.encryptString` back into a string.
This function will throw an error if decryption fails.
### `safeStorage.encryptStringAsync(plainText)`
* `plainText` string
Returns `Promise<Buffer>` - An array of bytes representing the encrypted string.
### `safeStorage.decryptStringAsync(encrypted)`
* `encrypted` Buffer
Returns `Promise<Object>` - Resolve with an object containing the following:
* `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)`