commit ba1fe6d23905cdaa4536ce17128c1e2dc90dbe5d Author: George Kadianakis desnacked@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.