diff options
Diffstat (limited to 'src/OpenSSL/SSL.py')
| -rw-r--r-- | src/OpenSSL/SSL.py | 196 |
1 files changed, 121 insertions, 75 deletions
diff --git a/src/OpenSSL/SSL.py b/src/OpenSSL/SSL.py index 9bff583..5def0aa 100644 --- a/src/OpenSSL/SSL.py +++ b/src/OpenSSL/SSL.py @@ -759,7 +759,7 @@ class Context(object): If capath is passed, it must be a directory prepared using the ``c_rehash`` tool included with OpenSSL. Either, but not both, of - *pemfile* or *capath* may be :py:data:`None`. + *pemfile* or *capath* may be :data:`None`. :param cafile: In which file we can find the certificates (``bytes`` or ``unicode``). @@ -1169,8 +1169,8 @@ class Context(object): Select a curve to use for ECDHE key exchange. :param curve: A curve object to use as returned by either - :py:meth:`OpenSSL.crypto.get_elliptic_curve` or - :py:meth:`OpenSSL.crypto.get_elliptic_curves`. + :meth:`OpenSSL.crypto.get_elliptic_curve` or + :meth:`OpenSSL.crypto.get_elliptic_curves`. :return: None """ @@ -1415,9 +1415,9 @@ class Context(object): @_requires_alpn def set_alpn_protos(self, protos): """ - Specify the ALPN protocol list of the client. - - These protocols are offered to the server during protocol negotiation. + Specify the protocols that the client is prepared to speak after the + TLS connection has been negotiated using Application Layer Protocol + Negotiation. :param protos: A list of the protocols to be offered to the server. This list should be a Python list of bytestrings representing the @@ -1624,15 +1624,16 @@ class Connection(object): def get_context(self): """ - Get session context + Retrieve the :class:`Context` object associated with this + :class:`Connection`. """ return self._context def set_context(self, context): """ - Switch this connection to a new session context + Switch this connection to a new session context. - :param context: A :py:class:`Context` instance giving the new session + :param context: A :class:`Context` instance giving the new session context to use. """ if not isinstance(context, Context): @@ -1647,7 +1648,9 @@ class Connection(object): Retrieve the servername extension value if provided in the client hello message, or None if there wasn't one. - :return: A byte string giving the server name or :py:data:`None`. + :return: A byte string giving the server name or :data:`None`. + + .. versionadded:: 0.13 """ name = _lib.SSL_get_servername( self._ssl, _lib.TLSEXT_NAMETYPE_host_name @@ -1663,6 +1666,8 @@ class Connection(object): Set the value of the servername extension to send in the client hello. :param name: A byte string giving the name. + + .. versionadded:: 0.13 """ if not isinstance(name, bytes): raise TypeError("name must be a byte string") @@ -1674,7 +1679,8 @@ class Connection(object): def pending(self): """ - Get the number of bytes that can be safely read from the connection + Get the number of bytes that can be safely read from the SSL buffer + (**not** the underlying transport buffer). :return: The number of bytes available in the receive buffer. """ @@ -1764,8 +1770,8 @@ class Connection(object): def recv_into(self, buffer, nbytes=None, flags=None): """ - Receive data on the connection and store the data into a buffer rather - than creating a new string. + Receive data on the connection and copy it directly into the provided + buffer, rather than creating a new string. :param buffer: The buffer to copy into. :param nbytes: (optional) The maximum number of bytes to read into the @@ -1823,8 +1829,11 @@ class Connection(object): def bio_read(self, bufsiz): """ - When using non-socket connections this function reads the "dirty" data - that would have traveled away on the network. + 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. :param bufsiz: The maximum number of bytes to read :return: The string read. @@ -1844,8 +1853,10 @@ class Connection(object): def bio_write(self, buf): """ - When using non-socket connections this function sends "dirty" data that - would have traveled in on the network. + 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 + :meth:`recv`). :param buf: The string to put into the memory BIO. :return: The number of bytes written @@ -1874,8 +1885,9 @@ class Connection(object): def do_handshake(self): """ - Perform an SSL handshake (usually called after renegotiate() or one of - set_*_state()). This can raise the same exceptions as send and recv. + Perform an SSL handshake (usually called after :meth:`renegotiate` or + one of :meth:`set_accept_state` or :meth:`set_accept_state`). This can + raise the same exceptions as :meth:`send` and :meth:`recv`. :return: None. """ @@ -1903,7 +1915,9 @@ class Connection(object): def connect(self, addr): """ - Connect to remote host and set up client-side SSL + Call the :meth:`connect` method of the underlying socket and set up SSL + on the socket, using the :class:`Context` object supplied to this + :class:`Connection` object at creation. :param addr: A remote address :return: What the socket's connect method returns @@ -1913,8 +1927,10 @@ class Connection(object): def connect_ex(self, addr): """ - Connect to remote host and set up client-side SSL. Note that if the - socket's connect_ex method doesn't return 0, SSL won't be initialized. + Call the :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 :meth:`connect_ex` method of the + socket doesn't return 0, SSL won't be initialized. :param addr: A remove address :return: What the socket's connect_ex method returns @@ -1925,10 +1941,13 @@ class Connection(object): def accept(self): """ - Accept incoming connection and set up SSL on it + Call the :meth:`accept` method of the underlying socket and set up SSL + on the returned socket, using the Context object supplied to this + :class:`Connection` object at creation. - :return: A (conn,addr) pair where conn is a Connection and addr is an - address + :return: A *(conn, addr)* pair where *conn* is the new + :class:`Connection` object created, and *address* is as returned by + the socket's :meth:`accept`. """ client, addr = self._socket.accept() conn = Connection(self._context, client) @@ -1937,8 +1956,9 @@ class Connection(object): def bio_shutdown(self): """ - When using non-socket connections this function signals end of - data on the input for this connection. + 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. :return: None """ @@ -1949,11 +1969,12 @@ class Connection(object): def shutdown(self): """ - Send closure alert + Send the shutdown message to the Connection. :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 + have sent closure alerts), False otherwise (in which case you + call :meth:`recv` or :meth:`send` when the connection becomes + readable/writeable). """ result = _lib.SSL_shutdown(self._ssl) if result < 0: @@ -1981,12 +2002,14 @@ class Connection(object): """ Get CAs whose certificates are suggested for client authentication. - :return: If this is a server connection, a list of X509Names - representing the acceptable CAs as set by - :py:meth:`OpenSSL.SSL.Context.set_client_ca_list` or - :py:meth:`OpenSSL.SSL.Context.add_client_ca`. If this is a client - connection, the list of such X509Names sent by the server, or an - empty list if that has not yet happened. + :return: If this is a server connection, the list of certificate + authorities that will be sent or has been sent to the client, as + controlled by this :class:`Connection`'s :class:`Context`. + + If this is a client connection, the list will be empty until the + connection with the server is established. + + .. versionadded:: 0.10 """ ca_names = _lib.SSL_get_client_CA_list(self._ssl) if ca_names == _ffi.NULL: @@ -2016,7 +2039,7 @@ class Connection(object): def get_app_data(self): """ - Get application data + Retrieve application data as set by :meth:`set_app_data`. :return: The application data """ @@ -2026,14 +2049,14 @@ class Connection(object): """ Set application data - :param data - The application data + :param data: The application data :return: None """ self._app_data = data def get_shutdown(self): """ - Get shutdown state + Get the shutdown state of the Connection. :return: The shutdown state, a bitvector of SENT_SHUTDOWN, RECEIVED_SHUTDOWN. @@ -2042,9 +2065,9 @@ class Connection(object): def set_shutdown(self, state): """ - Set shutdown state + Set the shutdown state of the Connection. - :param state - bitvector of SENT_SHUTDOWN, RECEIVED_SHUTDOWN. + :param state: bitvector of SENT_SHUTDOWN, RECEIVED_SHUTDOWN. :return: None """ if not isinstance(state, integer_types): @@ -2063,7 +2086,7 @@ class Connection(object): def server_random(self): """ - Get a copy of the server hello nonce. + Retrieve the random value used with the server hello message. :return: A string representing the state """ @@ -2078,7 +2101,7 @@ class Connection(object): def client_random(self): """ - Get a copy of the client hello nonce. + Retrieve the random value used with the client hello message. :return: A string representing the state """ @@ -2094,7 +2117,7 @@ class Connection(object): def master_key(self): """ - Get a copy of the master key. + Retrieve the value of the master key for this session. :return: A string representing the state """ @@ -2112,10 +2135,10 @@ class Connection(object): """ Obtain keying material for application use. - :param label - a disambiguating label string as described in RFC 5705 - :param olen - the length of the exported key material in bytes - :param context - a per-association context value - :return the exported key material bytes or None + :param: label - a disambiguating label string as described in RFC 5705 + :param: olen - the length of the exported key material in bytes + :param: context - a per-association context value + :return: the exported key material bytes or None """ outp = _no_zero_allocator("unsigned char[]", olen) context_buf = _ffi.NULL @@ -2134,7 +2157,8 @@ class Connection(object): def sock_shutdown(self, *args, **kwargs): """ - See shutdown(2) + Call the :meth:`shutdown` method of the underlying socket. + See :manpage:`shutdown(2)`. :return: What the socket's shutdown() method returns """ @@ -2210,8 +2234,10 @@ class Connection(object): """ Returns the Session currently used. - @return: An instance of :py:class:`OpenSSL.SSL.Session` or - :py:obj:`None` if no session exists. + :return: An instance of :class:`OpenSSL.SSL.Session` or + :obj:`None` if no session exists. + + .. versionadded:: 0.14 """ session = _lib.SSL_get1_session(self._ssl) if session == _ffi.NULL: @@ -2227,6 +2253,8 @@ class Connection(object): :param session: A Session instance representing the session to use. :returns: None + + .. versionadded:: 0.14 """ if not isinstance(session, Session): raise TypeError("session must be a Session instance") @@ -2237,15 +2265,15 @@ class Connection(object): def _get_finished_message(self, function): """ - Helper to implement :py:meth:`get_finished` and - :py:meth:`get_peer_finished`. + Helper to implement :meth:`get_finished` and + :meth:`get_peer_finished`. - :param function: Either :py:data:`SSL_get_finished`: or - :py:data:`SSL_get_peer_finished`. + :param function: Either :data:`SSL_get_finished`: or + :data:`SSL_get_peer_finished`. - :return: :py:data:`None` if the desired message has not yet been + :return: :data:`None` if the desired message has not yet been received, otherwise the contents of the message. - :rtype: :py:class:`bytes` or :py:class:`NoneType` + :rtype: :class:`bytes` or :class:`NoneType` """ # The OpenSSL documentation says nothing about what might happen if the # count argument given is zero. Specifically, it doesn't say whether @@ -2271,21 +2299,25 @@ class Connection(object): def get_finished(self): """ - Obtain the latest `handshake finished` message sent to the peer. + Obtain the latest TLS Finished message that we sent. - :return: The contents of the message or :py:obj:`None` if the TLS + :return: The contents of the message or :obj:`None` if the TLS handshake has not yet completed. - :rtype: :py:class:`bytes` or :py:class:`NoneType` + :rtype: :class:`bytes` or :class:`NoneType` + + .. versionadded:: 0.15 """ return self._get_finished_message(_lib.SSL_get_finished) def get_peer_finished(self): """ - Obtain the latest `handshake finished` message received from the peer. + Obtain the latest TLS Finished message that we received from the peer. - :return: The contents of the message or :py:obj:`None` if the TLS + :return: The contents of the message or :obj:`None` if the TLS handshake has not yet completed. - :rtype: :py:class:`bytes` or :py:class:`NoneType` + :rtype: :class:`bytes` or :class:`NoneType` + + .. versionadded:: 0.15 """ return self._get_finished_message(_lib.SSL_get_peer_finished) @@ -2293,9 +2325,11 @@ class Connection(object): """ Obtain the name of the currently used cipher. - :returns: The name of the currently used cipher or :py:obj:`None` + :returns: The name of the currently used cipher or :obj:`None` if no connection has been established. - :rtype: :py:class:`unicode` or :py:class:`NoneType` + :rtype: :class:`unicode` or :class:`NoneType` + + .. versionadded:: 0.15 """ cipher = _lib.SSL_get_current_cipher(self._ssl) if cipher == _ffi.NULL: @@ -2309,8 +2343,10 @@ class Connection(object): Obtain the number of secret bits of the currently used cipher. :returns: The number of secret bits of the currently used cipher - or :py:obj:`None` if no connection has been established. - :rtype: :py:class:`int` or :py:class:`NoneType` + or :obj:`None` if no connection has been established. + :rtype: :class:`int` or :class:`NoneType` + + .. versionadded:: 0.15 """ cipher = _lib.SSL_get_current_cipher(self._ssl) if cipher == _ffi.NULL: @@ -2323,8 +2359,10 @@ class Connection(object): Obtain the protocol version of the currently used cipher. :returns: The protocol name of the currently used cipher - or :py:obj:`None` if no connection has been established. - :rtype: :py:class:`unicode` or :py:class:`NoneType` + or :obj:`None` if no connection has been established. + :rtype: :class:`unicode` or :class:`NoneType` + + .. versionadded:: 0.15 """ cipher = _lib.SSL_get_current_cipher(self._ssl) if cipher == _ffi.NULL: @@ -2335,23 +2373,23 @@ class Connection(object): def get_protocol_version_name(self): """ - Obtain the protocol version of the current connection. + Retrieve the protocol version of the current connection. :returns: The TLS version of the current connection, for example the value for TLS 1.2 would be ``TLSv1.2``or ``Unknown`` for connections that were not successfully established. - :rtype: :py:class:`unicode` + :rtype: :class:`unicode` """ version = _ffi.string(_lib.SSL_get_version(self._ssl)) return version.decode("utf-8") def get_protocol_version(self): """ - Obtain the protocol version of the current connection. + Retrieve the SSL or TLS protocol version of the current connection. - :returns: The TLS version of the current connection, for example - the value for TLS 1 would be 0x769. - :rtype: :py:class:`int` + :returns: The TLS version of the current connection. For example, + it will return ``0x769`` for connections made over TLS version 1. + :rtype: :class:`int` """ version = _lib.SSL_version(self._ssl) return version @@ -2360,6 +2398,11 @@ class Connection(object): def get_next_proto_negotiated(self): """ Get the protocol that was negotiated by NPN. + + :returns: A bytestring of the protocol name. If no protocol has been + negotiated yet, returns an empty string. + + .. versionadded:: 0.15 """ data = _ffi.new("unsigned char **") data_len = _ffi.new("unsigned int *") @@ -2394,6 +2437,9 @@ class Connection(object): def get_alpn_proto_negotiated(self): """ Get the protocol that was negotiated by ALPN. + + :returns: A bytestring of the protocol name. If no protocol has been + negotiated yet, returns an empty string. """ data = _ffi.new("unsigned char **") data_len = _ffi.new("unsigned int *") |