man: man page updates for bpfc, curvetun

These are the writings so far. For sure they are not yet finished, so
I will push updates for both of them as soon as possible, but for now
this is a first version people can start to read.

Signed-off-by: Daniel Borkmann <dborkman@redhat.com>

2 files changed, 317 insertions, 0 deletions

diff --git a/man/bpfc.8 b/man/bpfc.8
new file mode 100644
index 0000000..42b3052
--- /dev/null
+++ b/man/bpfc.8
@@ -0,0 +1,121 @@
+.\" netsniff-ng - the packet sniffing beast
+.\" Copyright 2013 Daniel Borkmann.
+.\" Subject to the GPL, version 2.
+
+.TH BPFC 8 "03 March 2013" "Linux" "netsniff-ng toolkit"
+.SH NAME
+bpfc \- a Berkeley Packet Filter assembler/compiler
+
+.SH SYNOPSIS
+
+\fB bpfc\fR { [\fIoptions\fR] | [\fIsource-file\fR] }
+
+.SH DESCRIPTION
+
+bpfc is a small Berkeley Packet Filter assembler/compiler which is able to
+translate BPF assembler-like mnemonics into a numerical or C-like format,
+that can be read by tools such as netsniff-ng, iptables (xt_bpf) and many
+others. BPF is the one and only upstream filtering construct that is used
+in combination with packet(7) sockets. The Linux kernel and also BSD kernels
+implement ``virtual machine'' like constructs and JIT compilers that mimic
+a small register-based machine in BPF architecture and execute filter code
+that is e.g. composed by bpfc on a data buffer that is given by network
+packets. The purpose of this is to shift computation in time, so that the
+kernel can drop (or truncate) incoming packets as early as possible without
+having to push them to user space for further analysis first. Meanwhile,
+BPF constructs also find application in other areas like the communication
+between user and kernel space.
+
+By the time of writing this man page, the only available BPF compiler is
+part of the pcap(3) library and accessible through a high-level filter
+language that might be familiar for many people as tcpdump-like filters.
+
+However, quite often, it is useful to bypass that compiler and write
+optimized code that couldn't be produced by the pcap(3) compiler, was
+wrongly optimized, or is defective on purpose in order to debug test kernel
+code. Also, a reason to use bpfc could be to try out some new BPF extensions
+that are not supported by other compilers. Furthermore, bpfc can be of good
+use to verify JIT compiler behaviour or to find possible bugs that need
+to be fixed.
+
+bpfc is implemented with the help of flex(1) and bison(1), tokenizes the
+source file in a first stage and parses it's content into an AST. In two
+code generation stages it emits target opcodes. bpfc furthermore supports
+Linux kernel BPF extensions. More about that can be found in the syntax
+section.
+
+The Linux kernel BPF JIT compiler is automatically turned on if detected
+by netsniff-ng. However, it can also be manually turned on through the
+command ``echo "1" > /proc/sys/net/core/bpf_jit_enable'' (normal working
+mode) or ``echo "2" > /proc/sys/net/core/bpf_jit_enable'' (debug mode
+where emitted opcodes of the image are printed to the kernel log). An
+architecture generic BPF JIT image disassembler can be found in the kernel
+source tree under: tools/net/bpf_jit_disasm.c
+
+.SH OPTIONS
+
+.SS -i <source-file/->, --input <source-file/->
+Read BPF assembly instruction from an input file or from stdin.
+
+.SS -f <format>, --format <format>
+Specify a different output format than the default that is netsniff-ng
+compatible. The <format> specifier can be: C, netsniff-ng, xt_bpf, tcpdump.
+
+.SS -b, --bypass
+Bypass basic filter validation when emitting opcodes. This can be useful
+for explicitly creating malformed BPF expressions that should be injected
+into the kernel, e.g. for bug testing.
+
+.SS -V, --verbose
+Be more verbose and display some bpfc debugging information.
+
+.SS -v, --version
+Show versioning information.
+
+.SS -h, --help
+Show user help.
+
+.SH SYNTAX
+
+.SH SOURCE EXAMPLES
+
+.SH USAGE EXAMPLE
+
+.SS bpfc fubar
+Compile the source file ``fubar'' into BPF opcodes. Opcodes will be
+directed to stdout.
+
+.SS bpfc -f xt_bpf -b -i fubar, resp. iptables -A INPUT -m bpf --bytecode "`bpfc -f xt_bpf -i fubar`" -j LOG
+Compile the source file ``fubar'' into BPF opcodes, bypass basic filter
+validation and emit opcodes in netfilter's xt_bpf readable format.
+
+.SS bpfc -
+Read bpfc instruction from stdin and emit opcodes to stdout.
+
+.SS bpfc foo > bar, resp. netsniff-ng -f bar ...
+Compile filter instructions from file foo and redirect bpfc's output into
+the file bar, that can then be read by netsniff-ng(8) through option -f.
+
+.SS bpfc -f tcpdump -i fubar
+Output opcodes from source file fubar in the same behaviour as ``tcpdump -ddd''.
+
+.SH LEGAL
+bpfc is licensed under the GNU GPL version 2.0.
+
+.SH HISTORY
+.B bpfc
+was originally written for the netsniff-ng toolkit by Daniel Borkmann. It
+is currently maintained by Tobias Klauser <tklauser@distanz.ch> and Daniel
+Borkmann <dborkma@tik.ee.ethz.ch>.
+
+.SH SEE ALSO
+.BR netsniff-ng (8),
+.BR trafgen (8),
+.BR mausezahn (8),
+.BR ifpps (8),
+.BR flowtop (8),
+.BR astraceroute (8),
+.BR curvetun (8)
+
+.SH AUTHOR
+Manpage was written by Daniel Borkmann.
diff --git a/man/curvetun.8 b/man/curvetun.8
new file mode 100644
index 0000000..37208b4
--- /dev/null
+++ b/man/curvetun.8
@@ -0,0 +1,196 @@
+.\" netsniff-ng - the packet sniffing beast
+.\" Copyright 2013 Daniel Borkmann.
+.\" Subject to the GPL, version 2.
+
+.TH CURVETUN 8 "03 March 2013" "Linux" "netsniff-ng toolkit"
+.SH NAME
+curvetun \- a lightweight Curve25519 IP tunnel
+
+.SH SYNOPSIS
+
+\fB curvetun\fR [\fIoptions\fR]
+
+.SH DESCRIPTION
+curvetun is a lightweight, high-speed ECDH multiuser IP tunnel for Linux
+that is based on epoll(2). curvetun uses the Linux TUN/TAP interface and
+supports {IPv4, IPv6} over {IPv4, IPv6} with UDP or TCP as carrier protocols.
+
+It has an integrated packet forwarding trie, thus multiple users with
+different IPs can be handled via a single tunnel device on the server side
+and flows are scheduled for processing in a CPU affine way, at least in case
+of TCP as a carrier protocol.
+
+As key management, public-key cryptography based on elliptic curves are being
+used and packets are encrypted end-to-end by the symmetric stream cipher
+Salsa20 and authenticated by the MAC Poly1305, where keys have previously
+been computed with the ECDH key agreement protocol Curve25519.
+
+Cryptography is based on Daniel J. Bernstein's networking and cryptography
+library ``NaCl''. By design, curvetun does not provide any particular pattern
+or default port numbers that gives certainty that the connection from a
+particular flow is actually running curvetun.
+
+However, if you have further needs to bypass censorship, you can try using
+curvetun in combination with Tor's obfsproxy or Telex. Furthermore, curvetun
+also protects you against replay attacks and DH man in the middle.
+Additionally, server-side syslog event logging can also be disabled to not
+reveal any critical user connection data.
+
+.IP " 1." 4
+obfsproxy from the TOR project
+.RS 4
+\%https://www.torproject.org/projects/obfsproxy.html.en
+.RE
+
+.IP " 2." 4
+Telex, anticensorship in the network infrastructure
+.RS 4
+\%https://telex.cc/
+.RE
+
+.SH OPTIONS
+
+todo
+
+.SH CRYPTOGRAPHY
+IP tunnels are usually used to create virtual private networks (VPN), where
+parts of the network can only be reached via an unsecure or untrusted underlay
+network like the Internet. Only few software exists to create such tunnels,
+or, VPNs. Two popular representatives of such software are OpenVPN and VTUN.
+
+The latter also introduced the TUN/TAP interfaces into the Linux kernel. VTUN
+only has a rather basic encryption module, that doesn't fit into todays
+cryptographic needs. By default MD5 is used to create 128-Bit wide keys for
+the symmetric BlowFish cipher in ECB mode [1].
+
+Although OpenSSL is used in both, VTUN and OpenVPN, OpenVPN is much more
+feature rich regarding ciphers and user authentication. Nevertheless, letting
+people choose ciphers or authentication methods does not necessarily mean a
+good thing: administrators could either prefer speed over security and
+therefore choose weak ciphers, so that the communication system will be as
+good as without any cipher; they could choose weak passwords for symmetric
+encryption or they could misconfigure the communication system by having too
+much choices of ciphers and too little experience for picking the right one.
+
+Next to the administration issues, there are also software development issues.
+Cryptographic libraries like OpenSSL are a huge mess and too low-level and
+complex to probably fully understand or correctly apply, so that they form a
+further ground for vulnerabilities of such software.
+
+In 2010, the cryptographers Tanja Lange and Daniel J. Bernstein have therefore
+created and published a cryptography library for networking, which is called
+NaCl (pronounced ``salt''). NaCl challenges such addressed problems as in
+OpenSSL and, in contrast to the rather generic use of OpenSSL, was created
+with a strong focus on public-key authenticated encryption based on elliptic
+curve cryptography, which is used in curvetun. Partially quoting Daniel J.
+Bernstein:
+
+RSA is somewhat older than elliptic-curve cryptography: RSA was introduced
+in 1977, while elliptic-curve cryptography was introduced in 1985. However,
+RSA has shown many more weaknesses than elliptic-curve cryptography. RSA's
+effective security level was dramatically reduced by the linear sieve in the
+late 1970s, by the quadratic sieve and ECM in the 1980s, and by the
+number-field sieve in the 1990s. For comparison, a few attacks have been
+developed against some rare elliptic curves having special algebraic
+structures, and the amount of computer power available to attackers has
+predictably increased, but typical elliptic curves require just as much
+computer power to break today as they required twenty years ago.
+
+IEEE P1363 standardized elliptic-curve cryptography in the late 1990s,
+including a stringent list of security criteria for elliptic curves. NIST
+used the IEEE P1363 criteria to select fifteen specific elliptic curves at
+five different security levels. In 2005, NSA issued a new ``Suite B''
+standard, recommending the NIST elliptic curves (at two specific security
+levels) for all public-key cryptography and withdrawing previous
+recommendations of RSA.
+
+curvetun uses a particular elliptic curve, Curve25519, introduced in the
+following paper: Daniel J. Bernstein, ``Curve25519: new Diffie-Hellman speed
+records,'' pages 207-228 in Proceedings of PKC 2006, edited by Moti Yung,
+Yevgeniy Dodis, Aggelos Kiayias, and Tal Malkin, Lecture Notes in Computer
+Science 3958, Springer, 2006, ISBN 3-540-33851-9.
+
+This elliptic curve follows all of the standard IEEE P1363 security criteria.
+It also follows new recommendations that achieve ``side-channel immunity''
+and ``twist security'' while improving speed. What this means is that secure
+implementations of Curve25519 are considerably simpler and faster than secure
+implementations of (e.g.) NIST P-256; there are fewer opportunities for
+implementors to make mistakes that compromise security, and mistakes are
+more easily caught by reviewers.
+
+An attacker who spends a billion dollars on special-purpose chips to attack
+Curve25519, using the best attacks available today, has about 1 chance in
+1000000000000000000000000000 of breaking Curve25519 after a year of computation.
+One could achieve similar levels of security with 3000-bit RSA, but
+encryption and authentication with 3000-bit RSA are not nearly fast enough
+to handle tunnel traffic and would require much more space in network
+packets.
+
+.IP " 1." 4
+Security analysis of VTun
+.RS 4
+\%http://www.off.net/~jme/vtun_secu.html
+.RE
+
+.IP " 2." 4
+NaCl: Networking and Cryptography library
+.RS 4
+\%http://nacl.cr.yp.to/
+.RE
+
+.SH SETUP EXAMPLE
+If you've never run curvetun before, you need to do an initial setup once.
+
+At first, make sure that the servers and clients clocks are periodically
+synced, for instance, by running a ntp daemon. This is necessary to protect
+against replay attacks. Also, make sure if you have read and write access to
+/dev/net/tun. You should not run curvetun as root! Then, after you assured
+this, the first step is to generate keys and config files. On both, the client
+and server do:
+
+.B curvetun -k
+
+You are asked for a username. You can use an email address or whatever suits
+you. Here, we assume, you've entered 'mysrv1' on the server and 'myclient1'
+on the client side.
+
+Now, all necessary file have been created under ~/.curvetun. Files include
+``priv.key'', ``pub.key'', ``username', ``clients'' and ``servers''.
+
+``clients'' and ``servers'' are empty at the beginning and need to be filled.
+The ``clients'' file is meant for the server, so that it knows what clients
+are allowed to connect. The ``servers'' file is for the client, where it can
+select curvetun servers to connect to. Both files are kept very simple, so that
+a single configuration line per client or server is sufficient.
+
+The client needs to export it's public key data for the server:
+
+.B curvetun -x
+
+todo
+
+.SH NOTE
+This software is an experimental prototype intended for researchers. Likely,
+it will mature over time, but it is currently not advised using this software
+when life is put at risk.
+
+.SH LEGAL
+curvetun is licensed under the GNU GPL version 2.0.
+
+.SH HISTORY
+.B curvetun
+was originally written for the netsniff-ng toolkit by Daniel Borkmann. It is
+currently maintained by Tobias Klauser <tklauser@distanz.ch> and Daniel
+Borkmann <dborkma@tik.ee.ethz.ch>.
+
+.SH SEE ALSO
+.BR netsniff-ng (8),
+.BR trafgen (8),
+.BR mausezahn (8),
+.BR bpfc (8),
+.BR ifpps (8),
+.BR flowtop (8),
+.BR astraceroute (8)
+
+.SH AUTHOR
+Manpage was written by Daniel Borkmann.