tiCrypt Functional Architecture
tiCrypt is composed of several distinct components that communicate over tightly controlled channels. This article walks through the functional architecture of a tiCrypt deployment, explaining how requests flow from the user's workstation through the backend and into secure compute nodes. For infrastructure planning and deployment sizing, see Understanding tiCrypt Infrastructure.
Frontend Interface
The frontend interface is the user's entry point into tiCrypt. At its core is the tiCrypt Connect Application, a self-contained desktop application built on Wails (similar to Electron) that runs on the user's workstation. Connect serves two roles: it hosts the tiCrypt web interface in a secure browser context, and it acts as a bridge between the user's local machine and the secure enclave. File uploads from the local workstation, private key operations, TLS certificate generation for tunnels, and local port forwarding for application access all run through Connect. Without it, there is no path into the system.
The frontend communicates with the backend over two channels:
- REST API (port 443). All management operations, including authentication, file management, VM lifecycle commands, and notifications, pass through the REST frontend over HTTPS.
- Tunneled applications (ports 6000-6100). Interactive access to VMs (RDP, terminal, SFTP) is tunneled through the proxy service. Connect mediates this tunneling by generating TLS certificates, establishing connections through the proxy, and forwarding local ports to the corresponding ports inside the VM. The tunnel traffic is encrypted end-to-end between Connect and
ticrypt-vm-controllerinside the VM.
Authentication combines digital signatures with multi-factor authentication. The user provides a password to decrypt their private key, then signs a login challenge issued by the server. An external MFA provider (Duo, Shibboleth, NetID, or similar) issues a short-lived certificate (default 30 minutes) as an additional factor. The private key signature is the primary mechanism. MFA is required but not trusted on its own.
tiCrypt Backend Server
The backend server is the central coordination point for the entire system. It sits behind an external firewall at the authorization boundary and exposes two external interfaces: the REST frontend on port 443 and the proxy on ports 6000-6100. All HTTPS services run behind Nginx as reverse-proxied virtual domains, each with its own TLS certificate.
Internally, the backend runs several services:
- REST Frontend (
ticrypt-rest). Accepts all HTTPS requests from the frontend interface and routes them to internal services. Exposes both an external-facing endpoint (port 443) and an internal endpoint used by compute nodes. Also serves as the token-based API for programmatic access. - Proxy (
ticrypt-proxy). Mediates tunneled application traffic between the user's device and VMs on compute nodes. The proxy accepts connections on ports 6000-6100 externally and forwards them to port ranges 6000-6254 on VM hosts. It replicates traffic between two WebSocket connections but cannot read the contents because the payload is encrypted end-to-end using RSA-2048 co-authentication between the user and the VM. The proxy must listen only on the domain used for proxying; listening on other interfaces opens a security risk. - Authentication (
ticrypt-auth). Handles user authentication, authorization, and session management. Coordinates MFA certificate validation, key escrow operations, and acts as the global coordinator across all backend services. - File Manager. Manages encrypted file storage in the vault.
- Virtual Machines (
ticrypt-vm). Controls the full VM lifecycle across all compute hosts via Libvirt, including SLURM integration for batch processing. Connects to VM hosts over SSH using an injected RSA-2048 public key. - Maintenance. Handles system maintenance tasks and health monitoring.
- Notifications. Manages user and system notifications.
- Statistics. Collects and serves system usage metrics.
- Logging (
ticrypt-logger). Records all system activity into a tamper-resistant, blockchain-structured log. A primary copy is written to a local immutable file. A second copy is streamed to the tiCrypt Audit server over port 25000.
Compute Nodes
Compute nodes host the secure virtual machines where all computation occurs. A deployment can include VM hosts (for interactive VMs), SLURM hosts (for batch processing), or both.
Each compute node communicates with the backend through two channels:
- REST API (port 443 internal).
ticrypt-host-controlleron the compute node communicates with the backend over HTTPS to receive VM lifecycle commands, report status, and coordinate SLURM job provisioning. - Port 22. All user-facing VM traffic arrives on port 22. This port is not running SSH. It is bound by
ticrypt-vm-controllerinside each VM, which intentionally prevents any SSH server from running in its place. If port 22 cannot be bound, the VM controller fails to start.
On bootup, each VM's ticrypt-vm-controller generates an RSA-2048 key pair, registers with the backend using its UUID and public key, and opens a WebSocket connection to wait for a user session. When a user connects, the VM controller and the user's frontend co-authenticate using their respective public keys. If either side fails validation, the connection is rejected. All subsequent traffic is encrypted with a negotiated session key.
Port range 6000-6254 on each compute node receives forwarded proxy traffic from the backend, which is routed to port 22 on the appropriate VM.
VMs on compute nodes are connected to the backend via a flat Layer 2 OpenVSwitch network (br-secure), VLAN-isolated from all other traffic. The backend is the sole gateway and exit point. No VM traffic exits through the compute host directly.
A distributed file system connects the backend and all compute hosts, providing shared storage across three Libvirt pools: ticrypt-vm (volumes and temporary files), ticrypt-vm-drives (user drives), and ticrypt-bricks (VM images).
tiCrypt Audit Server
tiCrypt Audit (formerly tiAudit) is the audit tool used to process the secure logs generated by ticrypt-logger, allowing security teams and administrators to run queries and generate reports. It receives logs from the backend over port 25000, stores them in ClickHouse, and provides a web interface on port 443. Alert drivers support email (SMTP), Splunk integration, and screen output.
tiCrypt Audit is intentionally one-directional: the backend pushes logs to it, but it has no access back to the backend. This isolation means security teams can operate tiCrypt Audit without gaining access to any other part of the system. The complete system history is retained for the lifetime of the deployment.
Data Ingress
tiCrypt provides two mechanisms for securely receiving data from external contributors, both deployed outside the authorization boundary:
- SFTP Ingress (
ticrypt-sftp). Accepts files over SFTP on port 2022. Requires a network path to the backend REST interface. - Mailbox Ingress (
ticrypt-mailbox). A web-based file submission interface. Contributors upload files through a browser or CLI. Files are encrypted with the receiving user's public key so that only the intended recipient can decrypt them. The system auto-locks on detection of impersonation or malicious file patterns.
Both services allow external collaborators to submit data without accessing the secure system. Neither service has access to the internal network or compute nodes.
Traffic Flow Summary
| Path | Ports | Purpose |
|---|---|---|
| User to Backend (REST) | 443 | Authentication, file management, VM commands |
| User to Backend (Proxy) | 6000-6100 | Tunneled application access to VMs |
| User to External MFA | Varies | Multi-factor authentication (Duo, Shibboleth, etc.) |
| Backend to Compute Nodes (VM mgmt) | 22 (SSH) | VM lifecycle management via Libvirt |
| Backend to Compute Nodes (Proxy) | 6000-6254 to port 22 | Forwarded tunnel traffic to VMs |
| Backend to tiCrypt Audit | 25000 | Log delivery |
| Compute Nodes to Backend | 443 (internal) | Status, registration, data access |
| External to SFTP Ingress | 2022 | SFTP file submission |
| External to Mailbox Ingress | 443 | Web-based file submission |
| tiCrypt Audit to User | 443 | Audit web interface |
- All user traffic enters through the backend. Compute nodes are never directly exposed to users or the internet.
- The proxy carries encrypted, end-to-end authenticated traffic using RSA-2048 co-authentication. The backend cannot read the contents.
- Port 22 on VMs is not SSH. It is a tunnel endpoint bound by
ticrypt-vm-controllerthat requires digital signature authentication. No SSH server can run in its place. - VM controllers generate a fresh RSA-2048 key pair on every boot and co-authenticate with the connecting user before any data flows.
- tiCrypt Audit receives logs but has no return path to the backend, isolating the audit function from operational systems.
- Data ingress services (SFTP, Mailbox) operate outside the authorization boundary and have no access to the internal network.