Connection.shutdown docs and test don't quite match OpenSSL

[davidben]

The docs for shutdown say:

        :return: True if the shutdown completed successfully (i.e. both sides
                 have sent closure alerts), false otherwise (i.e. you have to
                 wait for a ZeroReturnError on a recv() method call

The test_shutdown test behaves accordingly.

This isn't quite how OpenSSL expects you to call SSL_shutdown. If you care about sending AND receiving close_notify, and the first successful SSL_shutdown returned 0, you call SSL_shutdown twice. The second success will return 1. (Or the first success may return 1 if you got a close_notify already. Then you only need to call it once.) https://www.openssl.org/docs/manmaster/ssl/SSL_shutdown.html

The documentation also suggests that you always should drive the shutdown to fully complete, but most applications do not care. It's just for reusing the transport, which no one does. (Think inverse of STARTTLS.) The spec says:

It is not required for the initiator of the close to wait for the responding close_notify alert before closing the read side of the connection.

If the application protocol using TLS provides that any data may be carried over the underlying transport after the TLS connection is closed, the TLS implementation must receive the responding close_notify alert before indicating to the application layer that the TLS connection has ended. If the application protocol will not transfer any additional data, but will only close the underlying transport connection, then the implementation MAY choose to close the transport without waiting for the responding close_notify. No part of this standard should be taken to dictate the manner in which a usage profile for TLS manages its data transport, including when connections are opened or closed.