SurePack User Manual - PublicKeyServer

Overview

SurePack is a secure file transfer application that uses post-quantum cryptography to protect your files. It allows you to send files securely and optionally anonymously to other users through encrypted packages.

Quick Start Guide

1. Create Your Identity (Alias)

# Anonymous alias (no email)
surepack create

# OR with email verification (optional)
surepack verify your@email.com

📧 Note: Check your email for the 6-digit verification code

surepack create your@email.com 123456

2. Send a File (Smart Detection)

# Smart parameter detection - just provide recipient and file!
surepack recipient@example.com document.pdf

# Or use traditional commands
surepack pack -i document.pdf -a recipient-alias -f your-alias -o package.surepack
surepack send -i package.surepack

3. Receive Packages (Smart Detection)

# Just provide your alias - automatically downloads and unpacks all packages
surepack your-alias@example.com

# Or use traditional command - also automatic by default
surepack receive -a your-alias

# For interactive mode (choose which packages)
surepack receive -a your-alias -i

4. Files Are Automatically Unpacked!

# No manual unpacking needed - files are automatically extracted!
# But you can still manually unpack if needed:
surepack unpack -i package.surepack -o output-folder

Smart Parameter Detection (NEW!)

SurePack now includes intelligent command detection that automatically determines what you want to do based on the parameters you provide. This makes common operations much simpler!

Smart Pack & Send

When you provide a recipient (email or alias) and a file, SurePack automatically:

Uses your most recent alias as the sender
Generates a timestamped output filename
Packs the file with encryption
Sends it immediately

# Examples - order doesn't matter!
surepack alice@example.com document.pdf
surepack document.pdf alice@example.com
surepack alice-bob-charlie.publickeyserver.org report.xlsx

# With additional options
surepack alice@example.com document.pdf -m "Here's the report"
surepack bob@company.com folder/ -p "mypassword"  # Auto-enables recursion for folders

Smart Receive

When you provide just an alias or email, SurePack knows you want to receive:

# Check specific alias for packages
surepack alice@example.com
surepack happy-tree-frog.publickeyserver.org

# Or use explicit receive for all aliases
surepack receive

Smart Verify & Create

SurePack detects when you want to verify an email or create an alias:

# Request email verification
surepack verify alice@example.com

# Create alias with email and token
surepack create alice@example.com 123456

# Create anonymous alias (no email)
surepack create

Smart About Page

No parameters? SurePack shows the about page:

surepack

GUI Launch (Experimental)

Launch the experimental graphical interface:

surepack gui

Note: All traditional commands with explicit flags continue to work exactly as before. Smart detection simply provides a convenient shortcut for common operations.

Complete Command Reference

`surepack about`

Display version and about information for SurePack.

Usage:

surepack about

Options:

-v, --verbose : Set output to verbose messages (default: 0)

`surepack certify`

Verify the certificate chain and authenticity of an alias.

Usage:

surepack certify -a alice.publickeyserver.org

Options:

-a, --alias : The alias to certify (required)
-v, --verbose : Set output to verbose messages
-p, --passphrase : Enter password
-d, --domain : Domain name

`surepack create`

Create a new alias (digital identity) for sending and receiving encrypted files.

Usage:

# Smart detection (NEW!)
# Create anonymous alias
surepack create

# Create alias with email and token
surepack create john@example.com 123456

# Traditional commands
# Create anonymous alias
surepack create

# Create alias with email
surepack create -e john@example.com -t 123456

Options:

-e, --email : Optional email address to associate with alias
-t, --token : Email validation token (obtained via verify command)
-d, --domain : Domain name (default: publickeyserver.org)
-p, --passphrase : Enter password
-v, --verbose : Set output to verbose messages

Example Output:

Creating...
Domain: publickeyserver.org

Please enter passphrase: ********

[✓] Generated RSA key pair
[✓] Generated Quantum Kyber key pair  
[✓] Generated Quantum Dilithium key pair
[✓] Root certificate fingerprint saved

Alias happy-cloud-tree.publickeyserver.org created

`surepack delete`

Delete an alias from both local storage and the server.

Usage:

surepack delete -a old-alias.publickeyserver.org

Options:

-a, --alias : The alias to delete (required)
-v, --verbose : Set output to verbose messages
-p, --passphrase : Enter password
-d, --domain : Domain name

Warning: This action is permanent and cannot be undone.

`surepack gui`

Launch the graphical user interface (experimental).

Usage:

# Launch GUI
surepack gui

# Open a surepack file in GUI
surepack gui -u package.surepack

# Create new package with file in GUI
surepack gui -i document.pdf

Options:

-u, --unpack : Unpack surepack file in GUI
-i, --input : Input file for packing in GUI
-v, --verbose : Set output to verbose messages

`surepack list`

List all your aliases and verify their certificates.

Usage:

surepack list

Options:

-v, --verbose : Set output to verbose messages
-p, --passphrase : Enter password

Example Output:

alice-smith.publickeyserver.org
bob-jones.publickeyserver.org
charlie-work.company.com

`surepack pack`

Create an encrypted package (.surepack file) from one or more files.

Usage:

# Smart detection (NEW!) - automatically packs and sends
surepack recipient@example.com file.pdf
surepack file.pdf recipient@example.com  # Order doesn't matter

# Traditional pack command
surepack pack -i document.pdf -a recipient -f sender -o package.surepack

# Pack multiple files with wildcard
surepack pack -i "*.txt" -a recipient -f sender -o documents.surepack

# Pack with multiple recipients
surepack pack -i file.doc -a alice,bob,charlie -f sender -o shared.surepack

# Pack with subdirectories
surepack pack -i "*" -r -a recipient -f sender -o everything.surepack

# Pack with message and subject
surepack pack -i report.xlsx -a boss -f employee -s "Q4 Report" -m "Please review" -o report.surepack

Options:

-i, --input : Input file(s) to pack (wildcards supported) (required)
-a, --aliases : Recipient aliases/emails (comma-delimited) (required)
-f, --from : Your sender alias (required)
-o, --output : Output package filename (required)
-r, --recurse : Include subdirectories
-s, --subject : Package subject line
-m, --message : Optional message to include
-c, --compression : Compression type [BROTLI, GZIP, NONE] (default: GZIP)
-v, --verbose : Set output to verbose messages
-p, --passphrase : Enter password

Examples:

Basic file packaging:

surepack pack -i invoice.pdf -a client.publickeyserver.org -f mycompany.publickeyserver.org -o invoice-package.surepack

Pack all PDFs in a folder:

surepack pack -i "reports/*.pdf" -a manager -f employee -o monthly-reports.surepack

Pack for multiple recipients with a message:

surepack pack -i contract.docx -a "alice,bob,legal@company.com" -f sender -s "Contract Review" -m "Please sign by Friday" -o contract.surepack

`surepack receive`

Automatically download and unpack all encrypted packages sent to your alias from the server.

Usage:

# Smart detection (NEW!) - just provide the alias
surepack your-alias@example.com

# Traditional receive commands
# Automatic receive all packages (default behavior)
surepack receive -a your-alias

# Interactive receive (choose which packages)
surepack receive -a your-alias -i

# Continuous monitoring (check every 60 seconds)
surepack receive -a your-alias -s 60

# Receive without auto-unpacking
surepack receive -a your-alias --no-unpack

# Receive and unpack to specific directory
surepack receive -a your-alias -o ./downloads

Options:

-a, --alias : Your alias to check for packages
-i, --interactive : Prompt before downloading each package (default is to download all)
-s, --seconds : Check for packages every X seconds (0 = once only)
--no-unpack : Skip automatic unpacking of received packages
-o, --output : Output directory for unpacked files (defaults to current directory)
--keep-packages : Keep .surepack files after unpacking (default is to delete)
-v, --verbose : Set output to verbose messages
-p, --passphrase : Enter password

Example Session (Automatic Mode - Default):

Receiving packages...
Auto-unpack: Enabled
Alias: alice.publickeyserver.org

Downloading all surepacks automatically
Found 3 packages:
1. package1.surepack (2.5 MB) from bob.publickeyserver.org
2. package2.surepack (512 KB) from charlie.publickeyserver.org  
3. package3.surepack (10 MB) from david.publickeyserver.org

Downloading package1.surepack... Done

Unpacking package1.surepack...
Unpacked to 2024-01-15_14-30_bob
Cleaned up package1.surepack

Downloading package2.surepack... Done

Unpacking package2.surepack...
Unpacked to 2024-01-15_14-31_charlie
Cleaned up package2.surepack

Summary:
  Packages received: 3
  Successfully unpacked: 3
  Package files cleaned up: 3

Example Session (Interactive Mode):

surepack receive -a alice.publickeyserver.org -i

Found 3 packages:
1. package1.surepack (2.5 MB) from bob.publickeyserver.org
2. package2.surepack (512 KB) from charlie.publickeyserver.org
3. package3.surepack (10 MB) from david.publickeyserver.org

Which surepack do you want to receive? ([1-3] or [a] for all, or [q] to quit): 1

Downloading package1.surepack... Done

`surepack send`

Upload encrypted packages to the server for recipients to download.

Usage:

# Send specific package
surepack send -i package.surepack

# Send all packages in outbox
surepack send

Options:

-i, --input : Package file to send (optional, sends all outbox if omitted)
-v, --verbose : Set output to verbose messages
-p, --passphrase : Enter password

Examples:

Send a specific package:

surepack send -i invoice-package.surepack

Send all pending packages from outbox:
```
surepack send
```

`surepack unpack`

Decrypt and extract files from a .surepack package.

Usage:

# Unpack to specific directory
surepack unpack -i package.surepack -o extracted-files/

# Unpack using specific alias
surepack unpack -i package.surepack -o output/ -a your-alias

Options:

-i, --input : Input .surepack file to unpack (required)
-o, --output : Output directory for extracted files
-a, --alias : Specific alias to use (auto-detects if omitted)
-v, --verbose : Set output to verbose messages
-p, --passphrase : Enter password

Example Output:

Unpacking surepack...
Input: package.surepack
Output directory: extracted-files/

Checking alias alice.publickeyserver.org...
[✓] Valid recipient
[✓] Certificate verified
[✓] Decrypting package...

Extracted files:
- document1.pdf (1.2 MB)
- document2.docx (456 KB)
- image.png (2.3 MB)

Package unpacked successfully to: extracted-files/

`surepack verify`

Request email verification code to associate an email with an alias.

Usage:

# Smart detection (NEW!)
surepack verify john@example.com

# Traditional command
surepack verify -e john@example.com

Options:

-e, --email : Email address to verify (required for traditional command)
-d, --domain : Domain name
-v, --verbose : Set output to verbose messages

Note: After receiving the verification code via email, use it when creating an alias:

# Smart detection
surepack create john@example.com 123456

# Traditional command
surepack create -e john@example.com -t 123456

Complete Workflow Examples

Example 1: Anonymous File Transfer

Sender (Alice):

# Create anonymous alias
surepack create
# Output: Alias alice-tree-cloud.publickeyserver.org created

# Pack sensitive documents
surepack pack -i "whistleblower-docs/*" -a journalist.newspaper.com -f alice-tree-cloud.publickeyserver.org -o anonymous-leak.surepack

# Send the package
surepack send -i anonymous-leak.surepack

Recipient (Journalist):

# Check for new packages - automatically downloads and unpacks!
surepack receive -a journalist.newspaper.com

# Files are automatically extracted to timestamped folders
# e.g., 2024-01-15_14-30_alice-tree-cloud/

Example 2: Business Document Exchange

Setup:

# Request email verification
surepack verify -e john@company.com
# Check email for verification code: 123456

# Create business alias with email
surepack create -e john@company.com -t 123456 -d company.com

Sending Contract:

# Pack contract with metadata
surepack pack -i "contract-v2.docx" -a "legal@client.com,ceo@client.com" -f john@company.com -s "Contract for Review" -m "Please review sections 3 and 5 carefully. Sign by EOD Friday." -o contract-package.surepack

# Send to server
surepack send -i contract-package.surepack

Receiving Response:

# Check for responses - automatically downloads and unpacks!
surepack receive -a john@company.com

# Files automatically extracted to dated folders
# e.g., 2024-01-15_16-45_legal/signed-contract.docx

Example 3: Batch Processing

# Pack all monthly reports
surepack pack -i "2024-reports/*.pdf" -a accounting@hq.com -f branch-office.company.com -s "Monthly Reports - January 2024" -o january-reports.surepack

# Pack all quarterly data with compression
surepack pack -i "Q4-data/*" -r -c BROTLI -a data-team@company.com -f analytics.company.com -o q4-data.surepack

# Send all packages in outbox
surepack send

Global Options

These options are available for all commands:

-v, --verbose : Verbosity level (0=quiet, 1=normal, 2=detailed, 3=debug)
-p, --passphrase : Provide password via command line (not recommended for security)
-d, --domain : Override default domain (publickeyserver.org)

Security Best Practices

Password Protection: Always use a strong password when creating aliases
Alias Verification: Use surepack certify to verify recipients before sending sensitive data
Anonymous Transfers: For maximum anonymity, create aliases without email association
Key Storage: Private keys are stored in:
- Windows: %LOCALAPPDATA%\surepack\aliases\
- Linux/Mac: ~/.local/share/surepack/aliases/

Troubleshooting

Common Issues

"Incorrect password"

Ensure you're using the password set when creating the alias
Passwords are case-sensitive

"Could not find alias in package"

You're trying to unpack a file not sent to any of your aliases
Use surepack list to see your available aliases

"Aliases do not share the same root certificate"

Sender and recipient must be from compatible servers
Check domain compatibility with administrator

Need More Help?

Run surepack <command> --help for detailed help on any command
Visit publickeyserver.org for documentation
Report issues at github.com/publickeyserver/surepack

SurePack Help Documentation

Overview

Quick Start Guide

1. Create Your Identity (Alias)

2. Send a File (Smart Detection)

3. Receive Packages (Smart Detection)

4. Files Are Automatically Unpacked!

Smart Parameter Detection (NEW!)

Smart Pack & Send

Smart Receive

Smart Verify & Create

Smart About Page

GUI Launch (Experimental)

Complete Command Reference

surepack about

surepack certify

surepack create

surepack delete

surepack gui

surepack list

surepack pack

surepack receive

surepack send

surepack unpack

surepack verify

Complete Workflow Examples

Example 1: Anonymous File Transfer

Example 2: Business Document Exchange

Example 3: Batch Processing

Global Options

Security Best Practices

Troubleshooting

Common Issues

Need More Help?

`surepack about`

`surepack certify`

`surepack create`

`surepack delete`

`surepack gui`

`surepack list`

`surepack pack`

`surepack receive`

`surepack send`

`surepack unpack`

`surepack verify`