1.. _openssl-ssl: 2 3:py:mod:`SSL` --- An interface to the SSL-specific parts of OpenSSL 4=================================================================== 5 6.. py:module:: OpenSSL.SSL 7 :synopsis: An interface to the SSL-specific parts of OpenSSL 8 9 10This module handles things specific to SSL. There are two objects defined: 11Context, Connection. 12 13.. py:data:: SSLv2_METHOD 14 SSLv3_METHOD 15 SSLv23_METHOD 16 TLSv1_METHOD 17 TLSv1_1_METHOD 18 TLSv1_2_METHOD 19 20 These constants represent the different SSL methods to use when creating a 21 context object. If the underlying OpenSSL build is missing support for any 22 of these protocols, constructing a :py:class:`Context` using the 23 corresponding :py:const:`*_METHOD` will raise an exception. 24 25 26.. py:data:: VERIFY_NONE 27 VERIFY_PEER 28 VERIFY_FAIL_IF_NO_PEER_CERT 29 30 These constants represent the verification mode used by the Context 31 object's :py:meth:`set_verify` method. 32 33 34.. py:data:: FILETYPE_PEM 35 FILETYPE_ASN1 36 37 File type constants used with the :py:meth:`use_certificate_file` and 38 :py:meth:`use_privatekey_file` methods of Context objects. 39 40 41.. py:data:: OP_SINGLE_DH_USE 42 OP_SINGLE_ECDH_USE 43 44 Constants used with :py:meth:`set_options` of Context objects. 45 46 When these options are used, a new key will always be created when using 47 ephemeral (Elliptic curve) Diffie-Hellman. 48 49 50.. py:data:: OP_EPHEMERAL_RSA 51 52 Constant used with :py:meth:`set_options` of Context objects. 53 54 When this option is used, ephemeral RSA keys will always be used when doing 55 RSA operations. 56 57 58.. py:data:: OP_NO_TICKET 59 60 Constant used with :py:meth:`set_options` of Context objects. 61 62 When this option is used, the session ticket extension will not be used. 63 64 65.. py:data:: OP_NO_COMPRESSION 66 67 Constant used with :py:meth:`set_options` of Context objects. 68 69 When this option is used, compression will not be used. 70 71 72.. py:data:: OP_NO_SSLv2 73 OP_NO_SSLv3 74 OP_NO_TLSv1 75 OP_NO_TLSv1_1 76 OP_NO_TLSv1_2 77 OP_NO_TLSv1_3 78 79 Constants used with :py:meth:`set_options` of Context objects. 80 81 Each of these options disables one version of the SSL/TLS protocol. This 82 is interesting if you're using e.g. :py:const:`SSLv23_METHOD` to get an 83 SSLv2-compatible handshake, but don't want to use SSLv2. If the underlying 84 OpenSSL build is missing support for any of these protocols, the 85 :py:const:`OP_NO_*` constant may be undefined. 86 87 88.. py:data:: SSLEAY_VERSION 89 SSLEAY_CFLAGS 90 SSLEAY_BUILT_ON 91 SSLEAY_PLATFORM 92 SSLEAY_DIR 93 94 Constants used with :py:meth:`SSLeay_version` to specify what OpenSSL version 95 information to retrieve. See the man page for the :py:func:`SSLeay_version` C 96 API for details. 97 98 99.. py:data:: SESS_CACHE_OFF 100 SESS_CACHE_CLIENT 101 SESS_CACHE_SERVER 102 SESS_CACHE_BOTH 103 SESS_CACHE_NO_AUTO_CLEAR 104 SESS_CACHE_NO_INTERNAL_LOOKUP 105 SESS_CACHE_NO_INTERNAL_STORE 106 SESS_CACHE_NO_INTERNAL 107 108 Constants used with :py:meth:`Context.set_session_cache_mode` to specify 109 the behavior of the session cache and potential session reuse. See the man 110 page for the :py:func:`SSL_CTX_set_session_cache_mode` C API for details. 111 112 .. versionadded:: 0.14 113 114 115.. py:data:: OPENSSL_VERSION_NUMBER 116 117 An integer giving the version number of the OpenSSL library used to build this 118 version of pyOpenSSL. See the man page for the :py:func:`SSLeay_version` C API 119 for details. 120 121 122.. py:data:: NO_OVERLAPPING_PROTOCOLS 123 124 A sentinel value that can be returned by the callback passed to 125 :py:meth:`Context.set_alpn_select_callback` to indicate that 126 the handshake can continue without a specific application protocol. 127 128 .. versionadded:: 19.1 129 130 131.. autofunction:: SSLeay_version 132 133 134.. py:data:: ContextType 135 136 See :py:class:`Context`. 137 138 139.. autoclass:: Context 140 141.. autoclass:: Session 142 143 144.. py:data:: ConnectionType 145 146 See :py:class:`Connection`. 147 148 149.. py:class:: Connection(context, socket) 150 151 A class representing SSL connections. 152 153 *context* should be an instance of :py:class:`Context` and *socket* 154 should be a socket [#connection-context-socket]_ object. *socket* may be 155 *None*; in this case, the Connection is created with a memory BIO: see 156 the :py:meth:`bio_read`, :py:meth:`bio_write`, and :py:meth:`bio_shutdown` 157 methods. 158 159.. py:exception:: Error 160 161 This exception is used as a base class for the other SSL-related 162 exceptions, but may also be raised directly. 163 164 Whenever this exception is raised directly, it has a list of error messages 165 from the OpenSSL error queue, where each item is a tuple *(lib, function, 166 reason)*. Here *lib*, *function* and *reason* are all strings, describing 167 where and what the problem is. See :manpage:`err(3)` for more information. 168 169 170.. py:exception:: ZeroReturnError 171 172 This exception matches the error return code 173 :py:data:`SSL_ERROR_ZERO_RETURN`, and is raised when the SSL Connection has 174 been closed. In SSL 3.0 and TLS 1.0, this only occurs if a closure alert has 175 occurred in the protocol, i.e. the connection has been closed cleanly. Note 176 that this does not necessarily mean that the transport layer (e.g. a socket) 177 has been closed. 178 179 It may seem a little strange that this is an exception, but it does match an 180 :py:data:`SSL_ERROR` code, and is very convenient. 181 182 183.. py:exception:: WantReadError 184 185 The operation did not complete; the same I/O method should be called again 186 later, with the same arguments. Any I/O method can lead to this since new 187 handshakes can occur at any time. 188 189 The wanted read is for **dirty** data sent over the network, not the 190 **clean** data inside the tunnel. For a socket based SSL connection, 191 **read** means data coming at us over the network. Until that read 192 succeeds, the attempted :py:meth:`OpenSSL.SSL.Connection.recv`, 193 :py:meth:`OpenSSL.SSL.Connection.send`, or 194 :py:meth:`OpenSSL.SSL.Connection.do_handshake` is prevented or incomplete. You 195 probably want to :py:meth:`select()` on the socket before trying again. 196 197 198.. py:exception:: WantWriteError 199 200 See :py:exc:`WantReadError`. The socket send buffer may be too full to 201 write more data. 202 203 204.. py:exception:: WantX509LookupError 205 206 The operation did not complete because an application callback has asked to be 207 called again. The I/O method should be called again later, with the same 208 arguments. 209 210 .. note:: This won't occur in this version, as there are no such 211 callbacks in this version. 212 213 214.. py:exception:: SysCallError 215 216 The :py:exc:`SysCallError` occurs when there's an I/O error and OpenSSL's 217 error queue does not contain any information. This can mean two things: An 218 error in the transport protocol, or an end of file that violates the protocol. 219 The parameter to the exception is always a pair *(errnum, 220 errstr)*. 221 222 223 224.. _openssl-context: 225 226Context objects 227--------------- 228 229Context objects have the following methods: 230 231.. autoclass:: OpenSSL.SSL.Context 232 :members: 233 234.. _openssl-session: 235 236Session objects 237--------------- 238 239Session objects have no methods. 240 241 242.. _openssl-connection: 243 244Connection objects 245------------------ 246 247Connection objects have the following methods: 248 249.. autoclass:: OpenSSL.SSL.Connection 250 :members: 251 252 253.. Rubric:: Footnotes 254 255.. [#connection-context-socket] Actually, all that is required is an object that 256 **behaves** like a socket, you could even use files, even though it'd be 257 tricky to get the handshakes right! 258