commit ba1fe6d23905cdaa4536ce17128c1e2dc90dbe5d
Author: George Kadianakis <desnacked(a)riseup.net>
Date: Thu Jan 12 15:29:17 2012 +0200
Move the obfs2 specification and threat model to doc/obfs2/.
---
doc/obfs2/protocol-spec.txt | 103 +++++++++++++++++++++++++++++++++++++++++++
doc/obfs2/threat-model.txt | 81 +++++++++++++++++++++++++++++++++
doc/obfs2_threat_model.txt | 81 ---------------------------------
doc/protocol-spec.txt | 103 -------------------------------------------
4 files changed, 184 insertions(+), 184 deletions(-)
diff --git a/doc/obfs2/protocol-spec.txt b/doc/obfs2/protocol-spec.txt
new file mode 100644
index 0000000..c0b0578
--- /dev/null
+++ b/doc/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/threat-model.txt b/doc/obfs2/threat-model.txt
new file mode 100644
index 0000000..c13da2c
--- /dev/null
+++ b/doc/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.
+
diff --git a/doc/obfs2_threat_model.txt b/doc/obfs2_threat_model.txt
deleted file mode 100644
index c13da2c..0000000
--- a/doc/obfs2_threat_model.txt
+++ /dev/null
@@ -1,81 +0,0 @@
- 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.
-
diff --git a/doc/protocol-spec.txt b/doc/protocol-spec.txt
deleted file mode 100644
index c0b0578..0000000
--- a/doc/protocol-spec.txt
+++ /dev/null
@@ -1,103 +0,0 @@
- 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.
