Secure FTP Plugin for Total Commander

📚 Table of Contents

• Feature Overview
• Architecture
• File Transfer Capabilities
• Authentication System
• Security & Password Storage
• Connection Management
• Module Map
• System Requirements
• Roadmap

Feature Overview

This plugin is a complete C++20 rewrite of the original SFTP plugin by Christian Ghisler (creator of Total Commander). The original C implementation served as the foundation, but has been completely re-engineered with modern C++ patterns, enhanced security features, and extended functionality.

This plugin targets Total Commander on Windows x64 and provides comprehensive secure file transfer capabilities:

Core Transfer Protocols

• SFTP (primary) with resume support and streaming transfers
• SCP (native) with >2GB file detection for 64-bit servers
• Shell Transfer Fallback (DD/base64) for restricted hosts blocking SFTP/SCP

Authentication Methods

• Password authentication with Keyboard-Interactive support
• Public key authentication (PEM/OpenSSH format)
• Native PPK v2/v3 decoding without external tools
• Pageant (SSH Agent) integration with auto-launch

Advanced Features

• Session import from PuTTY and WinSCP registry
• Comprehensive proxy support (HTTP CONNECT, SOCKS4/4a/5)
• Remote checksum calculation (MD5, SHA1, SHA256, SHA512)
• Automatic UTF-8 and line ending detection
• Host key fingerprint verification

Design Priorities

1. Practical interoperability on heterogeneous SSH servers
2. Deterministic failure behavior (timeouts, cleanup, no hidden loops)
3. Modern C++ architecture with RAII and interface abstraction
4. Zero external dependencies beyond statically-linked libssh2

Architecture

Layered Structure

WFX API Layer
  ↓
Plugin Entry Points (FsFindFirst/FsGetFile/FsPutFile/FsExecuteFile/...)
  ↓
┌─────────────────────────────────────────┐
│  Business Logic Layer                   │
│  ├─ Connection/Auth                     │
│  ├─ Transfer/RemoteOps                  │
│  └─ UI Separation (IUserFeedback)       │
└─────────────────────────────────────────┘
  ↓
ISshBackend Interface (ISshSession/ISshChannel/ISftpHandle)
  ↓
Libssh2Backend Implementation (libssh2)

Why This Architecture Matters

Backend Abstraction via ISshBackend
Polymorphic interfaces (ISshSession, ISshChannel, ISftpHandle) decouple the plug-in from direct libssh2 calls. This enables:

• Future backend migration without rewriting business logic
• Potential multi-backend support (libssh2, libssh, etc.)
• Easier unit testing via mock implementations

RAII Memory Management
Extensive use of std::unique_ptr for session/channel objects and handle_util::AutoHandle<HANDLE> for Windows file handles eliminates memory leaks common in older Total Commander plugins.

UI Separation via IUserFeedback
The IUserFeedback pattern (implemented by WindowsUserFeedback) separates transfer/connection logic from MessageBox dialogs, improving background thread stability in Total Commander's multi-threaded environment.

Connection Lifecycle

Operational Requirements:

• No unbounded EAGAIN loops
• Readiness checks in all network loops
• Stage timeout per critical phase (connect/auth/read)
• Cleanup on every failing exit path

File Transfer Capabilities

Standard SFTP & Native SCP

Shell DD / Base64 Fallback (New!)

Advanced workaround for servers with blocked SFTP subsystem and unavailable scp command. Uses hidden interactive channel for transfers.

Upload Path:

1. Split local data into chunks
2. Base64 encode each chunk
3. Send via printf '%s' | base64 -d through shell channel
4. Decode and append server-side

Download Path:

1. Try fast path via cat
2. Fallback to base64 -w 0 when needed
3. Incremental decode (streaming, no full-file buffering)

Throughput Note: Base64 adds ~33% overhead. Native SFTP/SCP is faster. Shell fallback is compatibility-first, not speed-first.

SCP > 2GB File Support

Remote Checksum Support

Calculate file hashes directly on the server without local computation:

Authentication System

Supported Methods

• Password - Traditional password authentication
• Keyboard-Interactive - With password change request handling
• PEM (OpenSSH) - Traditional private key format
• PPK v2/v3 - Native PuTTY format decoding (New!)
• Pageant - SSH Agent integration

Native PPK v2 & v3 Decoder (New!)

Revolutionary native parsing of PuTTY Private Key files without external tools:

Authentication Fallback Strategy

Key-Path Validation (Fail-Fast)

This avoids minute-long UI freezes on impossible auth attempts.

Pageant Integration

• Full integration with PuTTY Pageant
• Auto-launch pageant.lnk when needed
• Seamless fallback to file-based auth if agent unavailable

Security & Password Storage

Storage Modes

Security Enhancements

Connection Management

Session Import (New!)

Import configurations from Windows Registry:

Import Features:

• Non-conflicting conversion to plugin INI format
• Preserves connectivity fields (host, port, user, keys)
• No auto-connect side effects during import

Proxy Support

Network Features

• IPv4 / IPv6 dual-stack support
• Custom port configuration
• Host key verification with fingerprint storage
• First-time connection warnings
• Fingerprint changed alerts

Shell Engineering Highlights

Marker-Aware SCP Parsing

Real-world SSH servers differ in shell behavior. KVC handles edge cases:

Restricted Shell Handling

Module Map (for Maintainers)

System Requirements

Packaging

Distribution package contents:

Roadmap

Completed / Stable

• Backend abstraction layer (ISshBackend)
• Native PPK v2/v3 conversion with Argon2
• Shell DD/base64 fallback transfer
• Session import (WinSCP/PuTTY)
• Remote checksum support (MD5/SHA1/SHA256/SHA512)
• SCP >2GB file detection
• DPAPI + TC password manager integration
• x64 packaging flow

In Progress

• Splitting oversized legacy functions
• C-style buffer cleanup to safer C++ constructs
• UI/business-logic decoupling (WFX constraints)

Deferred (Intentional)

• Full rewrite of legacy parser modules
• Multi-platform support (Linux/macOS)
• Alternative backend (libssh)