From 2a97f075c9f05b09b03a2ab75f6c68d5ad3709aa Mon Sep 17 00:00:00 2001 From: Daniel Borkmann Date: Sat, 6 Apr 2013 10:40:52 +0200 Subject: [PATCH] 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 --- man/bpfc.8 | 121 +++++++++++++++++++++++++++++++++++ man/curvetun.8 | 196 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 317 insertions(+) create mode 100644 man/bpfc.8 create mode 100644 man/curvetun.8 diff --git a/man/bpfc.8 b/man/bpfc.8 new file mode 100644 index 00000000..42b30527 --- /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 , --input +Read BPF assembly instruction from an input file or from stdin. + +.SS -f , --format +Specify a different output format than the default that is netsniff-ng +compatible. The 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 and Daniel +Borkmann . + +.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 00000000..37208b46 --- /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 and Daniel +Borkmann . + +.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. -- 2.11.4.GIT