Skip to main content

safeStorage

允许访问简单的字符串加密和解密，以便在本地机器上存储。

进程：主进程

🌐 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

我们建议使用异步 API（encryptStringAsync/decryptStringAsync）而不是同步 API。 异步 API 是非阻塞的，支持密钥轮换，并能优雅地处理临时不可用情况。 同步 API 可能在将来的 Electron 版本中被弃用。

特定平台密钥提供者​

🌐 Platform-Specific Key Providers

同步 API​

🌐 Synchronous API

  • macOS：加密密钥会以一种防止其他应用在未经用户授权的情况下加载它们的方式，存储在你的应用的 钥匙串访问 中。因此，内容可以防止同一用户空间中的其他用户和其他应用访问。
  • Windows：加密密钥是通过 DPAPI 生成的。根据 Windows 文档：“通常，只有与加密数据的用户具有相同登录凭据的用户才能解密数据”。因此，内容可以防止同一台计算机上的其他用户访问，但无法防止在同一用户空间运行的其他应用访问。
  • Linux：加密密钥会生成并存储在一个秘密存储中，该存储取决于你的窗口管理器和系统设置。目前支持的选项有 kwallet、kwallet5、kwallet6 和 gnome-libsecret，但未来 Electron 版本中可能会提供更多选项。因此，通过 safeStorage API 保护的内容的安全语义在不同的窗口管理器和秘密存储之间有所不同。
    • 请注意，并非所有 Linux 系统都具有可用的密钥存储。如果没有可用的密钥存储，使用 safeStorage API 存储的项目将不受保护，因为它们是通过硬编码的明文密码加密的。当 safeStorage.getSelectedStorageBackend() 返回 basic_text 时，你可以检测到这种情况。

请注意，在 macOS 上，需要访问系统钥匙串，并且这些调用可能会阻塞当前线程以收集用户输入。对于 Linux，如果有密码管理工具可用，也同样适用。

🌐 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.

异步 API​

🌐 Asynchronous API

异步 API 使用插件化的密钥提供程序，具体取决于平台：

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

  • macOS：加密密钥存储并从 钥匙串访问 中检索。这提供与同步 API 相同的安全模型，保护内容免受同一用户空间中其他用户和其他应用的访问。
  • Windows：加密密钥通过 DPAPI 进行保护。这提供了与同步 API 相同的安全模型，可以防止同一台机器上的其他用户访问内容，但无法防止在同一用户空间中运行的其他应用访问内容。
  • Linux：根据桌面环境，可能有多个密钥提供者可用：
    • org.freedesktop.portal.Secret：使用 Portal Secret D-Bus 接口来检索应用特定的秘密。这是像 Flatpak 这样的沙盒环境的首选提供者。
    • Secret Service API：使用 freedesktop.org Secret Service API（例如，GNOME Keyring）进行密钥存储。
    • 回退提供者用于没有可用秘密服务的环境。

与同步 API 不同，这些操作是非阻塞的，并支持额外功能，如密钥轮换（由 shouldReEncrypt 表示）和临时不可用处理（由 isTemporarilyUnavailable 表示）。

🌐 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

safeStorage 模块会触发以下事件：

🌐 The safeStorage module emits the following events:

方法​

🌐 Methods

safeStorage 模块具有以下方法：

🌐 The safeStorage module has the following methods:

safeStorage.isEncryptionAvailable()​

返回 boolean - 是否可用加密。

🌐 Returns boolean - Whether encryption is available.

在 Linux 上，如果应用已触发 ready 事件并且密钥可用，则返回 true。 在 MacOS 上，如果 Keychain 可用，则返回 true。 在 Windows 上，一旦应用触发 ready 事件，则返回 true。

🌐 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()​

返回 Promise<Boolean> - 异步安全存储操作是否可用加密。

🌐 Returns Promise<Boolean> - Whether encryption is available for asynchronous safeStorage operations.

safeStorage.encryptString(plainText)​

  • plainText 字符串

返回 Buffer - 一个表示加密字符串的字节数组。

🌐 Returns Buffer - An array of bytes representing the encrypted string.

如果加密失败，此函数将抛出错误。

🌐 This function will throw an error if encryption fails.

safeStorage.decryptString(encrypted)​

  • encrypted 缓冲区

返回 string - 解密后的字符串。将使用 safeStorage.encryptString 获得的加密缓冲区解密回字符串。

🌐 Returns string - the decrypted string. Decrypts the encrypted buffer obtained with safeStorage.encryptString back into a string.

safeStorage.encryptStringAsync(plainText)​

  • plainText 字符串

返回 Promise<Buffer> - 表示加密字符串的字节数组。

🌐 Returns Promise<Buffer> - An array of bytes representing the encrypted string.

safeStorage.decryptStringAsync(encrypted)​

  • encrypted 缓冲区

返回 Promise<Object> - 解析为包含以下内容的对象：

🌐 Returns Promise<Object> - Resolve with an object containing the following:

  • shouldReEncrypt boolean - 是否刚从解密操作返回的数据应该重新加密，因为密钥已经轮换或有一个新的密钥可用，提供不同的安全级别。如果是 true，你应该再次调用 decryptStringAsync 来接收新的解密字符串。
  • result string - 解密后的字符串。

safeStorage.setUsePlainTextEncryption(usePlainText)​

  • usePlainText 布尔值

在 Linux 上，此功能将强制模块使用内存中的密码来创建对称密钥，该密钥用于加密/解密功能，当无法为当前活动桌面环境确定有效的操作系统密码管理器时使用。在 Windows 和 MacOS 上，此功能无操作效果。

🌐 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​

返回 string - 在 Linux 上选择的密码管理器的用户友好名称。

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

该函数将返回以下值之一：

🌐 This function will return one of the following values:

  • basic_text - 当桌面环境未被识别或提供以下命令行标志 --password-store="basic" 时。
  • gnome_libsecret - 当桌面环境是 X-Cinnamon、Deepin、GNOME、Pantheon、XFCE、UKUI、unity 时，或者提供了以下命令行参数 --password-store="gnome-libsecret"。
  • kwallet - 当桌面会话为 kde4 时，或提供以下命令行参数时 --password-store="kwallet"。
  • kwallet5 - 当桌面会话为 kde5 或提供以下命令行标志 --password-store="kwallet5" 时。
  • kwallet6 - 当桌面会话为 kde6 或者提供了以下命令行参数 --password-store="kwallet6" 时。
  • unknown - 当函数在应用发出 ready 事件之前被调用时。