SRCmail/vnc/S-MIME-USER-GUIDE.md

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?
2. Getting Started: Plugin Installation
3. Importing Your Certificate
4. Composing Signed & Encrypted Mail
5. Verifying Received Messages
6. Certificate Management
7. Settings
8. Troubleshooting
9. Enrollment with an Internal CA (Coming in a future version)

---

What is S/MIME?

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

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.

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

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

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

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

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

---

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

"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

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