blob: c678b280789442638eb31a42254040f22771ce54 [file] [log] [blame]
Jonathan Ballet6381da32011-07-20 16:43:38 +09001.. _openssl-ssl:
2
3:py:mod:`SSL` --- An interface to the SSL-specific parts of OpenSSL
4===================================================================
5
Jonathan Balletc9e066c2011-07-17 22:56:05 +09006.. py:module:: OpenSSL.SSL
Jonathan Ballet6381da32011-07-20 16:43:38 +09007 :synopsis: An interface to the SSL-specific parts of OpenSSL
Jonathan Balletc9e066c2011-07-17 22:56:05 +09008
Jonathan Balletc9e066c2011-07-17 22:56:05 +09009
10This module handles things specific to SSL. There are two objects defined:
11Context, Connection.
12
13.. py:data:: SSLv2_METHOD
Jonathan Ballet6381da32011-07-20 16:43:38 +090014 SSLv3_METHOD
15 SSLv23_METHOD
16 TLSv1_METHOD
Jean-Paul Calderone1461c492013-10-03 16:05:00 -040017 TLSv1_1_METHOD
18 TLSv1_2_METHOD
Jonathan Balletc9e066c2011-07-17 22:56:05 +090019
20 These constants represent the different SSL methods to use when creating a
Jean-Paul Calderone1461c492013-10-03 16:05:00 -040021 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.
Jonathan Balletc9e066c2011-07-17 22:56:05 +090024
25
26.. py:data:: VERIFY_NONE
Jonathan Ballet6381da32011-07-20 16:43:38 +090027 VERIFY_PEER
28 VERIFY_FAIL_IF_NO_PEER_CERT
Jonathan Balletc9e066c2011-07-17 22:56:05 +090029
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
Jonathan Ballet6381da32011-07-20 16:43:38 +090035 FILETYPE_ASN1
Jonathan Balletc9e066c2011-07-17 22:56:05 +090036
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
Akihiro Yamazaki7eee79d2015-09-05 23:50:05 +090042 OP_SINGLE_ECDH_USE
Jean-Paul Calderone1461c492013-10-03 16:05:00 -040043
Akihiro Yamazaki8509cec2015-09-06 02:01:21 +090044 Constants used with :py:meth:`set_options` of Context objects.
Jean-Paul Calderone1461c492013-10-03 16:05:00 -040045
Akihiro Yamazaki8509cec2015-09-06 02:01:21 +090046 When these options are used, a new key will always be created when using
Akihiro Yamazaki7eee79d2015-09-05 23:50:05 +090047 ephemeral (Elliptic curve) Diffie-Hellman.
Jean-Paul Calderone1461c492013-10-03 16:05:00 -040048
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
Jonathan Ballet6381da32011-07-20 16:43:38 +090073 OP_NO_SSLv3
74 OP_NO_TLSv1
Jean-Paul Calderone1461c492013-10-03 16:05:00 -040075 OP_NO_TLSv1_1
76 OP_NO_TLSv1_2
Jonathan Balletc9e066c2011-07-17 22:56:05 +090077
78 Constants used with :py:meth:`set_options` of Context objects.
79
Jean-Paul Calderone1461c492013-10-03 16:05:00 -040080 Each of these options disables one version of the SSL/TLS protocol. This
81 is interesting if you're using e.g. :py:const:`SSLv23_METHOD` to get an
82 SSLv2-compatible handshake, but don't want to use SSLv2. If the underlying
83 OpenSSL build is missing support for any of these protocols, the
84 :py:const:`OP_NO_*` constant may be undefined.
Jonathan Balletc9e066c2011-07-17 22:56:05 +090085
86
87.. py:data:: SSLEAY_VERSION
Jonathan Ballet6381da32011-07-20 16:43:38 +090088 SSLEAY_CFLAGS
89 SSLEAY_BUILT_ON
90 SSLEAY_PLATFORM
91 SSLEAY_DIR
Jonathan Balletc9e066c2011-07-17 22:56:05 +090092
93 Constants used with :py:meth:`SSLeay_version` to specify what OpenSSL version
94 information to retrieve. See the man page for the :py:func:`SSLeay_version` C
95 API for details.
96
Jean-Paul Calderone1461c492013-10-03 16:05:00 -040097
Jean-Paul Calderone8e8f90c2012-02-08 13:16:26 -050098.. py:data:: SESS_CACHE_OFF
99 SESS_CACHE_CLIENT
100 SESS_CACHE_SERVER
101 SESS_CACHE_BOTH
102 SESS_CACHE_NO_AUTO_CLEAR
103 SESS_CACHE_NO_INTERNAL_LOOKUP
104 SESS_CACHE_NO_INTERNAL_STORE
105 SESS_CACHE_NO_INTERNAL
106
107 Constants used with :py:meth:`Context.set_session_cache_mode` to specify
108 the behavior of the session cache and potential session reuse. See the man
109 page for the :py:func:`SSL_CTX_set_session_cache_mode` C API for details.
110
111 .. versionadded:: 0.14
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900112
Jean-Paul Calderone1461c492013-10-03 16:05:00 -0400113
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900114.. py:data:: OPENSSL_VERSION_NUMBER
115
116 An integer giving the version number of the OpenSSL library used to build this
117 version of pyOpenSSL. See the man page for the :py:func:`SSLeay_version` C API
118 for details.
119
120
Alex Chand072cae2018-02-15 09:57:59 +0000121.. autofunction:: SSLeay_version
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900122
123
124.. py:data:: ContextType
125
126 See :py:class:`Context`.
127
128
Alex Chand072cae2018-02-15 09:57:59 +0000129.. autoclass:: Context
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900130
Alex Chand072cae2018-02-15 09:57:59 +0000131.. autoclass:: Session
Jean-Paul Calderone6c896fe2012-02-16 08:10:04 -0500132
133
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900134.. py:data:: ConnectionType
135
136 See :py:class:`Connection`.
137
138
139.. py:class:: Connection(context, socket)
140
141 A class representing SSL connections.
142
143 *context* should be an instance of :py:class:`Context` and *socket*
144 should be a socket [#connection-context-socket]_ object. *socket* may be
145 *None*; in this case, the Connection is created with a memory BIO: see
146 the :py:meth:`bio_read`, :py:meth:`bio_write`, and :py:meth:`bio_shutdown`
147 methods.
148
149.. py:exception:: Error
150
151 This exception is used as a base class for the other SSL-related
152 exceptions, but may also be raised directly.
153
154 Whenever this exception is raised directly, it has a list of error messages
155 from the OpenSSL error queue, where each item is a tuple *(lib, function,
156 reason)*. Here *lib*, *function* and *reason* are all strings, describing
157 where and what the problem is. See :manpage:`err(3)` for more information.
158
159
160.. py:exception:: ZeroReturnError
161
162 This exception matches the error return code
163 :py:data:`SSL_ERROR_ZERO_RETURN`, and is raised when the SSL Connection has
164 been closed. In SSL 3.0 and TLS 1.0, this only occurs if a closure alert has
165 occurred in the protocol, i.e. the connection has been closed cleanly. Note
166 that this does not necessarily mean that the transport layer (e.g. a socket)
167 has been closed.
168
169 It may seem a little strange that this is an exception, but it does match an
170 :py:data:`SSL_ERROR` code, and is very convenient.
171
172
173.. py:exception:: WantReadError
174
175 The operation did not complete; the same I/O method should be called again
176 later, with the same arguments. Any I/O method can lead to this since new
177 handshakes can occur at any time.
178
179 The wanted read is for **dirty** data sent over the network, not the
180 **clean** data inside the tunnel. For a socket based SSL connection,
181 **read** means data coming at us over the network. Until that read
182 succeeds, the attempted :py:meth:`OpenSSL.SSL.Connection.recv`,
183 :py:meth:`OpenSSL.SSL.Connection.send`, or
184 :py:meth:`OpenSSL.SSL.Connection.do_handshake` is prevented or incomplete. You
185 probably want to :py:meth:`select()` on the socket before trying again.
186
187
188.. py:exception:: WantWriteError
189
190 See :py:exc:`WantReadError`. The socket send buffer may be too full to
191 write more data.
192
193
194.. py:exception:: WantX509LookupError
195
196 The operation did not complete because an application callback has asked to be
197 called again. The I/O method should be called again later, with the same
198 arguments.
199
200 .. note:: This won't occur in this version, as there are no such
201 callbacks in this version.
202
203
204.. py:exception:: SysCallError
205
206 The :py:exc:`SysCallError` occurs when there's an I/O error and OpenSSL's
207 error queue does not contain any information. This can mean two things: An
208 error in the transport protocol, or an end of file that violates the protocol.
209 The parameter to the exception is always a pair *(errnum,
210 errstr)*.
211
212
213
214.. _openssl-context:
215
216Context objects
217---------------
218
219Context objects have the following methods:
220
Alex Chand072cae2018-02-15 09:57:59 +0000221.. autoclass:: OpenSSL.SSL.Context
222 :members:
Cory Benfieldbe3e7b82014-05-10 09:48:55 +0100223
Jean-Paul Calderone6c896fe2012-02-16 08:10:04 -0500224.. _openssl-session:
225
226Session objects
227---------------
228
229Session objects have no methods.
230
231
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900232.. _openssl-connection:
233
234Connection objects
235------------------
236
237Connection objects have the following methods:
238
Alex Chand072cae2018-02-15 09:57:59 +0000239.. autoclass:: OpenSSL.SSL.Connection
240 :members:
Cory Benfield12eae892014-06-07 15:42:56 +0100241
Cory Benfieldbe3e7b82014-05-10 09:48:55 +0100242
Jonathan Ballet6381da32011-07-20 16:43:38 +0900243.. Rubric:: Footnotes
244
Jonathan Balletc9e066c2011-07-17 22:56:05 +0900245.. [#connection-context-socket] Actually, all that is required is an object that
246 **behaves** like a socket, you could even use files, even though it'd be
247 tricky to get the handshakes right!