メインコンテンツへ飛ぶ

safeStorage

文字列をローカルマシンに保管するにあたって簡単な暗号化と復号へのアクセスを可能にします。

プロセス: メイン

このモジュールは、OS 提供の暗号システムを使用して、ディスクの保存データにさらなる保護を追加します。 各プラットフォームの現在のセキュリティセマンティクスの概要を以下に示します。

[!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: 暗号化鍵は、ユーザーの許可なしに他のアプリケーションが読み込めないように キーチェーンアクセス にてアプリ用に保存されます。 したがって、コンテンツは同じユーザー空間で実行されている他のユーザーや他のアプリから保護されます。
  • Windows: 暗号化鍵は 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". したがって、コンテンツは同じマシン上の他のユーザーから保護されますが、同じユーザー空間で実行されている他のアプリからは保護されません。
  • Linux: 暗号化鍵は、ウインドウマネージャーとシステム設定に応じて異なるシークレットのストアで生成され、保存されます。 現在サポートされているオプションは kwallet、kwallet5、kwallet6、gnome-libsecret ですが、Electron の将来のバージョンではさらに多くのオプションが利用可能になる可能性があります。 そのため、safeStorage API を介して保護されたコンテンツのセキュリティセマンティクスは、ウインドウマネージャーとシークレットのストアによって異なります。
    • 注意として、すべての Linux セットアップでシークレットのストアが利用できるわけではありません。 If no secret store is available, items stored in using the safeStorage API will be unprotected as they are encrypted via hardcoded plaintext password. これは safeStorage.getSelectedStorageBackend() が 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. パスワード管理ツールが利用可能な場合、Linux でも同じことが言えます。

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

イベント​

safeStorage モジュールは以下のイベントが発生します。

メソッド​

safeStorage モジュールには以下のメソッドがあります。

safeStorage.isEncryptionAvailable()​

戻り値 boolean - 暗号化が利用可能かどうか。

Linux では、app で ready イベントが発生し、かつ秘密鍵が利用可能である場合は true を返します。 MacOS では、キーチェーンが利用可能な場合は true を返します。 Windows では、アプリで ready イベントが発生した以降は true を返します。

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

戻り値 Buffer - 暗号化した文字列を表すバイトの配列。

この関数は、暗号化に失敗するとエラーを送出します。

safeStorage.decryptString(encrypted)​

  • encrypted Buffer

戻り値 string - 復号した文字列。 safeStorage.encryptString で得た暗号化されたバッファを、文字列に復号します。

safeStorage.encryptStringAsync(plainText)​

  • plainText string

戻り値 Promise<Buffer> - 暗号化した文字列を表すバイトの配列。

safeStorage.decryptStringAsync(encrypted)​

  • encrypted Buffer

戻り値 Promise<Object> - 以下を含むオブジェクトで実行されます。

  • 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

Linux でのこの関数は、現在のアクティブなデスクトップ環境に対して有効な OS のパスワードマネージャーを決定できない場合、モジュールがインメモリのパスワードを使って暗号化/復号関数で使用する共通鍵を作成させます。 この関数は Windows と macOS では何もしません。

safeStorage.getSelectedStorageBackend() Linux​

戻り値 string - Linux で選択されたパスワードマネージャーのユーザーフレンドリーな名前。

この関数は以下のいずれかの値を返します。

  • 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 イベントを発行する前に関数が呼び出されたとき。