diff options
Diffstat (limited to '')
| -rw-r--r-- | src/content/docs/guides/email-operations.md | 46 | ||||
| -rw-r--r-- | src/content/docs/guides/file-operations.md | 54 | ||||
| -rw-r--r-- | src/content/docs/guides/fundamental-concepts.md | 54 | ||||
| -rw-r--r-- | src/content/docs/guides/generate-use-subkey.md | 133 | ||||
| -rw-r--r-- | src/content/docs/guides/key-group.md | 109 | ||||
| -rw-r--r-- | src/content/docs/guides/smart-card.md | 141 | ||||
| -rw-r--r-- | src/content/docs/guides/understand-interface.md | 131 |
7 files changed, 547 insertions, 121 deletions
diff --git a/src/content/docs/guides/email-operations.md b/src/content/docs/guides/email-operations.md index b632157..858ba27 100644 --- a/src/content/docs/guides/email-operations.md +++ b/src/content/docs/guides/email-operations.md @@ -11,7 +11,7 @@ protocols while maintaining robust OpenPGP compliance. Whether you're signing, encrypting, verifying, or decrypting emails, GpgFrontend ensures a secure and streamlined experience. -## **Purpose and Key Advantages** +## Purpose and Key Advantages GpgFrontend's email processing functionality is designed to empower users to handle PGP-signed and encrypted emails in situations where their email clients @@ -28,9 +28,9 @@ include: offline, local-first solution that minimizes exposure to online threats and untrusted environments. -## **Features Overview** +## Features Overview -### **1. OpenPGP Standards Compliance** +### OpenPGP Standards Compliance GpgFrontend adheres to OpenPGP standards (RFC 4880 and 3156) for email encryption and signing, ensuring compatibility with tools like Thunderbird and @@ -46,9 +46,9 @@ other OpenPGP-enabled clients. - **Decrypt and Verify Together or Separately**: Flexibly handle incoming messages. -### **2. Creating and Processing Emails** +### Creating and Processing Emails -#### **Creating and Signing Emails** +#### Creating and Signing Emails 1. Open GpgFrontend and click **"New E-Mail"** to create a blank email. @@ -61,7 +61,7 @@ other OpenPGP-enabled clients.  -#### **Encrypting Emails** +#### Encrypting Emails 1. Select the recipient's public key in the **Key Toolbox**. 2. Click **"Encrypt"** to secure the email content. @@ -69,15 +69,15 @@ other OpenPGP-enabled clients.  -#### **Saving Emails for Sending** +#### Saving Emails for Sending 1. Processed emails can be saved as `.eml` files using **File > Save As**. 2. Upload the `.eml` file to your email client's drafts folder or webmail interface, then send the email. -### **3. Receiving and Processing Emails** +### Receiving and Processing Emails -#### **Decrypting and Verifying Emails** +#### Decrypting and Verifying Emails 1. Export the email source as an `.eml` file from your email client or copy the raw email source. @@ -86,48 +86,48 @@ other OpenPGP-enabled clients. - **"Decrypt Verify"**: Decrypt and verify the email simultaneously. - **"Verify"**: Validate the signature without decrypting. - **"Decrypt"**: Decrypt without verifying. - +  -#### **Offline Validation** +#### Offline Validation - GpgFrontend processes all email verification and decryption offline, ensuring that no sensitive data is exposed to external servers. - Users retain full control of their private keys, which remain stored locally. -### **4. Why Use EML Format?** +### Why Use EML Format? -#### **Benefits of EML** +#### Benefits of EML - `.eml` is a widely supported format across email clients like Thunderbird, Outlook, and webmail platforms. - Unlike proprietary email handling protocols, `.eml` allows for seamless export, import, and offline processing. -#### **Why Not Use IMAP/SMTP?** +#### Why Not Use IMAP/SMTP? - Avoids the complexity and potential vulnerabilities introduced by integrating full-fledged email protocols. - Keeps the application lightweight and focused on local cryptographic operations. -#### **Addressing PGP Limitations in Clients** +#### Addressing PGP Limitations in Clients - Many email clients lack robust PGP support or offer inconsistent implementations. - GpgFrontend provides a reliable and flexible solution for users needing advanced PGP functionality. -## **Key Use Cases** +## Key Use Cases -### **1. Sending Emails** +### Sending Emails 1. Process the email in GpgFrontend (e.g., sign, encrypt, or both). 2. Save the processed email as an `.eml` file. 3. Import the `.eml` file into your email client or webmail interface, then send it. -### **2. Receiving Emails** +### Receiving Emails 1. Export the email source as `.eml` from your email client. 2. Open it in GpgFrontend to decrypt or verify. @@ -135,27 +135,27 @@ other OpenPGP-enabled clients. - A signed email will display a **"Good Digital Signature"** message. - An encrypted email will be decrypted and displayed in plaintext. -## **Advanced Features** +## Advanced Features -### **1. Combined Operations** +### Combined Operations - GpgFrontend supports simultaneous encryption and signing of outgoing emails. - Incoming emails can also be decrypted and verified in a single operation for convenience. -### **2. Flexible Processing** +### Flexible Processing - Choose separate or combined workflows for signing, encrypting, verifying, or decrypting based on your needs. - This flexibility makes GpgFrontend a versatile tool for various email scenarios. -### **3. Offline-First Design** +### Offline-First Design - All cryptographic operations are performed locally, ensuring that private keys and sensitive data are never exposed to external servers. -## **Best Practices for Secure Email Handling** +## Best Practices for Secure Email Handling 1. **Use Trusted Keys**: diff --git a/src/content/docs/guides/file-operations.md b/src/content/docs/guides/file-operations.md index 40d7189..6b25cce 100644 --- a/src/content/docs/guides/file-operations.md +++ b/src/content/docs/guides/file-operations.md @@ -8,17 +8,43 @@ GpgFrontend offers a fast and convenient method for working with files. The processes of encryption, decryption, signing, and verifying files are similar to text-based operations but involve binary input and output. -## Using File Panel for Encryption, Decryption, Signing, and Verifying +## Quick File Operations via Direct Selection + +GpgFrontend enables you to quickly process any file or directory directly from +the main interface, streamlining your workflow for secure file handling. + +1. Direct File Selection: In the main window, click the Open button and choose + either Open File or Open Directory from the drop-down menu. +2. In the system dialog, select the file (e.g., CCC.eml) or directory you want + to process. +3. Automatic File Panel Activation: If you select a file, the File Panel will + automatically open, with the chosen file highlighted and ready for operation. + If you select a directory, the File Panel opens showing the entire directory + contents, allowing you to browse and select one or more files for further + action. +4. Proceed with Cryptographic Operations: With the File Panel open, you can now + select one or more keys from the Key ToolBox (individual public keys or key + groups). Then, you can click the appropriate toolbar button—Encrypt, Decrypt, + Sign, or Verify—to perform the desired cryptographic operation on the + selected file(s). + + + +## Using File Panel Directly After clicking the **File Panel** button, a system directory selection dialog will appear. Follow these steps to perform various cryptographic operations: -1. Open File Panel: Click the **File Panel** button in the toolbar at the top of the interface. This will open a system dialog allowing you to choose a directory. -2. Select Directory: In the system dialog, navigate to the desired directory and select it. Once - selected, a new tab named "File Panel" will open in GpgFrontend, displaying - the contents of the chosen directory. -3. Select a File: In the File Panel tab, click on the file you want to encrypt, decrypt, sign, - or verify. +1. Open File Panel: Click the **File Panel** button in the toolbar at the top of + the interface. This will open a system dialog allowing you to choose a + directory. +2. Select Directory: In the system dialog, navigate to the desired directory and + select it. Once selected, a new tab named "File Panel" will open in + GpgFrontend, displaying the contents of the chosen directory. +3. Select a File: In the File Panel tab, click on the file you want to encrypt, + decrypt, sign, or verify. + + ### 4. File Operations (Encrypt, Decrypt, Sign, Verify) @@ -41,10 +67,12 @@ Understanding the appropriate file extensions helps in managing encrypted and signed files properly. Here’s a breakdown of the file extensions used: ### ASCII Format + - **.asc**: ASCII-armored files. Can contain encrypted data or signatures in a text-compatible format. ### Binary Format + - **.gpg**: Binary encrypted files or combined encrypted and signed files. More efficient for storage and transmission. - **.sig**: Binary signature files used exclusively for signature operations. @@ -61,11 +89,11 @@ settings. To change the output mode between ASCII and binary formats: 1. Open Settings: Navigate to the GnuPG Controller settings within GpgFrontend by accessing - the settings menu. -2. Locate Binary Mode Option: In the settings interface, under the "General" section, find the option - labeled "Use Binary Mode for File Operations". -3. Toggle Binary Mode: Check or uncheck this option to switch between binary (gpg/sig) and ASCII - (asc) output formats. + the settings menu. +2. Locate Binary Mode Option: In the settings interface, under the "General" + section, find the option labeled "Use Binary Mode for File Operations". +3. Toggle Binary Mode: Check or uncheck this option to switch between binary + (gpg/sig) and ASCII (asc) output formats. This streamlined process allows you to manage file encryption, decryption, signing, and verification efficiently with GpgFrontend. @@ -123,6 +151,7 @@ directory contents while preserving their original structure. When a folder is selected for encryption, GpgFrontend automatically performs the following operations: + 1. Archiving: The folder is first archived using the tar utility, combining all files and subdirectories into a single .tar archive. 2. Encryption: The `.tar` archive is then encrypted using GnuPG, resulting in a @@ -139,6 +168,7 @@ transferable format. GpgFrontend also offers automatic extraction when decrypting `.tar.gpg` or `.tar.asc` files: + 1. Decryption: The selected encrypted archive is decrypted using GnuPG, producing the original `.tar` archive. 2. Extraction: If the decrypted content is a `.tar` archive, GpgFrontend diff --git a/src/content/docs/guides/fundamental-concepts.md b/src/content/docs/guides/fundamental-concepts.md index f1223b2..8c58a24 100644 --- a/src/content/docs/guides/fundamental-concepts.md +++ b/src/content/docs/guides/fundamental-concepts.md @@ -19,16 +19,16 @@ At the heart of GPG is the **key pair**: two mathematically linked keys. - **Public Key**: Share this with anyone. Others use it to: - Send you encrypted messages. - Verify your digital signature. - - **Private Key**: Keep this secret. You use it to: - Decrypt messages sent to you. - Sign data so others know it’s really from you. - :::tip[Think of it like a mailbox] + - Your public key is the address — people can send you letters. - Your private key is the key to open the mailbox — only you can read what’s inside. + ::: ## 🔧 Generating a Key Pair @@ -61,6 +61,7 @@ independently. ## 🧱 Understanding the Primary Key Your **primary key** is your core identity. It: + - Links to your user ID (usually name + email). - Signs your subkeys. - Can certify other people's public keys (used to build trust networks). @@ -86,6 +87,7 @@ Imagine you want to send a private message to someone: 4. They can **verify your signature** with your public key. This ensures: + - **Privacy**: No one but the intended recipient can read the message. - **Authenticity**: The recipient knows the message is from you. @@ -98,6 +100,7 @@ others to: - Confirm that **you** are the sender. Digital signatures are used to: + - Sign emails. - Sign files or software packages. - Sign other people's public keys (to build trust). @@ -107,6 +110,7 @@ Digital signatures are used to: ### Secure Email You want to email a sensitive document: + - Encrypt it using the recipient’s public key. - Sign it with your private key. - The recipient decrypts and verifies it. @@ -114,15 +118,50 @@ You want to email a sensitive document: ### Software Publishing You release a file or program online: + - You sign it. - Users can verify the signature before using it. ### Building Trust You meet someone at a conference: + - You exchange and sign each other’s keys. - Anyone who trusts your key may now also trust theirs. +## 🏷️ Public Key Certificates + +A public key in GPG/PGP is not just a raw cryptographic key. It is always +packaged as a certificate, which contains more than just the key itself. + +A public key certificate includes: + +- The public key data (for encryption and verifying signatures) +- The User ID (your name and email address) +- Signatures made by your own primary key and, optionally, by other people + +### Why Are Certificates Important? + +- Binding Identity: The certificate links your key to your identity, such as + your name and email. This way, people can verify that the key truly belongs to + you. +- Establishing Trust: Others can “sign” your public key, vouching for your + identity. This signature acts as a recommendation, forming a “Web of Trust.” +- Subkey Relationship: If you use subkeys (for encryption or signing), their + certificates include signatures from your primary key. This proves that each + subkey really belongs to your primary identity, and not to someone else. + +### Example + +When you share your public key, you are actually sharing a certificate that: + +- Includes your identity and any subkeys +- Shows cryptographic proof that the subkeys are authorized by your primary key +- May be signed by other people who trust your identity + +This is why you should always distribute your full public key certificate—not +just the bare key! + ## ✅ Best Practices for New Users 1. **Back Up Your Keys**: Store your private key and revocation certificate in a @@ -138,15 +177,6 @@ You meet someone at a conference: 6. **Understand the Web of Trust**: GPG builds trust by people signing each other's keys — this forms a decentralized trust model. -## 🧭 Summary - -GPG is a powerful tool for privacy and digital identity. By learning: -- How keys work, -- When to encrypt vs. sign, -- And how to protect your credentials, - -You’re taking a big step toward securing your digital life. - ## 🧰 Where Does GpgFrontend Fit In? While GPG/PGP itself is powerful, it is mostly command-line based — which can be @@ -175,4 +205,4 @@ GPG with simplicity and clarity. You focus on **secure communication** — let GpgFrontend handle the complexity behind it. -:::
\ No newline at end of file +::: diff --git a/src/content/docs/guides/generate-use-subkey.md b/src/content/docs/guides/generate-use-subkey.md index 186925d..d1af9be 100644 --- a/src/content/docs/guides/generate-use-subkey.md +++ b/src/content/docs/guides/generate-use-subkey.md @@ -15,30 +15,30 @@ There are **two entry points** to generate a subkey: ### Method 1: From Key Management -1. **Open Key Management** - - Navigate to the main **KeyPair Management** interface. - - Right-click on the key pair to which you want to add a subkey. - - Select **“New Subkey”** from the context menu. +1. Open Key Management +2. Navigate to the main **KeyPair Management** interface. +3. Right-click on the key pair to which you want to add a subkey. +4. Select **“New Subkey”** from the context menu. -  - + ### Method 2: From Key Details View -1. **Open Key Details** - - Double-click on the desired key pair in the **Key Management** list. - - Switch to the **Keychain** tab. - - Click the **“Generate A New Subkey”** button. +1. Open Key Details +2. Double-click on the desired key pair in the **Key Management** list. +3. Switch to the **Keychain** tab. +4. Click the **“Generate A New Subkey”** button. -  + ### Configuring the Subkey Once the subkey generation dialog appears, configure the following settings: - **Algorithm**: Choose the algorithm for the subkey. Options include: - - RSA, DSA - - ECC (e.g., ED25519, ED448, CV25519, SECP256K1, Brainpool, NIST curves, etc.) + + - RSA, DSA + - ECC (e.g., ED25519, ED448, CV25519, SECP256K1, Brainpool, NIST curves, etc.) - ECDH for encryption, EdDSA for signing, etc. - **Key Size**: Select the desired key size. This setting is available for most @@ -48,6 +48,7 @@ Once the subkey generation dialog appears, configure the following settings: allows configurable sizes like 2048, 3072, or 4096 bits. - **Expiration Date**: Set how long the subkey remains valid: + - Predefined periods (e.g., 1 year, 2 years) - Exact date/time - Or enable **“Non Expired”** for permanent validity. @@ -56,7 +57,7 @@ Once the subkey generation dialog appears, configure the following settings: - `Encrypt` - `Sign` - `Authenticate` - *(Certification usage is reserved for primary keys.)* + _(Certification usage is reserved for primary keys.)_ ### Final Step: Generate @@ -153,8 +154,7 @@ and successfully export a subkey: a location to save the exported subkey. Choose a secure directory and save the subkey as a separate file. - + ### Step-by-Step Guide to Importing Subkeys @@ -165,16 +165,14 @@ to navigate the GpgFrontend interface and successfully import a subkey: 1. **Select the Key Database**: Choose the appropriate key database from the **Key Toolbox**. - + 1. **Import the Subkey**: Click on the **Import Key** button in the top toolbar, and select **File** from the dropdown menu. This action will open a dialog where you can browse your system to locate the previously exported subkey file. -  +  2. **Select Subkey File**: Browse to the location where the subkey file is saved, select it, and click **Open**. This will import the subkey into the @@ -188,8 +186,7 @@ Database](https://image.cdn.bktus.com/i/2024/11/29/0e8ff19e-4189-65db-5732-1a2e7 4. **Handling Primary Key**:You can now move your master key to a safe place. Then delete it at GpgFrontend. -  +  ### Confirming Primary Key Absence @@ -199,8 +196,7 @@ for this subkey does not exist in the current key database. This is expected if you have securely removed the primary key to minimize exposure, while retaining the subkeys for ongoing operations. - + You can confirm the absence of the primary key by opening the **Key Details** view of the imported subkey. In the **Primary Key Existence** section, it should @@ -215,8 +211,7 @@ Existence** section in the Key Details view, which will display **Not Exists**. This setup is intentional in many cases to improve security by isolating the primary key. - + ### Actions Limited by the Absence of a Primary Key: @@ -244,20 +239,82 @@ primary key poses a security risk. By isolating the primary key and relying solely on subkeys, you can maintain a balance between functionality and security. - + + +## Common Misconceptions about Subkey + +When you export only a subkey and then import it into a different key database +(or application), you may notice that: + +- The key listing still shows the primary key’s ID as the main identifier. +- The keyring still displays the original key structure—including the primary + key and potentially other subkeys—though only the exported subkey is available + for actual use (decryption, signing, etc.). +- The usage flags (such as CESA: Certify, Encrypt, Sign, Authenticate) may + change—only capabilities for which the private part is present remain active. + +### Why is this the case? + +This is not a bug, but a fundamental part of how OpenPGP and GnuPG represent keys. + +### Key Structure: Public Context is Required + +Even if you export and import only a subkey’s secret part, you are actually +exporting and importing a full public key structure (a certificate) with only a +partial set of private components. + +- The public key block still contains the primary key’s information, all user + IDs, and all subkey definitions. +- The secret part of the primary key is absent, so you cannot certify, revoke, + or generate further subkeys. +- The exported file needs to include the primary key’s public information, + because the subkey’s trust depends on its certification by the primary key. + +:::tip[Analogy] + +Exporting a subkey is like sending only the content of a letter but still +including the envelope, address, and signature. You need all of these for the +recipient (the application) to know who sent it and to verify its authenticity. + +::: + +The primary key is the identity anchor for the whole key structure. Subkeys +derive their trust from the fact that the primary key certified them. If the +primary key’s public info and signatures are missing, the subkey would not be +recognized as legitimate or trustworthy by other OpenPGP tools. + +### Multiple Subkeys Included + +If the key structure contains other subkeys, their definitions will also be +present in the exported key material—even if their secret parts are missing. +This design ensures the integrity and context of the key structure for any +OpenPGP-compliant tool. + +### Why is the Key ID Still the Primary Key’s? + +OpenPGP keyrings and applications (including GpgFrontend, Thunderbird, etc.) +identify the whole key structure by the primary key ID. This ensures consistency +and interoperability across tools and platforms. It’s not possible to create a +"standalone" subkey that appears as its own identity—the subkey’s value is only +recognized as part of the primary key’s web-of-trust. + +### Can I use only a subkey for all operations? + +Yes, as long as you have generated the necessary subkeys for signing, +encryption, and authentication. But certain actions, like certifying other keys +or adding User IDs, require the primary key. -### Tips for Secure Usage: +## Tips for Secure Usage -1. **Inspect Subkey Capabilities**: Always verify what operations a subkey can - perform by reviewing its **Usage** field. -2. **Plan Subkey Generation**: At the time of key creation, consider creating - multiple subkeys with distinct purposes (e.g., signing, encryption, - authentication). -3. **Backup Primary Key Securely**: Store the primary key in an offline, highly - secure location to allow recovery or advanced operations if needed. +- **Inspect Subkey Capabilities**: Always verify what operations a subkey can + perform by reviewing its **Usage** field. +- **Plan Subkey Generation**: At the time of key creation, consider creating + multiple subkeys with distinct purposes (e.g., signing, encryption, + authentication). +- **Backup Primary Key Securely**: Store the primary key in an offline, highly + secure location to allow recovery or advanced operations if needed. -### Additional Note on Subkey Algorithm Types +## Additional Note on Subkey Algorithm Types Subkeys in GpgFrontend offer more algorithm types than primary keys due to their specialized roles. While primary keys focus on establishing identity and trust, @@ -286,4 +343,4 @@ Algorithms](/extra/algorithms-comparison) - ECDH NIST P-521 - ECDH BrainPool P-256 (GnuPG >2.3.0) - ECDH BrainPool P-384 (GnuPG >2.3.0) -- ECDH BrainPool P-512 (GnuPG >2.3.0)
\ No newline at end of file +- ECDH BrainPool P-512 (GnuPG >2.3.0) diff --git a/src/content/docs/guides/key-group.md b/src/content/docs/guides/key-group.md new file mode 100644 index 0000000..2f4c3cb --- /dev/null +++ b/src/content/docs/guides/key-group.md @@ -0,0 +1,109 @@ +--- +title: Key Groups +--- + +A Key Group is a powerful feature in GpgFrontend that allows you to manage and +utilize a collection of public keys as if they were a single public key. This +greatly simplifies encryption and access control when you want to address +multiple recipients or roles at once. + +## What is a Key Group? + +A Key Group is essentially a named set of public keys. Instead of encrypting +data separately for each individual recipient, you can create a group, add the +relevant public keys, and use the group for encryption. All members of the group +will be able to decrypt messages or files encrypted to that group. + +## Key Group Characteristics + +- Collection of Public Keys: A key group consists of one or more public keys. +- Treated as a Single Key: In GpgFrontend, you can use a key group anywhere a + single public key would be used, such as for encryption, sharing, or defining + access. +- Nested Key Groups: Key groups can contain other key groups. This allows you to + create complex, hierarchical access structures or role-based groups. +- Flexible Management: You can easily add, remove, or reorganize members (public + keys or other key groups) within a group at any time. +- Naming and Organization: Each key group can be given a unique name for easy + identification and usage. + +## How to Create and Use Key Groups + +1. Select Keys to Group: At the Key ToolBox panel, select the public keys you + want to add to your group by checking the boxes in the “Select” column. +2. Click the “Create Key Group” Button: Once you have selected the desired keys, + click the Key Group button (key icon) in the toolbar above the key list. +3. Fill in Group Information: A dialog titled New Key Group will appear. Fill in + the group’s name, email(optional), and an optional comment. Click + Create to make the group. +4. Key Group Appears in List: After creation, your new key group will appear in + the key list with Type shown as group. You can now use this group for + encryption and other operations—just like a single public key. + + + + + +## Manage Members and Nested Groups + +You can edit a key group at any time. Double-click the group entry (or use the +group management menu) to open the Key Group Management window. Here you can add +or remove keys, or even nest groups within groups. + + + +## Typical Use Cases + +- Team Encryption: Encrypt a document once for an entire project team or + department. All team members (whose keys are in the group) can decrypt it. +- Role-Based Access: Define groups such as “Developers”, “Managers”, or + “Auditors” and grant or revoke access by modifying group membership. +- Nested Structures: Organize key groups hierarchically, e.g., a “Project A” + group containing “Frontend Team” and “Backend Team” key groups. + +## Special Notes & Behaviors for Key Groups + +Key Groups in GpgFrontend offer flexibility and powerful management for +encryption workflows, but they also come with specific behaviors and rules that +ensure proper usage and system integrity. The following notes highlight +important details about how Key Groups work, their operational constraints, and +how they interact with the broader GpgFrontend environment. Understanding these +points will help you make the most of Key Groups while avoiding common pitfalls. + +### Owner Trust Propagation + +You can right-click on a Key Group entry to set the Owner Trust level for the +group. When you do this, the Owner Trust value is applied to all public keys +contained within the group (including recursively for nested groups). This is a +convenient way to manage trust settings for many users at once. + +### Membership & Encryption Capability + +Only keys marked with the E (Encrypt) usage flag can be added to a Key Group. If +a key does not support encryption, you will not be able to include it. + +### Automatic Disabling of Invalid Groups + +Auto-Disabling on Startup: If, upon startup, any key in a Key Group no longer +meets requirements (e.g., is deleted or loses encryption capability), the Key +Group will be automatically disabled. + +- Disabled Key Groups are not shown in the Key ToolBox. +- You can still view and manage them in the Key Management interface, where they + are highlighted in red to indicate their invalid status. +- The disabled status will propagate: if a nested group becomes unavailable, any + parent group containing it is also disabled. + +### Key Group Usage and Limitations + +Key Groups as Encryption Targets Only: In GpgFrontend, a Key Group is treated as +a single encryptable entity—you can use it as a recipient for encryption just +like a public key. Key Groups cannot be used for signing, decryption, or +certification. They are only valid for encryption operations. + +### Independence from GnuPG keygroups + +Key Groups Are Local to GpgFrontend: GpgFrontend Key Groups are internal objects +managed only by GpgFrontend. They are not connected to GnuPG’s "keygroup" +feature or to the `gpg.conf` file. This means Key Groups are only visible and +usable within GpgFrontend, and will not appear in other OpenPGP tools. diff --git a/src/content/docs/guides/smart-card.md b/src/content/docs/guides/smart-card.md index 39bc18a..38a4765 100644 --- a/src/content/docs/guides/smart-card.md +++ b/src/content/docs/guides/smart-card.md @@ -11,6 +11,92 @@ essential operations, and manage keys directly on your smart card.  +## Core Concepts and Frequently Asked Questions + +### What is an OpenPGP Smart Card? + +An OpenPGP smart card (such as YubiKey, Nitrokey, or similar devices) is a +dedicated hardware token designed to generate, store, and use cryptographic keys +in accordance with the OpenPGP standard (RFC 4880). The key advantages are: + +- Private keys never leave the device: All cryptographic operations (signing, + decryption, authentication) are performed on the card. +- Hardware protection: Even if your computer is compromised, the private key + cannot be extracted from the card. +- Additional security features: Such as PIN protection, touch-to-sign, and + multi-factor authentication. + +OpenPGP smart cards are widely used for secure email (PGP/GPG), SSH +authentication, and other security-critical applications. + +### What is the difference between PIN and Admin PIN? + +OpenPGP smart cards support at least two types of PIN codes: + +#### User PIN (CHV1) + +This is the regular PIN you enter to unlock the card for daily operations, such +as signing or decrypting. + +- Usually 6 digits by default. +- Entering it incorrectly too many times will lock the card, requiring admin + intervention. + +#### Admin PIN (CHV2) + +This is the administrator PIN, used to perform high-privilege management +operations. + +- Usually 8 digits by default. +- Required for actions such as resetting the user PIN, generating or importing + keys, or changing cardholder information. +- Loss or compromise of the Admin PIN may result in loss of administrative + control over the card. + +In short: The User PIN is for everyday use; the Admin PIN is for advanced or +recovery operations. + +### What is a Key Stub? + +A key stub in the GnuPG keyring is a placeholder record that indicates the +actual private key is stored externally (e.g., on a smart card). It does not +contain the private key itself. + +- GnuPG uses the stub to know that, when a cryptographic operation is needed, it + should forward the request to the smart card. +- The stub includes information such as the key ID and associated smart card + serial number. +- If you remove the smart card, the stub remains but cannot be used to perform + cryptographic operations. + +If you lose the smart card, even though the stub remains in your GnuPG keyring, +you will not be able to sign or decrypt using that key. + +### Does the Smart Card store the private key and the public key? + +The smart card only stores the private key(s). The private key cannot be +exported or extracted from the card. And the public key is not stored on the +card by default. Instead, you are expected to distribute your public key +separately (e.g., via key servers, files, or URLs). + +### Why set a Public Key URL? + +Setting a public key URL allows others (and your own software) to retrieve your +public key automatically when needed. This helps with secure communication and +verification without manual key distribution. + +### What does the “Fetch” operation do? When should I use it? + +The Fetch operation reads and synchronizes information from the smart card to +the application interface: + +- Use it after inserting a new card, generating or changing keys, or if you + suspect the card’s status is not up-to-date. +- Fetch ensures that all data (such as card info and key stubs) are current and + correctly reflected in the application. +- In cases where the card is not detected, or after making changes to the card, + use Fetch to refresh the state. + ## Key Sections and Features Smart Card(s) Selection: At the top, you can select from multiple detected @@ -63,6 +149,61 @@ administration tasks: - Update user information stored on the card - Sync card keys with your GnuPG keyring +## Other Common Questions + +### What if I enter the wrong PIN too many times? + +If you exceed the maximum number of attempts for the User PIN, the card will +lock and require the Admin PIN to reset or unlock. If you also lose or forget +the Admin PIN, you may need the reset code or, in some cases, perform a factory +reset (which will erase all keys). + +### How many keys can be stored on the card? + +Most OpenPGP cards support up to three key slots: one each for signature, +encryption, and authentication. Actual capacity may vary by manufacturer and +card model. Refer to the documentation for your device. + +### How do I synchronize card keys with my GnuPG keyring? + +After using “Fetch,” GnuPG will automatically create the necessary key stubs, +enabling the software to reference the keys stored on the card. If you replace +or upgrade your card, remember to update your keyring to avoid mismatches or +missing keys. + +### Can My Smart Card (e.g., YubiKey) Store Multiple Types of Credentials? + +Yes, many modern security tokens and smart cards—such as YubiKey—support +multiple independent modules or “applications” on the same device. Typical +examples include: + +- OpenPGP: Used for cryptographic operations (signing, encryption, + authentication) with GPG/PGP. +- FIDO2 / Passkey: Used for passwordless logins, web authentication (WebAuthn), + and as a hardware security key for websites or services. +- PIV (Personal Identity Verification): Used in enterprise and government + settings for smart card logins, certificates, and secure authentication. + +#### Independence of Modules + +- Each module is logically and cryptographically independent. For example, + generating or importing a key in the OpenPGP module will not affect keys or + credentials in the FIDO2 or PIV modules, and vice versa. +- PINs and management codes are typically separate. Each module may have its own + set of PINs or management credentials. +- Operations and data are isolated: Using one module does not interfere with, or + grant access to, another module’s secrets. + +You can use your YubiKey for OpenPGP-based email encryption, as a passkey for +passwordless login, and as a smart card for Windows logon—all at the same time, +without conflicts. + +> While modules are independent, the overall storage of the device is shared. +> Each module has its own storage limit (e.g., number of FIDO2 credentials, +> slots for OpenPGP keys). You may need different software to manage each module +> (e.g., GPG for OpenPGP, YubiKey Manager for FIDO2, PIV tools for smart card +> management). + ## Security Note All sensitive operations (such as PIN change or key generation) are performed diff --git a/src/content/docs/guides/understand-interface.md b/src/content/docs/guides/understand-interface.md index 91b66fb..495f3e6 100644 --- a/src/content/docs/guides/understand-interface.md +++ b/src/content/docs/guides/understand-interface.md @@ -4,19 +4,46 @@ sidebar: order: 2 --- -This documentation explains the interface and functionality of GpgFrontend, -based on the latest UI design. It is intended to guide users through its -features effectively. +This documentation explains the layout and features of the latest GpgFrontend +interface, helping users to efficiently utilize all cryptographic operations in +different workspaces. - + -## Text Editing Zone +## Workspace Overview -The **Text Editing Zone** allows users to input any desired text or work on -existing files. You can open a new tab using the **"New"** or **"New E-Mail"** -button or load an existing file with **"Open"** from the menu bar. +GpgFrontend organizes your cryptographic workflow into multiple workspaces +(tabs), making it easy to work with files, plain text, and email data +simultaneously. -### Key Features: +There are three main workspace types, each represented by a tab: + +- File Panel: For batch file and folder operations. +- Text Editor: For editing and encrypting/decrypting plain text. +- Mail Editor: For handling email messages in a dedicated editor. + +You can open multiple tabs of each type and switch between them as needed. + +### File Panel + +The File Panel is dedicated to cryptographic operations on files and folders. It +allows you to: + +- Browse and select files or folders from your system. +- Encrypt, decrypt, sign, or verify one or multiple files. +- Switch between ASCII and binary output modes. +- Activate Batch Mode for multi-file operations. +- Automatically handle folder archiving/encryption (see the File Operations + section for details). + +Files and folders selected via Open are always opened in a File Panel tab. + +### Text Editor + +The Text Editor allows users to input any desired text or work on existing +files. + +#### Key Features - **Operations Bar**: Located at the top, it provides options to encrypt, decrypt, sign, and verify text directly. @@ -24,14 +51,28 @@ button or load an existing file with **"Open"** from the menu bar. and **Ctrl+S** for copying, pasting, and saving text. - **Plain Text Format**: Text is encoded in UTF-8 without formatting to ensure clarity and compatibility. Future plans may include rich text editing. - -#### Large Text File Support - - Files up to **1MB** are supported. Larger files may cause performance issues and are not recommended. - While loading large files, editing will be temporarily disabled until the entire file is processed. +### Mail Editor + +The Mail Editor is specifically designed for working with EML-format email +messages. + +- Open and Edit EML Files: Load .eml files (standard email format) directly for + viewing and editing their content. +- Compose, Encrypt, Sign, and Verify Emails: Easily write or modify email + content and apply encryption, digital signatures, or verify received + signatures—all in one place. + +:::caution[Note] + +The Mail Editor is optimized for .eml files, ensuring compatibility with standard email clients and maintaining proper formatting and metadata during cryptographic operations. + +::: + ## Information Panel The **Information Panel** displays the results of current operations (e.g., @@ -55,24 +96,38 @@ and algorithms used. ## Key Toolbox -The **Key Toolbox**, located on the right side of the interface, lists all -available keys. It provides details such as key type, name, email address, and -usage. Users can select keys for specific operations by ticking the boxes in the -first column. +Located on the right side, the Key Toolbox lists all your available keys, +including public, private, and key groups. + +Key features: + +- Selection: Tick boxes to choose keys for current operations. +- Type/Usage/Email: Quickly review each key’s function. +- Tab Filtering: Tabs let you quickly filter keys by type or status. + +Keys that are expired, revoked, or unavailable are hidden by default, but can be +managed in the Manage Keys interface. + +### Understanding the Key Toolbox Table -### Key Details +The Key Toolbox contains detailed information about each key. Some of the +columns and codes—especially in the Type and Usage columns—may not be +immediately obvious. The section below explains the meaning of these less +obvious—but essential—fields and codes, so you can confidently interpret key +types, usage, and status in your daily cryptographic operations. - **Type**: - `pub`: Public key (for encryption or verification). - `pub/sec`: Key pair with both public and private keys. - `pub/sec#`: Key pair with missing primary key. - `pub/sec^`: Key pair with components stored on a smart card. -- **Email Address**: Shows the email associated with each key. + - `group`: Key Group (a collection of public keys used as one recipient for + encryption). - **Usage**: Indicates key functionality with codes: - - `C`: Certification. - - `E`: Encryption. - - `S`: Signing. - - `A`: Authentication. + - `C`: Certification – can certify (sign) other keys (typically primary keys only) + - `E`: Encryption – can encrypt data to this key + - `S`: Signing – can create digital signatures + - `A`: Authentication – can be used for authentication (e.g. SSH) ### Categories @@ -82,20 +137,24 @@ Expired or revoked keys are not displayed by default and can be viewed in ## Operations Bar -The **Operations Bar**, at the top of the interface, provides quick access to -all core functionalities: - -1. **New E-Mail**: Create a new email or text file. -2. **Open**: Open an existing text file. -3. **File Panel**: Browse and select files from your system. -4. **Encrypt**: Encrypt text or files using selected keys. -5. **Encrypt Sign**: Encrypt and sign text or files simultaneously. -6. **Decrypt**: Decrypt text or files. -7. **Decrypt Verify**: Decrypt and verify signed files. -8. **Sign**: Digitally sign text or files. -9. **Verify**: Verify the signature of text or files. -10. **Manage Keys**: Access the key management interface. -11. **Import Key**: Import keys into your keyring. +The Operations Bar at the top provides one-click access to all core +cryptographic and workspace features. Here are the main buttons, from left to +right: + +1. **Open**: Open a file or directory, launching the File Panel for file-based + operations. +2. **Workspace**: Manage and switch between different workspaces or tabs, such + as File Panel, Text Editor, and Mail Editor. +3. **Encrypt**: Encrypt the currently selected file(s) or text using the + selected recipient keys. +4. **Decrypt**: Decrypt the currently selected encrypted file(s) or text. No key + selection is required—gpg automatically detects and uses the + appropriate private key(s) from your keyring. +5. **Sign**: Digitally sign the selected file(s) or text with your private key. +6. **Verify**: Verify the signature of the selected file(s) or text. +7. **New Keypair**: Generate a new key pair. +8. **Import Key...**: Import existing public or private keys into your keyring. +9. **Manage Keys**: Access the key management interface. ### Customization |