Skip to main content

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.

  • 苹果系统：加密密钥以一种防止其他应用在未经用户覆盖的情况下加载它们的方式存储在 密钥串访问 中。因此，内容受到保护，不会被其他用户和在同一用户空间中运行的其他应用访问。

    ¥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：加密密钥通过 DPAPI 生成。根据 Windows 文档："通常，只有拥有与加密数据的用户相同登录凭据的用户才能解密数据"。因此，内容受到保护，不会被同一台机器上的其他用户访问，但不会被在同一用户空间中运行的其他应用访问。

    ¥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：加密密钥生成并存储在秘密存储中，具体取决于你的窗口管理器和系统设置。当前支持的选项有 kwallet、kwallet5、kwallet6 和 gnome-libsecret，但未来版本的 Electron 中可能会提供更多选项。因此，通过 safeStorage API 保护的内容的安全语义在窗口管理器和秘密存储之间有所不同。

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

    • 请注意，并非所有 Linux 设置都有可用的秘密存储。如果没有可用的秘密存储，则使用 safeStorage API 存储的项目将不受保护，因为它们是通过硬编码的纯文本密码加密的。当 safeStorage.getSelectedStorageBackend() 返回 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.

请注意，在 Mac 上，需要访问系统密钥串，并且这些调用可能会阻止当前线程来收集用户输入。如果有密码管理工具可用，Linux 也是如此。

¥Note that on Mac, 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.

方法​

¥Methods

safeStorage 模块有以下方法：

¥The safeStorage module has the following methods:

safeStorage.isEncryptionAvailable()​

返回 boolean - 是否可以加密。

¥Returns boolean - Whether encryption is available.

在 Linux 上，如果应用已发出 ready 事件并且密钥可用，则返回 true。在 MacOS 上，如果密钥串可用，则返回 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.encryptString(plainText)​

  • plainText 字符串

    ¥plainText string

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

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

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

¥This function will throw an error if encryption fails.

safeStorage.decryptString(encrypted)​

  • encrypted 缓冲

    ¥encrypted Buffer

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

¥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.setUsePlainTextEncryption(usePlainText)​

  • usePlainText 布尔值

    ¥usePlainText boolean

当无法确定当前活动桌面环境的有效操作系统密码管理器时，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"。

    ¥basic_text - When the desktop environment is not recognised or if the following command line flag is provided --password-store="basic".

  • gnome_libsecret - 当桌面环境为 X-Cinnamon、Deepin、GNOME、Pantheon、XFCE、UKUI、unity 或提供以下命令行标志时 --password-store="gnome-libsecret"。

    ¥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 - 当桌面会话为 kde4 或提供以下命令行标志时为 --password-store="kwallet"。

    ¥kwallet - When the desktop session is kde4 or if the following command line flag is provided --password-store="kwallet".

  • kwallet5 - 当桌面会话为 kde5 或提供以下命令行标志时为 --password-store="kwallet5"。

    ¥kwallet5 - When the desktop session is kde5 or if the following command line flag is provided --password-store="kwallet5".

  • kwallet6 - 当桌面会话为 kde6 时。

    ¥kwallet6 - When the desktop session is kde6.

  • unknown - 在应用发出 ready 事件之前调用该函数时。

    ¥unknown - When the function is called before app has emitted the ready event.