[tor-commits] [stem/master] Add check_recognized_field instance method to BaseRelayCell

[atagar at torproject.org]

commit f82d839704788a063135a2b32f7657b2f9167fda
Author: Dave Rolek <dmr-x at riseup.net>
Date:   Sun Aug 19 03:48:05 2018 +0000

    Add check_recognized_field instance method to BaseRelayCell
    
    This is new functionality. (Nothing in stem.client currently attempts to
    check the 'recognized' field.)
    
    Not yet used.
    
    This is arguably a very inefficient method, and it might even obscure
    its purpose by existing (it's extremely simple), but it seemed better to
    break it out and deal with the foreseeable performance hit than to trend
    towards premature optimization.
    
    (It also is a bit counterintuitive for a value of 0 to mean True, so
    breaking this out makes that clearer.)
    
    There are many ways this could be optimized, and - especially since so
    much of this unit is still in flux - it doesn't make sense yet to do so.
---
 stem/client/cell.py | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/stem/client/cell.py b/stem/client/cell.py
index 5235331e..250d400a 100644
--- a/stem/client/cell.py
+++ b/stem/client/cell.py
@@ -354,6 +354,22 @@ class BaseRelayCell(CircuitCell):
     # unlike everywhere else, we actually want to use the subclass type, NOT *this* class
     return cls(circ_id, content)
 
+  def check_recognized_field(self):
+    """
+    Checks the 'recognized' field of the cell payload, which indicates whether
+    it is **probably** fully decrypted.
+
+    :returns: **bool** indicating whether the 'recognized' field indicates
+      likely decryption. Per the spec:
+        * **False** guarantees the cell *not* to be fully decrypted.
+        * **True** does *not* guarantee the cell to be fully decrypted, and it
+          must be checked further. See also
+          :func:`~stem.client.cell.BaseRelayCell.check_digest`
+    """
+
+    _, recognized_from_cell, _, _, _, _, _ = RelayCell._unpack_payload(self.payload)
+    return recognized_from_cell == 0
+
   def check_digest(self, digest):
     """
     Calculates the running digest of the cell payload per the spec, returning