February 2018 - tor-commits - lists.torproject.org

[stem/master] Support CREATE_FAST and CREATED_FAST cells
by atagar＠torproject.org 07 Feb '18

07 Feb '18

commit 32188dd28f20170f8d2b2dd1da73e29b47bac1a2 Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Jan 21 20:24:35 2018 -0800 Support CREATE_FAST and CREATED_FAST cells --- stem/client/cell.py | 125 ++++++++++++++++++++++++++++++++++++++--------- test/unit/client/cell.py | 31 ++++++++++++ 2 files changed, 133 insertions(+), 23 deletions(-) diff --git a/stem/client/cell.py b/stem/client/cell.py index 3a596b9c..6f107b79 100644 --- a/stem/client/cell.py +++ b/stem/… [View More]client/cell.py @@ -49,6 +49,7 @@ from stem.util import _hash_attr, datetime_to_unix FIXED_PAYLOAD_LEN = 509 AUTH_CHALLENGE_SIZE = 32 +HASH_LEN = 20 class Cell(object): @@ -120,7 +121,7 @@ class Cell(object): raise ValueError('%s cell should have a payload of %i bytes, but only had %i' % (cls.NAME, payload_len, len(content))) payload, content = split(content, payload_len) - return cls._unpack(payload, link_version, circ_id), content + return cls._unpack(payload, circ_id, link_version), content @classmethod def _pack(cls, link_version, payload, circ_id = 0): @@ -144,6 +145,15 @@ class Cell(object): :raise: **ValueError** if cell type invalid or payload is too large """ + if isinstance(cls, CircuitCell) and circ_id is None: + if cls.NAME.startswith('CREATE'): + # Since we're initiating the circuit we pick any value from a range + # that's determined by our link version. + + circ_id = 0x80000000 if link_version > 3 else 0x01 + else: + raise ValueError('%s cells require a circ_id' % cls.NAME) + cell = io.BytesIO() cell.write(Size.LONG.pack(circ_id) if link_version > 3 else Size.SHORT.pack(circ_id)) cell.write(Size.CHAR.pack(cls.VALUE)) @@ -189,30 +199,12 @@ class Cell(object): class CircuitCell(Cell): """ Cell concerning circuits. - """ - - @classmethod - def _pack(cls, link_version, payload, circ_id): - """ - Provides bytes that can be used on the wire for these cell attributes. - - :param str name: cell command - :param int link_version: link protocol version - :param bytes payload: cell payload - :param int circ_id: circuit id - - :raise: **ValueError** if cell type invalid or payload is too large - """ - - if circ_id is None and cls.NAME.startswith('CREATE'): - # Since we're initiating the circuit we pick any value from a range - # that's determined by our link version. - circ_id = 0x80000000 if link_version > 3 else 0x01 - else: - raise ValueError('%s cells require a circ_id' % cls.NAME) + :var int circ_id: circuit id + """ - return Cell._pack(link_version, payload, circ_id) + def __init__(self, circ_id): + self.circ_id = circ_id class PaddingCell(Cell): @@ -275,16 +267,103 @@ class DestroyCell(CircuitCell): class CreateFastCell(CircuitCell): + """ + Create a circuit with our first hop. This is lighter weight than further hops + because we've already established the relay's identity and secret key. + + :var bytes key_material: randomized key material + """ + NAME = 'CREATE_FAST' VALUE = 5 IS_FIXED_SIZE = True + def __init__(self, circ_id, key_material): + super(CreateFastCell, self).__init__(circ_id) + self.key_material = key_material + + @classmethod + def pack(cls, link_version, circ_id, key_material = None): + """ + Provides a randomized circuit construction payload. + + :param int link_version: link protocol version + :param int circ_id: circuit id + :param bytes key_material: randomized key material + + :returns: **bytes** with our randomized key material + """ + + if key_material and len(key_material) != HASH_LEN: + raise ValueError('Key material should be %i bytes, but was %i' % (HASH_LEN, len(key_material))) + + return cls._pack(link_version, key_material if key_material else os.urandom(HASH_LEN), circ_id) + + @classmethod + def _unpack(cls, content, circ_id, link_version): + content = content.rstrip(ZERO) + + if len(content) != HASH_LEN: + raise ValueError('Key material should be %i bytes, but was %i' % (HASH_LEN, len(content))) + + return CreateFastCell(circ_id, content) + + def __hash__(self): + return _hash_attr(self, 'key_material') + class CreatedFastCell(CircuitCell): + """ + CREATE_FAST reply. + + :var bytes key_material: randomized key material + :var bytes derivative_key: hash proving the relay knows our shared key + """ + NAME = 'CREATED_FAST' VALUE = 6 IS_FIXED_SIZE = True + def __init__(self, circ_id, key_material, derivative_key): + super(CreatedFastCell, self).__init__(circ_id) + self.key_material = key_material + self.derivative_key = derivative_key + + @classmethod + def pack(cls, link_version, circ_id, derivative_key, key_material = None): + """ + Provides a randomized circuit construction payload. + + :param int link_version: link protocol version + :param int circ_id: circuit id + :param bytes derivative_key: hash proving the relay knows our shared key + :param bytes key_material: randomized key material + + :returns: **bytes** with our randomized key material + """ + + if key_material and len(key_material) != HASH_LEN: + raise ValueError('Key material should be %i bytes, but was %i' % (HASH_LEN, len(key_material))) + elif len(derivative_key) != HASH_LEN: + raise ValueError('Derivatived key should be %i bytes, but was %i' % (HASH_LEN, len(derivative_key))) + + if not key_material: + key_material = os.urandom(HASH_LEN) + + return cls._pack(link_version, key_material + derivative_key, circ_id) + + @classmethod + def _unpack(cls, content, circ_id, link_version): + content = content.rstrip(ZERO) + + if len(content) != HASH_LEN * 2: + raise ValueError('Key material and derivatived key should be %i bytes, but was %i' % (HASH_LEN * 2, len(content))) + + return CreatedFastCell(circ_id, content[:HASH_LEN], content[HASH_LEN:]) + + def __hash__(self): + return _hash_attr(self, 'derivative_key', 'key_material') + class VersionsCell(Cell): """ diff --git a/test/unit/client/cell.py b/test/unit/client/cell.py index 22de54d9..577114c3 100644 --- a/test/unit/client/cell.py +++ b/test/unit/client/cell.py @@ -13,6 +13,8 @@ from stem.client.cell import ( FIXED_PAYLOAD_LEN, Cell, PaddingCell, + CreateFastCell, + CreatedFastCell, VersionsCell, NetinfoCell, VPaddingCell, @@ -27,6 +29,14 @@ PADDING_CELLS = { '\x00\x00\x00' + RANDOM_PAYLOAD: RANDOM_PAYLOAD, } +CREATE_FAST_CELLS = { + ('\x80\x00\x00\x00\x05\x92O\x0c\xcb\xa8\xac\xfb\xc9\x7f\xd0\rz\x1a\x03u\x91\xceas\xce' + ZERO * 489): (2147483648, '\x92O\x0c\xcb\xa8\xac\xfb\xc9\x7f\xd0\rz\x1a\x03u\x91\xceas\xce'), +} + +CREATED_FAST_CELLS = { + ('\x80\x00\x00\x00\x06\x92O\x0c\xcb\xa8\xac\xfb\xc9\x7f\xd0\rz\x1a\x03u\x91\xceas\xce\x13Z\x99\xb2\x1e\xb6\x05\x85\x17\xfc\x1c\x00{\xa9\xae\x83^K\x99\xb2' + ZERO * 469): (2147483648, '\x92O\x0c\xcb\xa8\xac\xfb\xc9\x7f\xd0\rz\x1a\x03u\x91\xceas\xce', '\x13Z\x99\xb2\x1e\xb6\x05\x85\x17\xfc\x1c\x00{\xa9\xae\x83^K\x99\xb2'), +} + VERSIONS_CELLS = { '\x00\x00\x07\x00\x00': [], '\x00\x00\x07\x00\x02\x00\x01': [1], @@ -118,6 +128,27 @@ class TestCell(unittest.TestCase): self.assertEqual(cell_bytes, PaddingCell.pack(2, payload)) self.assertEqual(payload, Cell.unpack(cell_bytes, 2)[0].payload) + def test_create_fast(self): + for cell_bytes, (circ_id, key_material) in CREATE_FAST_CELLS.items(): + self.assertEqual(cell_bytes, CreateFastCell.pack(5, circ_id, key_material)) + + cell = Cell.unpack(cell_bytes, 5)[0] + self.assertEqual(circ_id, cell.circ_id) + self.assertEqual(key_material, cell.key_material) + + self.assertRaisesRegexp(ValueError, 'Key material should be 20 bytes, but was 3', CreateFastCell.pack, 2, 5, 'boo') + + def test_created_fast(self): + for cell_bytes, (circ_id, key_material, derivative_key) in CREATED_FAST_CELLS.items(): + self.assertEqual(cell_bytes, CreatedFastCell.pack(5, circ_id, derivative_key, key_material)) + + cell = Cell.unpack(cell_bytes, 5)[0] + self.assertEqual(circ_id, cell.circ_id) + self.assertEqual(key_material, cell.key_material) + self.assertEqual(derivative_key, cell.derivative_key) + + self.assertRaisesRegexp(ValueError, 'Key material should be 20 bytes, but was 3', CreateFastCell.pack, 2, 5, 'boo') + def test_versions_packing(self): for cell_bytes, versions in VERSIONS_CELLS.items(): self.assertEqual(cell_bytes, VersionsCell.pack(versions)) [View Less]

1 0

[stem/master] Initial attempt at a Circuit class
by atagar＠torproject.org 07 Feb '18

07 Feb '18

commit ce8d1ff8f922ccda30a9edeef91adf61eded7024 Author: Damian Johnson <atagar(a)torproject.org> Date: Wed Jan 31 12:34:28 2018 -0800 Initial attempt at a Circuit class Haven't a clue if this is close to what we want, but lets just get something down to get this ball rolling. --- stem/client/__init__.py | 38 +++++++++++++++++++++++++++++++++++--- 1 file changed, 35 insertions(+), 3 deletions(-) diff --git a/stem/client/__init__.py b/stem/client/__init__.py index … [View More]f3e842c6..0accaa59 100644 --- a/stem/client/__init__.py +++ b/stem/client/__init__.py @@ -13,9 +13,6 @@ a wrapper for :class:`~stem.socket.RelaySocket`, much the same way as split - splits bytes into substrings - KDF - KDF-TOR derivatived attributes - +- from_value - parses key material - Field - Packable and unpackable datatype. |- Size - Field of a static size. |- Address - Relay address. @@ -25,6 +22,9 @@ a wrapper for :class:`~stem.socket.RelaySocket`, much the same way as |- unpack - decodes content +- pop - decodes content with remainder + KDF - KDF-TOR derivatived attributes + +- from_value - parses key material + .. data:: AddrType (enum) Form an address takes. @@ -114,6 +114,7 @@ import hashlib import io import struct +import stem.prereq import stem.util.connection import stem.util.enum @@ -498,6 +499,37 @@ class KDF(collections.namedtuple('KDF', ['key_hash', 'forward_digest', 'backward return KDF(key_hash, forward_digest, backward_digest, forward_key, backward_key) +class Circuit(collections.namedtuple('Circuit', ['id', 'forward_digest', 'backward_digest', 'forward_key', 'backward_key'])): + """ + Circuit through which requests can be made of a `Tor relay's ORPort + <https://gitweb.torproject.org/torspec.git/tree/tor-spec.txt>`_. + + :var int id: circuit id + :var hashlib.sha1 forward_digest: digest for forward integrity check + :var hashlib.sha1 backward_digest: digest for backward integrity check + :var bytes forward_key: forward encryption key + :var bytes backward_key: backward encryption key + """ + + @staticmethod + def from_kdf(circ_id, kdf): + if not stem.prereq.is_crypto_available(): + raise ImportError('Circuit construction requires the cryptography module') + + from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes + from cryptography.hazmat.backends import default_backend + + ctr = modes.CTR(ZERO * (algorithms.AES.block_size / 8)) + + return Circuit( + circ_id, + hashlib.sha1(kdf.forward_digest), + hashlib.sha1(kdf.backward_digest), + Cipher(algorithms.AES(kdf.forward_key), ctr, default_backend()).encryptor(), + Cipher(algorithms.AES(kdf.backward_key), ctr, default_backend()).decryptor(), + ) + + setattr(Size, 'CHAR', Size('CHAR', 1, '!B')) setattr(Size, 'SHORT', Size('SHORT', 2, '!H')) setattr(Size, 'LONG', Size('LONG', 4, '!L')) [View Less]

1 0

[stem/master] Rename Cell.unpack to Cell.pop
by atagar＠torproject.org 07 Feb '18

07 Feb '18

commit 28467fc87102069fabb1b5b496725f9e9855256e Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Jan 28 12:48:46 2018 -0800 Rename Cell.unpack to Cell.pop Usually when we unpack cells we'll want to process everything from a response. As such having Cell.unpack provide a generator, and renaming our previous function that unpacked a single cell to Cell.pop. --- stem/client/cell.py | 30 +++++++++++++++++++++++++----- test/unit/client/cell.py | 42 +++++… [View More]++++++++++++++++--------------------- 2 files changed, 46 insertions(+), 26 deletions(-) diff --git a/stem/client/cell.py b/stem/client/cell.py index e2e589f5..59fbc14c 100644 --- a/stem/client/cell.py +++ b/stem/client/cell.py @@ -32,8 +32,9 @@ Messages communicated over a Tor relay's ORPort. |- AuthenticateCell - Client authentication. (section 4.5) |- AuthorizeCell - Client authorization. (not yet used) | - |- pack - Provides encoded bytes for this cell class. - +- unpack - Decodes bytes for this cell class. + |- pack - encodes cell into bytes + |- unpack - decodes series of cells + +- pop - decodes cell with remainder """ import datetime @@ -95,9 +96,31 @@ class Cell(object): raise ValueError("'%s' isn't a valid cell value" % value) + def pack(self, link_version): + raise NotImplementedError('Unpacking not yet implemented for %s cells' % type(self).NAME) + @staticmethod def unpack(content, link_version): """ + Unpacks all cells from a response. + + :param bytes content: payload to decode + :param int link_version: link protocol version + + :returns: :class:`~stem.client.cell.Cell` generator + + :raises: + * ValueError if content is malformed + * NotImplementedError if unable to unpack any of the cell types + """ + + while content: + cell, content = Cell.pop(content, link_version) + yield cell + + @staticmethod + def pop(content, link_version): + """ Unpacks the first cell. :param bytes content: payload to decode @@ -125,9 +148,6 @@ class Cell(object): payload, content = split(content, payload_len) return cls._unpack(payload, circ_id, link_version), content - def pack(self, link_version): - raise NotImplementedError('Unpacking not yet implemented for %s cells' % type(self).NAME) - @classmethod def _pack(cls, link_version, payload, circ_id = 0): """ diff --git a/test/unit/client/cell.py b/test/unit/client/cell.py index ba28238e..1fde76cf 100644 --- a/test/unit/client/cell.py +++ b/test/unit/client/cell.py @@ -99,7 +99,7 @@ class TestCell(unittest.TestCase): self.assertRaises(ValueError, Cell.by_value, None) def test_unpack_not_implemented(self): - self.assertRaisesRegexp(NotImplementedError, 'Unpacking not yet implemented for AUTHORIZE cells', Cell.unpack, '\x00\x00\x84\x00\x06\x00\x01\x00\x02\x00\x03', 2) + self.assertRaisesRegexp(NotImplementedError, 'Unpacking not yet implemented for AUTHORIZE cells', Cell.pop, '\x00\x00\x84\x00\x06\x00\x01\x00\x02\x00\x03', 2) def test_unpack_for_new_link(self): expected_certs = ( @@ -112,10 +112,10 @@ class TestCell(unittest.TestCase): content = test_data('new_link_cells') - version_cell, content = Cell.unpack(content, 2) + version_cell, content = Cell.pop(content, 2) self.assertEqual(VersionsCell([3, 4, 5]), version_cell) - certs_cell, content = Cell.unpack(content, 2) + certs_cell, content = Cell.pop(content, 2) self.assertEqual(CertsCell, type(certs_cell)) self.assertEqual(len(expected_certs), len(certs_cell.certificates)) @@ -124,10 +124,10 @@ class TestCell(unittest.TestCase): self.assertEqual(cert_type_int, certs_cell.certificates[i].type_int) self.assertTrue(certs_cell.certificates[i].value.startswith(cert_prefix)) - auth_challenge_cell, content = Cell.unpack(content, 2) + auth_challenge_cell, content = Cell.pop(content, 2) self.assertEqual(AuthChallengeCell([1, 3], '\x89Y\t\x99\xb2\x1e\xd9*V\xb6\x1bn\n\x05\xd8/\xe3QH\x85\x13Z\x17\xfc\x1c\x00{\xa9\xae\x83^K'), auth_challenge_cell) - netinfo_cell, content = Cell.unpack(content, 2) + netinfo_cell, content = Cell.pop(content, 2) self.assertEqual(NetinfoCell, type(netinfo_cell)) self.assertEqual(datetime.datetime(2018, 1, 14, 1, 46, 56), netinfo_cell.timestamp) self.assertEqual(Address('127.0.0.1'), netinfo_cell.receiver_address) @@ -138,14 +138,14 @@ class TestCell(unittest.TestCase): def test_padding_cell(self): for cell_bytes, payload in PADDING_CELLS.items(): self.assertEqual(cell_bytes, PaddingCell(payload).pack(2)) - self.assertEqual(payload, Cell.unpack(cell_bytes, 2)[0].payload) + self.assertEqual(payload, Cell.pop(cell_bytes, 2)[0].payload) def test_relay_cell(self): for cell_bytes, (command, command_int, circ_id, stream_id, data, digest) in RELAY_CELLS.items(): self.assertEqual(cell_bytes, RelayCell(circ_id, command, data, digest, stream_id).pack(2)) self.assertEqual(cell_bytes, RelayCell(circ_id, command_int, data, digest, stream_id).pack(2)) - cell = Cell.unpack(cell_bytes, 2)[0] + cell = Cell.pop(cell_bytes, 2)[0] self.assertEqual(circ_id, cell.circ_id) self.assertEqual(command, cell.command) self.assertEqual(command_int, cell.command_int) @@ -158,18 +158,18 @@ class TestCell(unittest.TestCase): self.assertEqual(cell_bytes, DestroyCell(circ_id, reason).pack(5)) self.assertEqual(cell_bytes, DestroyCell(circ_id, reason_int).pack(5)) - cell = Cell.unpack(cell_bytes, 5)[0] + cell = Cell.pop(cell_bytes, 5)[0] self.assertEqual(circ_id, cell.circ_id) self.assertEqual(reason, cell.reason) self.assertEqual(reason_int, cell.reason_int) - self.assertRaisesRegexp(ValueError, 'Circuit closure reason should be a single byte, but was 2', Cell.unpack, '\x80\x00\x00\x00\x04\x01\x01' + ZERO * 507, 5) + self.assertRaisesRegexp(ValueError, 'Circuit closure reason should be a single byte, but was 2', Cell.pop, '\x80\x00\x00\x00\x04\x01\x01' + ZERO * 507, 5) def test_create_fast_cell(self): for cell_bytes, (circ_id, key_material) in CREATE_FAST_CELLS.items(): self.assertEqual(cell_bytes, CreateFastCell(circ_id, key_material).pack(5)) - cell = Cell.unpack(cell_bytes, 5)[0] + cell = Cell.pop(cell_bytes, 5)[0] self.assertEqual(circ_id, cell.circ_id) self.assertEqual(key_material, cell.key_material) @@ -179,7 +179,7 @@ class TestCell(unittest.TestCase): for cell_bytes, (circ_id, key_material, derivative_key) in CREATED_FAST_CELLS.items(): self.assertEqual(cell_bytes, CreatedFastCell(circ_id, derivative_key, key_material).pack(5)) - cell = Cell.unpack(cell_bytes, 5)[0] + cell = Cell.pop(cell_bytes, 5)[0] self.assertEqual(circ_id, cell.circ_id) self.assertEqual(key_material, cell.key_material) self.assertEqual(derivative_key, cell.derivative_key) @@ -189,13 +189,13 @@ class TestCell(unittest.TestCase): def test_versions_cell(self): for cell_bytes, versions in VERSIONS_CELLS.items(): self.assertEqual(cell_bytes, VersionsCell(versions).pack()) - self.assertEqual(versions, Cell.unpack(cell_bytes, 2)[0].versions) + self.assertEqual(versions, Cell.pop(cell_bytes, 2)[0].versions) def test_netinfo_cell(self): for cell_bytes, (timestamp, receiver_address, sender_addresses) in NETINFO_CELLS.items(): self.assertEqual(cell_bytes, NetinfoCell(receiver_address, sender_addresses, timestamp).pack(2)) - cell = Cell.unpack(cell_bytes, 2)[0] + cell = Cell.pop(cell_bytes, 2)[0] self.assertEqual(timestamp, cell.timestamp) self.assertEqual(receiver_address, cell.receiver_address) self.assertEqual(sender_addresses, cell.sender_addresses) @@ -203,31 +203,31 @@ class TestCell(unittest.TestCase): def test_vpadding_cell(self): for cell_bytes, payload in VPADDING_CELLS.items(): self.assertEqual(cell_bytes, VPaddingCell(payload = payload).pack(2)) - self.assertEqual(payload, Cell.unpack(cell_bytes, 2)[0].payload) + self.assertEqual(payload, Cell.pop(cell_bytes, 2)[0].payload) self.assertRaisesRegexp(ValueError, 'VPaddingCell constructor specified both a size of 5 bytes and payload of 1 bytes', VPaddingCell, 5, '\x02') def test_certs_cell(self): for cell_bytes, certs in CERTS_CELLS.items(): self.assertEqual(cell_bytes, CertsCell(certs).pack(2)) - self.assertEqual(certs, Cell.unpack(cell_bytes, 2)[0].certificates) + self.assertEqual(certs, Cell.pop(cell_bytes, 2)[0].certificates) # extra bytes after the last certificate should be ignored - self.assertEqual([Certificate(1, '\x08')], Cell.unpack('\x00\x00\x81\x00\x07\x01\x01\x00\x01\x08\x06\x04', 2)[0].certificates) + self.assertEqual([Certificate(1, '\x08')], Cell.pop('\x00\x00\x81\x00\x07\x01\x01\x00\x01\x08\x06\x04', 2)[0].certificates) # ... but truncated or missing certificates should error - self.assertRaisesRegexp(ValueError, 'CERTS cell should have a certificate with 3 bytes, but only had 1 remaining', Cell.unpack, '\x00\x00\x81\x00\x05\x01\x01\x00\x03\x08', 2) - self.assertRaisesRegexp(ValueError, 'CERTS cell indicates it should have 2 certificates, but only contained 1', Cell.unpack, '\x00\x00\x81\x00\x05\x02\x01\x00\x01\x08', 2) + self.assertRaisesRegexp(ValueError, 'CERTS cell should have a certificate with 3 bytes, but only had 1 remaining', Cell.pop, '\x00\x00\x81\x00\x05\x01\x01\x00\x03\x08', 2) + self.assertRaisesRegexp(ValueError, 'CERTS cell indicates it should have 2 certificates, but only contained 1', Cell.pop, '\x00\x00\x81\x00\x05\x02\x01\x00\x01\x08', 2) def test_auth_challenge_cell(self): for cell_bytes, (challenge, methods) in AUTH_CHALLENGE_CELLS.items(): self.assertEqual(cell_bytes, AuthChallengeCell(methods, challenge).pack(2)) - cell = Cell.unpack(cell_bytes, 2)[0] + cell = Cell.pop(cell_bytes, 2)[0] self.assertEqual(challenge, cell.challenge) self.assertEqual(methods, cell.methods) - self.assertRaisesRegexp(ValueError, 'AUTH_CHALLENGE cell should have a payload of 38 bytes, but only had 16', Cell.unpack, '\x00\x00\x82\x00&%s\x00\x02\x00\x01\x00\x03' % CHALLENGE[:10], 2) - self.assertRaisesRegexp(ValueError, 'AUTH_CHALLENGE should have 3 methods, but only had 4 bytes for it', Cell.unpack, '\x00\x00\x82\x00&%s\x00\x03\x00\x01\x00\x03' % CHALLENGE, 2) + self.assertRaisesRegexp(ValueError, 'AUTH_CHALLENGE cell should have a payload of 38 bytes, but only had 16', Cell.pop, '\x00\x00\x82\x00&%s\x00\x02\x00\x01\x00\x03' % CHALLENGE[:10], 2) + self.assertRaisesRegexp(ValueError, 'AUTH_CHALLENGE should have 3 methods, but only had 4 bytes for it', Cell.pop, '\x00\x00\x82\x00&%s\x00\x03\x00\x01\x00\x03' % CHALLENGE, 2) [View Less]

1 0

[stem/master] Replace kdf_tor function with a KDF class
by atagar＠torproject.org 07 Feb '18

07 Feb '18

commit e2e7b5d58fdc14014df8c476c59457b1b5483c2e Author: Damian Johnson <atagar(a)torproject.org> Date: Tue Jan 30 12:21:04 2018 -0800 Replace kdf_tor function with a KDF class On reflection callers actually don't care about the KDF-TOR value. Rather, they care about its derived attributes. --- stem/client/__init__.py | 47 ++++++++++++++++++++++++++++++++------------- test/unit/client/kdf_tor.py | 21 +++++++++++++++++--- 2 files changed, 52 insertions(+), 16 … [View More]deletions(-) diff --git a/stem/client/__init__.py b/stem/client/__init__.py index 663bc048..4c6bdb12 100644 --- a/stem/client/__init__.py +++ b/stem/client/__init__.py @@ -12,7 +12,7 @@ a wrapper for :class:`~stem.socket.RelaySocket`, much the same way as :: split - splits bytes into substrings - kdf_tor - calculates the derived key using the KDF-TOR protocol + KDF - KDF-TOR key derivative for TAP, CREATE_FAST handshakes, and hidden serivces Field - Packable and unpackable datatype. |- Size - Field of a static size. @@ -461,24 +461,45 @@ class Certificate(Field): return _hash_attr(self, 'type_int', 'value') -def kdf_tor(key): +class KDF(object): + """ + Tor's derived key for TAP, CREATE_FAST handshakes, and hidden service + protocols as defined tor-spec section 5.2.1. + + :var bytes key_hash: expected derived key that proves knowledge of our shared + computed key + :var bytes forward_digest: forward digest hash seed + :var bytes backward_digest: backward digest hash seed + :var bytes forward_key: forward encryption key + :var bytes backward_key: backward encryption key """ - Tor's key derivation function used by TAP, CREATE_FAST handshakes, and hidden - service protocols as defined in section 5.2.1 of the tor spec. - :param bytes key: shared key with endpoint (K0 in the spec) + def __init__(self, key_material): + value = KDF._value(key_material) - :returns: **bytes** with the KDF-TOR of the key - """ + self.key_hash, value = split(value, HASH_LEN) + self.forward_digest, value = split(value, HASH_LEN) + self.backward_digest, value = split(value, HASH_LEN) + self.forward_key, value = split(value, KEY_LEN) + self.backward_key, value = split(value, KEY_LEN) + + @staticmethod + def _value(key): + """ + Computes the KDF-TOR value... + + K = H(K0 | [00]) | H(K0 | [01]) | H(K0 | [02]) | ... + """ - derived_key_len = KEY_LEN * 2 + HASH_LEN * 3 - derived_key, counter = '', 0 + derived_key = '' + derived_key_len = KEY_LEN * 2 + HASH_LEN * 3 + counter = 0 - while len(derived_key) < derived_key_len: - derived_key += hashlib.sha1(key + Size.CHAR.pack(counter)).digest() - counter += 1 + while len(derived_key) < derived_key_len: + derived_key += hashlib.sha1(key + Size.CHAR.pack(counter)).digest() + counter += 1 - return derived_key[:derived_key_len] + return derived_key[:derived_key_len] setattr(Size, 'CHAR', Size('CHAR', 1, '!B')) diff --git a/test/unit/client/kdf_tor.py b/test/unit/client/kdf_tor.py index 894d4fae..f356d2cd 100644 --- a/test/unit/client/kdf_tor.py +++ b/test/unit/client/kdf_tor.py @@ -14,6 +14,21 @@ DERIVED_2 = '\xbc0\xf99\x8e;Te\xbb+\xdb\xabR3l\xb9f?\x07KZC8\xe7\xa15\xd1IS\xd9\ class TestKdfTor(unittest.TestCase): - def test_kdf_tor(self): - self.assertEqual(DERIVED_1, stem.client.kdf_tor(KEY_1)) - self.assertEqual(DERIVED_2, stem.client.kdf_tor(KEY_2)) + def test_kdf_value(self): + self.assertEqual(DERIVED_1, stem.client.KDF._value(KEY_1)) + self.assertEqual(DERIVED_2, stem.client.KDF._value(KEY_2)) + + def test_kdf_attributes(self): + k1 = stem.client.KDF(KEY_1) + self.assertEqual('\xca+\x81\x05\x14\x9d)o\xa6\x82\xe9B\xa8?\xf2\xaf\x85\x1b]6', k1.key_hash) + self.assertEqual('\xac\xcc\xbc\x91\xb1\xaf\xd7\xe0\xe9\x9dF#\xd8\xdbz\xe8\xe6\xca\x83,', k1.forward_digest) + self.assertEqual('*\xe5scX\xbb+\xca \xcb\xa4\xbc\xad\x0f\x95\x0cO\xcc\xac\xf1', k1.backward_digest) + self.assertEqual('\xc3\xbe\xc9\xe1\xf4\x90f\xdai\xf3\xf3\xf5\x14\xb5\xb9\x03', k1.forward_key) + self.assertEqual('U\xaf\x1e\x1b\xb1q||\x86A<_\xf7\xa0%\x86', k1.backward_key) + + k2 = stem.client.KDF(KEY_1) + self.assertEqual('\xca+\x81\x05\x14\x9d)o\xa6\x82\xe9B\xa8?\xf2\xaf\x85\x1b]6', k2.key_hash) + self.assertEqual('\xac\xcc\xbc\x91\xb1\xaf\xd7\xe0\xe9\x9dF#\xd8\xdbz\xe8\xe6\xca\x83,', k2.forward_digest) + self.assertEqual('*\xe5scX\xbb+\xca \xcb\xa4\xbc\xad\x0f\x95\x0cO\xcc\xac\xf1', k2.backward_digest) + self.assertEqual('\xc3\xbe\xc9\xe1\xf4\x90f\xdai\xf3\xf3\xf5\x14\xb5\xb9\x03', k2.forward_key) + self.assertEqual('U\xaf\x1e\x1b\xb1q||\x86A<_\xf7\xa0%\x86', k2.backward_key) [View Less]

1 0

[stem/master] Initial circuit creation function
by atagar＠torproject.org 07 Feb '18

07 Feb '18

commit 47a331d642f766af9f45d438b16dcf675b602608 Author: Damian Johnson <atagar(a)torproject.org> Date: Fri Feb 2 13:35:56 2018 -0800 Initial circuit creation function Finally our first function that actually interacts with a socket. Just circuit creation to start with. Still needs tests. This is the first tidbit we'll be able to integ test! --- stem/client/__init__.py | 24 ++++++++++++++++++++++-- stem/client/cell.py | 4 ++-- 2 files changed, 24 insertions(+… [View More]), 4 deletions(-) diff --git a/stem/client/__init__.py b/stem/client/__init__.py index 0accaa59..cbeed403 100644 --- a/stem/client/__init__.py +++ b/stem/client/__init__.py @@ -499,11 +499,12 @@ class KDF(collections.namedtuple('KDF', ['key_hash', 'forward_digest', 'backward return KDF(key_hash, forward_digest, backward_digest, forward_key, backward_key) -class Circuit(collections.namedtuple('Circuit', ['id', 'forward_digest', 'backward_digest', 'forward_key', 'backward_key'])): +class Circuit(collections.namedtuple('Circuit', ['socket', 'id', 'forward_digest', 'backward_digest', 'forward_key', 'backward_key'])): """ Circuit through which requests can be made of a `Tor relay's ORPort <https://gitweb.torproject.org/torspec.git/tree/tor-spec.txt>`_. + :var stem.socket.RelaySocket socket: socket through which this circuit has been established :var int id: circuit id :var hashlib.sha1 forward_digest: digest for forward integrity check :var hashlib.sha1 backward_digest: digest for backward integrity check @@ -512,16 +513,35 @@ class Circuit(collections.namedtuple('Circuit', ['id', 'forward_digest', 'backwa """ @staticmethod - def from_kdf(circ_id, kdf): + def create(relay_socket, circ_id, link_version): + """ + Constructs a new circuit over the given ORPort. + """ + if not stem.prereq.is_crypto_available(): raise ImportError('Circuit construction requires the cryptography module') from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes from cryptography.hazmat.backends import default_backend + create_fast_cell = stem.client.cell.CreateFastCell(circ_id) + relay_socket.send(create_fast_cell.pack(link_version)) + + response = stem.client.cell.Cell.unpack(relay_socket.recv(), link_version) + created_fast_cells = filter(lambda cell: isinstance(cell, stem.client.cell.CreatedFastCell), response) + + if not created_fast_cells: + raise ValueError('We should get a CREATED_FAST response from a CREATE_FAST request') + + created_fast_cell = created_fast_cells[0] + kdf = KDF.from_value(create_fast_cell.key_material + created_fast_cell.key_material) ctr = modes.CTR(ZERO * (algorithms.AES.block_size / 8)) + if created_fast_cell.derivative_key != kdf.key_hash: + raise ValueError('Remote failed to prove that it knows our shared key') + return Circuit( + relay_socket, circ_id, hashlib.sha1(kdf.forward_digest), hashlib.sha1(kdf.backward_digest), diff --git a/stem/client/cell.py b/stem/client/cell.py index 9b0c3274..2bae4fc5 100644 --- a/stem/client/cell.py +++ b/stem/client/cell.py @@ -277,7 +277,7 @@ class RelayCell(CircuitCell): """ Command concerning a relay circuit. - :var stem.client.RelayCommand command: reason the circuit is being closed + :var stem.client.RelayCommand command: command to be issued :var int command_int: integer value of our command :var bytes data: payload of the cell :var int digest: running digest held with the relay @@ -295,7 +295,7 @@ class RelayCell(CircuitCell): VALUE = 3 IS_FIXED_SIZE = True - def __init__(self, circ_id, command, data, digest, stream_id = 0): + def __init__(self, circ_id, command, data, digest = 0, stream_id = 0): super(RelayCell, self).__init__(circ_id) self.command, self.command_int = stem.client.RelayCommand.get(command) self.data = data [View Less]

1 0

[stem/master] Change KDF to a named tuple
by atagar＠torproject.org 07 Feb '18

07 Feb '18

commit 984add2da2e62b8c102f60a671717b240a004bac Author: Damian Johnson <atagar(a)torproject.org> Date: Wed Jan 31 11:57:51 2018 -0800 Change KDF to a named tuple Been going back and forth on this but yeah, think it's a bit nicer this way. --- stem/client/__init__.py | 46 +++++++++++++++------------------ test/settings.cfg | 2 +- test/unit/client/__init__.py | 2 +- test/unit/client/{kdf_tor.py => kdf.py} | 17 ++++----… [View More]---- 4 files changed, 28 insertions(+), 39 deletions(-) diff --git a/stem/client/__init__.py b/stem/client/__init__.py index 4c6bdb12..f3e842c6 100644 --- a/stem/client/__init__.py +++ b/stem/client/__init__.py @@ -12,7 +12,9 @@ a wrapper for :class:`~stem.socket.RelaySocket`, much the same way as :: split - splits bytes into substrings - KDF - KDF-TOR key derivative for TAP, CREATE_FAST handshakes, and hidden serivces + + KDF - KDF-TOR derivatived attributes + +- from_value - parses key material Field - Packable and unpackable datatype. |- Size - Field of a static size. @@ -107,6 +109,7 @@ a wrapper for :class:`~stem.socket.RelaySocket`, much the same way as ===================== =========== """ +import collections import hashlib import io import struct @@ -461,45 +464,38 @@ class Certificate(Field): return _hash_attr(self, 'type_int', 'value') -class KDF(object): +class KDF(collections.namedtuple('KDF', ['key_hash', 'forward_digest', 'backward_digest', 'forward_key', 'backward_key'])): """ - Tor's derived key for TAP, CREATE_FAST handshakes, and hidden service - protocols as defined tor-spec section 5.2.1. + Computed KDF-TOR derived values for TAP, CREATE_FAST handshakes, and hidden + service protocols as defined tor-spec section 5.2.1. - :var bytes key_hash: expected derived key that proves knowledge of our shared - computed key + :var bytes key_hash: hash that proves knowledge of our shared key :var bytes forward_digest: forward digest hash seed :var bytes backward_digest: backward digest hash seed :var bytes forward_key: forward encryption key :var bytes backward_key: backward encryption key """ - def __init__(self, key_material): - value = KDF._value(key_material) - - self.key_hash, value = split(value, HASH_LEN) - self.forward_digest, value = split(value, HASH_LEN) - self.backward_digest, value = split(value, HASH_LEN) - self.forward_key, value = split(value, KEY_LEN) - self.backward_key, value = split(value, KEY_LEN) - @staticmethod - def _value(key): - """ - Computes the KDF-TOR value... - - K = H(K0 | [00]) | H(K0 | [01]) | H(K0 | [02]) | ... - """ + def from_value(key_material): + # Derived key material, as per... + # + # K = H(K0 | [00]) | H(K0 | [01]) | H(K0 | [02]) | ... derived_key = '' - derived_key_len = KEY_LEN * 2 + HASH_LEN * 3 counter = 0 - while len(derived_key) < derived_key_len: - derived_key += hashlib.sha1(key + Size.CHAR.pack(counter)).digest() + while len(derived_key) < KEY_LEN * 2 + HASH_LEN * 3: + derived_key += hashlib.sha1(key_material + Size.CHAR.pack(counter)).digest() counter += 1 - return derived_key[:derived_key_len] + key_hash, derived_key = split(derived_key, HASH_LEN) + forward_digest, derived_key = split(derived_key, HASH_LEN) + backward_digest, derived_key = split(derived_key, HASH_LEN) + forward_key, derived_key = split(derived_key, KEY_LEN) + backward_key, derived_key = split(derived_key, KEY_LEN) + + return KDF(key_hash, forward_digest, backward_digest, forward_key, backward_key) setattr(Size, 'CHAR', Size('CHAR', 1, '!B')) diff --git a/test/settings.cfg b/test/settings.cfg index 7af57181..4080ca2a 100644 --- a/test/settings.cfg +++ b/test/settings.cfg @@ -233,7 +233,7 @@ test.unit_tests |test.unit.client.size.TestSize |test.unit.client.address.TestAddress |test.unit.client.certificate.TestCertificate -|test.unit.client.kdf_tor.TestKdfTor +|test.unit.client.kdf.TestKDF |test.unit.client.cell.TestCell |test.unit.connection.authentication.TestAuthenticate |test.unit.connection.connect.TestConnect diff --git a/test/unit/client/__init__.py b/test/unit/client/__init__.py index ba93b3e6..91d3b2be 100644 --- a/test/unit/client/__init__.py +++ b/test/unit/client/__init__.py @@ -6,7 +6,7 @@ __all__ = [ 'address', 'cell', 'certificate', - 'kdf_tor', + 'kdf', 'size', ] diff --git a/test/unit/client/kdf_tor.py b/test/unit/client/kdf.py similarity index 59% rename from test/unit/client/kdf_tor.py rename to test/unit/client/kdf.py index f356d2cd..56665d31 100644 --- a/test/unit/client/kdf_tor.py +++ b/test/unit/client/kdf.py @@ -1,5 +1,5 @@ """ -Unit tests for stem.client.kdf_tor. +Unit tests for stem.client.KDF. """ import unittest @@ -9,24 +9,17 @@ import stem.client KEY_1 = '\xec\xec.\xeb7R\xf2\n\xcb\xce\x97\xf4\x86\x82\x19#\x10\x0f\x08\xf0\xa2Z\xdeJ\x8f2\x8cc\xf6\xfa\x0e\t\x83f\xc5\xe2\xb3\x94\xa8\x13' KEY_2 = '\xe0v\xe4\xfaTB\x91\x1c\x81Gz\xa0\tI\xcb{\xc56\xcfV\xc2\xa0\x19\x9c\x98\x9a\x06\x0e\xc5\xfa\xb0z\x83\xa6\x10\xf6r"<b' -DERIVED_1 = '\xca+\x81\x05\x14\x9d)o\xa6\x82\xe9B\xa8?\xf2\xaf\x85\x1b]6\xac\xcc\xbc\x91\xb1\xaf\xd7\xe0\xe9\x9dF#\xd8\xdbz\xe8\xe6\xca\x83,*\xe5scX\xbb+\xca \xcb\xa4\xbc\xad\x0f\x95\x0cO\xcc\xac\xf1\xc3\xbe\xc9\xe1\xf4\x90f\xdai\xf3\xf3\xf5\x14\xb5\xb9\x03U\xaf\x1e\x1b\xb1q||\x86A<_\xf7\xa0%\x86' -DERIVED_2 = '\xbc0\xf99\x8e;Te\xbb+\xdb\xabR3l\xb9f?\x07KZC8\xe7\xa15\xd1IS\xd9\xd4\x1e\x96\xf6\xcd\x82\x91\x0b}r\x7f\xc5\xc0\xb1/[\x97dW\xba\x82g\xe7m^\x06[\xe6\xf8\xb4\x83f>c\x8b\x0f\x03\xcc\x98\x1f~t\x88\xe1\x83\xec\xbf*_\x8cF\x0e1\xa9\x17\xce\xa6\xa3\xd1+]\x1f' - -class TestKdfTor(unittest.TestCase): - def test_kdf_value(self): - self.assertEqual(DERIVED_1, stem.client.KDF._value(KEY_1)) - self.assertEqual(DERIVED_2, stem.client.KDF._value(KEY_2)) - - def test_kdf_attributes(self): - k1 = stem.client.KDF(KEY_1) +class TestKDF(unittest.TestCase): + def test_parsing(self): + k1 = stem.client.KDF.from_value(KEY_1) self.assertEqual('\xca+\x81\x05\x14\x9d)o\xa6\x82\xe9B\xa8?\xf2\xaf\x85\x1b]6', k1.key_hash) self.assertEqual('\xac\xcc\xbc\x91\xb1\xaf\xd7\xe0\xe9\x9dF#\xd8\xdbz\xe8\xe6\xca\x83,', k1.forward_digest) self.assertEqual('*\xe5scX\xbb+\xca \xcb\xa4\xbc\xad\x0f\x95\x0cO\xcc\xac\xf1', k1.backward_digest) self.assertEqual('\xc3\xbe\xc9\xe1\xf4\x90f\xdai\xf3\xf3\xf5\x14\xb5\xb9\x03', k1.forward_key) self.assertEqual('U\xaf\x1e\x1b\xb1q||\x86A<_\xf7\xa0%\x86', k1.backward_key) - k2 = stem.client.KDF(KEY_1) + k2 = stem.client.KDF.from_value(KEY_1) self.assertEqual('\xca+\x81\x05\x14\x9d)o\xa6\x82\xe9B\xa8?\xf2\xaf\x85\x1b]6', k2.key_hash) self.assertEqual('\xac\xcc\xbc\x91\xb1\xaf\xd7\xe0\xe9\x9dF#\xd8\xdbz\xe8\xe6\xca\x83,', k2.forward_digest) self.assertEqual('*\xe5scX\xbb+\xca \xcb\xa4\xbc\xad\x0f\x95\x0cO\xcc\xac\xf1', k2.backward_digest) [View Less]

1 0

[stem/master] Initial Relay class
by atagar＠torproject.org 07 Feb '18

07 Feb '18

commit db52d5fcf38127c107399065768e710b297378c8 Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Feb 3 14:03:00 2018 -0800 Initial Relay class Clearly from all the todos just a start. --- stem/__init__.py | 2 ++ stem/client/__init__.py | 9 ++++--- stem/control.py | 2 +- stem/relay.py | 71 +++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 79 insertions(+), 5 deletions(-) diff --git a/stem/__init__.py b/stem/… [View More]__init__.py index 2741cee7..2d2e1c6d 100644 --- a/stem/__init__.py +++ b/stem/__init__.py @@ -485,6 +485,7 @@ __url__ = 'https://stem.torproject.org/' __license__ = 'LGPLv3' __all__ = [ + 'client', 'descriptor', 'response', 'util', @@ -493,6 +494,7 @@ __all__ = [ 'exit_policy', 'prereq', 'process', + 'relay', 'socket', 'version', 'ControllerError', diff --git a/stem/client/__init__.py b/stem/client/__init__.py index cbeed403..9f4217c5 100644 --- a/stem/client/__init__.py +++ b/stem/client/__init__.py @@ -2,10 +2,11 @@ # See LICENSE for licensing information """ -Interaction with a Tor relay's ORPort. :class:`~stem.client.Relay` is -a wrapper for :class:`~stem.socket.RelaySocket`, much the same way as -:class:`~stem.control.Controller` provides higher level functions for -:class:`~stem.socket.ControlSocket`. +Support for `Tor's ORPort protocol +<https://gitweb.torproject.org/torspec.git/tree/tor-spec.txt>`_. + +**This module only consists of low level components, and is not intended for +users.** See our :class:`~stem.relay.Relay` the API you probably want. .. versionadded:: 1.7.0 diff --git a/stem/control.py b/stem/control.py index 94ad5eaf..123e3b20 100644 --- a/stem/control.py +++ b/stem/control.py @@ -989,7 +989,7 @@ class BaseController(object): class Controller(BaseController): """ - Communicates with a control socket. This is built on top of the + Connection with Tor's control socket. This is built on top of the BaseController and provides a more user friendly API for library users. """ diff --git a/stem/relay.py b/stem/relay.py new file mode 100644 index 00000000..7d1e8282 --- /dev/null +++ b/stem/relay.py @@ -0,0 +1,71 @@ +# Copyright 2018, Damian Johnson and The Tor Project +# See LICENSE for licensing information + +""" +Interaction with a Tor relay's ORPort. :class:`~stem.relay.Relay` is +a wrapper for :class:`~stem.socket.RelaySocket`, much the same way as +:class:`~stem.control.Controller` provides higher level functions for +:class:`~stem.socket.ControlSocket`. + +.. versionadded:: 1.7.0 + +:: + + Relay - Connection with a tor relay's ORPort. + | +- connect - Establishes a connection with a relay. +""" + +import stem.client +import stem.client.cell +import stem.socket +import stem.util.connection + +DEFAULT_LINK_VERSIONS = (3, 4, 5) + + +class Relay(object): + """ + Connection with a Tor relay's ORPort. + """ + + def __init__(self, orport): + self._orport = orport + + @staticmethod + def connect(address, port, link_versions = DEFAULT_LINK_VERSIONS): + """ + Establishes a connection with the given ORPort. + + :param str address: ip address of the relay + :param int port: ORPort of the relay + :param tuple link_versions: acceptable link protocol versions + + :raises: + * **ValueError** if address or port are invalid + * :class:`stem.SocketError` if we're unable to establish a connection + """ + + if stem.util.connection.is_valid_ipv4_address(address): + addr_type = stem.client.AddrType.IPv4 + elif stem.util.connection.is_valid_ipv6_address(address): + addr_type = stem.client.AddrType.IPv6 + else: + raise ValueError("'%s' isn't an IPv4 or IPv6 address" % address) + + if not stem.util.connection.is_port(port): + raise ValueError("'%s' isn't a valid port" % port) + + conn = stem.socket.RelaySocket(address, port) + conn.send(stem.client.cell.VersionsCell(link_versions).pack()) + versions_reply = stem.client.cell.Cell.pop(conn.recv(), 2)[0] + + # TODO: determine the highest common link versions + # TODO: we should fill in our address, right? + # TODO: what happens if we skip the NETINFO? + + link_version = 3 + conn.send(stem.client.cell.NetinfoCell(stem.client.Address(address, addr_type), []).pack(link_version)) + + # TODO: what if no link protocol versions are acceptable? + + return Relay(conn) [View Less]

1 0

[stem/master] Initial ORPort integ tests
by atagar＠torproject.org 07 Feb '18

07 Feb '18

commit 3fe2221ae2bad6d826c05fd0ce96e5c09a21fc01 Author: Damian Johnson <atagar(a)torproject.org> Date: Sat Feb 3 14:13:27 2018 -0800 Initial ORPort integ tests Nothing too interesting yet. --- stem/relay.py | 54 +++++++++++++++++++++++++++++----------- test/integ/__init__.py | 1 + test/integ/client/__init__.py | 7 ++++++ test/integ/client/connection.py | 49 ++++++++++++++++++++++++++++++++++++ test/integ/control/controller.py | 4 +--… [View More] test/runner.py | 4 ++- test/settings.cfg | 1 + 7 files changed, 103 insertions(+), 17 deletions(-) diff --git a/stem/relay.py b/stem/relay.py index 7d1e8282..20341721 100644 --- a/stem/relay.py +++ b/stem/relay.py @@ -15,30 +15,34 @@ a wrapper for :class:`~stem.socket.RelaySocket`, much the same way as | +- connect - Establishes a connection with a relay. """ +import stem import stem.client import stem.client.cell import stem.socket import stem.util.connection -DEFAULT_LINK_VERSIONS = (3, 4, 5) +DEFAULT_LINK_PROTOCOLS = (3, 4, 5) class Relay(object): """ Connection with a Tor relay's ORPort. + + :var int link_protocol: link protocol version we established """ - def __init__(self, orport): + def __init__(self, orport, link_protocol): + self.link_protocol = link_protocol self._orport = orport @staticmethod - def connect(address, port, link_versions = DEFAULT_LINK_VERSIONS): + def connect(address, port, link_protocols = DEFAULT_LINK_PROTOCOLS): """ Establishes a connection with the given ORPort. :param str address: ip address of the relay :param int port: ORPort of the relay - :param tuple link_versions: acceptable link protocol versions + :param tuple link_protocols: acceptable link protocol versions :raises: * **ValueError** if address or port are invalid @@ -52,20 +56,42 @@ class Relay(object): else: raise ValueError("'%s' isn't an IPv4 or IPv6 address" % address) - if not stem.util.connection.is_port(port): + if not stem.util.connection.is_valid_port(port): raise ValueError("'%s' isn't a valid port" % port) + elif not link_protocols: + raise ValueError("Connection can't be established without a link protocol.") + + try: + conn = stem.socket.RelaySocket(address, port) + except stem.SocketError as exc: + if 'Connection refused' in str(exc): + raise stem.SocketError("Failed to connect to %s:%i. Maybe it isn't an ORPort?" % (address, port)) + elif 'SSL: UNKNOWN_PROTOCOL' in str(exc): + raise stem.SocketError("Failed to SSL authenticate to %s:%i. Maybe it isn't an ORPort?" % (address, port)) + else: + raise + + conn.send(stem.client.cell.VersionsCell(link_protocols).pack()) + response = conn.recv() + + # Link negotiation ends right away if we lack a common protocol + # version. (#25139) - conn = stem.socket.RelaySocket(address, port) - conn.send(stem.client.cell.VersionsCell(link_versions).pack()) - versions_reply = stem.client.cell.Cell.pop(conn.recv(), 2)[0] + if not response: + conn.close() + raise stem.SocketError('Unable to establish a common link protocol with %s:%i' % (address, port)) + + versions_reply = stem.client.cell.Cell.pop(response, 2)[0] + common_protocols = set(link_protocols).intersection(versions_reply.versions) + + if not common_protocols: + conn.close() + raise stem.SocketError('Unable to find a common link protocol. We support %s but %s:%i supports %s.' % (', '.join(link_protocols), address, port, ', '.join(versions_reply.versions))) - # TODO: determine the highest common link versions # TODO: we should fill in our address, right? # TODO: what happens if we skip the NETINFO? - link_version = 3 - conn.send(stem.client.cell.NetinfoCell(stem.client.Address(address, addr_type), []).pack(link_version)) - - # TODO: what if no link protocol versions are acceptable? + link_protocol = max(common_protocols) + conn.send(stem.client.cell.NetinfoCell(stem.client.Address(address, addr_type), []).pack(link_protocol)) - return Relay(conn) + return Relay(conn, link_protocol) diff --git a/test/integ/__init__.py b/test/integ/__init__.py index 886d1c89..31e6084f 100644 --- a/test/integ/__init__.py +++ b/test/integ/__init__.py @@ -3,6 +3,7 @@ Integration tests for the stem library. """ __all__ = [ + 'client', 'connection', 'control', 'descriptor', diff --git a/test/integ/client/__init__.py b/test/integ/client/__init__.py new file mode 100644 index 00000000..8d77a653 --- /dev/null +++ b/test/integ/client/__init__.py @@ -0,0 +1,7 @@ +""" +Integration tests for tor's ORPort (stem.relay and stem.client). +""" + +__all__ = [ + 'connection', +] diff --git a/test/integ/client/connection.py b/test/integ/client/connection.py new file mode 100644 index 00000000..bb6ae762 --- /dev/null +++ b/test/integ/client/connection.py @@ -0,0 +1,49 @@ +""" +Integration tests for establishing a connection with tor's ORPort. +""" + +import unittest + +import stem +import test.runner + +from stem.relay import Relay + + +class TestConnection(unittest.TestCase): + def test_invalid_arguments(self): + """ + Provide invalid arguments to Relay.connect(). + """ + + self.assertRaisesRegexp(ValueError, "'nope' isn't an IPv4 or IPv6 address", Relay.connect, 'nope', 80) + self.assertRaisesRegexp(ValueError, "'-54' isn't a valid port", Relay.connect, '127.0.0.1', -54) + self.assertRaisesRegexp(ValueError, "Connection can't be established without a link protocol.", Relay.connect, '127.0.0.1', 54, []) + + def test_not_orport(self): + """ + Attempt to connect to an ORPort that doesn't exist. + """ + + self.assertRaisesRegexp(stem.SocketError, "Failed to connect to 127.0.0.1:1587. Maybe it isn't an ORPort?", Relay.connect, '127.0.0.1', 1587) + + # connect to our ControlPort like it's an ORPort + + if test.runner.Torrc.PORT in test.runner.get_runner().get_options(): + self.assertRaisesRegexp(stem.SocketError, "Failed to SSL authenticate to 127.0.0.1:1111. Maybe it isn't an ORPort?", Relay.connect, '127.0.0.1', test.runner.CONTROL_PORT) + + def test_no_common_link_protocol(self): + """ + Connection without a commonly accepted link protocol version. + """ + + for link_protocol in (1, 2, 6, 20): + self.assertRaisesRegexp(stem.SocketError, 'Unable to establish a common link protocol with 127.0.0.1:1113', Relay.connect, '127.0.0.1', test.runner.ORPORT, [link_protocol]) + + def test_established(self): + """ + Successfully establish ORPort connection. + """ + + conn = Relay.connect('127.0.0.1', test.runner.ORPORT) + self.assertEqual(5, conn.link_protocol) diff --git a/test/integ/control/controller.py b/test/integ/control/controller.py index b2ba77a5..16061eee 100644 --- a/test/integ/control/controller.py +++ b/test/integ/control/controller.py @@ -845,7 +845,7 @@ class TestController(unittest.TestCase): runner = test.runner.get_runner() with runner.get_tor_controller() as controller: - self.assertEqual([], controller.get_ports(Listener.OR)) + self.assertEqual([test.runner.ORPORT], controller.get_ports(Listener.OR)) self.assertEqual([], controller.get_ports(Listener.DIR)) self.assertEqual([test.runner.SOCKS_PORT], controller.get_ports(Listener.SOCKS)) self.assertEqual([], controller.get_ports(Listener.TRANS)) @@ -866,7 +866,7 @@ class TestController(unittest.TestCase): runner = test.runner.get_runner() with runner.get_tor_controller() as controller: - self.assertEqual([], controller.get_listeners(Listener.OR)) + self.assertEqual([('0.0.0.0', test.runner.ORPORT)], controller.get_listeners(Listener.OR)) self.assertEqual([], controller.get_listeners(Listener.DIR)) self.assertEqual([('127.0.0.1', test.runner.SOCKS_PORT)], controller.get_listeners(Listener.SOCKS)) self.assertEqual([], controller.get_listeners(Listener.TRANS)) diff --git a/test/runner.py b/test/runner.py index 0a307c87..fe01f74f 100644 --- a/test/runner.py +++ b/test/runner.py @@ -58,14 +58,16 @@ CONFIG = stem.util.conf.config_dict('test', { }) SOCKS_PORT = 1112 +ORPORT = 1113 BASE_TORRC = """# configuration for stem integration tests DataDirectory %%s SocksPort %i +ORPort %i DownloadExtraInfo 1 Log notice stdout Log notice file %%s/tor_log -""" % SOCKS_PORT +""" % (SOCKS_PORT, ORPORT) # singleton Runner instance INTEG_RUNNER = None diff --git a/test/settings.cfg b/test/settings.cfg index 4080ca2a..6d543bac 100644 --- a/test/settings.cfg +++ b/test/settings.cfg @@ -252,6 +252,7 @@ test.integ_tests |test.integ.interpreter.TestInterpreter |test.integ.version.TestVersion |test.integ.manual.TestManual +|test.integ.client.connection.TestConnection |test.integ.response.protocolinfo.TestProtocolInfo |test.integ.socket.control_socket.TestControlSocket |test.integ.socket.control_message.TestControlMessage [View Less]

1 0

[stem/master] Add basic socket functions to Relay class
by atagar＠torproject.org 07 Feb '18

07 Feb '18

commit ad47e6f72cad9ceb61e7ff1dfdc4d8e7755aa0a8 Author: Damian Johnson <atagar(a)torproject.org> Date: Sun Feb 4 12:31:07 2018 -0800 Add basic socket functions to Relay class Like the BaseController, callers will want basic socket passthroughs. Adding is_alive(), connection_time(), close(), and context management. --- stem/control.py | 7 +++---- stem/relay.py | 40 ++++++++++++++++++++++++++++++++++++++++ stem/socket.py … [View More] | 1 + test/integ/client/connection.py | 17 +++++++++++++++++ 4 files changed, 61 insertions(+), 4 deletions(-) diff --git a/stem/control.py b/stem/control.py index 123e3b20..b78707c1 100644 --- a/stem/control.py +++ b/stem/control.py @@ -153,8 +153,7 @@ If you're fine with allowing your script to raise exceptions then this can be mo |- get_socket - provides the socket used for control communication |- get_latest_heartbeat - timestamp for when we last heard from tor |- add_status_listener - notifies a callback of changes in our status - |- remove_status_listener - prevents further notification of status changes - +- __enter__ / __exit__ - manages socket connection + +- remove_status_listener - prevents further notification of status changes .. data:: State (enum) @@ -674,7 +673,7 @@ class BaseController(object): def is_alive(self): """ Checks if our socket is currently connected. This is a pass-through for our - socket's :func:`~stem.socket.ControlSocket.is_alive` method. + socket's :func:`~stem.socket.BaseSocket.is_alive` method. :returns: **bool** that's **True** if our socket is connected and **False** otherwise """ @@ -729,7 +728,7 @@ class BaseController(object): def close(self): """ Closes our socket connection. This is a pass-through for our socket's - :func:`~stem.socket.ControlSocket.close` method. + :func:`~stem.socket.BaseSocket.close` method. """ self._socket.close() diff --git a/stem/relay.py b/stem/relay.py index 20341721..14b7833f 100644 --- a/stem/relay.py +++ b/stem/relay.py @@ -13,6 +13,10 @@ a wrapper for :class:`~stem.socket.RelaySocket`, much the same way as Relay - Connection with a tor relay's ORPort. | +- connect - Establishes a connection with a relay. + | + |- is_alive - reports if our connection is open or closed + |- connection_time - time when we last connected or disconnected + +- close - shuts down our connection """ import stem @@ -95,3 +99,39 @@ class Relay(object): conn.send(stem.client.cell.NetinfoCell(stem.client.Address(address, addr_type), []).pack(link_protocol)) return Relay(conn, link_protocol) + + def is_alive(self): + """ + Checks if our socket is currently connected. This is a pass-through for our + socket's :func:`~stem.socket.BaseSocket.is_alive` method. + + :returns: **bool** that's **True** if our socket is connected and **False** otherwise + """ + + return self._orport.is_alive() + + def connection_time(self): + """ + Provides the unix timestamp for when our socket was either connected or + disconnected. That is to say, the time we connected if we're currently + connected and the time we disconnected if we're not connected. + + :returns: **float** for when we last connected or disconnected, zero if + we've never connected + """ + + return self._orport.connection_time() + + def close(self): + """ + Closes our socket connection. This is a pass-through for our socket's + :func:`~stem.socket.BaseSocket.close` method. + """ + + return self._orport.close() + + def __enter__(self): + return self + + def __exit__(self, exit_type, value, traceback): + self.close() diff --git a/stem/socket.py b/stem/socket.py index 7a2ec9de..bde68cc9 100644 --- a/stem/socket.py +++ b/stem/socket.py @@ -60,6 +60,7 @@ Tor... | |- is_alive - reports if the socket is known to be closed |- is_localhost - returns if the socket is for the local system or not + |- connection_time - timestamp when socket last connected or disconnected |- connect - connects a new socket |- close - shuts down the socket +- __enter__ / __exit__ - manages socket connection diff --git a/test/integ/client/connection.py b/test/integ/client/connection.py index bb6ae762..f5399a71 100644 --- a/test/integ/client/connection.py +++ b/test/integ/client/connection.py @@ -2,6 +2,7 @@ Integration tests for establishing a connection with tor's ORPort. """ +import time import unittest import stem @@ -40,6 +41,22 @@ class TestConnection(unittest.TestCase): for link_protocol in (1, 2, 6, 20): self.assertRaisesRegexp(stem.SocketError, 'Unable to establish a common link protocol with 127.0.0.1:1113', Relay.connect, '127.0.0.1', test.runner.ORPORT, [link_protocol]) + def test_connection_time(self): + """ + Checks duration we've been connected. + """ + + before = time.time() + + with Relay.connect('127.0.0.1', test.runner.ORPORT) as conn: + connection_time = conn.connection_time() + self.assertTrue(time.time() >= connection_time >= before) + time.sleep(0.02) + self.assertTrue(conn.is_alive()) + + self.assertFalse(conn.is_alive()) + self.assertTrue(conn.connection_time() >= connection_time + 0.02) + def test_established(self): """ Successfully establish ORPort connection. [View Less]

1 0

[stem/master] Move cell decryption into circuit
by atagar＠torproject.org 07 Feb '18

07 Feb '18

commit 981760fd7996c849945a1b41e6c304d191267d26 Author: Damian Johnson <atagar(a)torproject.org> Date: Mon Feb 5 18:37:00 2018 -0800 Move cell decryption into circuit --- stem/client/__init__.py | 4 ++++ stem/client/cell.py | 21 ++++++--------------- 2 files changed, 10 insertions(+), 15 deletions(-) diff --git a/stem/client/__init__.py b/stem/client/__init__.py index 4f9ed17c..8d34b626 100644 --- a/stem/client/__init__.py +++ b/stem/client/__init__.py @@ -234,6 +234,10 @@ … [View More]class Circuit(object): encrypted_payload = header + self.forward_key.update(payload) self.relay._orport.send(encrypted_payload) + reply = next(stem.client.cell.Cell.unpack(self.relay._orport.recv(), self.relay.link_protocol)) + + decrypted = self.backward_key.update(reply.pack(3)[3:]) + return stem.client.cell.RelayCell._unpack(decrypted, self.id, 3) except: self.forward_digest = orig_digest self.forward_key = orig_key diff --git a/stem/client/cell.py b/stem/client/cell.py index c4a19940..041e1c39 100644 --- a/stem/client/cell.py +++ b/stem/client/cell.py @@ -292,6 +292,7 @@ class RelayCell(CircuitCell): :var stem.client.RelayCommand command: command to be issued :var int command_int: integer value of our command :var bytes data: payload of the cell + :var int recognized: zero if endpoint is this hop, non-zero otherwise :var int digest: running digest held with the relay :var int stream_id: specific stream this concerns """ @@ -307,7 +308,7 @@ class RelayCell(CircuitCell): VALUE = 3 IS_FIXED_SIZE = True - def __init__(self, circ_id, command, data, digest = 0, stream_id = 0, raw_content = None): + def __init__(self, circ_id, command, data, digest = 0, stream_id = 0, recognized = 0): if 'hashlib.HASH' in str(type(digest)): # Unfortunately hashlib generates from a dynamic private class so # isinstance() isn't such a great option. @@ -323,9 +324,9 @@ class RelayCell(CircuitCell): super(RelayCell, self).__init__(circ_id) self.command, self.command_int = RelayCommand.get(command) self.data = data + self.recognized = recognized self.digest = digest self.stream_id = stream_id - self._raw_content = raw_content if not stream_id and self.command in STREAM_ID_REQUIRED: raise ValueError('%s relay cells require a stream id' % self.command) @@ -335,7 +336,7 @@ class RelayCell(CircuitCell): def pack(self, link_protocol): payload = io.BytesIO() payload.write(Size.CHAR.pack(self.command_int)) - payload.write(Size.SHORT.pack(0)) # 'recognized' field + payload.write(Size.SHORT.pack(self.recognized)) payload.write(Size.SHORT.pack(self.stream_id)) payload.write(Size.LONG.pack(self.digest)) payload.write(Size.SHORT.pack(len(self.data))) @@ -343,28 +344,18 @@ class RelayCell(CircuitCell): return RelayCell._pack(link_protocol, payload.getvalue(), self.circ_id) - def decrypt(self, circ): - # TODO: clearly funky, just a spot to start... - - if not self._raw_content: - raise ValueError('Only received cells can be decrypted') - - decrypted = circ.backward_key.update(self._raw_content) - return RelayCell._unpack(decrypted, self.circ_id, 3) - - @classmethod def _unpack(cls, content, circ_id, link_protocol): orig_content = content command, content = Size.CHAR.pop(content) - _, content = Size.SHORT.pop(content) # 'recognized' field + recognized, content = Size.SHORT.pop(content) # 'recognized' field stream_id, content = Size.SHORT.pop(content) digest, content = Size.LONG.pop(content) data_len, content = Size.SHORT.pop(content) data, content = split(content, data_len) - return RelayCell(circ_id, command, data, digest, stream_id, orig_content) + return RelayCell(circ_id, command, data, digest, stream_id, recognized) def __hash__(self): return _hash_attr(self, 'command_int', 'stream_id', 'digest', 'data') [View Less]

1 0