]> Cypherpunks.ru repositories - govpn.git/commitdiff
[DOC] Refactoring
authorSergey Matveev <stargrave@stargrave.org>
Sun, 23 Aug 2015 13:01:56 +0000 (16:01 +0300)
committerSergey Matveev <stargrave@stargrave.org>
Sun, 23 Aug 2015 14:04:47 +0000 (17:04 +0300)
Signed-off-by: Sergey Matveev <stargrave@stargrave.org>
13 files changed:
README
doc/developer.texi
doc/example.texi
doc/govpn.texi
doc/identity.texi
doc/installation.texi
doc/keywords.texi [deleted file]
doc/overview.texi [deleted file]
doc/precautions.texi
doc/proxy.texi
doc/sources.texi
doc/transport.texi
doc/user.texi

diff --git a/README b/README
index 7fdd2e87e8c1d227e5a84bad6476aac5cabed460..6173be42fcacc5efa8ff620d25c297b79bd89572 100644 (file)
--- a/README
+++ b/README
@@ -1,11 +1,14 @@
 GoVPN is simple secure free software virtual private network daemon,
 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.
 
 
 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:
 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.
 
 For futher information please read either doc/govpn.info or doc/govpn.texi.
index d7a4b07ea3693f96bb4e8c298e403a3ce3b0cdd7..7ccd9270a353fbb1c9dfb46afde4acb120ae7c38 100644 (file)
@@ -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
 @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),
 @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.
 @item Entropy required
 832 bits in average on client, 832 bits in average on server side per
 handshake.
index 757bd031ad6bdda5ad6e283fdeb3d36222a3eb64..a2e417394bae8f72f5ff759130d30780626bd64c 100644 (file)
@@ -21,7 +21,7 @@ software: download, check the signature, compile.
 "Alice":
 
 @example
 "Alice":
 
 @example
-% ./utils/newclient.sh Alice
+server% ./utils/newclient.sh Alice
 Place verifier to peers/6d4ac605ce8dc37c2f0bf21cb542a713/verifier
 @end example
 
 Place verifier to peers/6d4ac605ce8dc37c2f0bf21cb542a713/verifier
 @end example
 
@@ -31,11 +31,11 @@ Place verifier to peers/6d4ac605ce8dc37c2f0bf21cb542a713/verifier
 identity:
 
 @example
 identity:
 
 @example
-% ./utils/storekey.sh /tmp/passphrase
+client% ./utils/storekey.sh /tmp/passphrase
 Enter passphrase:[my secure passphrase is here]
 Enter passphrase:[my secure passphrase is here]
-% govpn-verifier -id 6d4ac605ce8dc37c2f0bf21cb542a713 -key /tmp/passphrase
+client% govpn-verifier -id 6d4ac605ce8dc37c2f0bf21cb542a713 -key /tmp/passphrase
 562556cc9ecf0019b4cf45bcdf42706944ae9b3ac7c73ad299d83f2d5a169c55
 562556cc9ecf0019b4cf45bcdf42706944ae9b3ac7c73ad299d83f2d5a169c55
-% rm /tmp/passphrase
+client% rm /tmp/passphrase
 @end example
 
 "562556cc9ecf0019b4cf45bcdf42706944ae9b3ac7c73ad299d83f2d5a169c55" --
 @end example
 
 "562556cc9ecf0019b4cf45bcdf42706944ae9b3ac7c73ad299d83f2d5a169c55" --
@@ -44,7 +44,7 @@ this is verifier itself.
 @strong{Save verifier on server}.
 
 @example
 @strong{Save verifier on server}.
 
 @example
-% cat > peers/6d4ac605ce8dc37c2f0bf21cb542a713/verifier <<EOF
+server% cat > peers/6d4ac605ce8dc37c2f0bf21cb542a713/verifier <<EOF
 562556cc9ecf0019b4cf45bcdf42706944ae9b3ac7c73ad299d83f2d5a169c55
 EOF
 @end example
 562556cc9ecf0019b4cf45bcdf42706944ae9b3ac7c73ad299d83f2d5a169c55
 EOF
 @end example
index c0f622c6496db4afd4fbe3741bfb7aa58f6418db..c4cd8c9a82bae4acdc2007f1e638818f427a5f23 100644 (file)
@@ -5,7 +5,8 @@
 
 @copying
 This manual is for GoVPN -- simple secure free software virtual private
 
 @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}
 
 
 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,
 @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
 
 @include media.texi
 
 @menu
-* Overview::
 * News::
 * Installation::
 * Precautions::
 * News::
 * Installation::
 * Precautions::
@@ -47,7 +96,6 @@ statistics, IPv4/IPv6-compatibility. GNU/Linux and FreeBSD support.
 * TODO::
 @end menu
 
 * TODO::
 @end menu
 
-@include overview.texi
 @include news.texi
 @include installation.texi
 @include precautions.texi
 @include news.texi
 @include installation.texi
 @include precautions.texi
index 3288d2ef55eeae508c4b4bc992bd97b88ac44c84..cb3061f4b0abc11accfed9a1f6e0195990a8ab59 100644 (file)
@@ -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.
 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.
index bb3faeb53b96cb0f131c8ff95ba69a2e03398449..3d496e3ead62c6a7fc6af5bd219463e7002958d7 100644 (file)
@@ -1,10 +1,15 @@
 @node Installation
 @unnumbered Installation
 
 @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.
 @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:
 
 
 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
 
 @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}
 @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
 
 @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 (file)
index 8100179..0000000
+++ /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 (file)
index 9f7846e..0000000
+++ /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
index 0539822893cd83d64bec34431b6c73c588c69438..fad882d6b411e0f2f74d1473888a897ba4b94e69 100644 (file)
@@ -9,7 +9,7 @@ passphrases. Also remember to keep passphrase in temporary file and read
 it securely as described in @ref{Verifier}.
 
 @item
 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
 
 @item
 You must use @strong{cryptographically good} pseudo random number
index e5f5b807b03a30920b8c3a8615073ae893066ccf..0e990350df2aa5c45a8ce9d20dba500e72c30369 100644 (file)
@@ -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.
 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
index 19cc422955f401e0f73927fe0302a2845ec1bc3b..3b7e02cf613aae84fa5fa9e1ae65252886bd4f3a 100644 (file)
@@ -1,10 +1,10 @@
 @node Development source code
 @section Development source code
 
 @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:
 
 You can obtain it by cloning Git repository and fetching dependent
 libraries source code as git submodules:
index 26e6d6f59bf7f6f3f97032db0250b6f2398c0166..51dc9de50a03eb6bae6ab8d228144ea7eca31221 100644 (file)
@@ -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
 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.
 
 @code{SERIAL} is message's serial number. Odds are reserved for
 client(->server) messages, evens for server(->client) messages.
index 413982279bdc87a83b0e02f31c921e64f1ed3112..0d237a0130aeae9b7ec3d6ecea833172c42e663a 100644 (file)
@@ -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}
 
 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
 
 @menu
 * EGD:: Entropy gathering daemon