commit 86540f43e8afd4100c703e7ac3db411470925450 Author: Isis Lovecruft isis@torproject.org Date: Mon Apr 22 00:49:01 2013 +0000

Reformat docstrings for several HandshakeTest functions to Sphinx format.

Includes updates to docstrings for functions: * makeConnection() * connectionFailed() * connectionSucceeded() * connectionShutdown() * handleWantRead() * handleWantWrite() * doHandshake() * handshakeSucceeded() * handshakefailed() --- nettests/experimental/tls_handshake.py | 170 ++++++++++++++++++-------------- 1 file changed, 94 insertions(+), 76 deletions(-)

diff --git a/nettests/experimental/tls_handshake.py b/nettests/experimental/tls_handshake.py index 6a0d7b6..c26b279 100644 --- a/nettests/experimental/tls_handshake.py +++ b/nettests/experimental/tls_handshake.py @@ -297,14 +297,15 @@ class HandshakeTest(nettest.NetTestCase): """xxx fill me in"""

def makeConnection(host): - """ - Create a socket to the host's IP address, then get the TLS/SSL context - method and ciphersuite list. Lastly, initiate a connection to the - host. - - @param host: A tuple of the host IP and port, i.e. (addr, port). - @returns: A :class:`OpenSSL.SSL.Connection` object (or any Exception - that was raised), and the :param:`host`. + """Create a socket to the remote host's IP address, then get the + TLS/SSL context method and ciphersuite list. Lastly, initiate a + connection to the host. + + :param tuple host: A tuple of the remote host's IP address as a + string, and an integer specifying the remote host port, i.e. + ('1.1.1.1',443) + :raises: :exc:`ConnectionTimeout` if the socket timed out. + :returns: A :class:`OpenSSL.SSL.Connection <Connection>`. """ addr, port = host sckt = self.buildSocket(addr) @@ -319,14 +320,18 @@ class HandshakeTest(nettest.NetTestCase): return connection

def connectionFailed(connection, host): - """ - Handle errors raised while attempting to create the socket, TLS/SSL - context, and :class:`OpenSSL.SSL.Connection` object. - - @param connection: The Exception that was raised in - :func:`makeConnection`. - @param host: A tuple of the host IP address as a string, and an int - specifying the host port, i.e. ('1.1.1.1', 443) + """Handle errors raised while attempting to create the socket and + :class:`OpenSSL.SSL.Connection <Connection>`, and setting the + TLS/SSL context. + + :type connection: :exc:Exception + :param connection: The exception that was raised in + :func:`HandshakeTest.test_handshake.makeConnection + <makeConnection>`. + :param tuple host: A tuple of the host IP address as a string, and + an int specifying the host port, i.e. ('1.1.1.1', 443) + :rtype: :exc:Exception + :returns: The original exception. """ addr, port = host

@@ -355,13 +360,15 @@ class HandshakeTest(nettest.NetTestCase): return connection

def connectionSucceeded(connection, host, timeout): - """ - If we have created a connection, set the socket options, and log the - connection state and peer name. + """If we have created a connection, set the socket options, and log + the connection state and peer name.

- @param connection: A :class:`OpenSSL.SSL.Connection` object. - @param host: A tuple of the host IP and port, i.e. ('1.1.1.1', 443). + :param connection: A :class:`OpenSSL.SSL.Connection <Connection>`. + :param tuple host: A tuple of the remote host's IP address as a + string, and an integer specifying the remote host port, i.e. + ('1.1.1.1',443) """ + ## xxx TODO to get this to work with a non-blocking socket, see how ## twisted.internet.tcp.Client handles socket objects. connection.setblocking(1) @@ -391,6 +398,14 @@ class HandshakeTest(nettest.NetTestCase): return connection

def connectionRenegotiate(connection, host, error_message): + """Handle a server-initiated SSL/TLS handshake renegotiation. + + :param connection: A :class:`OpenSSL.SSL.Connection <Connection>`. + :param tuple host: A tuple of the remote host's IP address as a + string, and an integer specifying the remote host port, i.e. + ('1.1.1.1',443) + """ + log.msg("Server requested renegotiation from: %s" % host) log.debug("Renegotiation reason: %s" % error_message) log.debug("State: %s" % connection.state_string()) @@ -415,30 +430,31 @@ class HandshakeTest(nettest.NetTestCase): return connection

def connectionShutdown(connection, host): - """ - Handle shutting down a :class:`OpenSSL.SSL.Connection`, including - correct handling of halfway shutdown connections. - - Calls to :meth:`OpenSSL.SSL.Connection.shutdown` return a boolean - value: if the connection is already shutdown, it returns True, - else it returns false. Thus we loop through a block which detects - if the connection is an a partial shutdown state and corrects that - if that is the case, else it waits for one second, then attempts - shutting down the connection again. + """Handle shutting down a :class:`OpenSSL.SSL.Connection + <Connection>`, including correct handling of halfway shutdown + connections. + + Calls to :meth:`OpenSSL.SSL.Connection.shutdown + <Connection.shutdown()>` return a boolean value -- if the + connection is already shutdown, it returns True, else it returns + false. Thus we loop through a block which detects if the connection + is an a partial shutdown state and corrects that if that is the + case, else it waits for one second, then attempts shutting down the + connection again.

Detection of a partial shutdown state is done through - :meth:`OpenSSL.SSL.Connection.get_shutdown` which queries OpenSSL - for a bitvector of the server and client shutdown states. For - example, the binary string '0b00' is an open connection, and - '0b10' is a partially closed connection that has been shutdown on - the serverside. - - @param connection: A :class:`OpenSSL.SSL.Connection`. - - @param host: A tuple of: a string representation of the remote - host's IP address, and an integer specifying the - port. + :meth:`OpenSSL.SSL.Connection.get_shutdown + <Connection.get_shutdown()>` which queries OpenSSL for a bitvector + of the server and client shutdown states. For example, the binary + string '0b00' is an open connection, and '0b10' is a partially + closed connection that has been shutdown on the serverside. + + :param connection: A :class:`OpenSSL.SSL.Connection <Connection>`. + :param tuple host: A tuple of the remote host's IP address as a + string, and an integer specifying the remote host port, i.e. + ('1.1.1.1',443) """ + peername, peerport = host

if isinstance(connection, SSL.Connection): @@ -460,15 +476,15 @@ class HandshakeTest(nettest.NetTestCase): % (peername, peerport)) elif isinstance(connection, types.NoneType): log.debug("connectionShutdown: got NoneType for connection") + return else: - log.debug("connectionShutdown: expected connection, got %s" + log.debug("connectionShutdown: expected connection, got %r" % connection.__repr__())

return connection

def handleWantRead(connection): - """ - From OpenSSL memory BIO documentation on ssl_read(): + """From OpenSSL memory BIO documentation on ssl_read():

If the underlying BIO is blocking, SSL_read() will only return, once the read operation has been finished or an error @@ -545,9 +561,7 @@ class HandshakeTest(nettest.NetTestCase): return connection

def handleWantWrite(connection): - """ - See :func:`handleWantRead`. - """ + """See :func:HandshakeTest.test_hanshake.handleWantRead """ try: while connection.want_write(): self.state = connection.state_string() @@ -565,8 +579,7 @@ class HandshakeTest(nettest.NetTestCase): return connection

def doHandshake(connection): - """ - Attemp a TLS/SSL handshake with the host. + """Attempt a TLS/SSL handshake with the host.

If, after the first attempt at handshaking, OpenSSL's memory BIO state machine does not report success, then try reading and @@ -578,15 +591,19 @@ class HandshakeTest(nettest.NetTestCase): possible that the connection has timed out, and move on to the connectionShutdown step.

- @param connection: A :class:`OpenSSL.SSL.Connection`. - @ivar peername: The host IP address, as reported by getpeername(). - @ivar peerport: The host port, reported by getpeername(). - @ivar sent: The number of bytes sent to to the remote host. - @ivar received: The number of bytes received from the remote host. - @ivar _read_buffer: An integer for the max bytes that can be read - from the connection. - @returns: The :param:connection with handshake completed, else - the unhandled error that was raised. + :param connection: A :class:`OpenSSL.SSL.Connection <Connection>`. + :ivar peername: The host IP address, as reported by + :meth:`Connection.getpeername <connection.getpeername()>`. + :ivar peerport: The host port, reported by + :meth:`Connection.getpeername <connection.getpeername()>`. + :ivar int sent: The number of bytes sent to to the remote host. + :ivar int received: The number of bytes received from the remote + host. + :ivar int _read_buffer: The max bytes that can be read from the + connection. + :returns: The :param:`doHandshake.connection <connection>` with + handshake completed, else the unhandled error that was + raised. """ peername, peerport = connection.getpeername()

@@ -647,19 +664,18 @@ class HandshakeTest(nettest.NetTestCase): return connection

def handshakeSucceeded(connection): - """ - Get the details from the server certificate, cert chain, and + """Get the details from the server certificate, cert chain, and server ciphersuite list, and put them in our report.

WARNING: do *not* do this: - >>> server_cert.get_pubkey() - <OpenSSL.crypto.PKey at 0x4985d28> - >>> pk = server_cert.get_pubkey() - >>> pk.check() - Segmentation fault - - @param connection: A :class:`OpenSSL.SSL.Connection`. - @returns: None. + >>> server_cert.get_pubkey() + <OpenSSL.crypto.PKey at 0x4985d28> + >>> pk = server_cert.get_pubkey() + >>> pk.check() + Segmentation fault + + :param connection: A :class:`OpenSSL.SSL.Connection <Connection>`. + :returns: :param:`handshakeSucceeded.connection <connection>`. """ host, port = connection.getpeername() log.msg("Handshake with %s:%d successful!" % (host, port)) @@ -719,13 +735,15 @@ class HandshakeTest(nettest.NetTestCase): return connection

def handshakeFailed(connection, host): - """ - xxx fill me in - - @param connection: A :class:`twisted.python.failure.Failure` or - :class:`exceptions.Exception`. - @param host: A tuple of the host IP and port, i.e. ('1.1.1.1', 443). - @returns: None. + """Handle a failed handshake attempt and report the failure reason. + + :type connection: :class:`twisted.python.failure.Failure <Failure>` + or :exc:Exception + :param connection: The failed connection. + :param tuple host: A tuple of the remote host's IP address as a + string, and an integer specifying the remote host port, i.e. + ('1.1.1.1',443) + :returns: None """ addr, port = host log.msg("Handshake with %s:%d failed!" % host)