Secure Tunnel

Secure Tunnel is an Enterprise security module that implements TLS-like encryption at the application layer. It provides end-to-end encryption for all communication between your browser and HomeDock OS, independent of the underlying transport protocol.

_{Secure Tunnel is a reimplementation of TLS cryptographic primitives (RSA-OAEP key exchange + AES-256-GCM symmetric encryption) at the application layer. See the node-forge documentation for implementation details.}

Why Application-Layer TLS?

Standard HTTPS encrypts traffic between client and server, but encryption terminates at various points:

Load balancers that decrypt for routing decisions
Reverse proxies that inspect traffic
Corporate proxies with TLS interception
CDNs with edge termination

Secure Tunnel encrypts data inside the HTTP payload, so even if TLS terminates at an intermediary, the actual data remains encrypted end-to-end.

Ideal For

Secure Tunnel is essential for organizations handling sensitive data where maximum encryption is non-negotiable:

Financial institutions - Banks, insurance companies, and fintech requiring regulatory compliance
Government agencies - Public sector deployments with strict security mandates
Healthcare - HIPAA-compliant environments protecting patient data
Legal firms - Attorney-client privileged communications
Research institutions - Protecting intellectual property and confidential findings

For privacy-conscious enterprises, Secure Tunnel elevates HomeDock OS encryption to a level suitable for the most demanding security requirements.

How It Works

The handshake mirrors TLS key exchange:

Client generates session key: A random 256-bit AES key is generated
Server sends public key: Client fetches RSA public key from /api/pksend
Key encryption: Client encrypts the AES key using RSA-OAEP with SHA-256
Key exchange: Encrypted key is sent to server via /api/handshake
Session established: Both parties now share the symmetric key

After handshake, all API requests/responses are encrypted with AES-256-GCM using the shared session key.

Cryptographic Implementation

Secure Tunnel uses two implementations with automatic fallback:

Environment	Implementation
Secure context (HTTPS)	Web Crypto API (native, hardware-accelerated)
Non-secure context (HTTP)	node-forge (pure JavaScript)

Algorithms Used

Operation	Algorithm
Key Exchange	RSA-OAEP with SHA-256
Symmetric Encryption	AES-256-GCM
IV Generation	12 bytes random per request
Authentication	GCM tag (128-bit)

The node-forge fallback allows Secure Tunnel to work over plain HTTP, useful for development environments or networks where HTTPS cannot be configured.

Enabling Secure Tunnel

Go to Settings in HomeDock OS
Navigate to the System tab
Find the Advanced Security section
Toggle Secure Tunnel to on

The toggle shows a loading state during handshake. Once complete, all subsequent communications are encrypted.

Encrypted Payload Format

Each encrypted request/response follows this structure:

{
  "encrypted": true,
  "iv": "<base64-encoded-12-byte-IV>",
  "tag": "<base64-encoded-16-byte-auth-tag>",
  "data": "<base64-encoded-ciphertext>"
}

Session Persistence

Automatic reconnection: Tunnel attempts to re-establish on page refresh
Session scoped: Closing the browser ends the session
No persistent storage: Encryption keys only exist in memory

Excluded Routes

These routes are excluded from encryption (required for handshake):

/api/pksend - Server public key retrieval
/api/handshake - Key exchange
/api/tunnel/clear - Session termination

Tray Indicator

When active, a shield icon in the system tray provides visual confirmation that Secure Tunnel is protecting your session.

Troubleshooting

Tunnel fails to establish

Verify network connectivity to the server
Check browser console for handshake errors
Try clearing session storage and retry

Performance

AES-256-GCM is highly efficient. Web Crypto API uses hardware acceleration when available. The node-forge fallback is slightly slower but still performant for typical API payloads.