# OnionShare Integration & Tor Control Security Guide

Subsystem: Snigdha Privacy Suite
Application: OnionShare 2.6.5
Distribution: Snigdha OS Decentralized

---

# 1. Overview & Capabilities

OnionShare is an open-source tool that allows users to securely and anonymously share files, receive documents, host temporary websites, and run private chat rooms using ephemeral Tor v3 onion services.

Supported operations:

• Send Files: Hosts a temporary onion site serving selected documents.
• Receive Files: Creates an anonymous Dropbox-style submission portal.
• Host Website: Publishes static HTML sites over .onion.
• Private Chat: Runs an ephemeral, unlogged chatroom.

---

# 2. Tor Control Security: The snigdha-tor-broker Filter

To create ephemeral onion services, OnionShare must issue ADD_ONION and DEL_ONION commands to Tor's ControlSocket.

# The Security Vulnerability:

Granting an unprivileged desktop application direct access to /run/tor/control:

• Exposes full administrative control over the Tor network daemon.
• Allows reading active circuits (GETINFO circuit-status).
• Allows arbitrary network reconfiguration (SETCONF).
• Allows shutting down or crashing Tor (SIGNAL SHUTDOWN).

# The Snigdha OS Defense:

snigdha-tor-broker acts as an authenticating, filtering intermediary proxy:

1. Listens on 127.0.0.1:9051 and /run/tor/control.filtered (accessible to desktop users).
2. Authenticates upstream using the protected /run/tor/control.authcookie.
3. Intercepts and filters every command:
   • Allowed: PROTOCOLINFO, AUTHENTICATE, GETINFO version|status/bootstrap-phase|net/listeners/socks, GETCONF SocksPort, SETEVENTS SIGNAL|HS_DESC, ADD_ONION NEW:(BEST|ED25519-V3)... Port=..., DEL_ONION, SIGNAL NEWNYM.
   • Denied: All SETCONF, SAVECONF, SIGNAL SHUTDOWN, GETINFO address, and administrative queries are rejected with 510 Command filtered.
4. Automatic Ephemeral Service Teardown: When OnionShare disconnects or exits, the broker automatically executes DEL_ONION for every service created in that session, preventing zombie onion services.

---

# 3. Service Defaults & Cryptographic Hygiene

• Client Authentication Enabled by Default: Every service requires a cryptographic authentication key (ClientAuthV3), preventing unauthorized visitors from reaching the onion service.
• Public Services Warning: Disabling client authentication makes the .onion address globally crawlable.
• Ephemeral Private Keys: Service keys are held in volatile RAM only (Flags=DiscardPK). They are never written to disk.
• Volatile Receive Directory: Received files default to ~/Downloads/OnionShare/ in RAM tmpfs. Users must explicitly move files to ~/Persistent/ to preserve them across reboots.

---

# 4. Threat Model & Operational Pitfalls

• Out-of-Band Channel Exposure: If you send an .onion URL and private key via SMS, unencrypted email, or proprietary messengers, your identity is linked to the onion service.
• Network Dependency: OnionShare is strictly gated by NetGuard. If Tor loses connectivity, all services cease immediately.