diff options
Diffstat (limited to 'doc/api/ssl.rst')
| -rw-r--r-- | doc/api/ssl.rst | 360 |
1 files changed, 2 insertions, 358 deletions
diff --git a/doc/api/ssl.rst b/doc/api/ssl.rst index 8a0bd64..c678b28 100644 --- a/doc/api/ssl.rst +++ b/doc/api/ssl.rst @@ -236,364 +236,8 @@ Connection objects Connection objects have the following methods: -.. py:method:: Connection.accept() - - Call the :py:meth:`accept` method of the underlying socket and set up SSL on the - returned socket, using the Context object supplied to this Connection object at - creation. Returns a pair *(conn, address)*. where *conn* is the new - Connection object created, and *address* is as returned by the socket's - :py:meth:`accept`. - - -.. py:method:: Connection.bind(address) - - Call the :py:meth:`bind` method of the underlying socket. - - -.. py:method:: Connection.close() - - Call the :py:meth:`close` method of the underlying socket. Note: If you want - correct SSL closure, you need to call the :py:meth:`shutdown` method first. - - -.. py:method:: Connection.connect(address) - - Call the :py:meth:`connect` method of the underlying socket and set up SSL on the - socket, using the Context object supplied to this Connection object at - creation. - - -.. py:method:: Connection.connect_ex(address) - - Call the :py:meth:`connect_ex` method of the underlying socket and set up SSL on - the socket, using the Context object supplied to this Connection object at - creation. Note that if the :py:meth:`connect_ex` method of the socket doesn't - return 0, SSL won't be initialized. - - -.. py:method:: Connection.do_handshake() - - Perform an SSL handshake (usually called after :py:meth:`renegotiate` or one of - :py:meth:`set_accept_state` or :py:meth:`set_accept_state`). This can raise the - same exceptions as :py:meth:`send` and :py:meth:`recv`. - - -.. py:method:: Connection.fileno() - - Retrieve the file descriptor number for the underlying socket. - - -.. py:method:: Connection.listen(backlog) - - Call the :py:meth:`listen` method of the underlying socket. - - -.. py:method:: Connection.get_app_data() - - Retrieve application data as set by :py:meth:`set_app_data`. - - -.. automethod:: Connection.get_cipher_list - - -.. py:method:: Connection.get_protocol_version() - - Retrieve the version of the SSL or TLS protocol used by the Connection. - For example, it will return ``0x769`` for connections made over TLS - version 1. - - -.. py:method:: Connection.get_protocol_version_name() - - Retrieve the version of the SSL or TLS protocol used by the Connection as - a unicode string. For example, it will return ``TLSv1`` for connections - made over TLS version 1, or ``Unknown`` for connections that were not - successfully established. - - -.. py:method:: Connection.get_client_ca_list() - - Retrieve the list of preferred client certificate issuers sent by the server - as :py:class:`OpenSSL.crypto.X509Name` objects. - - If this is a client :py:class:`Connection`, the list will be empty until the - connection with the server is established. - - If this is a server :py:class:`Connection`, return the list of certificate - authorities that will be sent or has been sent to the client, as controlled - by this :py:class:`Connection`'s :py:class:`Context`. - - .. versionadded:: 0.10 - - -.. py:method:: Connection.get_context() - - Retrieve the Context object associated with this Connection. - - -.. py:method:: Connection.set_context(context) - - Specify a replacement Context object for this Connection. - - -.. py:method:: Connection.get_peer_certificate() - - Retrieve the other side's certificate (if any) - - -.. py:method:: Connection.get_peer_cert_chain() - - Retrieve the tuple of the other side's certificate chain (if any) - - -.. py:method:: Connection.getpeername() - - Call the :py:meth:`getpeername` method of the underlying socket. - - -.. py:method:: Connection.getsockname() - - Call the :py:meth:`getsockname` method of the underlying socket. - - -.. py:method:: Connection.getsockopt(level, optname[, buflen]) - - Call the :py:meth:`getsockopt` method of the underlying socket. - - -.. py:method:: Connection.pending() - - Retrieve the number of bytes that can be safely read from the SSL buffer - (**not** the underlying transport buffer). - - -.. py:method:: Connection.recv(bufsize[, flags]) - - Receive data from the Connection. The return value is a string representing the - data received. The maximum amount of data to be received at once, is specified - by *bufsize*. The only supported flag is ``MSG_PEEK``, all other flags are - ignored. - - -.. py:method:: Connection.recv_into(buffer[, nbytes[, flags]]) - - Receive data from the Connection and copy it directly into the provided - buffer. The return value is the number of bytes read from the connection. - The maximum amount of data to be received at once is specified by *nbytes*. - The only supported flag is ``MSG_PEEK``, all other flags are ignored. - -.. py:method:: Connection.bio_write(bytes) - - If the Connection was created with a memory BIO, this method can be used to add - bytes to the read end of that memory BIO. The Connection can then read the - bytes (for example, in response to a call to :py:meth:`recv`). - - -.. automethod:: Connection.renegotiate - -.. automethod:: Connection.renegotiate_pending - -.. automethod:: Connection.total_renegotiations - -.. py:method:: Connection.send(string) - - Send the *string* data to the Connection. - - -.. py:method:: Connection.bio_read(bufsize) - - If the Connection was created with a memory BIO, this method can be used to - read bytes from the write end of that memory BIO. Many Connection methods will - add bytes which must be read in this manner or the buffer will eventually fill - up and the Connection will be able to take no further actions. - - -.. py:method:: Connection.sendall(string) - - Send all of the *string* data to the Connection. This calls :py:meth:`send` - repeatedly until all data is sent. If an error occurs, it's impossible to tell - how much data has been sent. - - -.. py:method:: Connection.set_accept_state() - - Set the connection to work in server mode. The handshake will be handled - automatically by read/write. - - -.. py:method:: Connection.set_app_data(data) - - Associate *data* with this Connection object. *data* can be retrieved - later using the :py:meth:`get_app_data` method. - - -.. py:method:: Connection.set_connect_state() - - Set the connection to work in client mode. The handshake will be handled - automatically by read/write. - - -.. py:method:: Connection.setblocking(flag) - - Call the :py:meth:`setblocking` method of the underlying socket. - - -.. py:method:: Connection.setsockopt(level, optname, value) - - Call the :py:meth:`setsockopt` method of the underlying socket. - - -.. py:method:: Connection.shutdown() - - Send the shutdown message to the Connection. Returns true if the shutdown - message exchange is completed and false otherwise (in which case you call - :py:meth:`recv` or :py:meth:`send` when the connection becomes - readable/writeable. - - -.. py:method:: Connection.get_shutdown() - - Get the shutdown state of the Connection. Returns a bitvector of either or - both of *SENT_SHUTDOWN* and *RECEIVED_SHUTDOWN*. - - -.. py:method:: Connection.set_shutdown(state) - - Set the shutdown state of the Connection. *state* is a bitvector of - either or both of *SENT_SHUTDOWN* and *RECEIVED_SHUTDOWN*. - - -.. py:method:: Connection.sock_shutdown(how) - - Call the :py:meth:`shutdown` method of the underlying socket. - - -.. py:method:: Connection.bio_shutdown() - - If the Connection was created with a memory BIO, this method can be used to - indicate that *end of file* has been reached on the read end of that memory - BIO. - - -.. automethod:: Connection.get_state_string - -.. py:method:: Connection.client_random() - - Retrieve the random value used with the client hello message. - - -.. py:method:: Connection.server_random() - - Retrieve the random value used with the server hello message. - - -.. py:method:: Connection.master_key() - - Retrieve the value of the master key for this session. - - -.. py:method:: Connection.want_read() - - Checks if more data has to be read from the transport layer to complete an - operation. - - -.. py:method:: Connection.want_write() - - Checks if there is data to write to the transport layer to complete an - operation. - - -.. py:method:: Connection.set_tlsext_host_name(name) - - Specify the byte string to send as the server name in the client hello message. - - .. versionadded:: 0.13 - - -.. py:method:: Connection.get_servername() - - Get the value of the server name received in the client hello message. - - .. versionadded:: 0.13 - - -.. py:method:: Connection.get_session() - - Get a :py:class:`Session` instance representing the SSL session in use by - the connection, or :py:obj:`None` if there is no session. - - .. versionadded:: 0.14 - - -.. py:method:: Connection.set_session(session) - - Set a new SSL session (using a :py:class:`Session` instance) to be used by - the connection. - - .. versionadded:: 0.14 - - -.. py:method:: Connection.get_finished() - - Obtain latest TLS Finished message that we sent, or :py:obj:`None` if - handshake is not completed. - - .. versionadded:: 0.15 - - -.. py:method:: Connection.get_peer_finished() - - Obtain latest TLS Finished message that we expected from peer, or - :py:obj:`None` if handshake is not completed. - - .. versionadded:: 0.15 - - -.. py:method:: Connection.get_cipher_name() - - Obtain the name of the currently used cipher. - - .. versionadded:: 0.15 - - -.. py:method:: Connection.get_cipher_bits() - - Obtain the number of secret bits of the currently used cipher. - - .. versionadded:: 0.15 - - -.. py:method:: Connection.get_cipher_version() - - Obtain the protocol name of the currently used cipher. - - .. versionadded:: 0.15 - - -.. py:method:: Connection.get_next_proto_negotiated(): - - Get the protocol that was negotiated by Next Protocol Negotiation. Returns - a bytestring of the protocol name. If no protocol has been negotiated yet, - returns an empty string. - - .. versionadded:: 0.15 - -.. py:method:: Connection.set_alpn_protos(protos) - - Specify the protocols that the client is prepared to speak after the TLS - connection has been negotiated using Application Layer Protocol - Negotiation. - - *protos* should be a list of protocols that the client is offering, each - as a bytestring. For example, ``[b'http/1.1', b'spdy/2']``. - - -.. py:method:: Connection.get_alpn_proto_negotiated() - - Get the protocol that was negotiated by Application Layer Protocol - Negotiation. Returns a bytestring of the protocol name. If no protocol has - been negotiated yet, returns an empty string. +.. autoclass:: OpenSSL.SSL.Connection + :members: .. Rubric:: Footnotes |