2f8dfd1
# cjdns
2f8dfd1
2f8dfd1
[Upstream](README.md)
2f8dfd1
2f8dfd1
#### *Networking Reinvented*
2f8dfd1
2f8dfd1
Cjdns implements an encrypted IPv6 network using public-key cryptography for
2f8dfd1
address allocation and a distributed hash table for routing. This provides
2f8dfd1
near-zero-configuration networking, and prevents many of the security and
2f8dfd1
scalability issues that plague existing networks.
2f8dfd1
a6396ab
## Why?
a6396ab
a6396ab
If you're here from the hyperboria docs, you're already sold - proceed to
a6396ab
Installing.  But why should a Fedora user install cjdns?  I'll mention just two
a6396ab
contrasting use cases, one mundane and the other paranoid.
a6396ab
a6396ab
### VPN Mesh
a6396ab
a6396ab
Configuring a point to point VPN connection with openvpn is fairly
a6396ab
straightforward, as is configuring a centralized VPN server and clients.
a6396ab
However, when every node in the VPN network needs to talk securely with many
a6396ab
other nodes, relaying every packet through the central server becomes a drag on
a6396ab
performance, and a single point of failure.  Mesh VPNs, like tinc and cjdns
a6396ab
automatically create point to point connections based on a shared overall
a6396ab
configuration.  Each node only needs a connection to one or more peers (that
a6396ab
can be reused) to get things started.  
a6396ab
a6396ab
With cjdns, however, things are much better than with tinc.  On a local LAN or
a6396ab
mesh with broadcast, it is zero configuration.  Peers are automatically
a6396ab
discovered via the 0xFC00 layer 2 protocol.  There is no shared configuration -
a6396ab
the only thing required is adding one or more (for redundancy) internet peers
a6396ab
when no peers on the local LAN or mesh are available.  Even better, when your
a6396ab
node is mobile, and you have geographically separated peers configured, cjdns
a6396ab
automatically switches to a faster peer as the relative performance changes.
a6396ab
a6396ab
### Darknet
a6396ab
a6396ab
In a widespread VPN, address assignment must be coordinated by a central
a6396ab
authority.  The internet also uses centralized IP assignment, which means a
a6396ab
government can take away your IP at any time.  Cjdns uses CryptoGraphic
a6396ab
Addressing (CGA).  Your IP6 is the double SHA-512 of your public key truncated
a6396ab
to 128 bits.  Your IP is as safe as the private key pair which produced it, and
a6396ab
cannot [insert standard cryptography disclaimer] be spoofed.  Most mesh VPNs
a6396ab
decrypt packets before routing to a new node.  This means that if a relay node
a6396ab
is compromised in a conventional VPN, it can see and even alter packets.  All
a6396ab
cjdns packets are end to end encrypted - relay nodes are untrusted.  Cjdns is
a6396ab
source routed, there is no centralized routing.  If a node is "blackholing"
a6396ab
your packets for some reason - simply doesn't route through that node anymore.
a6396ab
(But see Security below.)  The usual security problems with source routing
a6396ab
don't apply because cjdns IPs can't be (easily) spoofed.
a6396ab
2f8dfd1
## Startup
2f8dfd1
2f8dfd1
The key part of cjdns is the cjdroute background daemon.  To start cjdroute:
2f8dfd1
2f8dfd1
    systemctl start cjdns
2f8dfd1
2f8dfd1
This will generate `/etc/cjdroute.conf` pre-populated with random keys and
2f8dfd1
passwords.  At first startup, cjdroute looks for neighboring cjdns peers
2f8dfd1
on all active network interfaces using a layer 2 (e.g. ethernet) protocol.
a6396ab
This is exactly what you want if you are on a LAN or wifi mesh.  If you only
a6396ab
have a conventional "clearnet" ISP, see the [upstream](README.md) README for
2f8dfd1
instructions on adding peers using the UDP protocol.  (Search for "Find a
2f8dfd1
friend".)
2f8dfd1
2f8dfd1
After adding peers to `/etc/cjdroute.conf`, restart cjdroute with:
2f8dfd1
2f8dfd1
    systemctl restart cjdns
2f8dfd1
2f8dfd1
To have cjdroute start whenever you boot, use
2f8dfd1
2f8dfd1
    systemctl enable cjdns
2f8dfd1
2f8dfd1
If you are on a laptop and suspend or hibernate it, cjdroute will take a few
2f8dfd1
minutes to make coffee and figure out what just happened when it wakes up.  You
2f8dfd1
can speed this up dramatically with:
2f8dfd1
2f8dfd1
    systemctl enable cjdns-resume
2f8dfd1
2f8dfd1
The resume service restarts cjdns when the system wakes up from sleep.
dcdbe47
dcdbe47
For rhel6, use ```start cjdns``` instead of systemctl - ditto for restart
dcdbe47
and stop.
dcdbe47
a6396ab
## Security
dcdbe47
dcdbe47
By default, Fedora Workstation will treat the tun device created by cjdroute as
dcdbe47
"public", with SSH being the only incoming port allowed.  There is no
dcdbe47
additional exposure with cjdns and the default Fedora firewall.  If you have
dcdbe47
modified the firewall config beyond opening additional incoming ports, be sure
dcdbe47
that the cjdns tun is treated as public - because anyone in the world can
dcdbe47
attempt to connect to you through it.  Sometimes, people configure their
dcdbe47
firewall to treat all tun devices as "VPN", and therefore somewhat more
dcdbe47
trusted.  This would be a mistake with cjdns.  It is a VPN, for sure, but one
dcdbe47
anyone in the world can join.
dcdbe47
dcdbe47
Public keys for cjdns are based on Elliptic Curves.  There is a known quantum
dcdbe47
algorithm that could be used to crack them if quantum computers with sufficient
dcdbe47
qubits are ever built.  The solution when that happens is larger keys - which
dcdbe47
are more cumbersome.
dcdbe47
dcdbe47
The Distributed Hash Table algorithm is a core component of cjdns - which is
dcdbe47
vulnerable to a Denial of Service attack known as "Sybil".  This attack can
dcdbe47
block specific updates to the DHT - to prevent your node from joining a mesh,
dcdbe47
for instance.
dcdbe47
dcdbe47
On the positive side, you can safely use telnet to cjdns IPs and the http
dcdbe47
protocol is automatically encrypted (but you need a secure DNS or raw ip to be
dcdbe47
sure you are talking to the right node).  Many other protocols are
dcdbe47
automatically encrypted while using cjdns.  In general, connecting to a raw
dcdbe47
cjdns IP is functionally equivalent to SSL/TLS with both client and server
dcdbe47
authentication.
dcdbe47
dcdbe47
Since the cjdroute core routing code parses network packets from untrusted
dcdbe47
sources, it is a security risk and is heavily sandboxed.  It runs as the cjdns
dcdbe47
user in a chroot jail in an empty directory, with RLIMIT_NPROC set to 1 to
dcdbe47
disable forking.  Seccomp is used to limit available system calls to only those
dcdbe47
actually needed.  Installing the cjdns-selinux package installs a targeted
dcdbe47
selinux policy that also restricts what the privileged process can access.
dcdbe47
0f417ec
### Routing security
dcdbe47
dcdbe47
If cjdns is not running, cjdns packets will get routed in plaintext
dcdbe47
to your default gateway by default.  An attacker could then play
dcdbe47
man-in-the-middle.  If your default gateway is running cjdns, this
dcdbe47
could even happen accidentally.
dcdbe47
dcdbe47
This can be blocked by restricting ```fc00::/8``` to the interface 
0f417ec
used by cjdroute in the firewall.   An even simpler solution is
0f417ec
to not have a "default" route.  Instead route ```2000::/3``` to your
0f417ec
gateway.  All globally routable ips begin with ```001``` as the first
0f417ec
three bits.
0f417ec
0f417ec
### Application security
0f417ec
0f417ec
The squid cache package default config allows ```fc00::/7``` unrestricted
0f417ec
access to the proxy.  If the proxy port is not otherwise firewalled,
0f417ec
you probably want to change this to ```fd00::/8``` when using cjdns
0f417ec
on the proxy server.  Apart from that default config, squid works very
0f417ec
well with cjdns - you can allow specific cjdns ips unrestricted access:
0f417ec
0f417ec
```
0f417ec
acl adultpcs src fc25:dede:dede:dede:dede:dede:dede:dede
0f417ec
acl adultpcs src fc37:daaa:daaa:daaa:daaa:daaa:daaa:daaa 
0f417ec
http_access allow adultpcs
0f417ec
```
dcdbe47
dcdbe47
## Advanced config
dcdbe47
dcdbe47
You may install a network service that depends on cjdns, for instance you might
dcdbe47
install thttpd to serve up
dcdbe47
[nodeinfo.json](https://docs.meshwith.me/en/cjdns/nodeinfo.json.html).  If
dcdbe47
thttpd is configured to listen only on your cjdns IP, then it will not start
dcdbe47
until cjdns is up and running.  Add ```After=cjdns-wait-online.service``` to
dcdbe47
```thttpd.service``` to hold off starting the service until cjdns has the
dcdbe47
tunnel up and ready.
dcdbe47