# VNCmail+ S/MIME User Guide

**Version:** 0.3.0 | **Last updated:** 2026-08-04

This guide walks you through setting up and using S/MIME encryption and digital signatures in VNCmail+. S/MIME lets you send cryptographically signed and encrypted emails that are verifiable and private, with your private keys secured in your browser using WebCrypto.

---

## Table of Contents

1. [What is S/MIME?](#what-is-smime)
2. [Getting Started: Plugin Installation](#plugin-installation)
3. [Importing Your Certificate](#importing-certificate)
4. [Composing Signed & Encrypted Mail](#composing-mail)
5. [Verifying Received Messages](#verifying-received)
6. [Certificate Management](#certificate-management)
7. [Settings](#settings)
8. [Troubleshooting](#troubleshooting)
9. [Enrollment with an Internal CA](#ca-enrollment) *(Coming in a future version)*

---

## What is S/MIME? {#what-is-smime}

S/MIME (Secure/Multipurpose Internet Mail Extensions) is a standard for cryptographically signing and encrypting email. It uses public-key cryptography:

- **Digital Signing**: Proves the email is from you and hasn't been altered.
- **Encryption**: Scrambles the message so only the intended recipient can read it.

In VNCmail+, the S/MIME plugin handles all the cryptography in your browser. Your private keys are:

- **Imported from a PKCS#12 file** (.p12 or .pfx) — a password-protected container holding your certificate and private key.
- **Encrypted at rest** with a passphrase you choose.
- **Unlocked into WebCrypto keys** that never leave your browser.

---

## Getting Started: Plugin Installation {#plugin-installation}

The S/MIME plugin must be installed and enabled in your VNCmail+ instance. This is typically done by an administrator.

### Checking if S/MIME is Installed

1. Navigate to **Settings** (gear icon in the left sidebar).
2. In the search box, type **S/MIME** to filter the settings menu.
3. You should see two options appear:
   - **Plugins** (under the "ERWEITER" / Extended section)
   - **S/MIME** (a sub-item under Plugins)

The **Plugins** view will show a card for the S/MIME plugin. If you see a badge labeled **"running"** and a toggle switch that is ON (blue), S/MIME is active and ready to use.

![Screenshot: S/MIME plugin showing "running" status](./assets/smime-plugin-running.png)

If the toggle is OFF or the plugin is not listed, contact your administrator to install it.

### Admin: Installing the Plugin

Administrators can install the S/MIME plugin through the admin dashboard:

1. Navigate to **Settings** > **Plugins**.
2. Click the **"Upload Plugin"** button (or similar, depending on your admin interface).
3. Select the S/MIME plugin bundle (`smime-vnc.zip` or equivalent from the VNC team).
4. The system will scan the plugin for security issues. If all checks pass, click **Install**.
5. Toggle the switch to enable it for all users.

---

## Importing Your Certificate {#importing-certificate}

Before you can sign or encrypt mail, you need to import a PKCS#12 certificate file into VNCmail+.

### Step 1: Prepare Your Certificate File

Obtain a `.p12` or `.pfx` file that contains:
- Your X.509 certificate
- Your private key
- Your password (to unlock the file)

If you don't have a certificate yet, see [Enrollment with an Internal CA](#ca-enrollment) below.

### Step 2: Import into VNCmail+

1. In Settings, navigate to **S/MIME** (the sub-section under Plugins).
2. You'll see a section labeled **"Your Certificates"** or similar.
3. Click **"Import Certificate"** or **"Upload PKCS#12"**.
4. Select your `.p12` file.
5. When prompted, enter the password that protects the PKCS#12 file.
6. VNCmail+ will extract your certificate and verify it is valid.
7. You'll be prompted to choose a **local passphrase** — this is what you'll enter each time you want to unlock your key for signing or decryption. Use a strong passphrase; it is NOT synced or recoverable.

Once imported, your certificate will appear in the list with:
- Your email address(es) it is authorized for.
- The certificate issuer (e.g., "VNC Root CA R1").
- The expiration date.

### Step 3: Verify the Import

After importing, you should see your certificate listed. Click on it to view details:
- **Subject**: Your name and email address.
- **Issuer**: The Certificate Authority that issued it.
- **Valid from / until**: The certificate's lifespan.
- **Serial Number**: A unique identifier.
- **Public Key Size**: (e.g., 2048-bit RSA).

---

## Composing Signed & Encrypted Mail {#composing-mail}

Once a certificate is imported, you can compose signed and encrypted messages.

### Step 1: Start a New Message

1. Click **"Compose"** or press `C`.
2. Fill in the recipient, subject, and message body as normal.

### Step 2: Enable Signing and Encryption

At the top of the compose area, you'll see the S/MIME toolbar:

- **Sign** button (looks like a signed document or checkmark with a certificate icon).
- **Encrypt** button (looks like a lock or envelope).
- **Certificate selector** (dropdown showing your imported certificate).

1. If you have multiple certificates, select the one you want to sign with from the dropdown.
2. Click **Sign** to digitally sign the message. Once enabled, it shows as active (highlighted or colored).
3. Click **Encrypt** to encrypt the message. Once enabled, it also shows as active.

#### For Signing Only

- Click **Sign** only. The recipient will receive a message they can verify came from you, without encryption.

#### For Encryption Only

- Click **Encrypt** only. (Typically combined with signing, but not required.)

#### For Signing + Encryption (Recommended)

- Click both **Sign** and **Encrypt**. The message will be signed by you and encrypted so only the recipient can read it.

### Step 3: Encrypt the Recipient's Email

If you've enabled encryption, you must have the recipient's certificate in your **trusted contacts**. VNCmail+ will:

1. Check if you've previously received a signed email from the recipient and auto-imported their certificate.
2. If not found, you'll see a warning: **"Recipient certificate not found"** or similar.

#### Auto-Import (Recommended)

If you've received a signed email from the recipient before, their certificate was likely auto-imported. Verify by:

1. Going to Settings > S/MIME > **Trusted Contacts**.
2. Searching for the recipient's email address.
3. If their certificate is listed, you can encrypt to them immediately.

#### Manual Import

If their certificate is not auto-imported:

1. Ask the recipient to send you a **signed email** (even a blank one will do).
2. When you receive it, the S/MIME plugin will automatically import their certificate.
3. On your next reply, you'll be able to encrypt.

Alternatively, ask the recipient to provide their certificate via a secure channel and manually import it through Settings > S/MIME > **Trusted Contacts** > **Import**.

### Step 4: Send

1. Once signing/encryption is configured and the recipient's certificate is available (for encryption), click **Send**.
2. If you enabled encryption, the local passphrase for your private key will be requested. Enter it to unlock your key and sign/encrypt the message.
3. The message is then sent, signed and/or encrypted as configured.

---

## Verifying Received Messages {#verifying-received}

When you receive a signed or encrypted message, VNCmail+ automatically processes and verifies it.

### Signed Messages

When you open a signed message:

1. A **signature verification banner** appears at the top of the message:
   - **✓ Valid signature from [sender]** — The message is authentic and unaltered.
   - **⚠ Invalid signature** or **⚠ Untrusted issuer** — The signature failed verification (rare; may indicate tampering).
   - **? No signature** — The message was not signed.

2. The signer's certificate details are shown in the banner:
   - The signer's email address.
   - The certificate issuer (CA).
   - The signing timestamp.

### Encrypted Messages

When you open an encrypted message:

1. The message is automatically decrypted using your imported private key.
2. You may be prompted to enter your **local passphrase** to unlock your private key (once per session, then cached).
3. The decrypted message body is displayed.
4. A **decryption success banner** confirms the message was encrypted to your certificate.

### Combined: Signed + Encrypted

If a message is both signed and encrypted:

1. It is decrypted first (using your private key).
2. The signature is then verified (using the sender's certificate).
3. Both banners are shown, confirming both the authenticity and privacy of the message.

### Auto-Import of Sender's Certificate

When you open a signed message, the S/MIME plugin automatically imports the sender's certificate (if its setting is enabled). This means on your next reply, if you want to encrypt to them, their certificate is already available.

---

## Certificate Management {#certificate-management}

### Viewing Your Certificates

**Settings > S/MIME > Your Certificates**

Each certificate shows:
- The email address(es) it is authorized for.
- The issuer.
- Expiration date.
- Options to **view details**, **export**, or **delete**.

### Viewing Trusted Contacts

**Settings > S/MIME > Trusted Contacts**

Lists all certificates you've imported or auto-imported from signed emails:
- Click a contact to see their certificate details.
- Delete a contact's certificate if you no longer trust them.

### Exporting a Certificate

You can export your own certificate (with or without the private key):

1. Go to **Settings > S/MIME > Your Certificates**.
2. Click **Export** on your certificate.
3. Choose:
   - **Certificate only** (.cer or .pem): Public key only, safe to share.
   - **With private key** (.p12 or .pfx): Includes your private key, requires a password. **Only do this if you need a backup.**

### Revoking a Certificate

If you suspect your private key is compromised:

1. Go to **Settings > S/MIME > Your Certificates**.
2. Click **Revoke** on the certificate.
3. Confirm the action. The certificate is marked as revoked and can no longer be used to verify your signatures.
4. Request a new certificate from your Certificate Authority (see [Enrollment with an Internal CA](#ca-enrollment)).

---

## Settings {#settings}

### S/MIME Settings

**Settings > S/MIME**

The plugin offers a few configurable options:

#### Content Encryption Algorithm

- **AES-256-GCM** (default, recommended): Strong encryption with integrity checking.
- **AES-128-GCM**: Slightly smaller; still strong.

#### Auto-Save Signer Certificates

When enabled (default), the S/MIME plugin automatically imports certificates from signed emails you receive. This makes it easy to encrypt replies without manually importing certificates.

#### Render HTML in Legacy-Encrypted Mail

When disabled (default, recommended), HTML content in older messages encrypted with AES-CBC is not rendered. This is a defense against EFAIL attacks. Modern messages you send are always AES-GCM and render fully. Toggle this only if you receive frequent legacy AES-CBC emails and trust the senders.

#### Display Encryption/Signature Banners

Control whether banners appear on signed/encrypted messages. Usually left on for visibility.

---

## Troubleshooting {#troubleshooting}

### "Recipient certificate not found"

**Problem**: You're trying to encrypt a message but VNCmail+ can't find the recipient's certificate.

**Solution**:
1. Ask the recipient to send you a signed email.
2. Open it; their certificate will auto-import.
3. Compose your encrypted reply.

Alternatively, ask the recipient for their certificate via a secure channel and manually import it through Settings > S/MIME > Trusted Contacts.

### "Could not decrypt message"

**Problem**: You received an encrypted message but it won't decrypt.

**Cause**:
- The message was encrypted to a different certificate than the one you imported.
- Your private key is unavailable.

**Solution**:
1. Verify the recipient encrypted the message to the correct email address.
2. Verify you've imported the correct certificate for that email.
3. Try refreshing the page and re-opening the message.

### "Invalid signature"

**Problem**: You received a signed message and the signature doesn't verify.

**Cause**:
- The message was tampered with after it was sent.
- The sender's certificate has expired or been revoked.
- The certificate issuer is not trusted.

**Solution**:
1. Ask the sender to resend the message.
2. If the problem persists, ask the sender to renew their certificate.

### "Passphrase required on every action"

**Problem**: You're prompted for your local passphrase every time you send a signed/encrypted message.

**Cause**:
- Your browser session has expired.
- Your private key is not cached in memory.

**Solution**:
- This is normal for security reasons. If it's inconvenient, you can reduce your session timeout in Account Settings (though shorter timeouts are more secure).

### "Browser doesn't support S/MIME"

**Problem**: You're getting a compatibility warning or S/MIME isn't working.

**Cause**:
- You're using an older browser that doesn't support WebCrypto.

**Solution**:
- Upgrade to a recent version of Chrome, Firefox, Safari, or Edge.

---

## Enrollment with an Internal CA {#ca-enrollment}

**Status:** Coming in a future version (v0.4.0)

VNCmail+ is being enhanced to support direct certificate enrollment from an internal Certificate Authority (CA). In the future, you'll be able to:

1. Generate a keypair directly in your browser (using WebCrypto).
2. Request a certificate from the internal CA without needing to import a pre-issued certificate.
3. Have your certificate automatically validated against your email address, preventing certificate misuse.

### For Now

If you need a certificate, you can:

1. **Request from an external CA** (e.g., Let's Encrypt, DigiCert) using standard tooling.
2. **Request from your organization** if they operate a CA.
3. **Self-sign a certificate** for testing (not recommended for production).

Once you have a `.p12` or `.pfx` file, follow the [Importing Your Certificate](#importing-certificate) steps above.

The internal CA enrollment feature will be announced in a future release.

---

## Getting Help

For questions or issues:

1. Check the **Troubleshooting** section above.
2. Contact your administrator.
3. Visit the VNCmail+ documentation at `docs/` in the project repository.

---

## Version History

| Version | Date | Changes |
|---------|------|---------|
| 0.3.0 | 2026-08-04 | Initial S/MIME User Guide; internal CA foundation (enrollment coming in 0.4.0). |

---

## Glossary

- **PKCS#12**: A file format (`.p12`, `.pfx`) that contains a certificate and private key, typically password-protected.
- **X.509**: The standard format for digital certificates.
- **Certificate Authority (CA)**: An organization that issues and manages digital certificates.
- **WebCrypto**: A JavaScript API for performing cryptography in the browser without sending keys to a server.
- **AES-GCM**: An authenticated encryption algorithm that ensures both confidentiality and integrity.
- **RFC 5751**: The standard for S/MIME message format and processing.