From 95b485e2f211bf280ae14564e6a21fc313214f4a Mon Sep 17 00:00:00 2001
From: Sergey Matveev <stargrave@stargrave.org>
Date: Sun, 23 Aug 2015 16:01:56 +0300
Subject: [PATCH] [DOC] Refactoring

Signed-off-by: Sergey Matveev <stargrave@stargrave.org>
---
 README                | 17 ++++++----
 doc/developer.texi    |  4 +--
 doc/example.texi      | 10 +++---
 doc/govpn.texi        | 70 +++++++++++++++++++++++++++++++++-------
 doc/identity.texi     |  7 ++++
 doc/installation.texi | 25 +++++++--------
 doc/keywords.texi     | 13 --------
 doc/overview.texi     | 74 -------------------------------------------
 doc/precautions.texi  |  2 +-
 doc/proxy.texi        |  7 ++++
 doc/sources.texi      |  8 ++---
 doc/transport.texi    |  2 +-
 doc/user.texi         |  2 +-
 13 files changed, 108 insertions(+), 133 deletions(-)
 delete mode 100644 doc/keywords.texi
 delete mode 100644 doc/overview.texi

diff --git a/README b/README
index 7fdd2e8..6173be4 100644
--- a/README
+++ b/README
@@ -1,11 +1,14 @@
 GoVPN is simple secure free software virtual private network daemon,
-aimed to be reviewable, secure, DPI-resistant, written on Go.
+aimed to be reviewable, secure, DPI/censorship-resistant, written on Go.
 
-It uses fast PAKE DH A-EKE for mutual strong zero-knowledge peers
-authentication. Data transport is encrypted, authenticated, hides
-message's length and timestamp. PFS property, resistance to dictionary
-attacks, replay attacks. Built-in heartbeating, rehandshaking, real-time
-statistics, IPv4/IPv6-compatibility. GNU/Linux and FreeBSD support.
+It uses fast strong password authenticated key agreement protocol with
+augmented mutual peers authentication (PAKE DH A-EKE). Encrypted,
+authenticated data transport that hides message's length and timestamps.
+Perfect forward secrecy property. Resistance to: offline dictionary
+attacks, replay attacks, client's passwords compromising and dictionary
+attacks on the server side. Built-in heartbeating, rehandshaking,
+real-time statistics. Ability to work through UDP, TCP and HTTP proxies.
+IPv4/IPv6-compatibility. GNU/Linux and FreeBSD support.
 
 GoVPN is free software: see the file COPYING for copying conditions.
 
@@ -20,6 +23,6 @@ subscription and archive access information, or send email with the
 subject "subscribe" to govpn-devel-request@lists.cypherpunks.ru.
 
 Development Git source code repository currently is located here:
-https://github.com/stargrave/govpn.git
+http://git.cypherpunks.ru/cgit.cgi/govpn.git/
 
 For futher information please read either doc/govpn.info or doc/govpn.texi.
diff --git a/doc/developer.texi b/doc/developer.texi
index d7a4b07..7ccd927 100644
--- a/doc/developer.texi
+++ b/doc/developer.texi
@@ -19,10 +19,10 @@ and @url{http://ed25519.cr.yp.to/, Ed25519}.
 @url{https://en.wikipedia.org/wiki/PBKDF2, PBKDF2} based on
 @url{https://en.wikipedia.org/wiki/SHA-2, SHA-512}.
 @item Packet overhead
-26 bytes per packet. Two more bytes for TCP mode.
+26 bytes per packet. Two more bytes in TCP mode.
 @item Handshake overhead
 4 UDP (2 from client, 2 from server) packets (round-trips for TCP),
-264 bytes total payload (8 bytes more for TCP mode).
+264 bytes total payload (8 bytes more in TCP mode).
 @item Entropy required
 832 bits in average on client, 832 bits in average on server side per
 handshake.
diff --git a/doc/example.texi b/doc/example.texi
index 757bd03..a2e4173 100644
--- a/doc/example.texi
+++ b/doc/example.texi
@@ -21,7 +21,7 @@ software: download, check the signature, compile.
 "Alice":
 
 @example
-% ./utils/newclient.sh Alice
+server% ./utils/newclient.sh Alice
 Place verifier to peers/6d4ac605ce8dc37c2f0bf21cb542a713/verifier
 @end example
 
@@ -31,11 +31,11 @@ Place verifier to peers/6d4ac605ce8dc37c2f0bf21cb542a713/verifier
 identity:
 
 @example
-% ./utils/storekey.sh /tmp/passphrase
+client% ./utils/storekey.sh /tmp/passphrase
 Enter passphrase:[my secure passphrase is here]
-% govpn-verifier -id 6d4ac605ce8dc37c2f0bf21cb542a713 -key /tmp/passphrase
+client% govpn-verifier -id 6d4ac605ce8dc37c2f0bf21cb542a713 -key /tmp/passphrase
 562556cc9ecf0019b4cf45bcdf42706944ae9b3ac7c73ad299d83f2d5a169c55
-% rm /tmp/passphrase
+client% rm /tmp/passphrase
 @end example
 
 "562556cc9ecf0019b4cf45bcdf42706944ae9b3ac7c73ad299d83f2d5a169c55" --
@@ -44,7 +44,7 @@ this is verifier itself.
 @strong{Save verifier on server}.
 
 @example
-% cat > peers/6d4ac605ce8dc37c2f0bf21cb542a713/verifier <<EOF
+server% cat > peers/6d4ac605ce8dc37c2f0bf21cb542a713/verifier <<EOF
 562556cc9ecf0019b4cf45bcdf42706944ae9b3ac7c73ad299d83f2d5a169c55
 EOF
 @end example
diff --git a/doc/govpn.texi b/doc/govpn.texi
index c0f622c..c4cd8c9 100644
--- a/doc/govpn.texi
+++ b/doc/govpn.texi
@@ -5,7 +5,8 @@
 
 @copying
 This manual is for GoVPN -- simple secure free software virtual private
-network (VPN) daemon, written entirely on Go programming language.
+network daemon, aimed to be reviewable, secure, DPI/censorship-resistant,
+written on Go.
 
 Copyright @copyright{} 2014-2015 @email{stargrave@@stargrave.org, Sergey Matveev}
 
@@ -22,20 +23,68 @@ A copy of the license is included in the section entitled "Copying conditions".
 @top GoVPN
 
 GoVPN is simple secure free software virtual private network daemon,
-aimed to be reviewable, secure, DPI-resistant, written on Go.
+aimed to be reviewable, secure and
+@url{https://en.wikipedia.org/wiki/Deep_packet_inspection, DPI}/censorship-resistant.
 
-It uses fast PAKE DH A-EKE for mutual strong zero-knowledge peers
-authentication. Data transport is encrypted, authenticated, hides
-message's length and timestamp. PFS property, resistance to dictionary
-attacks, replay attacks. Built-in heartbeating, rehandshaking, real-time
-statistics, IPv4/IPv6-compatibility. GNU/Linux and FreeBSD support.
-
-@include keywords.texi
+@itemize @bullet
+@item
+Copylefted free software: licensed under
+@url{https://www.gnu.org/licenses/gpl-3.0.html, GPLv3+}.
+@item
+Fast strong @ref{PAKE, password authenticated} augmented key agreement
+(PAKE DH A-EKE) @ref{Handshake protocol, handshake}.
+@item
+Mutual two-side zero-knowledge peers authentication.
+@item
+@ref{Verifier structure, Augmented authentication tokens} resistant to
+offline dictionary attacks. An attacker can not masquerade a client
+even with server password verifiers compromising.
+@item
+Encrypted and authenticated @ref{Transport protocol, payload transport}
+with 128-bit @ref{Developer manual, security margin} state-of-the-art
+cryptography and censorship resistance (indistinguishability from noise).
+@item
+@url{https://en.wikipedia.org/wiki/Forward_secrecy, Perfect forward secrecy}
+property.
+@item
+Replay attack protection (using one-time MACs).
+@item
+Built-in rehandshake (session key rotation) and heartbeat features.
+@item
+Ability to hide payload packets length with the @ref{Noise, noise} data.
+@item
+Ability to hide payload timestamps with @ref{CPR, constant packet rate}
+traffic.
+@item
+Compatible with @url{http://egd.sourceforge.net/, EGD} (entropy
+gathering daemon) PRNGs.
+@item
+Several simultaneous clients support with per-client configuration
+options. Clients have pre-established @ref{Identity, identity} invisible
+for third-parties (they are anonymous).
+@item
+Uses @url{https://en.wikipedia.org/wiki/TAP_(network_driver), TAP}
+underlying network interfaces.
+@item
+Can use @ref{Network transport, UDP and TCP} or HTTP @ref{Proxy, proxies}
+for accessing the server.
+@item
+Fully IPv4 and IPv6 compatible.
+@item
+Optional built-in HTTP-server for retrieving
+@ref{Stats, statistics} information about known connected peers in
+@url{http://json.org/, JSON} format.
+@item
+Written on on @url{http://golang.org/, Go} programming language with
+simple code that can be read and reviewed.
+@item
+@url{https://www.gnu.org/, GNU}/Linux and
+@url{http://www.freebsd.org/, FreeBSD} support.
+@end itemize
 
 @include media.texi
 
 @menu
-* Overview::
 * News::
 * Installation::
 * Precautions::
@@ -47,7 +96,6 @@ statistics, IPv4/IPv6-compatibility. GNU/Linux and FreeBSD support.
 * TODO::
 @end menu
 
-@include overview.texi
 @include news.texi
 @include installation.texi
 @include precautions.texi
diff --git a/doc/identity.texi b/doc/identity.texi
index 3288d2e..cb3061f 100644
--- a/doc/identity.texi
+++ b/doc/identity.texi
@@ -4,3 +4,10 @@
 Client's identity is 128-bit string. It is not secret, so can be
 transmitted and stored in the clear. However handshake applies PRP on it
 to make DPI and deanonymization much harder to success.
+
+@example
+% ./utils/newclient.sh doesnotmatter
+Place verifier to peers/6d4ac605ce8dc37c2f0bf21cb542a713/verifier
+@end example
+
+"6d4ac605ce8dc37c2f0bf21cb542a713" is client's identity.
diff --git a/doc/installation.texi b/doc/installation.texi
index bb3faeb..3d496e3 100644
--- a/doc/installation.texi
+++ b/doc/installation.texi
@@ -1,10 +1,15 @@
 @node Installation
 @unnumbered Installation
 
-GoVPN is written on @url{http://golang.org/, Go programming language},
+GoVPN is written on Go programming language and you have to install Go
+compiler (1.5+ version is highly recommended): @code{lang/go} port in
+FreeBSD and @code{golang} package in most GNU/Linux distributions.
 @emph{Make} is recommended for convenient building.
-@url{https://www.gnu.org/software/texinfo/, Texinfo}
-is used for building documentation.
+@url{https://www.gnu.org/software/texinfo/, Texinfo} is used for
+building documentation.
+Possibly you also need to install TUN/TAP interface utilities (depending
+on your operating system): @code{uml-utilities} package in most
+GNU/Linux distributions.
 
 Included required libraries:
 
@@ -15,18 +20,10 @@ Included required libraries:
 @item @code{github.com/bigeagle/water} @tab GNU/Linux @tab BSD 3-Clause
 @end multitable
 
-Get the tarball and run @code{make}.
+Get @ref{Prepared tarballs, the tarball}, check its
+@ref{Tarballs integrity check, authenticity} and run @code{make}.
 @emph{govpn-client}, @emph{govpn-server}, @emph{govpn-verifier}
-binaries will be build in the current directory.
-
-As a prerequisite you must install Go compiler (version 1.5 is highly
-recommended) and possibly TUN/TAP interfaces utilities:
-
-@itemize @bullet
-@item @code{lang/go} port in FreeBSD.
-@item @code{golang} and @code{uml-utilities} packages in GNU/Linux
-distributions.
-@end itemize
+binaries will be built in the current directory:
 
 @example
 % wget http://www.cypherpunks.ru/govpn/download/govpn-2.3.tar.xz
diff --git a/doc/keywords.texi b/doc/keywords.texi
deleted file mode 100644
index 8100179..0000000
--- a/doc/keywords.texi
+++ /dev/null
@@ -1,13 +0,0 @@
-Some keywords describing this project: encryption, authentication, key
-exchange, EKE, Diffie-Hellman, DH, DH-EKE, Augmented EKE, A-EKE,
-security, encrypted key exchange, 128-bit margin, DPI, censorship,
-resistance, free software, GPLv3+, reviewability, easy, simple,
-Curve25519, Ed25519, Elligator, SHA-512, Salsa20, Poly1305, AEAD, XTEA,
-PBKDF2, PRP, signatures, asymmetric cryptography, zero-knowledge
-password proof, PAKE, password, passphrase, password authenticated key
-exchange, perfect forward secrecy, PFS, MAC, nonce, verifier,
-rehandshake, heartbeat, replay attack, MiTM, length hiding, timestamps
-hiding, noise, constant traffic, constant packet rate, CPR, EGD,
-entropy, UDP, TCP, TAP, TAP, VPN, GNU, Linux, FreeBSD, IPv6, dictionary
-attack, mutual authentication, simultaneous clients, JSON, HTTP-server,
-statistics, PRNG, traffic analysis, Go, golang.
diff --git a/doc/overview.texi b/doc/overview.texi
deleted file mode 100644
index 9f7846e..0000000
--- a/doc/overview.texi
+++ /dev/null
@@ -1,74 +0,0 @@
-@node Overview
-@unnumbered Overview
-
-GoVPN is simple secure virtual private network daemon, written entirely
-on @url{http://golang.org/, Go programming language}.
-
-Reviewability, high 128-bit security margin and
-@url{https://en.wikipedia.org/wiki/Deep_packet_inspection, DPI}
-censorship resistance in mind in free software solution are the main
-goals for that daemon. Most modern widespread protocols and their
-implementations in software are too complex to be reviewed, analyzed and
-modified.
-
-@ref{Developer manual, State off art cryptography technologies}. Strong
-mutual authenticated key exchange is invulnerable to man-in-the middle
-attachs.
-@url{https://en.wikipedia.org/wiki/Forward_secrecy, Perfect forward secrecy}
-property guarantees that compromising of long-term authentication keys
-does not lead to previously captured traffic decrypting.
-Compromising of peers password files on server side won't allow attacker
-to masquerade as the client, because of asymmetric @strong{verifiers}
-usage, resistant to dictionary attacks. Rehandshaking ensures session
-keys rotation. One-time keys MAC authentication protects against
-@url{https://en.wikipedia.org/wiki/Replay_attack, replay attacks}.
-
-Server can work with several clients simultaneously. Each client is
-@strong{identified} by 128-bit key, that does not leak during handshake
-and each client stays @strong{anonymous} for MiTM and DPI. All settings
-are applied per-peer separately.
-
-Optional ability to hide payload packets lengths by appending
-@strong{noise} to them during transmission. Ability to generate constant
-packet rate traffic (@strong{CPR}) that will hide even the fact of
-packets appearance, their timestamps.
-
-The only platform specific requirement is TAP network interface support.
-API to that kind of device is different, OS dependent and non portable.
-So only a few operating systems is officially supported. Author has no
-proprietary software to work with, so currently there is lack of either
-popular Microsoft Windows or Apple OS X support.
-
-@itemize @bullet
-@item
-Copylefted free software: licensed under
-@url{https://www.gnu.org/licenses/gpl-3.0.html, GPLv3+}.
-@item
-Works with @url{https://en.wikipedia.org/wiki/TAP_(network_driver), TAP}
-network interfaces on top of either UDP or TCP entirely.
-@item Ability to use HTTP proxies to access TCP server.
-@item
-@url{https://www.gnu.org/, GNU}/Linux and
-@url{http://www.freebsd.org/, FreeBSD} support.
-@item IPv6 compatible.
-@item Encrypted and authenticated payload transport.
-@item Relatively fast handshake.
-@item Password-authenticated key exchange.
-@item Server-side password verifiers are secure against dictionary
-attacks.
-@item Attacker can not masquerade a client even with password files
-compromising.
-@item Replay attack protection.
-@item Perfect forward secrecy property.
-@item Mutual two-side authentication.
-@item Zero knowledge authentication.
-@item Built-in rehandshake and heartbeat features.
-@item Several simultaneous clients support.
-@item Per-client configuration options.
-@item Hiding of payload packets length with noise.
-@item Hiding of payload packets timestamps with constant packet rate
-traffic.
-@item Optional built-in HTTP-server for retrieving information about
-known connected peers in @url{http://json.org/, JSON} format.
-@item Compatibility with @url{http://egd.sourceforge.net/, EGD} PRNGs.
-@end itemize
diff --git a/doc/precautions.texi b/doc/precautions.texi
index 0539822..fad882d 100644
--- a/doc/precautions.texi
+++ b/doc/precautions.texi
@@ -9,7 +9,7 @@ passphrases. Also remember to keep passphrase in temporary file and read
 it securely as described in @ref{Verifier}.
 
 @item
-You must @strong{never} use one key for multiple clients.
+You must @strong{never} use the same key for multiple clients.
 
 @item
 You must use @strong{cryptographically good} pseudo random number
diff --git a/doc/proxy.texi b/doc/proxy.texi
index e5f5b80..0e99035 100644
--- a/doc/proxy.texi
+++ b/doc/proxy.texi
@@ -14,3 +14,10 @@ any external HTTP proxy server can be used.
 Client has @emph{-proxy} option forcing it to connect to proxy and send
 CONNECT method. Optionally it can be authenticated on it using
 @emph{-proxy-auth} HTTP Basic method.
+
+@example
+% govpn-client [...] -proto tcp \
+    -remote "$REMOTE_ADDR":1194 \
+    -proxy 192.168.55.1:8888 \
+    -proxy-auth mylogin:password
+@end example
diff --git a/doc/sources.texi b/doc/sources.texi
index 19cc422..3b7e02c 100644
--- a/doc/sources.texi
+++ b/doc/sources.texi
@@ -1,10 +1,10 @@
 @node Development source code
 @section Development source code
 
-Development source contains the latest version of the code. It may be
-buggy. It does not contain compiled documentation and dependent
-libraries source code. Because of that it is not recommended for
-porters: use prepared tarballs!
+Development source code contains the latest version of the code. It may
+be buggy. It does not contain compiled documentation and dependent
+libraries source code. Because of that, it is not recommended for
+porters: use @ref{Prepared tarballs} instead.
 
 You can obtain it by cloning Git repository and fetching dependent
 libraries source code as git submodules:
diff --git a/doc/transport.texi b/doc/transport.texi
index 26e6d6f..51dc9de 100644
--- a/doc/transport.texi
+++ b/doc/transport.texi
@@ -10,7 +10,7 @@ All transport and handshake messages are indistinguishable from
 pseudo random noise, except when using TCP connections.
 
 @code{PktLen} is used only with TCP connections. It is big-endian
-@emph{uin16} length of the whole packet (except PktLen itself).
+@emph{uint16} length of the whole packet (except @code{PktLen} itself).
 
 @code{SERIAL} is message's serial number. Odds are reserved for
 client(->server) messages, evens for server(->client) messages.
diff --git a/doc/user.texi b/doc/user.texi
index 4139822..0d237a0 100644
--- a/doc/user.texi
+++ b/doc/user.texi
@@ -11,7 +11,7 @@ automate it using up and down shell scripts.
 
 What network performance can user expect? For example single
 @emph{Intel i5-2450M 2.5 GHz} core on @emph{FreeBSD 10.2 amd64}
-with @emph{Go 1.5} gives 435 Mbps TCP throughput.
+with @emph{Go 1.5} gives 435 Mbps TCP (over UDP) throughput.
 
 @menu
 * EGD:: Entropy gathering daemon
-- 
2.44.0