[Pkg-privacy-commits] [obfsproxy] 116/353: Add more documentation and improve the existing.
Ximin Luo
infinity0 at moszumanska.debian.org
Sat Aug 22 13:01:47 UTC 2015
This is an automated email from the git hooks/post-receive script.
infinity0 pushed a commit to branch master
in repository obfsproxy.
commit 00ce28dc38ddad2c7db64df2df6972c3904cbe22
Author: George Kadianakis <desnacked at riseup.net>
Date: Thu Feb 7 15:48:21 2013 +0000
Add more documentation and improve the existing.
Add a TODO and copy the obfs2 docs from the obfsproxy codebase.
---
README | 10 +++-
TODO | 13 +++++
doc/obfs2/obfs2-protocol-spec.txt | 103 ++++++++++++++++++++++++++++++++++++++
doc/obfs2/obfs2-threat-model.txt | 81 ++++++++++++++++++++++++++++++
4 files changed, 205 insertions(+), 2 deletions(-)
diff --git a/README b/README
index 3b3f311..8419d3e 100644
--- a/README
+++ b/README
@@ -1,2 +1,8 @@
-This is a python implementation of the Pluggable Transports for Circumvention specification for Tor:
-https://gitweb.torproject.org/torspec.git/blob_plain/HEAD:/proposals/180-pluggable-transport.txt
+Pyobfsproxy is a pluggable transport proxy written in Python. Its
+architecture is similar to the architecture of Obfsproxy.
+
+See doc/HOWTO.txt for installation instructions.
+
+If you want to write a pluggable transport, see the code of already
+existing transports in obfsproxy/transports/ . Unfortunately a coding
+guide for pluggable transport authors does not exist at the moment!
diff --git a/TODO b/TODO
new file mode 100644
index 0000000..641f0e4
--- /dev/null
+++ b/TODO
@@ -0,0 +1,13 @@
+* Write more transports.
+
+* Write more docs (architecture document, HACKING, etc.)
+
+* Improve the integration testers (especially add better debugging
+ support for when a test fails)
+
+* Kill all the XXXs in the code.
+
+* Convert all the leftover camelCases to underscore_naming.
+
+* Implement a SOCKS client, so that Pyobfsproxy can send its data
+ through a SOCKS proxy.
\ No newline at end of file
diff --git a/doc/obfs2/obfs2-protocol-spec.txt b/doc/obfs2/obfs2-protocol-spec.txt
new file mode 100644
index 0000000..c0b0578
--- /dev/null
+++ b/doc/obfs2/obfs2-protocol-spec.txt
@@ -0,0 +1,103 @@
+ obfs2 (The Twobfuscator)
+
+0. Protocol overview
+
+ This is a protocol obfuscation layer for TCP protocols. Its purpose
+ is to keep a third party from telling what protocol is in use based
+ on message contents. It is based on brl's ssh obfuscation protocol.
+
+ It does not provide authentication or data integrity. It does not
+ hide data lengths. It is more suitable for providing a layer of
+ obfuscation for an existing authenticated protocol, like SSH or TLS.
+
+ The protocol has two phases: in the first phase, the parties
+ establish keys. In the second, the parties exchange superenciphered
+ traffic.
+
+1. Primitives, notation, and constants.
+
+ H(x) is SHA256 of x.
+ H^n(x) is H(x) called iteratively n times.
+
+ E(K,s) is the AES-CTR-128 encryption of s using K as key.
+
+ x | y is the concatenation of x and y.
+ UINT32(n) is the 4 byte value of n in big-endian (network) order.
+ SR(n) is n bytes of strong random data.
+ WR(n) is n bytes of weaker random data.
+ "xyz" is the ASCII characters 'x', 'y', and 'z', not NUL-terminated.
+ s[:n] is the first n bytes of s.
+ s[n:] is the last n bytes of s.
+
+ MAGIC_VALUE is 0x2BF5CA7E
+ SEED_LENGTH is 16
+ MAX_PADDING is 8192
+ HASH_ITERATIONS is 100000
+
+ KEYLEN is the length of the key used by E(K,s) -- that is, 16.
+ IVLEN is the length of the IV used by E(K,s) -- that is, 16.
+
+ HASHLEN is the length of the output of H() -- that is, 32.
+
+ MAC(s, x) = H(s | x | s)
+
+ A "byte" is an 8-bit octet.
+
+ We require that HASHLEN >= KEYLEN + IVLEN
+
+2. Key establishment phase.
+
+ The party who opens the connection is the 'initiator'; the one who
+ accepts it is the 'responder'. Each begins by generating a seed
+ and a padding key as follows. The initiator generates:
+
+ INIT_SEED = SR(SEED_LENGTH)
+ INIT_PAD_KEY = MAC("Initiator obfuscation padding", INIT_SEED)[:KEYLEN]
+
+ And the responder generates:
+
+ RESP_SEED = SR(SEED_LENGTH)
+ RESP_PAD_KEY = MAC("Responder obfuscation padding", INIT_SEED)[:KEYLEN]
+
+ Each then generates a random number PADLEN in range from 0 through
+ MAX_PADDING (inclusive).
+
+ The initiator then sends:
+
+ INIT_SEED | E(INIT_PAD_KEY, UINT32(MAGIC_VALUE) | UINT32(PADLEN) | WR(PADLEN))
+
+ and the responder sends:
+
+ RESP_SEED | E(RESP_PAD_KEY, UINT32(MAGIC_VALUE) | UINT32(PADLEN) | WR(PADLEN))
+
+ Upon receiving the SEED from the other party, each party derives
+ the other party's padding key value as above, and decrypts the next
+ 8 bytes of the key establishment message. If the MAGIC_VALUE does
+ not match, or the PADLEN value is greater than MAX_PADDING, the
+ party receiving it should close the connection immediately.
+ Otherwise, it should read the remaining PADLEN bytes of padding data
+ and discard them.
+
+ Additional keys are then derived as:
+
+ INIT_SECRET = MAC("Initiator obfuscated data", INIT_SEED|RESP_SEED)
+ RESP_SECRET = MAC("Responder obfuscated data", INIT_SEED|RESP_SEED)
+ INIT_KEY = INIT_SECRET[:KEYLEN]
+ INIT_IV = INIT_SECRET[KEYLEN:]
+ RESP_KEY = RESP_SECRET[:KEYLEN]
+ RESP_IV = RESP_SECRET[KEYLEN:]
+
+ The INIT_KEY value keys a stream cipher used to encrypt values from
+ initiator to responder thereafter. The stream cipher's IV is
+ INIT_IV. The RESP_KEY value keys a stream cipher used to encrypt
+ values from responder to initiator thereafter. That stream cipher's
+ IV is RESP_IV.
+
+3. Shared-secret extension
+
+ Optionally, if the client and server share a secret value SECRET,
+ they can replace the MAC function with:
+
+ MAC(s,x) = H^n(s | x | H(SECRET) | s)
+
+ where n = HASH_ITERATIONS.
diff --git a/doc/obfs2/obfs2-threat-model.txt b/doc/obfs2/obfs2-threat-model.txt
new file mode 100644
index 0000000..c13da2c
--- /dev/null
+++ b/doc/obfs2/obfs2-threat-model.txt
@@ -0,0 +1,81 @@
+ Threat model for the obfs2 obfuscation protocol
+
+ George Kadianakis
+ Nick Mathewson
+
+0. Abstract
+
+ We discuss the intended threat model for the 'obfs2' protocol
+ obfuscator, its limitations, and its implications for the protocol
+ design.
+
+ The 'obfs2' protocol is based on Bruce Leidl's obfuscated SSH layer,
+ and is documented in the 'doc/protocol-spec.txt' file in the obfsproxy
+ distribution.
+
+1. Adversary capabilities and non-capabilities
+
+ We assume a censor with limited per-connection resources.
+
+ The adversary controls the infrastructure of the network within and
+ at the edges of her jurisdiction, and she can potentially monitor,
+ block, alter, and inject traffic anywhere within this region.
+
+ However, the adversary's computational resources are limited.
+ Specifically, the adversary does not have the resources in her
+ censorship infrastructure to store very much long-term information
+ about any given IP or connection.
+
+ The adversary also holds a blacklist of network protocols, which she
+ is interested in blocking. We assume that the adversary does not have
+ a complete list of specific IPs running that protocol, though
+ preventing this is out-of-scope.
+
+2. The adversary's goals
+
+ The censor wants to ban particular encrypted protocols or
+ applications, and is willing to tolerate some collateral damage, but
+ is not willing to ban all encrypted traffic entirely.
+
+3. Goals of obfs2
+
+ Currently, most attackers in the category described above implement
+ their censorship by one or more firewalls that looking for protocol
+ signatures and block protocols matching those signatures. These
+ signatures are typically in the form of static strings to be matched
+ or regular expressions to be evaluated, over a packet or TCP flow.
+
+ obfs2 attempts to counter the above attack by removing content
+ signatures from network traffic. obfs2 encrypts the traffic stream
+ with a stream cipher, which results in the traffic looking uniformly
+ random.
+
+4. Non-goals of obfs2
+
+ obfs2 was designed as a proof-of-concept for Tor's pluggable
+ transport system: it is simple, useable and easily implementable. It
+ does _not_ try to protect against more sophisticated adversaries.
+
+ obfs2 does not try to protect against non-content protocol
+ fingerprints, like the packet size or timing.
+
+ obfs2 does not try to protect against attackers capable of measuring
+ traffic entropy.
+
+ obfs2 (in its default configuration) does not try to protect against
+ Deep Packet Inspection machines that expect the obfs2 protocol and
+ have the resources to run it. Such machines can trivially retrieve
+ the decryption key off the traffic stream and use it to decrypt obfs2
+ and detect the Tor protocol.
+
+ obfs2 assumes that the underlying protocol provides (or does not
+ need!) integrity, confidentiality, and authentication; it provides
+ none of those on its own.
+
+ In other words, obfs2 does not try to protect against anything other
+ than fingerprintable TLS content patterns.
+
+ That said, obfs2 is not useless. It protects against many real-life
+ Tor traffic detection methods currentl deployed, since most of them
+ currently use static SSL handshake strings as signatures.
+
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-privacy/packages/obfsproxy.git
More information about the Pkg-privacy-commits
mailing list