blob: 3a609089f1bb14c3ed32dbcdf731459ff08c5c17 [file] [log] [blame]
Thomas Woutersed03b412007-08-28 21:37:11 +00001# Wrapper module for _ssl, providing some additional facilities
2# implemented in Python. Written by Bill Janssen.
3
Guido van Rossum5b8b1552007-11-16 00:06:11 +00004"""This module provides some more Pythonic support for SSL.
Thomas Woutersed03b412007-08-28 21:37:11 +00005
6Object types:
7
Thomas Wouters1b7f8912007-09-19 03:06:30 +00008 SSLSocket -- subtype of socket.socket which does SSL over the socket
Thomas Woutersed03b412007-08-28 21:37:11 +00009
10Exceptions:
11
Thomas Wouters1b7f8912007-09-19 03:06:30 +000012 SSLError -- exception raised for I/O errors
Thomas Woutersed03b412007-08-28 21:37:11 +000013
14Functions:
15
16 cert_time_to_seconds -- convert time string used for certificate
17 notBefore and notAfter functions to integer
18 seconds past the Epoch (the time values
19 returned from time.time())
20
21 fetch_server_certificate (HOST, PORT) -- fetch the certificate provided
22 by the server running on HOST at port PORT. No
23 validation of the certificate is performed.
24
25Integer constants:
26
27SSL_ERROR_ZERO_RETURN
28SSL_ERROR_WANT_READ
29SSL_ERROR_WANT_WRITE
30SSL_ERROR_WANT_X509_LOOKUP
31SSL_ERROR_SYSCALL
32SSL_ERROR_SSL
33SSL_ERROR_WANT_CONNECT
34
35SSL_ERROR_EOF
36SSL_ERROR_INVALID_ERROR_CODE
37
38The following group define certificate requirements that one side is
39allowing/requiring from the other side:
40
41CERT_NONE - no certificates from the other side are required (or will
42 be looked at if provided)
43CERT_OPTIONAL - certificates are not required, but if provided will be
44 validated, and if validation fails, the connection will
45 also fail
46CERT_REQUIRED - certificates are required, and will be validated, and
47 if validation fails, the connection will also fail
48
49The following constants identify various SSL protocol variants:
50
51PROTOCOL_SSLv2
52PROTOCOL_SSLv3
53PROTOCOL_SSLv23
54PROTOCOL_TLSv1
Antoine Pitrou2463e5f2013-03-28 22:24:43 +010055PROTOCOL_TLSv1_1
56PROTOCOL_TLSv1_2
Antoine Pitrou58ddc9d2013-01-05 21:20:29 +010057
58The following constants identify various SSL alert message descriptions as per
59http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-6
60
61ALERT_DESCRIPTION_CLOSE_NOTIFY
62ALERT_DESCRIPTION_UNEXPECTED_MESSAGE
63ALERT_DESCRIPTION_BAD_RECORD_MAC
64ALERT_DESCRIPTION_RECORD_OVERFLOW
65ALERT_DESCRIPTION_DECOMPRESSION_FAILURE
66ALERT_DESCRIPTION_HANDSHAKE_FAILURE
67ALERT_DESCRIPTION_BAD_CERTIFICATE
68ALERT_DESCRIPTION_UNSUPPORTED_CERTIFICATE
69ALERT_DESCRIPTION_CERTIFICATE_REVOKED
70ALERT_DESCRIPTION_CERTIFICATE_EXPIRED
71ALERT_DESCRIPTION_CERTIFICATE_UNKNOWN
72ALERT_DESCRIPTION_ILLEGAL_PARAMETER
73ALERT_DESCRIPTION_UNKNOWN_CA
74ALERT_DESCRIPTION_ACCESS_DENIED
75ALERT_DESCRIPTION_DECODE_ERROR
76ALERT_DESCRIPTION_DECRYPT_ERROR
77ALERT_DESCRIPTION_PROTOCOL_VERSION
78ALERT_DESCRIPTION_INSUFFICIENT_SECURITY
79ALERT_DESCRIPTION_INTERNAL_ERROR
80ALERT_DESCRIPTION_USER_CANCELLED
81ALERT_DESCRIPTION_NO_RENEGOTIATION
82ALERT_DESCRIPTION_UNSUPPORTED_EXTENSION
83ALERT_DESCRIPTION_CERTIFICATE_UNOBTAINABLE
84ALERT_DESCRIPTION_UNRECOGNIZED_NAME
85ALERT_DESCRIPTION_BAD_CERTIFICATE_STATUS_RESPONSE
86ALERT_DESCRIPTION_BAD_CERTIFICATE_HASH_VALUE
87ALERT_DESCRIPTION_UNKNOWN_PSK_IDENTITY
Thomas Woutersed03b412007-08-28 21:37:11 +000088"""
89
Christian Heimes05e8be12008-02-23 18:30:17 +000090import textwrap
Antoine Pitrou59fdd672010-10-08 10:37:08 +000091import re
Christian Heimes46bebee2013-06-09 19:03:31 +020092import sys
Christian Heimes6d7ad132013-06-09 18:02:55 +020093import os
Christian Heimesa6bc95a2013-11-17 19:59:14 +010094from collections import namedtuple
Antoine Pitrou172f0252014-04-18 20:33:08 +020095from enum import Enum as _Enum, IntEnum as _IntEnum
Thomas Woutersed03b412007-08-28 21:37:11 +000096
97import _ssl # if we can't import it, let the error propagate
Thomas Wouters1b7f8912007-09-19 03:06:30 +000098
Antoine Pitrou04f6a322010-04-05 21:40:07 +000099from _ssl import OPENSSL_VERSION_NUMBER, OPENSSL_VERSION_INFO, OPENSSL_VERSION
Antoine Pitroub1fdf472014-10-05 20:41:53 +0200100from _ssl import _SSLContext, MemoryBIO
Antoine Pitrou41032a62011-10-27 23:56:55 +0200101from _ssl import (
102 SSLError, SSLZeroReturnError, SSLWantReadError, SSLWantWriteError,
103 SSLSyscallError, SSLEOFError,
104 )
Thomas Woutersed03b412007-08-28 21:37:11 +0000105from _ssl import CERT_NONE, CERT_OPTIONAL, CERT_REQUIRED
Christian Heimes22587792013-11-21 23:56:13 +0100106from _ssl import (VERIFY_DEFAULT, VERIFY_CRL_CHECK_LEAF, VERIFY_CRL_CHECK_CHAIN,
107 VERIFY_X509_STRICT)
Christian Heimesa6bc95a2013-11-17 19:59:14 +0100108from _ssl import txt2obj as _txt2obj, nid2obj as _nid2obj
Victor Stinner99c8b162011-05-24 12:05:19 +0200109from _ssl import RAND_status, RAND_egd, RAND_add, RAND_bytes, RAND_pseudo_bytes
Antoine Pitrou58ddc9d2013-01-05 21:20:29 +0100110
111def _import_symbols(prefix):
112 for n in dir(_ssl):
113 if n.startswith(prefix):
114 globals()[n] = getattr(_ssl, n)
115
116_import_symbols('OP_')
117_import_symbols('ALERT_DESCRIPTION_')
118_import_symbols('SSL_ERROR_')
119
Antoine Pitroud5d17eb2012-03-22 00:23:03 +0100120from _ssl import HAS_SNI, HAS_ECDH, HAS_NPN
Antoine Pitrou58ddc9d2013-01-05 21:20:29 +0100121
Antoine Pitroub9ac25d2011-07-08 18:47:06 +0200122from _ssl import _OPENSSL_API_VERSION
123
Antoine Pitrou172f0252014-04-18 20:33:08 +0200124_SSLMethod = _IntEnum('_SSLMethod',
125 {name: value for name, value in vars(_ssl).items()
126 if name.startswith('PROTOCOL_')})
127globals().update(_SSLMethod.__members__)
Antoine Pitrou58ddc9d2013-01-05 21:20:29 +0100128
Antoine Pitrou172f0252014-04-18 20:33:08 +0200129_PROTOCOL_NAMES = {value: name for name, value in _SSLMethod.__members__.items()}
130
Victor Stinner3de49192011-05-09 00:42:58 +0200131try:
Antoine Pitrou8f85f902012-01-03 22:46:48 +0100132 _SSLv2_IF_EXISTS = PROTOCOL_SSLv2
Antoine Pitrou172f0252014-04-18 20:33:08 +0200133except NameError:
Antoine Pitrou8f85f902012-01-03 22:46:48 +0100134 _SSLv2_IF_EXISTS = None
Antoine Pitrou2463e5f2013-03-28 22:24:43 +0100135
Christian Heimes46bebee2013-06-09 19:03:31 +0200136if sys.platform == "win32":
Christian Heimes44109d72013-11-22 01:51:30 +0100137 from _ssl import enum_certificates, enum_crls
Christian Heimes46bebee2013-06-09 19:03:31 +0200138
Antoine Pitrou15399c32011-04-28 19:23:55 +0200139from socket import socket, AF_INET, SOCK_STREAM, create_connection
Antoine Pitrou3e86ba42013-12-28 17:26:33 +0100140from socket import SOL_SOCKET, SO_TYPE
Thomas Wouters1b7f8912007-09-19 03:06:30 +0000141import base64 # for DER-to-PEM translation
Antoine Pitroude8cf322010-04-26 17:29:05 +0000142import errno
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000143
Andrew Svetlov0832af62012-12-18 23:10:48 +0200144
145socket_error = OSError # keep that public name in module namespace
146
Antoine Pitroud6494802011-07-21 01:11:30 +0200147if _ssl.HAS_TLS_UNIQUE:
148 CHANNEL_BINDING_TYPES = ['tls-unique']
149else:
150 CHANNEL_BINDING_TYPES = []
Thomas Woutersed03b412007-08-28 21:37:11 +0000151
Antoine Pitrou8f85f902012-01-03 22:46:48 +0100152# Disable weak or insecure ciphers by default
153# (OpenSSL's default setting is 'DEFAULT:!aNULL:!eNULL')
Donald Stufft79ccaa22014-03-21 21:33:34 -0400154# Enable a better set of ciphers by default
155# This list has been explicitly chosen to:
156# * Prefer cipher suites that offer perfect forward secrecy (DHE/ECDHE)
157# * Prefer ECDHE over DHE for better performance
158# * Prefer any AES-GCM over any AES-CBC for better performance and security
159# * Then Use HIGH cipher suites as a fallback
160# * Then Use 3DES as fallback which is secure but slow
161# * Finally use RC4 as a fallback which is problematic but needed for
162# compatibility some times.
163# * Disable NULL authentication, NULL encryption, and MD5 MACs for security
164# reasons
165_DEFAULT_CIPHERS = (
166 'ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+HIGH:'
167 'DH+HIGH:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+HIGH:RSA+3DES:ECDH+RC4:'
168 'DH+RC4:RSA+RC4:!aNULL:!eNULL:!MD5'
169)
Antoine Pitrou8f85f902012-01-03 22:46:48 +0100170
Donald Stufft6a2ba942014-03-23 19:05:28 -0400171# Restricted and more secure ciphers for the server side
Donald Stufft79ccaa22014-03-21 21:33:34 -0400172# This list has been explicitly chosen to:
173# * Prefer cipher suites that offer perfect forward secrecy (DHE/ECDHE)
174# * Prefer ECDHE over DHE for better performance
175# * Prefer any AES-GCM over any AES-CBC for better performance and security
176# * Then Use HIGH cipher suites as a fallback
177# * Then Use 3DES as fallback which is secure but slow
178# * Disable NULL authentication, NULL encryption, MD5 MACs, DSS, and RC4 for
179# security reasons
Donald Stufft6a2ba942014-03-23 19:05:28 -0400180_RESTRICTED_SERVER_CIPHERS = (
Donald Stufft79ccaa22014-03-21 21:33:34 -0400181 'ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+HIGH:'
182 'DH+HIGH:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+HIGH:RSA+3DES:!aNULL:'
183 '!eNULL:!MD5:!DSS:!RC4'
184)
Christian Heimes4c05b472013-11-23 15:58:30 +0100185
Thomas Woutersed03b412007-08-28 21:37:11 +0000186
Antoine Pitrou59fdd672010-10-08 10:37:08 +0000187class CertificateError(ValueError):
188 pass
189
190
Georg Brandl72c98d32013-10-27 07:16:53 +0100191def _dnsname_match(dn, hostname, max_wildcards=1):
192 """Matching according to RFC 6125, section 6.4.3
193
194 http://tools.ietf.org/html/rfc6125#section-6.4.3
195 """
Antoine Pitrou59fdd672010-10-08 10:37:08 +0000196 pats = []
Georg Brandl72c98d32013-10-27 07:16:53 +0100197 if not dn:
198 return False
199
200 leftmost, *remainder = dn.split(r'.')
201
202 wildcards = leftmost.count('*')
203 if wildcards > max_wildcards:
204 # Issue #17980: avoid denials of service by refusing more
205 # than one wildcard per fragment. A survery of established
206 # policy among SSL implementations showed it to be a
207 # reasonable choice.
208 raise CertificateError(
209 "too many wildcards in certificate DNS name: " + repr(dn))
210
211 # speed up common case w/o wildcards
212 if not wildcards:
213 return dn.lower() == hostname.lower()
214
215 # RFC 6125, section 6.4.3, subitem 1.
216 # The client SHOULD NOT attempt to match a presented identifier in which
217 # the wildcard character comprises a label other than the left-most label.
218 if leftmost == '*':
219 # When '*' is a fragment by itself, it matches a non-empty dotless
220 # fragment.
221 pats.append('[^.]+')
222 elif leftmost.startswith('xn--') or hostname.startswith('xn--'):
223 # RFC 6125, section 6.4.3, subitem 3.
224 # The client SHOULD NOT attempt to match a presented identifier
225 # where the wildcard character is embedded within an A-label or
226 # U-label of an internationalized domain name.
227 pats.append(re.escape(leftmost))
228 else:
229 # Otherwise, '*' matches any dotless string, e.g. www*
230 pats.append(re.escape(leftmost).replace(r'\*', '[^.]*'))
231
232 # add the remaining fragments, ignore any wildcards
233 for frag in remainder:
234 pats.append(re.escape(frag))
235
236 pat = re.compile(r'\A' + r'\.'.join(pats) + r'\Z', re.IGNORECASE)
237 return pat.match(hostname)
Antoine Pitrou59fdd672010-10-08 10:37:08 +0000238
239
240def match_hostname(cert, hostname):
241 """Verify that *cert* (in decoded format as returned by
Georg Brandl72c98d32013-10-27 07:16:53 +0100242 SSLSocket.getpeercert()) matches the *hostname*. RFC 2818 and RFC 6125
243 rules are followed, but IP addresses are not accepted for *hostname*.
Antoine Pitrou59fdd672010-10-08 10:37:08 +0000244
245 CertificateError is raised on failure. On success, the function
246 returns nothing.
247 """
248 if not cert:
Christian Heimes1aa9a752013-12-02 02:41:19 +0100249 raise ValueError("empty or no certificate, match_hostname needs a "
250 "SSL socket or SSL context with either "
251 "CERT_OPTIONAL or CERT_REQUIRED")
Antoine Pitrou59fdd672010-10-08 10:37:08 +0000252 dnsnames = []
253 san = cert.get('subjectAltName', ())
254 for key, value in san:
255 if key == 'DNS':
Georg Brandl72c98d32013-10-27 07:16:53 +0100256 if _dnsname_match(value, hostname):
Antoine Pitrou59fdd672010-10-08 10:37:08 +0000257 return
258 dnsnames.append(value)
Antoine Pitrou1c86b442011-05-06 15:19:49 +0200259 if not dnsnames:
260 # The subject is only checked when there is no dNSName entry
261 # in subjectAltName
Antoine Pitrou59fdd672010-10-08 10:37:08 +0000262 for sub in cert.get('subject', ()):
263 for key, value in sub:
264 # XXX according to RFC 2818, the most specific Common Name
265 # must be used.
266 if key == 'commonName':
Georg Brandl72c98d32013-10-27 07:16:53 +0100267 if _dnsname_match(value, hostname):
Antoine Pitrou59fdd672010-10-08 10:37:08 +0000268 return
269 dnsnames.append(value)
270 if len(dnsnames) > 1:
271 raise CertificateError("hostname %r "
272 "doesn't match either of %s"
273 % (hostname, ', '.join(map(repr, dnsnames))))
274 elif len(dnsnames) == 1:
275 raise CertificateError("hostname %r "
276 "doesn't match %r"
277 % (hostname, dnsnames[0]))
278 else:
279 raise CertificateError("no appropriate commonName or "
280 "subjectAltName fields were found")
281
282
Christian Heimesa6bc95a2013-11-17 19:59:14 +0100283DefaultVerifyPaths = namedtuple("DefaultVerifyPaths",
Christian Heimes6d7ad132013-06-09 18:02:55 +0200284 "cafile capath openssl_cafile_env openssl_cafile openssl_capath_env "
285 "openssl_capath")
286
287def get_default_verify_paths():
288 """Return paths to default cafile and capath.
289 """
290 parts = _ssl.get_default_verify_paths()
291
292 # environment vars shadow paths
293 cafile = os.environ.get(parts[0], parts[1])
294 capath = os.environ.get(parts[2], parts[3])
295
296 return DefaultVerifyPaths(cafile if os.path.isfile(cafile) else None,
297 capath if os.path.isdir(capath) else None,
298 *parts)
299
300
Christian Heimesa6bc95a2013-11-17 19:59:14 +0100301class _ASN1Object(namedtuple("_ASN1Object", "nid shortname longname oid")):
302 """ASN.1 object identifier lookup
303 """
304 __slots__ = ()
305
306 def __new__(cls, oid):
307 return super().__new__(cls, *_txt2obj(oid, name=False))
308
309 @classmethod
310 def fromnid(cls, nid):
311 """Create _ASN1Object from OpenSSL numeric ID
312 """
313 return super().__new__(cls, *_nid2obj(nid))
314
315 @classmethod
316 def fromname(cls, name):
317 """Create _ASN1Object from short name, long name or OID
318 """
319 return super().__new__(cls, *_txt2obj(name, name=True))
320
321
Christian Heimes72d28502013-11-23 13:56:58 +0100322class Purpose(_ASN1Object, _Enum):
323 """SSLContext purpose flags with X509v3 Extended Key Usage objects
324 """
325 SERVER_AUTH = '1.3.6.1.5.5.7.3.1'
326 CLIENT_AUTH = '1.3.6.1.5.5.7.3.2'
327
328
Antoine Pitrou152efa22010-05-16 18:19:27 +0000329class SSLContext(_SSLContext):
330 """An SSLContext holds various SSL-related configuration options and
331 data, such as certificates and possibly a private key."""
332
Antoine Pitrou58ddc9d2013-01-05 21:20:29 +0100333 __slots__ = ('protocol', '__weakref__')
Christian Heimes72d28502013-11-23 13:56:58 +0100334 _windows_cert_stores = ("CA", "ROOT")
Antoine Pitrou152efa22010-05-16 18:19:27 +0000335
336 def __new__(cls, protocol, *args, **kwargs):
Antoine Pitrou8f85f902012-01-03 22:46:48 +0100337 self = _SSLContext.__new__(cls, protocol)
338 if protocol != _SSLv2_IF_EXISTS:
339 self.set_ciphers(_DEFAULT_CIPHERS)
340 return self
Antoine Pitrou152efa22010-05-16 18:19:27 +0000341
342 def __init__(self, protocol):
343 self.protocol = protocol
344
345 def wrap_socket(self, sock, server_side=False,
346 do_handshake_on_connect=True,
Antoine Pitroud5323212010-10-22 18:19:07 +0000347 suppress_ragged_eofs=True,
348 server_hostname=None):
Antoine Pitrou152efa22010-05-16 18:19:27 +0000349 return SSLSocket(sock=sock, server_side=server_side,
350 do_handshake_on_connect=do_handshake_on_connect,
351 suppress_ragged_eofs=suppress_ragged_eofs,
Antoine Pitroud5323212010-10-22 18:19:07 +0000352 server_hostname=server_hostname,
Antoine Pitrou152efa22010-05-16 18:19:27 +0000353 _context=self)
354
Antoine Pitroub1fdf472014-10-05 20:41:53 +0200355 def wrap_bio(self, incoming, outgoing, server_side=False,
356 server_hostname=None):
357 sslobj = self._wrap_bio(incoming, outgoing, server_side=server_side,
358 server_hostname=server_hostname)
359 return SSLObject(sslobj)
360
Antoine Pitroud5d17eb2012-03-22 00:23:03 +0100361 def set_npn_protocols(self, npn_protocols):
362 protos = bytearray()
363 for protocol in npn_protocols:
364 b = bytes(protocol, 'ascii')
365 if len(b) == 0 or len(b) > 255:
366 raise SSLError('NPN protocols must be 1 to 255 in length')
367 protos.append(len(b))
368 protos.extend(b)
369
370 self._set_npn_protocols(protos)
371
Christian Heimes72d28502013-11-23 13:56:58 +0100372 def _load_windows_store_certs(self, storename, purpose):
373 certs = bytearray()
374 for cert, encoding, trust in enum_certificates(storename):
375 # CA certs are never PKCS#7 encoded
376 if encoding == "x509_asn":
377 if trust is True or purpose.oid in trust:
378 certs.extend(cert)
379 self.load_verify_locations(cadata=certs)
380 return certs
381
382 def load_default_certs(self, purpose=Purpose.SERVER_AUTH):
383 if not isinstance(purpose, _ASN1Object):
384 raise TypeError(purpose)
385 if sys.platform == "win32":
386 for storename in self._windows_cert_stores:
387 self._load_windows_store_certs(storename, purpose)
Benjamin Peterson5915b0f2014-10-03 17:27:05 -0400388 self.set_default_verify_paths()
Christian Heimes72d28502013-11-23 13:56:58 +0100389
Antoine Pitrou152efa22010-05-16 18:19:27 +0000390
Christian Heimes4c05b472013-11-23 15:58:30 +0100391def create_default_context(purpose=Purpose.SERVER_AUTH, *, cafile=None,
392 capath=None, cadata=None):
393 """Create a SSLContext object with default settings.
394
395 NOTE: The protocol and settings may change anytime without prior
396 deprecation. The values represent a fair balance between maximum
397 compatibility and security.
398 """
399 if not isinstance(purpose, _ASN1Object):
400 raise TypeError(purpose)
Donald Stufft6a2ba942014-03-23 19:05:28 -0400401
402 context = SSLContext(PROTOCOL_SSLv23)
403
Christian Heimes4c05b472013-11-23 15:58:30 +0100404 # SSLv2 considered harmful.
405 context.options |= OP_NO_SSLv2
Donald Stufft6a2ba942014-03-23 19:05:28 -0400406
407 # SSLv3 has problematic security and is only required for really old
408 # clients such as IE6 on Windows XP
409 context.options |= OP_NO_SSLv3
410
Christian Heimesdec813f2013-11-28 08:06:54 +0100411 # disable compression to prevent CRIME attacks (OpenSSL 1.0+)
412 context.options |= getattr(_ssl, "OP_NO_COMPRESSION", 0)
Donald Stufft6a2ba942014-03-23 19:05:28 -0400413
Christian Heimes4c05b472013-11-23 15:58:30 +0100414 if purpose == Purpose.SERVER_AUTH:
Donald Stufft6a2ba942014-03-23 19:05:28 -0400415 # verify certs and host name in client mode
Christian Heimes4c05b472013-11-23 15:58:30 +0100416 context.verify_mode = CERT_REQUIRED
Christian Heimes1aa9a752013-12-02 02:41:19 +0100417 context.check_hostname = True
Donald Stufft6a2ba942014-03-23 19:05:28 -0400418 elif purpose == Purpose.CLIENT_AUTH:
419 # Prefer the server's ciphers by default so that we get stronger
420 # encryption
421 context.options |= getattr(_ssl, "OP_CIPHER_SERVER_PREFERENCE", 0)
422
423 # Use single use keys in order to improve forward secrecy
424 context.options |= getattr(_ssl, "OP_SINGLE_DH_USE", 0)
425 context.options |= getattr(_ssl, "OP_SINGLE_ECDH_USE", 0)
426
427 # disallow ciphers with known vulnerabilities
428 context.set_ciphers(_RESTRICTED_SERVER_CIPHERS)
429
Christian Heimes4c05b472013-11-23 15:58:30 +0100430 if cafile or capath or cadata:
431 context.load_verify_locations(cafile, capath, cadata)
432 elif context.verify_mode != CERT_NONE:
433 # no explicit cafile, capath or cadata but the verify mode is
434 # CERT_OPTIONAL or CERT_REQUIRED. Let's try to load default system
435 # root CA certificates for the given purpose. This may fail silently.
436 context.load_default_certs(purpose)
437 return context
438
439
Christian Heimes67986f92013-11-23 22:43:47 +0100440def _create_stdlib_context(protocol=PROTOCOL_SSLv23, *, cert_reqs=None,
Christian Heimesa02c69a2013-12-02 20:59:28 +0100441 check_hostname=False, purpose=Purpose.SERVER_AUTH,
Christian Heimes67986f92013-11-23 22:43:47 +0100442 certfile=None, keyfile=None,
443 cafile=None, capath=None, cadata=None):
444 """Create a SSLContext object for Python stdlib modules
445
446 All Python stdlib modules shall use this function to create SSLContext
447 objects in order to keep common settings in one place. The configuration
448 is less restrict than create_default_context()'s to increase backward
449 compatibility.
450 """
451 if not isinstance(purpose, _ASN1Object):
452 raise TypeError(purpose)
453
454 context = SSLContext(protocol)
455 # SSLv2 considered harmful.
456 context.options |= OP_NO_SSLv2
457
458 if cert_reqs is not None:
459 context.verify_mode = cert_reqs
Christian Heimesa02c69a2013-12-02 20:59:28 +0100460 context.check_hostname = check_hostname
Christian Heimes67986f92013-11-23 22:43:47 +0100461
462 if keyfile and not certfile:
463 raise ValueError("certfile must be specified")
464 if certfile or keyfile:
465 context.load_cert_chain(certfile, keyfile)
466
467 # load CA root certs
468 if cafile or capath or cadata:
469 context.load_verify_locations(cafile, capath, cadata)
470 elif context.verify_mode != CERT_NONE:
471 # no explicit cafile, capath or cadata but the verify mode is
472 # CERT_OPTIONAL or CERT_REQUIRED. Let's try to load default system
473 # root CA certificates for the given purpose. This may fail silently.
474 context.load_default_certs(purpose)
475
476 return context
477
Antoine Pitroub1fdf472014-10-05 20:41:53 +0200478
479class SSLObject:
480 """This class implements an interface on top of a low-level SSL object as
481 implemented by OpenSSL. This object captures the state of an SSL connection
482 but does not provide any network IO itself. IO needs to be performed
483 through separate "BIO" objects which are OpenSSL's IO abstraction layer.
484
485 This class does not have a public constructor. Instances are returned by
486 ``SSLContext.wrap_bio``. This class is typically used by framework authors
487 that want to implement asynchronous IO for SSL through memory buffers.
488
489 When compared to ``SSLSocket``, this object lacks the following features:
490
491 * Any form of network IO incluging methods such as ``recv`` and ``send``.
492 * The ``do_handshake_on_connect`` and ``suppress_ragged_eofs`` machinery.
493 """
494
495 def __init__(self, sslobj, owner=None):
496 self._sslobj = sslobj
497 # Note: _sslobj takes a weak reference to owner
498 self._sslobj.owner = owner or self
499
500 @property
501 def context(self):
502 """The SSLContext that is currently in use."""
503 return self._sslobj.context
504
505 @context.setter
506 def context(self, ctx):
507 self._sslobj.context = ctx
508
509 @property
510 def server_side(self):
511 """Whether this is a server-side socket."""
512 return self._sslobj.server_side
513
514 @property
515 def server_hostname(self):
516 """The currently set server hostname (for SNI), or ``None`` if no
517 server hostame is set."""
518 return self._sslobj.server_hostname
519
520 def read(self, len=0, buffer=None):
521 """Read up to 'len' bytes from the SSL object and return them.
522
523 If 'buffer' is provided, read into this buffer and return the number of
524 bytes read.
525 """
526 if buffer is not None:
527 v = self._sslobj.read(len, buffer)
528 else:
529 v = self._sslobj.read(len or 1024)
530 return v
531
532 def write(self, data):
533 """Write 'data' to the SSL object and return the number of bytes
534 written.
535
536 The 'data' argument must support the buffer interface.
537 """
538 return self._sslobj.write(data)
539
540 def getpeercert(self, binary_form=False):
541 """Returns a formatted version of the data in the certificate provided
542 by the other end of the SSL channel.
543
544 Return None if no certificate was provided, {} if a certificate was
545 provided, but not validated.
546 """
547 return self._sslobj.peer_certificate(binary_form)
548
549 def selected_npn_protocol(self):
550 """Return the currently selected NPN protocol as a string, or ``None``
551 if a next protocol was not negotiated or if NPN is not supported by one
552 of the peers."""
553 if _ssl.HAS_NPN:
554 return self._sslobj.selected_npn_protocol()
555
556 def cipher(self):
557 """Return the currently selected cipher as a 3-tuple ``(name,
558 ssl_version, secret_bits)``."""
559 return self._sslobj.cipher()
560
561 def compression(self):
562 """Return the current compression algorithm in use, or ``None`` if
563 compression was not negotiated or not supported by one of the peers."""
564 return self._sslobj.compression()
565
566 def pending(self):
567 """Return the number of bytes that can be read immediately."""
568 return self._sslobj.pending()
569
570 def do_handshake(self, block=False):
571 """Start the SSL/TLS handshake."""
572 self._sslobj.do_handshake()
573 if self.context.check_hostname:
574 if not self.server_hostname:
575 raise ValueError("check_hostname needs server_hostname "
576 "argument")
577 match_hostname(self.getpeercert(), self.server_hostname)
578
579 def unwrap(self):
580 """Start the SSL shutdown handshake."""
581 return self._sslobj.shutdown()
582
583 def get_channel_binding(self, cb_type="tls-unique"):
584 """Get channel binding data for current connection. Raise ValueError
585 if the requested `cb_type` is not supported. Return bytes of the data
586 or None if the data is not available (e.g. before the handshake)."""
587 if cb_type not in CHANNEL_BINDING_TYPES:
588 raise ValueError("Unsupported channel binding type")
589 if cb_type != "tls-unique":
590 raise NotImplementedError(
591 "{0} channel binding type not implemented"
592 .format(cb_type))
593 return self._sslobj.tls_unique_cb()
594
595 def version(self):
596 """Return a string identifying the protocol version used by the
597 current SSL channel. """
598 return self._sslobj.version()
599
600
Antoine Pitrou152efa22010-05-16 18:19:27 +0000601class SSLSocket(socket):
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000602 """This class implements a subtype of socket.socket that wraps
603 the underlying OS socket in an SSL context when necessary, and
604 provides read and write methods over that channel."""
605
Bill Janssen6e027db2007-11-15 22:23:56 +0000606 def __init__(self, sock=None, keyfile=None, certfile=None,
Thomas Woutersed03b412007-08-28 21:37:11 +0000607 server_side=False, cert_reqs=CERT_NONE,
Bill Janssen6e027db2007-11-15 22:23:56 +0000608 ssl_version=PROTOCOL_SSLv23, ca_certs=None,
609 do_handshake_on_connect=True,
610 family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None,
Antoine Pitroud5d17eb2012-03-22 00:23:03 +0100611 suppress_ragged_eofs=True, npn_protocols=None, ciphers=None,
Antoine Pitroud5323212010-10-22 18:19:07 +0000612 server_hostname=None,
Antoine Pitrou152efa22010-05-16 18:19:27 +0000613 _context=None):
Bill Janssen6e027db2007-11-15 22:23:56 +0000614
Antoine Pitrou152efa22010-05-16 18:19:27 +0000615 if _context:
Antoine Pitrou58ddc9d2013-01-05 21:20:29 +0100616 self._context = _context
Antoine Pitrou152efa22010-05-16 18:19:27 +0000617 else:
Giampaolo Rodolà745ab382010-08-29 19:25:49 +0000618 if server_side and not certfile:
619 raise ValueError("certfile must be specified for server-side "
620 "operations")
Giampaolo Rodolà8b7da622010-08-30 18:28:05 +0000621 if keyfile and not certfile:
622 raise ValueError("certfile must be specified")
Antoine Pitrou152efa22010-05-16 18:19:27 +0000623 if certfile and not keyfile:
624 keyfile = certfile
Antoine Pitrou58ddc9d2013-01-05 21:20:29 +0100625 self._context = SSLContext(ssl_version)
626 self._context.verify_mode = cert_reqs
Antoine Pitrou152efa22010-05-16 18:19:27 +0000627 if ca_certs:
Antoine Pitrou58ddc9d2013-01-05 21:20:29 +0100628 self._context.load_verify_locations(ca_certs)
Antoine Pitrou152efa22010-05-16 18:19:27 +0000629 if certfile:
Antoine Pitrou58ddc9d2013-01-05 21:20:29 +0100630 self._context.load_cert_chain(certfile, keyfile)
Antoine Pitroud5d17eb2012-03-22 00:23:03 +0100631 if npn_protocols:
Antoine Pitrou58ddc9d2013-01-05 21:20:29 +0100632 self._context.set_npn_protocols(npn_protocols)
Antoine Pitrou152efa22010-05-16 18:19:27 +0000633 if ciphers:
Antoine Pitrou58ddc9d2013-01-05 21:20:29 +0100634 self._context.set_ciphers(ciphers)
Antoine Pitrou152efa22010-05-16 18:19:27 +0000635 self.keyfile = keyfile
636 self.certfile = certfile
637 self.cert_reqs = cert_reqs
638 self.ssl_version = ssl_version
639 self.ca_certs = ca_certs
640 self.ciphers = ciphers
Antoine Pitrou3e86ba42013-12-28 17:26:33 +0100641 # Can't use sock.type as other flags (such as SOCK_NONBLOCK) get
642 # mixed in.
643 if sock.getsockopt(SOL_SOCKET, SO_TYPE) != SOCK_STREAM:
644 raise NotImplementedError("only stream sockets are supported")
Antoine Pitroud5323212010-10-22 18:19:07 +0000645 if server_side and server_hostname:
646 raise ValueError("server_hostname can only be specified "
647 "in client mode")
Christian Heimes1aa9a752013-12-02 02:41:19 +0100648 if self._context.check_hostname and not server_hostname:
649 if HAS_SNI:
650 raise ValueError("check_hostname requires server_hostname")
651 else:
652 raise ValueError("check_hostname requires server_hostname, "
653 "but it's not supported by your OpenSSL "
654 "library")
Giampaolo Rodolà745ab382010-08-29 19:25:49 +0000655 self.server_side = server_side
Antoine Pitroud5323212010-10-22 18:19:07 +0000656 self.server_hostname = server_hostname
Antoine Pitrou152efa22010-05-16 18:19:27 +0000657 self.do_handshake_on_connect = do_handshake_on_connect
658 self.suppress_ragged_eofs = suppress_ragged_eofs
Bill Janssen6e027db2007-11-15 22:23:56 +0000659 if sock is not None:
Bill Janssen54cc54c2007-12-14 22:08:56 +0000660 socket.__init__(self,
661 family=sock.family,
662 type=sock.type,
663 proto=sock.proto,
Antoine Pitroue43f9d02010-08-08 23:24:50 +0000664 fileno=sock.fileno())
Antoine Pitrou40f08742010-04-24 22:04:40 +0000665 self.settimeout(sock.gettimeout())
Antoine Pitrou6e451df2010-08-09 20:39:54 +0000666 sock.detach()
Bill Janssen6e027db2007-11-15 22:23:56 +0000667 elif fileno is not None:
668 socket.__init__(self, fileno=fileno)
669 else:
670 socket.__init__(self, family=family, type=type, proto=proto)
671
Antoine Pitrou242db722013-05-01 20:52:07 +0200672 # See if we are connected
673 try:
674 self.getpeername()
675 except OSError as e:
676 if e.errno != errno.ENOTCONN:
677 raise
678 connected = False
679 else:
680 connected = True
681
Antoine Pitroufa2b9382010-04-26 22:17:47 +0000682 self._closed = False
683 self._sslobj = None
Antoine Pitroue93bf7a2011-02-26 23:24:06 +0000684 self._connected = connected
Antoine Pitroufa2b9382010-04-26 22:17:47 +0000685 if connected:
686 # create the SSL object
Bill Janssen6e027db2007-11-15 22:23:56 +0000687 try:
Antoine Pitroub1fdf472014-10-05 20:41:53 +0200688 sslobj = self._context._wrap_socket(self, server_side,
689 server_hostname)
690 self._sslobj = SSLObject(sslobj, owner=self)
Bill Janssen6e027db2007-11-15 22:23:56 +0000691 if do_handshake_on_connect:
Bill Janssen48dc27c2007-12-05 03:38:10 +0000692 timeout = self.gettimeout()
693 if timeout == 0.0:
694 # non-blocking
695 raise ValueError("do_handshake_on_connect should not be specified for non-blocking sockets")
Bill Janssen6e027db2007-11-15 22:23:56 +0000696 self.do_handshake()
Bill Janssen48dc27c2007-12-05 03:38:10 +0000697
Christian Heimes1aa9a752013-12-02 02:41:19 +0100698 except (OSError, ValueError):
Bill Janssen6e027db2007-11-15 22:23:56 +0000699 self.close()
Christian Heimes1aa9a752013-12-02 02:41:19 +0100700 raise
Antoine Pitrou242db722013-05-01 20:52:07 +0200701
Antoine Pitrou58ddc9d2013-01-05 21:20:29 +0100702 @property
703 def context(self):
704 return self._context
705
706 @context.setter
707 def context(self, ctx):
708 self._context = ctx
709 self._sslobj.context = ctx
Bill Janssen6e027db2007-11-15 22:23:56 +0000710
Guido van Rossumb7b030e2007-11-16 01:28:45 +0000711 def dup(self):
712 raise NotImplemented("Can't dup() %s instances" %
713 self.__class__.__name__)
714
Bill Janssen6e027db2007-11-15 22:23:56 +0000715 def _checkClosed(self, msg=None):
716 # raise an exception here if you wish to check for spurious closes
717 pass
718
Antoine Pitrou242db722013-05-01 20:52:07 +0200719 def _check_connected(self):
720 if not self._connected:
721 # getpeername() will raise ENOTCONN if the socket is really
722 # not connected; note that we can be connected even without
723 # _connected being set, e.g. if connect() first returned
724 # EAGAIN.
725 self.getpeername()
726
Bill Janssen54cc54c2007-12-14 22:08:56 +0000727 def read(self, len=0, buffer=None):
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000728 """Read up to LEN bytes and return them.
729 Return zero-length string on EOF."""
730
Bill Janssen6e027db2007-11-15 22:23:56 +0000731 self._checkClosed()
Antoine Pitrou60a26e02013-07-20 19:35:16 +0200732 if not self._sslobj:
733 raise ValueError("Read on closed or unwrapped SSL socket.")
Bill Janssen6e027db2007-11-15 22:23:56 +0000734 try:
Antoine Pitroub1fdf472014-10-05 20:41:53 +0200735 return self._sslobj.read(len, buffer)
Bill Janssen6e027db2007-11-15 22:23:56 +0000736 except SSLError as x:
737 if x.args[0] == SSL_ERROR_EOF and self.suppress_ragged_eofs:
Antoine Pitrou24e561a2010-09-03 18:38:17 +0000738 if buffer is not None:
Bill Janssen54cc54c2007-12-14 22:08:56 +0000739 return 0
740 else:
741 return b''
Bill Janssen6e027db2007-11-15 22:23:56 +0000742 else:
743 raise
Thomas Woutersed03b412007-08-28 21:37:11 +0000744
745 def write(self, data):
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000746 """Write DATA to the underlying SSL channel. Returns
747 number of bytes of DATA actually transmitted."""
748
Bill Janssen6e027db2007-11-15 22:23:56 +0000749 self._checkClosed()
Antoine Pitrou60a26e02013-07-20 19:35:16 +0200750 if not self._sslobj:
751 raise ValueError("Write on closed or unwrapped SSL socket.")
Thomas Woutersed03b412007-08-28 21:37:11 +0000752 return self._sslobj.write(data)
753
Thomas Wouters1b7f8912007-09-19 03:06:30 +0000754 def getpeercert(self, binary_form=False):
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000755 """Returns a formatted version of the data in the
756 certificate provided by the other end of the SSL channel.
757 Return None if no certificate was provided, {} if a
758 certificate was provided, but not validated."""
759
Bill Janssen6e027db2007-11-15 22:23:56 +0000760 self._checkClosed()
Antoine Pitrou242db722013-05-01 20:52:07 +0200761 self._check_connected()
Antoine Pitroub1fdf472014-10-05 20:41:53 +0200762 return self._sslobj.getpeercert(binary_form)
Thomas Wouters1b7f8912007-09-19 03:06:30 +0000763
Antoine Pitroud5d17eb2012-03-22 00:23:03 +0100764 def selected_npn_protocol(self):
765 self._checkClosed()
766 if not self._sslobj or not _ssl.HAS_NPN:
767 return None
768 else:
769 return self._sslobj.selected_npn_protocol()
770
Guido van Rossum5b8b1552007-11-16 00:06:11 +0000771 def cipher(self):
Bill Janssen6e027db2007-11-15 22:23:56 +0000772 self._checkClosed()
Thomas Wouters1b7f8912007-09-19 03:06:30 +0000773 if not self._sslobj:
774 return None
775 else:
776 return self._sslobj.cipher()
Thomas Woutersed03b412007-08-28 21:37:11 +0000777
Antoine Pitrou8abdb8a2011-12-20 10:13:40 +0100778 def compression(self):
779 self._checkClosed()
780 if not self._sslobj:
781 return None
782 else:
783 return self._sslobj.compression()
784
Guido van Rossum5b8b1552007-11-16 00:06:11 +0000785 def send(self, data, flags=0):
Bill Janssen6e027db2007-11-15 22:23:56 +0000786 self._checkClosed()
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000787 if self._sslobj:
788 if flags != 0:
789 raise ValueError(
790 "non-zero flags not allowed in calls to send() on %s" %
791 self.__class__)
Antoine Pitroub4bebda2014-04-29 10:03:28 +0200792 return self._sslobj.write(data)
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000793 else:
794 return socket.send(self, data, flags)
Thomas Woutersed03b412007-08-28 21:37:11 +0000795
Antoine Pitroua468adc2010-09-14 14:43:44 +0000796 def sendto(self, data, flags_or_addr, addr=None):
Bill Janssen6e027db2007-11-15 22:23:56 +0000797 self._checkClosed()
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000798 if self._sslobj:
Bill Janssen980f3142008-06-29 00:05:51 +0000799 raise ValueError("sendto not allowed on instances of %s" %
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000800 self.__class__)
Antoine Pitroua468adc2010-09-14 14:43:44 +0000801 elif addr is None:
802 return socket.sendto(self, data, flags_or_addr)
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000803 else:
Antoine Pitroua468adc2010-09-14 14:43:44 +0000804 return socket.sendto(self, data, flags_or_addr, addr)
Thomas Woutersed03b412007-08-28 21:37:11 +0000805
Nick Coghlan513886a2011-08-28 00:00:27 +1000806 def sendmsg(self, *args, **kwargs):
807 # Ensure programs don't send data unencrypted if they try to
808 # use this method.
809 raise NotImplementedError("sendmsg not allowed on instances of %s" %
810 self.__class__)
811
Guido van Rossum5b8b1552007-11-16 00:06:11 +0000812 def sendall(self, data, flags=0):
Bill Janssen6e027db2007-11-15 22:23:56 +0000813 self._checkClosed()
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000814 if self._sslobj:
Giampaolo Rodolà374f8352010-08-29 12:08:09 +0000815 if flags != 0:
816 raise ValueError(
817 "non-zero flags not allowed in calls to sendall() on %s" %
818 self.__class__)
Bill Janssen6e027db2007-11-15 22:23:56 +0000819 amount = len(data)
820 count = 0
821 while (count < amount):
822 v = self.send(data[count:])
823 count += v
824 return amount
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000825 else:
826 return socket.sendall(self, data, flags)
Thomas Woutersed03b412007-08-28 21:37:11 +0000827
Giampaolo Rodola'915d1412014-06-11 03:54:30 +0200828 def sendfile(self, file, offset=0, count=None):
829 """Send a file, possibly by using os.sendfile() if this is a
830 clear-text socket. Return the total number of bytes sent.
831 """
832 if self._sslobj is None:
833 # os.sendfile() works with plain sockets only
834 return super().sendfile(file, offset, count)
835 else:
836 return self._sendfile_use_send(file, offset, count)
837
Guido van Rossum5b8b1552007-11-16 00:06:11 +0000838 def recv(self, buflen=1024, flags=0):
Bill Janssen6e027db2007-11-15 22:23:56 +0000839 self._checkClosed()
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000840 if self._sslobj:
841 if flags != 0:
842 raise ValueError(
Antoine Pitrou5733c082010-03-22 14:49:10 +0000843 "non-zero flags not allowed in calls to recv() on %s" %
844 self.__class__)
845 return self.read(buflen)
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000846 else:
847 return socket.recv(self, buflen, flags)
Thomas Woutersed03b412007-08-28 21:37:11 +0000848
Guido van Rossum5b8b1552007-11-16 00:06:11 +0000849 def recv_into(self, buffer, nbytes=None, flags=0):
Bill Janssen6e027db2007-11-15 22:23:56 +0000850 self._checkClosed()
851 if buffer and (nbytes is None):
852 nbytes = len(buffer)
853 elif nbytes is None:
854 nbytes = 1024
855 if self._sslobj:
856 if flags != 0:
857 raise ValueError(
Guido van Rossum5b8b1552007-11-16 00:06:11 +0000858 "non-zero flags not allowed in calls to recv_into() on %s" %
859 self.__class__)
Antoine Pitrou5733c082010-03-22 14:49:10 +0000860 return self.read(nbytes, buffer)
Bill Janssen6e027db2007-11-15 22:23:56 +0000861 else:
862 return socket.recv_into(self, buffer, nbytes, flags)
863
Antoine Pitroua468adc2010-09-14 14:43:44 +0000864 def recvfrom(self, buflen=1024, flags=0):
Bill Janssen6e027db2007-11-15 22:23:56 +0000865 self._checkClosed()
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000866 if self._sslobj:
Bill Janssen980f3142008-06-29 00:05:51 +0000867 raise ValueError("recvfrom not allowed on instances of %s" %
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000868 self.__class__)
869 else:
Antoine Pitroua468adc2010-09-14 14:43:44 +0000870 return socket.recvfrom(self, buflen, flags)
Thomas Woutersed03b412007-08-28 21:37:11 +0000871
Bill Janssen58afe4c2008-09-08 16:45:19 +0000872 def recvfrom_into(self, buffer, nbytes=None, flags=0):
873 self._checkClosed()
874 if self._sslobj:
875 raise ValueError("recvfrom_into not allowed on instances of %s" %
876 self.__class__)
877 else:
878 return socket.recvfrom_into(self, buffer, nbytes, flags)
879
Nick Coghlan513886a2011-08-28 00:00:27 +1000880 def recvmsg(self, *args, **kwargs):
881 raise NotImplementedError("recvmsg not allowed on instances of %s" %
882 self.__class__)
883
884 def recvmsg_into(self, *args, **kwargs):
885 raise NotImplementedError("recvmsg_into not allowed on instances of "
886 "%s" % self.__class__)
887
Guido van Rossum5b8b1552007-11-16 00:06:11 +0000888 def pending(self):
Bill Janssen6e027db2007-11-15 22:23:56 +0000889 self._checkClosed()
890 if self._sslobj:
891 return self._sslobj.pending()
892 else:
893 return 0
894
Guido van Rossum5b8b1552007-11-16 00:06:11 +0000895 def shutdown(self, how):
Bill Janssen6e027db2007-11-15 22:23:56 +0000896 self._checkClosed()
Thomas Wouters1b7f8912007-09-19 03:06:30 +0000897 self._sslobj = None
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000898 socket.shutdown(self, how)
Thomas Woutersed03b412007-08-28 21:37:11 +0000899
Ezio Melottidc55e672010-01-18 09:15:14 +0000900 def unwrap(self):
Bill Janssen40a0f662008-08-12 16:56:25 +0000901 if self._sslobj:
Antoine Pitroub1fdf472014-10-05 20:41:53 +0200902 s = self._sslobj.unwrap()
Bill Janssen40a0f662008-08-12 16:56:25 +0000903 self._sslobj = None
904 return s
905 else:
906 raise ValueError("No SSL wrapper around " + str(self))
907
Guido van Rossum5b8b1552007-11-16 00:06:11 +0000908 def _real_close(self):
Thomas Wouters1b7f8912007-09-19 03:06:30 +0000909 self._sslobj = None
Bill Janssen54cc54c2007-12-14 22:08:56 +0000910 socket._real_close(self)
Bill Janssen6e027db2007-11-15 22:23:56 +0000911
Bill Janssen48dc27c2007-12-05 03:38:10 +0000912 def do_handshake(self, block=False):
Bill Janssen6e027db2007-11-15 22:23:56 +0000913 """Perform a TLS/SSL handshake."""
Antoine Pitrou242db722013-05-01 20:52:07 +0200914 self._check_connected()
Bill Janssen48dc27c2007-12-05 03:38:10 +0000915 timeout = self.gettimeout()
Bill Janssen6e027db2007-11-15 22:23:56 +0000916 try:
Bill Janssen48dc27c2007-12-05 03:38:10 +0000917 if timeout == 0.0 and block:
918 self.settimeout(None)
Bill Janssen6e027db2007-11-15 22:23:56 +0000919 self._sslobj.do_handshake()
Bill Janssen48dc27c2007-12-05 03:38:10 +0000920 finally:
921 self.settimeout(timeout)
Thomas Woutersed03b412007-08-28 21:37:11 +0000922
Antoine Pitroub4410db2011-05-18 18:51:06 +0200923 def _real_connect(self, addr, connect_ex):
Giampaolo Rodolà745ab382010-08-29 19:25:49 +0000924 if self.server_side:
925 raise ValueError("can't connect in server-side mode")
Thomas Woutersed03b412007-08-28 21:37:11 +0000926 # Here we assume that the socket is client-side, and not
927 # connected at the time of the call. We connect it, then wrap it.
Antoine Pitroue93bf7a2011-02-26 23:24:06 +0000928 if self._connected:
Thomas Wouters1b7f8912007-09-19 03:06:30 +0000929 raise ValueError("attempt to connect already-connected SSLSocket!")
Antoine Pitroub1fdf472014-10-05 20:41:53 +0200930 sslobj = self.context._wrap_socket(self, False, self.server_hostname)
931 self._sslobj = SSLObject(sslobj, owner=self)
Bill Janssen54cc54c2007-12-14 22:08:56 +0000932 try:
Antoine Pitroub4410db2011-05-18 18:51:06 +0200933 if connect_ex:
934 rc = socket.connect_ex(self, addr)
Antoine Pitroue93bf7a2011-02-26 23:24:06 +0000935 else:
Antoine Pitroub4410db2011-05-18 18:51:06 +0200936 rc = None
937 socket.connect(self, addr)
938 if not rc:
Antoine Pitrou242db722013-05-01 20:52:07 +0200939 self._connected = True
Antoine Pitroub4410db2011-05-18 18:51:06 +0200940 if self.do_handshake_on_connect:
941 self.do_handshake()
Antoine Pitroub4410db2011-05-18 18:51:06 +0200942 return rc
Christian Heimes1aa9a752013-12-02 02:41:19 +0100943 except (OSError, ValueError):
Antoine Pitroub4410db2011-05-18 18:51:06 +0200944 self._sslobj = None
945 raise
Antoine Pitroue93bf7a2011-02-26 23:24:06 +0000946
947 def connect(self, addr):
948 """Connects to remote ADDR, and then wraps the connection in
949 an SSL channel."""
950 self._real_connect(addr, False)
951
952 def connect_ex(self, addr):
953 """Connects to remote ADDR, and then wraps the connection in
954 an SSL channel."""
955 return self._real_connect(addr, True)
Thomas Woutersed03b412007-08-28 21:37:11 +0000956
957 def accept(self):
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000958 """Accepts a new connection from a remote client, and returns
959 a tuple containing that new connection wrapped with a server-side
960 SSL channel, and the address of the remote client."""
961
962 newsock, addr = socket.accept(self)
Antoine Pitrou5c89b4e2012-11-11 01:25:36 +0100963 newsock = self.context.wrap_socket(newsock,
964 do_handshake_on_connect=self.do_handshake_on_connect,
965 suppress_ragged_eofs=self.suppress_ragged_eofs,
966 server_side=True)
967 return newsock, addr
Thomas Wouters1b7f8912007-09-19 03:06:30 +0000968
Antoine Pitroud6494802011-07-21 01:11:30 +0200969 def get_channel_binding(self, cb_type="tls-unique"):
970 """Get channel binding data for current connection. Raise ValueError
971 if the requested `cb_type` is not supported. Return bytes of the data
972 or None if the data is not available (e.g. before the handshake).
973 """
Antoine Pitroud6494802011-07-21 01:11:30 +0200974 if self._sslobj is None:
975 return None
Antoine Pitroub1fdf472014-10-05 20:41:53 +0200976 return self._sslobj.get_channel_binding(cb_type)
Antoine Pitroud6494802011-07-21 01:11:30 +0200977
Antoine Pitrou47e40422014-09-04 21:00:10 +0200978 def version(self):
979 """
980 Return a string identifying the protocol version used by the
981 current SSL channel, or None if there is no established channel.
982 """
983 if self._sslobj is None:
984 return None
985 return self._sslobj.version()
986
Bill Janssen54cc54c2007-12-14 22:08:56 +0000987
Thomas Wouters1b7f8912007-09-19 03:06:30 +0000988def wrap_socket(sock, keyfile=None, certfile=None,
989 server_side=False, cert_reqs=CERT_NONE,
Bill Janssen6e027db2007-11-15 22:23:56 +0000990 ssl_version=PROTOCOL_SSLv23, ca_certs=None,
Bill Janssen48dc27c2007-12-05 03:38:10 +0000991 do_handshake_on_connect=True,
Antoine Pitroud5d17eb2012-03-22 00:23:03 +0100992 suppress_ragged_eofs=True,
993 ciphers=None):
Thomas Wouters1b7f8912007-09-19 03:06:30 +0000994
Bill Janssen6e027db2007-11-15 22:23:56 +0000995 return SSLSocket(sock=sock, keyfile=keyfile, certfile=certfile,
Thomas Wouters1b7f8912007-09-19 03:06:30 +0000996 server_side=server_side, cert_reqs=cert_reqs,
Bill Janssen6e027db2007-11-15 22:23:56 +0000997 ssl_version=ssl_version, ca_certs=ca_certs,
Bill Janssen48dc27c2007-12-05 03:38:10 +0000998 do_handshake_on_connect=do_handshake_on_connect,
Antoine Pitrou2d9cb9c2010-04-17 17:40:45 +0000999 suppress_ragged_eofs=suppress_ragged_eofs,
1000 ciphers=ciphers)
Thomas Wouters1b7f8912007-09-19 03:06:30 +00001001
Thomas Woutersed03b412007-08-28 21:37:11 +00001002# some utility functions
1003
1004def cert_time_to_seconds(cert_time):
Antoine Pitrouc695c952014-04-28 20:57:36 +02001005 """Return the time in seconds since the Epoch, given the timestring
1006 representing the "notBefore" or "notAfter" date from a certificate
1007 in ``"%b %d %H:%M:%S %Y %Z"`` strptime format (C locale).
Thomas Wouters47b49bf2007-08-30 22:15:33 +00001008
Antoine Pitrouc695c952014-04-28 20:57:36 +02001009 "notBefore" or "notAfter" dates must use UTC (RFC 5280).
1010
1011 Month is one of: Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec
1012 UTC should be specified as GMT (see ASN1_TIME_print())
1013 """
1014 from time import strptime
1015 from calendar import timegm
1016
1017 months = (
1018 "Jan","Feb","Mar","Apr","May","Jun",
1019 "Jul","Aug","Sep","Oct","Nov","Dec"
1020 )
1021 time_format = ' %d %H:%M:%S %Y GMT' # NOTE: no month, fixed GMT
1022 try:
1023 month_number = months.index(cert_time[:3].title()) + 1
1024 except ValueError:
1025 raise ValueError('time data %r does not match '
1026 'format "%%b%s"' % (cert_time, time_format))
1027 else:
1028 # found valid month
1029 tt = strptime(cert_time[3:], time_format)
1030 # return an integer, the previous mktime()-based implementation
1031 # returned a float (fractional seconds are always zero here).
1032 return timegm((tt[0], month_number) + tt[2:6])
Thomas Woutersed03b412007-08-28 21:37:11 +00001033
Thomas Wouters1b7f8912007-09-19 03:06:30 +00001034PEM_HEADER = "-----BEGIN CERTIFICATE-----"
1035PEM_FOOTER = "-----END CERTIFICATE-----"
1036
1037def DER_cert_to_PEM_cert(der_cert_bytes):
Thomas Wouters1b7f8912007-09-19 03:06:30 +00001038 """Takes a certificate in binary DER format and returns the
1039 PEM version of it as a string."""
1040
Bill Janssen6e027db2007-11-15 22:23:56 +00001041 f = str(base64.standard_b64encode(der_cert_bytes), 'ASCII', 'strict')
1042 return (PEM_HEADER + '\n' +
1043 textwrap.fill(f, 64) + '\n' +
1044 PEM_FOOTER + '\n')
Thomas Wouters1b7f8912007-09-19 03:06:30 +00001045
1046def PEM_cert_to_DER_cert(pem_cert_string):
Thomas Wouters1b7f8912007-09-19 03:06:30 +00001047 """Takes a certificate in ASCII PEM format and returns the
1048 DER-encoded version of it as a byte sequence"""
1049
1050 if not pem_cert_string.startswith(PEM_HEADER):
1051 raise ValueError("Invalid PEM encoding; must start with %s"
1052 % PEM_HEADER)
1053 if not pem_cert_string.strip().endswith(PEM_FOOTER):
1054 raise ValueError("Invalid PEM encoding; must end with %s"
1055 % PEM_FOOTER)
1056 d = pem_cert_string.strip()[len(PEM_HEADER):-len(PEM_FOOTER)]
Georg Brandl706824f2009-06-04 09:42:55 +00001057 return base64.decodebytes(d.encode('ASCII', 'strict'))
Thomas Wouters1b7f8912007-09-19 03:06:30 +00001058
Antoine Pitrou94a5b662014-04-16 18:56:28 +02001059def get_server_certificate(addr, ssl_version=PROTOCOL_SSLv23, ca_certs=None):
Thomas Wouters1b7f8912007-09-19 03:06:30 +00001060 """Retrieve the certificate from the server at the specified address,
1061 and return it as a PEM-encoded string.
1062 If 'ca_certs' is specified, validate the server cert against it.
1063 If 'ssl_version' is specified, use it in the connection attempt."""
1064
1065 host, port = addr
Christian Heimes67986f92013-11-23 22:43:47 +01001066 if ca_certs is not None:
Thomas Wouters1b7f8912007-09-19 03:06:30 +00001067 cert_reqs = CERT_REQUIRED
1068 else:
1069 cert_reqs = CERT_NONE
Christian Heimes67986f92013-11-23 22:43:47 +01001070 context = _create_stdlib_context(ssl_version,
1071 cert_reqs=cert_reqs,
1072 cafile=ca_certs)
1073 with create_connection(addr) as sock:
1074 with context.wrap_socket(sock) as sslsock:
1075 dercert = sslsock.getpeercert(True)
Thomas Wouters1b7f8912007-09-19 03:06:30 +00001076 return DER_cert_to_PEM_cert(dercert)
1077
Guido van Rossum5b8b1552007-11-16 00:06:11 +00001078def get_protocol_name(protocol_code):
Victor Stinner3de49192011-05-09 00:42:58 +02001079 return _PROTOCOL_NAMES.get(protocol_code, '<unknown>')