diff options
Diffstat (limited to 'src/content/docs/advanced')
| -rw-r--r-- | src/content/docs/advanced/gnupg-controller.md | 140 | ||||
| -rw-r--r-- | src/content/docs/advanced/key-database.md | 124 | ||||
| -rw-r--r-- | src/content/docs/advanced/module-controller.md | 214 |
3 files changed, 478 insertions, 0 deletions
diff --git a/src/content/docs/advanced/gnupg-controller.md b/src/content/docs/advanced/gnupg-controller.md new file mode 100644 index 0000000..70b5d29 --- /dev/null +++ b/src/content/docs/advanced/gnupg-controller.md @@ -0,0 +1,140 @@ +--- +title: A Comprehensive Guide of GpgController +sidebar: + label: Gpg Controller +--- + +The **GpgController** in **GpgFrontend** is a powerful tool for configuring and +managing GPG-related settings. It provides advanced options for file operations, +password input methods, and custom GPG configurations, catering to both general +and advanced users. + +## Accessing the GpgController + +To access the **GpgController**: + +1. Navigate to the **Advanced** menu in the top toolbar. +2. Select **Open GnuPG Controller** from the dropdown menu. + +  + +The **GpgController** interface includes three tabs: **General**, **Key +Database**, and **Advanced**. Below is a detailed explanation of each tab's +features. + +## General Tab: Core Settings + +The **General** tab provides essential configuration options for GpgFrontend's interaction with GPG. + + + +### Available Options + +1. **Use Binary Mode for File Operations** + + - This option determines the format used for encrypted or signed files: + - **Binary Mode**: Produces compact and efficient files, ideal for storage + and processing. + - **ASCII Mode**: Generates human-readable files encoded in ASCII format. + This is useful for sharing files over email or systems that might corrupt + binary files. + - **Recommendation**: Use binary mode for local file operations and ASCII + mode for file sharing or email attachments. + +2. **Use Pinentry as Password Input Dialog** + + - GpgFrontend includes a built-in password input dialog designed as a + temporary fallback when no external **Pinentry** program is available. + However, the built-in dialog has limitations and may not work for all + password input scenarios. + - **Recommendation**: Users are strongly encouraged to install a + full-featured **Pinentry** program to ensure a seamless and secure password + input experience. **Pinentry** is optimized for GnuPG's requirements and + provides additional features such as better passphrase caching and hardware + token support. + +3. **Enable GpgME Debug Log** + + - Enables verbose logging for troubleshooting GPG operations via the + **GpgME** library. This is useful for advanced users diagnosing issues in + encryption or signing workflows. + +4. **Restart Gpg Agent on Start** + + - Ensures that the GPG agent is restarted whenever GpgFrontend launches. This + helps avoid issues caused by stale GPG agent processes. + +5. **Kill All GPG Daemons at Close** + + - Terminates all GPG-related background processes when the application exits. + This ensures that no sensitive information is cached in memory or + accessible after the session ends. + - **Recommendation**: Always enable this option for improved security. + + > **Note**: Changes to any settings in the General tab will require + > restarting GpgFrontend to take effect. + +--- + +## Key Database Tab: Overview + +The **Key Database** tab allows users to manage multiple key databases. While +detailed documentation is available elsewhere, note the following key points: + +- **Add New Key Database**: Easily create and manage isolated key databases for + different projects or security requirements. +- **Switch Between Databases**: Use the **Key Toolbox** dropdown in the main + interface to select the active database. + +  + + > For more information on key database management, refer to the dedicated + > documentation. + +--- + +## Advanced Tab: Custom GnuPG Configuration + +The **Advanced** tab is designed for users who need to configure custom GPG installations. + + + +### Configuring Custom GnuPG + +1. **Enable Custom GnuPG** + + - Check the **Use Custom GnuPG** box to enable this feature. + +2. **Specify GPG Configuration Path** + + - Use the **Select GnuPG Path** button to locate and set the directory where + `gpgconf` resides. This is critical because GpgFrontend relies on the paths + provided by `gpgconf` to locate essential components like `gpg`, `gpgsm`, + and `gpg-agent`. + +3. **Verifying Custom Configuration** + + - After setting the path, you can test the configuration by running `gpgconf +--list-components` in a terminal. This command lists all available GPG + components and their paths, ensuring that GpgFrontend can access them + correctly. + +  + + > **Note**: If `gpgconf` is not configured correctly, GpgFrontend may fail to + > locate and execute necessary GPG binaries. + +--- + +## Tips for Using GpgController Effectively + +1. **Choose File Formats Wisely** + + - Use **Binary Mode** for efficiency in local operations and **ASCII Mode** + for readability and compatibility in file sharing. + +2. **Install a Full-Featured Pinentry** + + - Avoid relying on GpgFrontend's built-in password dialog for critical + operations. Installing **Pinentry** ensures better compatibility and + security. diff --git a/src/content/docs/advanced/key-database.md b/src/content/docs/advanced/key-database.md new file mode 100644 index 0000000..44bb2ed --- /dev/null +++ b/src/content/docs/advanced/key-database.md @@ -0,0 +1,124 @@ +--- +title: Multi-Key Database Support +sidebar: + label: Multi-Key Database +--- + +GpgFrontend introduces **Multi-Key Database Support**, providing users with a +flexible and organized way to manage multiple key databases. This feature is +ideal for users who require separate cryptographic environments for different +projects, organizations, or levels of security. + +## Features and Benefits + +### Key Features + +1. **Multiple Key Databases**: Manage distinct key databases for specific + purposes or contexts. +2. **Flexible Switching**: Easily switch between databases for different + operations without affecting other configurations. +3. **Customizable Management**: Add, edit, reorder, or remove databases as + needed. + +### Benefits + +- **Improved Security**: Isolate sensitive keys in dedicated databases to + minimize exposure. +- **Enhanced Organization**: Maintain separate databases for better operational + clarity. +- **Streamlined Workflows**: Quickly switch between databases for various + projects or encryption tasks. + +## Accessing the Multi-Key Database Feature + +### Opening the GnuPG Controller + +To manage multiple key databases, follow these steps: + +1. **Access the Advanced Menu** + + - Click on the **Advanced** menu in the top navigation bar. + - Select **Open GnuPG Controller** from the dropdown options. + +  + +2. **Navigate to the Key Database Tab** + + - In the **GnuPG Controller** window, switch to the **Key Database** tab. + - Here, you will find a list of all configured key databases. + +  + +## Managing Key Databases + +The **Key Database** tab allows you to perform the following operations: + +### 1. Adding a New Key Database + +- Click the **Add New Key Database** button. +- Specify a name and path for the new database. This will create an isolated + environment for new keys. + +### 2. Editing and Reordering Key Databases + +- Right-click on a database entry to view options like: + - **Move Up/Move Down**: Reorder the database list. + - **Move to Top**: Prioritize a database by moving it to the top. + - **Edit**: Rename or modify the path of an existing database. + - **Remove**: Delete a database from the configuration. + + + +> **Note**: Any changes to the key database settings will require an application +> restart to take effect. + +### 3. Switching Between Databases + +- Use the **Key Toolbox** dropdown in the main interface to switch between + configured databases. +- Select the desired database, and the corresponding keys will be displayed. + + + +## Use Cases for Multi-Key Databases + +1. **Project Isolation** + + - Maintain separate databases for different projects to avoid accidental + cross-use of keys. + +2. **Organizational Separation** + + - Keep departmental or team-specific keys isolated to ensure they are only + accessible to authorized personnel. + +3. **Enhanced Security for Sensitive Keys** + - Store high-security keys in a dedicated database, minimizing the risk of + exposure during routine operations. + +## Tips for Effective Multi-Key Database Usage + +1. **Name Databases Clearly** + + - Use descriptive names for each database to make it easier to identify their + purpose. + +2. **Regular Backups** + + - Backup each database regularly to prevent loss of critical keys. Store + backups in secure, encrypted locations. + +3. **Audit Database Usage** + + - Periodically review the contents and usage of each database to ensure + proper organization and security. + +4. **Isolate Sensitive Operations** + + - For highly sensitive keys, consider using a dedicated device or environment + to manage their database. + +5. **Avoid Overloading Databases** + + - Distribute keys evenly across multiple databases instead of overloading a + single one. This enhances performance and organization. diff --git a/src/content/docs/advanced/module-controller.md b/src/content/docs/advanced/module-controller.md new file mode 100644 index 0000000..7f5dfaa --- /dev/null +++ b/src/content/docs/advanced/module-controller.md @@ -0,0 +1,214 @@ +--- +title: "Module Controller: Extending GpgFrontend Functionality" +sidebar: + label: Module Controller +--- + +The **Module Controller** in **GpgFrontend** allows users to manage modular +extensions that enhance the core functionality of the application. These modules +provide features such as email integration, version checking, and key +synchronization, offering flexibility for different workflows. + +This guide provides an overview of the **Module Controller** interface, +instructions for managing modules, and guidance for advanced users interested in +developing custom modules. + +--- + +## Accessing the Module Controller + +To access the **Module Controller**: + +1. Open the **Advanced** menu in the top toolbar. +2. Select **Open Module Controller**. + +  + +The **Module Controller** interface consists of the following tabs: + +- **Registered Modules** +- **Global Register Table** + +--- + +## Registered Modules Tab + +The **Registered Modules** tab displays all available modules and provides tools +for managing their activation, metadata, and storage. + +### Key Features + +1. **Module List** + + - The left panel lists all currently available modules. + - Modules prefixed with `*` are **Integrated Modules**, meaning they are + bundled with the GpgFrontend application. + +2. **Module Information** + + - When a module is selected, detailed metadata is displayed in the right + panel, including: + + - **ID**: The unique identifier of the module. + - **Version**: The current module version. + - **SDK Version**: The version of the SDK required by the module. + - **Path**: The physical location of the module file. + - **Activation Status**: Indicates whether the module is active or set to + auto-activate. + + Example: + + ``` + - ID: com.bktus.gpgfrontend.module.email + - Version: 1.0.0 + - SDK Version: 2.1.5 + - Path: /path/to/module/file + - Auto Activate: True + - Active: True + ``` + +  + +3. **Module Actions** + + - **Deactivate**: Temporarily disables the selected module. + - **Disable Auto Activate**: Prevents the module from loading automatically + when GpgFrontend starts. + +4. **Show Mods Directory** + + - Opens the directory where external modules are stored. Users can manually + add or remove custom modules by placing or deleting files in this + directory. + + > **Tip for Integrated Modules**: + + - **Windows/Mac Users**: Integrated Modules (prefixed with `*`) can be + removed by deleting the corresponding `.dll` (Windows) or `.dylib` (Mac) + file from the `modules` directory. + - **Linux Users**: Due to the nature of **AppImage** and **Flatpak** + packages, removing Integrated Modules may require recompiling and + repackaging the application. + +## Global Register Table Tab + +The **Global Register Table** provides a detailed view of the internal data +structure used by GpgFrontend and its modules. This table is primarily useful +for developers and advanced users who want to debug or inspect module +interactions with the core application. + +### Key Features + +1. **Key-Value Data** + + - Displays the hierarchical structure of global variables, including: + - Module-specific settings (e.g., version checking, state tracking). + - GnuPG paths and environment configurations. + - Example: + ``` + gpgme: + ctx: + app_path: /opt/homebrew/Cellar/gnupg/2.4.5_1/bin/gpg + gnupg_version: 2.4.5 + gpgconf_path: /opt/homebrew/bin/gpgconf + ``` + +2. **Navigation** + + - Expand nodes to explore detailed properties for modules or core components. + +  + +## Developing Custom Modules + +The **Module Controller** supports custom modules, allowing developers to extend +GpgFrontend's functionality for specialized use cases. All modules adhere to a +strict **C ABI (Application Binary Interface)** and are dynamically linked to +the `libgpgfrontend_sdk` library. + +### Key Points for Developers + +1. **C ABI Compliance** + + - Modules must be implemented using the C ABI to ensure compatibility across + all supported platforms (Windows, macOS, Linux). + +2. **Dynamic SDK Linking** + + - Modules interact with GpgFrontend by linking dynamically to the + **libgpgfrontend_sdk** library. This library provides the necessary + interfaces for module initialization, data exchange, and runtime + interaction. + +3. **SDK Limitations** + + - The current SDK API is still under development and may not cover all + potential use cases. Developers are encouraged to contact the project + maintainer for guidance or feature requests. + +4. **Getting Started** + - Place the compiled module file (`.dll`, `.dylib`, or `.so`) in the + `modules` directory. Use the **Show Mods Directory** button to locate this + directory. + +--- + +## Tips for Managing Modules + +1. **Backup Before Changes** + + - Always create a backup of the `modules` directory before making changes, + especially when adding or removing modules. + +2. **Regular Updates** + + - Check for updates to both GpgFrontend and its modules to ensure + compatibility and access to the latest features. + +3. **Safe Removal** + + - Follow the guidelines for deleting Integrated Modules based on your + platform to avoid accidental issues. + +4. **Use Global Register Table for Debugging** + - Advanced users can verify module configurations and GPG environment paths + through the **Global Register Table**. + +--- + +## Example Module: Version Checking + +The **VersionChecking** module is a bundled example of how GpgFrontend uses +modules to provide additional functionality. + +### Features: + +- Checks the current application version. +- Displays release notes for new updates. +- Notifies users when an upgrade is available. + +### Example Metadata: + +``` +- ID: com.bktus.gpgfrontend.module.version_checking +- Version: 1.0.0 +- Auto Activate: True +``` + +### Global Register Table: + +``` +com.bktus.gpgfrontend.module.version_checking: + current_version: v2.1.5 + need_upgrade: false + latest_version: v2.1.5 +``` + +--- + +By leveraging the **Module Controller**, users can customize and extend +GpgFrontend to suit their needs. Developers interested in creating new modules +are encouraged to experiment with the SDK and collaborate with the maintainer +for additional API support. For more details, visit the [GpgFrontend Modules +GitHub +Repository](https://github.com/saturneric/GpgFrontend-Modules/blob/main/README.md). |