{"id":13539524,"url":"https://github.com/maqp/tfc","last_synced_at":"2025-05-16T03:02:50.826Z","repository":{"id":40523947,"uuid":"50497794","full_name":"maqp/tfc","owner":"maqp","description":"Tinfoil Chat - Onion-routed, endpoint secure messaging system","archived":false,"fork":false,"pushed_at":"2025-05-03T05:19:34.000Z","size":3157,"stargazers_count":1264,"open_issues_count":30,"forks_count":88,"subscribers_count":53,"default_branch":"master","last_synced_at":"2025-05-03T06:21:39.625Z","etag":null,"topics":["data-diode","end-to-end-encryption","endpoint-security","hidden-services","onion-service","onion-services","open-source","privacy-by-design","python3","qubes-os","secure-by-default","secure-messenger","tails","tor","tor-onion-service"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/maqp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-01-27T09:51:02.000Z","updated_at":"2025-04-27T19:24:21.000Z","dependencies_parsed_at":"2023-01-28T11:45:56.325Z","dependency_job_id":"afd8c121-86eb-4f46-ad23-78f0c3ed464a","html_url":"https://github.com/maqp/tfc","commit_stats":{"total_commits":66,"total_committers":3,"mean_commits":22.0,"dds":"0.045454545454545414","last_synced_commit":"07a819b3a8e1ce98bfc292b0ee8a76cb713e9645"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maqp%2Ftfc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maqp%2Ftfc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maqp%2Ftfc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/maqp%2Ftfc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/maqp","download_url":"https://codeload.github.com/maqp/tfc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254459081,"owners_count":22074604,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["data-diode","end-to-end-encryption","endpoint-security","hidden-services","onion-service","onion-services","open-source","privacy-by-design","python3","qubes-os","secure-by-default","secure-messenger","tails","tor","tor-onion-service"],"created_at":"2024-08-01T09:01:27.168Z","updated_at":"2025-05-16T03:02:50.799Z","avatar_url":"https://github.com/maqp.png","language":"Python","readme":"\u003cimg align=\"right\" src=\"https://cs.helsinki.fi/u/oottela/tfc_logo.png\" style=\"position: relative; top: 0; left: 0;\"\u003e\n\n### Tinfoil Chat\n\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![Python 3.9|3.10](https://img.shields.io/badge/Python-3.9%20%7C%203.10-blue)](https://python.org)\n[![Checked with mypy](http://www.mypy-lang.org/static/mypy_badge.svg)](http://mypy-lang.org/)\n[![Unit Tests](https://github.com/maqp/tfc/actions/workflows/unit_tests.yml/badge.svg?branch=master)](https://github.com/maqp/tfc/actions/workflows/unit_tests.yml)\n[![codecov](https://codecov.io/gh/maqp/tfc/branch/master/graph/badge.svg?token=RJv2hFFdnR)](https://codecov.io/gh/maqp/tfc)\n[![Codacy Badge](https://app.codacy.com/project/badge/Grade/71fa9cc1da424f52a576a04c2722da26)](https://www.codacy.com/gh/maqp/tfc/dashboard?utm_source=github.com\u0026amp;utm_medium=referral\u0026amp;utm_content=maqp/tfc\u0026amp;utm_campaign=Badge_Grade)\n[![CodeFactor](https://www.codefactor.io/repository/github/maqp/tfc/badge)](https://www.codefactor.io/repository/github/maqp/tfc)\n[![Snyk Report](https://snyk.io/test/github/maqp/tfc/badge.svg)](https://snyk.io/test/github/maqp/tfc) \n\nTinfoil Chat (TFC) is a\n[FOSS](https://www.gnu.org/philosophy/free-sw.html)+[FHD](https://www.gnu.org/philosophy/free-hardware-designs.en.html)\n[peer-to-peer](https://en.wikipedia.org/wiki/Peer-to-peer)\nmessaging system that relies on high assurance hardware architecture to protect users from\n[passive collection](https://en.wikipedia.org/wiki/Upstream_collection), \n[MITM attacks](https://en.wikipedia.org/wiki/Man-in-the-middle_attack)\nand most importantly,\n[remote key exfiltration](https://en.wikipedia.org/wiki/Data_exfiltration). \nTFC is designed for people with one of the most complex threat models: organized crime \ngroups and nation state hackers who bypass end-to-end encryption of traditional secure \nmessaging apps by hacking the endpoint.\n\n\n#### State-of-the-art cryptography\n\nTFC uses\n[XChaCha20](https://cr.yp.to/chacha/chacha-20080128.pdf)-[Poly1305](https://cr.yp.to/mac/poly1305-20050329.pdf)\n[end-to-end encryption](https://en.wikipedia.org/wiki/End-to-end_encryption)\nwith\n[deniable authentication](https://en.wikipedia.org/wiki/Deniable_encryption#Deniable_authentication)\nto protect all messages and files sent to individual recipients and groups. \nThe symmetric keys are either\n[pre-shared](https://en.wikipedia.org/wiki/Pre-shared_key),\nor exchanged using\n[X448](https://eprint.iacr.org/2015/625.pdf),\nthe base-10\n[fingerprints](https://en.wikipedia.org/wiki/Public_key_fingerprint)\nof which are verified via an out-of-band channel. TFC provides per-message\n[forward secrecy](https://en.wikipedia.org/wiki/Forward_secrecy)\nwith\n[BLAKE2b](https://blake2.net/blake2.pdf) \nbased\n[hash ratchet](https://www.youtube.com/watch?v=9sO2qdTci-s#t=1m34s).\nAll persistent user data is encrypted locally using XChaCha20-Poly1305, the key \nof which is derived from password and salt using \n[Argon2id](https://github.com/P-H-C/phc-winner-argon2/blob/master/argon2-specs.pdf),\nthe parameters of which are automatically tuned according to best \npractices. Key generation of TFC relies on Linux kernel's \n[getrandom()](https://manpages.debian.org/testing/manpages-dev/getrandom.2.en.html),\na syscall for its ChaCha20 based \n[CSPRNG](https://en.wikipedia.org/wiki/Cryptographically_secure_pseudorandom_number_generator).\n\n\n#### Anonymous by design\nTFC routes all communication exclusively through the \n[Tor](https://2019.www.torproject.org/about/overview.html.en) \nanonymity network. It uses the next generation\n([v3](https://trac.torproject.org/projects/tor/wiki/doc/NextGenOnions))\n[Tor Onion Services](https://2019.www.torproject.org/docs/onion-services)\nto enable P2P communication that never exits the Tor network. This makes it hard for the \nusers to accidentally deanonymize themselves. It also means that unlike (de)centralized \nmessengers, there's no third party server with access to user metadata such as who is \ntalking to whom, when, and how much. The network architecture means TFC runs exclusively \non the user's devices. There are no ads or tracking, and it collects no data whatsoever \nabout the user. All data is always encrypted with keys the user controls, and the \ndatabases never leave the user's device.\n\nUsing Onion Services also means no account registration is needed. During the first launch \nTFC generates a random TFC account (an Onion Service address) for the user, e.g.\n`4sci35xrhp2d45gbm3qpta7ogfedonuw2mucmc36jxemucd7fmgzj3ad`. By knowing this TFC account, \nanyone can send the user a contact request and talk to them without ever learning their \nreal life identity, IP-address, or geolocation. Protected geolocation makes physical \nattacks very difficult because the attacker doesn't know where the device is located on \nthe planet. At the same time it makes the communication censorship resistant: Blocking TFC \nrequires blocking Tor categorically, nation-wide.\n\nTFC also features a traffic masking mode that hides the type, quantity, and schedule of \ncommunication, even if the network facing device of the user is hacked. To provide even\nfurther metadata protection from hackers, the Internet-facing part of TFC can be run on \n[Tails](https://tails.boum.org/), a privacy and anonymity focused operating system that \ncontains no personal files of the user (which makes it hard to deduce to whom the endpoint\nbelongs to), and that provides \n[additional layers of protection](https://github.com/Whonix/onion-grater)\nfor their anonymity.\n\n\n#### First messaging system with endpoint security\n\nTFC is designed to be used in hardware configuration that provides strong\n[endpoint security](https://en.wikipedia.org/wiki/Endpoint_security).\nThis configuration uses three computers per endpoint: Encryption and decryption processes\nare separated from each other onto two isolated computers, the Source Computer, and the \nDestination Computer. These two devices are dedicated for TFC. This split \n[TCB](https://en.wikipedia.org/wiki/Trusted_computing_base)\ninteracts with the network via the user's daily computer, called the Networked Computer.\n\nIn TFC data moves from the Source Computer to the Networked Computer, and from the Networked \nComputer to the Destination Computer, unidirectionally. The unidirectionality of data\nflow is enforced, as the data is passed from one device to another only through a free \nhardware design\n[data diode](https://en.wikipedia.org/wiki/Unidirectional_network), \nthat is connected to the three computers using one USB-cable per device.\nThe Source and Destination Computers are not connected to the Internet, or to any device \nother than the data diode.\n\n\n![](https://www.cs.helsinki.fi/u/oottela/wiki/readme/data_diode.jpg)\n[TFC data diode](https://www.cs.helsinki.fi/u/oottela/wiki/readme/data_diode.jpg)\n\nOptical repeater inside the\n[optocouplers](https://en.wikipedia.org/wiki/Opto-isolator)\nof the data diode enforce direction of data transmission with the fundamental laws of \nphysics. This protection is so strong, the certified implementations of data diodes are \ntypically found in critical infrastructure protection and government networks where the\nclassification level of data varies between systems. A data diode might e.g. allow access \nto a nuclear power plant's safety system readings, while at the same time preventing \nattackers from exploiting these critical systems. An alternative use case is to allow \nimporting data from less secure systems to ones that contain classified documents that \nmust be protected from exfiltration.\n\nIn TFC the hardware data diode ensures that neither of the TCB-halves can be accessed \nbidirectionally. Since the protection relies on physical limitations of the hardware's\ncapabilities, no piece of malware, not even a \n[zero-day exploit](https://en.wikipedia.org/wiki/Zero-day_(computing))\ncan bypass the security provided by the data diode.\n\n\n### How it works\n\nWith the hardware in place, all that's left for the users to do is launch the device \nspecific TFC program on each computer.\n\n![](https://www.cs.helsinki.fi/u/oottela/wiki/readme/overview.png)\n[System overview](https://www.cs.helsinki.fi/u/oottela/wiki/readme/overview.png)\n\nIn the illustration above, Alice enters messages and commands to Transmitter Program \nrunning on her Source Computer. The Transmitter Program encrypts and signs plaintext \ndata and relays the ciphertexts from Source Computer to her Networked Computer \nthrough the data diode.\n\nRelay Program on Alice's Networked Computer relays commands and copies of outgoing \nmessages to her Destination Computer via the data diode. Receiver Program on Alice's \nDestination Computer authenticates, decrypts and processes the received message/command.\n\nAlice's Relay Program shares messages and files to Bob over a Tor Onion Service. \nThe web client of Bob's Relay Program fetches the ciphertext from Alice's Onion \nService and forwards it to his Destination Computer through his data diode. Bob's \nReceiver Program then authenticates, decrypts and processes the received message/file.\n\nWhen Bob responds, he will type his message to the Transmitter Program on his Source \nComputer, and after a mirrored process, Alice reads the message from the Receiver Program\non her Destination Computer. All this happens seamlessly and automatically.\n\n\n### Why keys and plaintexts cannot be exfiltrated\n\nThe architecture described above simultaneously utilizes both\n[the classical and the alternative data diode models](https://en.wikipedia.org/wiki/Unidirectional_network#Applications) \nto enable bidirectional communication between two users, while at the same time providing \nhardware enforced endpoint security: \n\n1. The Destination Computer uses the classical data diode model. This means it can receive \ndata from the insecure Networked Computer, but is unable to send data back to the Networked \nComputer. The Receiver Program is designed to function under these constraints. However,\neven though the program authenticates and validates all incoming data, it is not ruled out \nmalware couldn't still infiltrate the Destination Computer. In the event that would happen, \nthe malware would be unable to exfiltrate sensitive keys or plaintexts back to the Networked \nComputer, as the data diode prevents all outbound traffic.\n\n2. The Source Computer uses the alternative data diode model. This means it can output\nencrypted data to the insecure Networked Computer without having to worry about being\ncompromised. The data diode lacks the hardware that would allow transmission of data to the \nSource Computer, which protects the Source Computer from all remote attacks. The Transmitter \nProgram is also designed to work under the data flow constraints introduced by the data diode; \nTo allow key exchanges, the short elliptic-curve public keys are input manually by the user. \n\n3. The Networked Computer is designed under the assumption it can be compromised by a\nremote attacker: All sensitive data that passes through the Relay Program is protected by \n[authenticated encryption](https://en.wikipedia.org/wiki/Authenticated_encryption)\nwith no exceptions. Since the attacker is unable to exfiltrate decryption keys from \nthe Source or Destination Computer, the ciphertexts obtained from Networked Computer\nare of no value to the attacker. \n\n\n![](https://www.cs.helsinki.fi/u/oottela/wiki/readme/attacks.png)\n[Exfiltration security](https://www.cs.helsinki.fi/u/oottela/wiki/readme/attacks.png)\n\n\n### Qubes-isolated intermediate solution\n\nFor some users the\n[APTs](https://en.wikipedia.org/wiki/Advanced_persistent_threat) \nof the modern world are not part of the threat model, and for others, the \nrequirement of having to build the data diode by themselves is a deal-breaker. Yet, for \nall of them, storing private keys on a networked device is still a security risk.\n\nTo meet these users' needs, TFC can also be run in three dedicated \n[Qubes](https://www.qubes-os.org/)\nvirtual machines. With the Qubes configuration, the isolation is provided by the \n[Xen hypervisor](https://xenproject.org/users/security/), \nand the unidirectionality of data flow between the VMs is enforced with Qubes' \n[qrexec framework](https://www.qubes-os.org/doc/qrexec/). \nThis intermediate isolation mechanism runs on a single computer which means no hardware data diode is needed. \n\n\n### Supported Operating Systems\n\n#### Source/Destination Computer\n- Debian 12.5\n- PureOS 10.3\n- *buntu 24.04 LTS\n- Pop!_OS 22.04 LTS\n- Linux Mint 21.3\n- LMDE 6\n- Zorin OS 17.1\n- Qubes 4.2.1 (Debian 12 VM)\n\n#### Networked Computer\n- Tails 6.2\n- Debian 12.5\n- PureOS 10.3\n- *buntu 24.04 LTS\n- Pop!_OS 22.04 LTS\n- Linux Mint 21.3\n- LMDE 6\n- Zorin OS 17.1\n- Qubes 4.2.1 (Debian 12 VM)\n\n\n### More information\n[Threat model](https://github.com/maqp/tfc/wiki/Threat-model)\u003cbr\u003e\n[FAQ](https://github.com/maqp/tfc/wiki/FAQ)\u003cbr\u003e\n[Security design](https://github.com/maqp/tfc/wiki/Security-design)\u003cbr\u003e\n\nHardware Data Diode\u003cBr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;[Breadboard version](https://github.com/maqp/tfc/wiki/TTL-Data-Diode-(breadboard)) (Easy)\u003cbr\u003e \n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;[Perfboard version](https://github.com/maqp/tfc/wiki/TTL-Data-Diode-(perfboard)) (Intermediate)\u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;[PCB version](https://github.com/maqp/tfc/wiki/TTL-Data-Diode-(PCB)) (Advanced)\u003cbr\u003e\n\nHow to use\u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;[Installation](https://github.com/maqp/tfc/wiki/Installation)\u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;[Master password setup](https://github.com/maqp/tfc/wiki/Master-Password)\u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;[Local key setup](https://github.com/maqp/tfc/wiki/Local-Key-Setup)\u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;[Onion Service setup](https://github.com/maqp/tfc/wiki/Onion-Service-Setup)\u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;[X448 key exchange](https://github.com/maqp/tfc/wiki/X448)\u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;[Pre-shared keys](https://github.com/maqp/tfc/wiki/PSK)\u003cbr\u003e\n\u0026nbsp;\u0026nbsp;\u0026nbsp;\u0026nbsp;[Commands](https://github.com/maqp/tfc/wiki/Commands)\u003cbr\u003e\n\n[Update log](https://github.com/maqp/tfc/wiki/Update-Log)\u003cbr\u003e\n","funding_links":[],"categories":["Instant Messaging","\u003ca id=\"1a9934198e37d6d06b881705b863afc8\"\u003e\u003c/a\u003e通信\u0026\u0026代理\u0026\u0026反向代理\u0026\u0026隧道","\u003ca id=\"6e80463404d46f0493cf6e84597e4b5c\"\u003e\u003c/a\u003e工具"],"sub_categories":["P2P","\u003ca id=\"b03a7c05fd5b154ad593b6327578718b\"\u003e\u003c/a\u003e匿名网络","\u003ca id=\"e99ba5f3de02f68412b13ca718a0afb6\"\u003e\u003c/a\u003eTor\u0026\u0026\u0026Onion\u0026\u0026洋葱"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaqp%2Ftfc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmaqp%2Ftfc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmaqp%2Ftfc/lists"}