blob: e1913904f3a39a89001224716d7bde507181857c [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
Christian Heimes598894f2016-09-05 23:19:05 +020054PROTOCOL_TLS
Thomas Woutersed03b412007-08-28 21:37:11 +000055PROTOCOL_TLSv1
Antoine Pitrou2463e5f2013-03-28 22:24:43 +010056PROTOCOL_TLSv1_1
57PROTOCOL_TLSv1_2
Antoine Pitrou58ddc9d2013-01-05 21:20:29 +010058
59The following constants identify various SSL alert message descriptions as per
60http://www.iana.org/assignments/tls-parameters/tls-parameters.xml#tls-parameters-6
61
62ALERT_DESCRIPTION_CLOSE_NOTIFY
63ALERT_DESCRIPTION_UNEXPECTED_MESSAGE
64ALERT_DESCRIPTION_BAD_RECORD_MAC
65ALERT_DESCRIPTION_RECORD_OVERFLOW
66ALERT_DESCRIPTION_DECOMPRESSION_FAILURE
67ALERT_DESCRIPTION_HANDSHAKE_FAILURE
68ALERT_DESCRIPTION_BAD_CERTIFICATE
69ALERT_DESCRIPTION_UNSUPPORTED_CERTIFICATE
70ALERT_DESCRIPTION_CERTIFICATE_REVOKED
71ALERT_DESCRIPTION_CERTIFICATE_EXPIRED
72ALERT_DESCRIPTION_CERTIFICATE_UNKNOWN
73ALERT_DESCRIPTION_ILLEGAL_PARAMETER
74ALERT_DESCRIPTION_UNKNOWN_CA
75ALERT_DESCRIPTION_ACCESS_DENIED
76ALERT_DESCRIPTION_DECODE_ERROR
77ALERT_DESCRIPTION_DECRYPT_ERROR
78ALERT_DESCRIPTION_PROTOCOL_VERSION
79ALERT_DESCRIPTION_INSUFFICIENT_SECURITY
80ALERT_DESCRIPTION_INTERNAL_ERROR
81ALERT_DESCRIPTION_USER_CANCELLED
82ALERT_DESCRIPTION_NO_RENEGOTIATION
83ALERT_DESCRIPTION_UNSUPPORTED_EXTENSION
84ALERT_DESCRIPTION_CERTIFICATE_UNOBTAINABLE
85ALERT_DESCRIPTION_UNRECOGNIZED_NAME
86ALERT_DESCRIPTION_BAD_CERTIFICATE_STATUS_RESPONSE
87ALERT_DESCRIPTION_BAD_CERTIFICATE_HASH_VALUE
88ALERT_DESCRIPTION_UNKNOWN_PSK_IDENTITY
Thomas Woutersed03b412007-08-28 21:37:11 +000089"""
90
Antoine Pitrouc481bfb2015-02-15 18:12:20 +010091import ipaddress
Christian Heimes05e8be12008-02-23 18:30:17 +000092import textwrap
Antoine Pitrou59fdd672010-10-08 10:37:08 +000093import re
Christian Heimes46bebee2013-06-09 19:03:31 +020094import sys
Christian Heimes6d7ad132013-06-09 18:02:55 +020095import os
Christian Heimesa6bc95a2013-11-17 19:59:14 +010096from collections import namedtuple
Antoine Pitrou172f0252014-04-18 20:33:08 +020097from enum import Enum as _Enum, IntEnum as _IntEnum
Thomas Woutersed03b412007-08-28 21:37:11 +000098
99import _ssl # if we can't import it, let the error propagate
Thomas Wouters1b7f8912007-09-19 03:06:30 +0000100
Antoine Pitrou04f6a322010-04-05 21:40:07 +0000101from _ssl import OPENSSL_VERSION_NUMBER, OPENSSL_VERSION_INFO, OPENSSL_VERSION
Antoine Pitroub1fdf472014-10-05 20:41:53 +0200102from _ssl import _SSLContext, MemoryBIO
Antoine Pitrou41032a62011-10-27 23:56:55 +0200103from _ssl import (
104 SSLError, SSLZeroReturnError, SSLWantReadError, SSLWantWriteError,
105 SSLSyscallError, SSLEOFError,
106 )
Thomas Woutersed03b412007-08-28 21:37:11 +0000107from _ssl import CERT_NONE, CERT_OPTIONAL, CERT_REQUIRED
Christian Heimesa6bc95a2013-11-17 19:59:14 +0100108from _ssl import txt2obj as _txt2obj, nid2obj as _nid2obj
Victor Stinnerbeeb5122014-11-28 13:28:25 +0100109from _ssl import RAND_status, RAND_add, RAND_bytes, RAND_pseudo_bytes
110try:
111 from _ssl import RAND_egd
112except ImportError:
113 # LibreSSL does not provide RAND_egd
114 pass
Antoine Pitrou58ddc9d2013-01-05 21:20:29 +0100115
116def _import_symbols(prefix):
117 for n in dir(_ssl):
118 if n.startswith(prefix):
119 globals()[n] = getattr(_ssl, n)
120
121_import_symbols('OP_')
122_import_symbols('ALERT_DESCRIPTION_')
123_import_symbols('SSL_ERROR_')
Benjamin Peterson7bcf9a52015-03-04 23:18:57 -0500124_import_symbols('VERIFY_')
Antoine Pitrou58ddc9d2013-01-05 21:20:29 +0100125
Benjamin Petersoncca27322015-01-23 16:35:37 -0500126from _ssl import HAS_SNI, HAS_ECDH, HAS_NPN, HAS_ALPN
Antoine Pitrou58ddc9d2013-01-05 21:20:29 +0100127
Antoine Pitroub9ac25d2011-07-08 18:47:06 +0200128from _ssl import _OPENSSL_API_VERSION
129
Ethan Furman24e837f2015-03-18 17:27:57 -0700130_IntEnum._convert(
131 '_SSLMethod', __name__,
Christian Heimes598894f2016-09-05 23:19:05 +0200132 lambda name: name.startswith('PROTOCOL_') and name != 'PROTOCOL_SSLv23',
Ethan Furman24e837f2015-03-18 17:27:57 -0700133 source=_ssl)
Antoine Pitrou58ddc9d2013-01-05 21:20:29 +0100134
Christian Heimes598894f2016-09-05 23:19:05 +0200135PROTOCOL_SSLv23 = _SSLMethod.PROTOCOL_SSLv23 = _SSLMethod.PROTOCOL_TLS
Antoine Pitrou172f0252014-04-18 20:33:08 +0200136_PROTOCOL_NAMES = {value: name for name, value in _SSLMethod.__members__.items()}
137
Victor Stinner3de49192011-05-09 00:42:58 +0200138try:
Antoine Pitrou8f85f902012-01-03 22:46:48 +0100139 _SSLv2_IF_EXISTS = PROTOCOL_SSLv2
Antoine Pitrou172f0252014-04-18 20:33:08 +0200140except NameError:
Antoine Pitrou8f85f902012-01-03 22:46:48 +0100141 _SSLv2_IF_EXISTS = None
Antoine Pitrou2463e5f2013-03-28 22:24:43 +0100142
Christian Heimes46bebee2013-06-09 19:03:31 +0200143if sys.platform == "win32":
Christian Heimes44109d72013-11-22 01:51:30 +0100144 from _ssl import enum_certificates, enum_crls
Christian Heimes46bebee2013-06-09 19:03:31 +0200145
Antoine Pitrou15399c32011-04-28 19:23:55 +0200146from socket import socket, AF_INET, SOCK_STREAM, create_connection
Antoine Pitrou3e86ba42013-12-28 17:26:33 +0100147from socket import SOL_SOCKET, SO_TYPE
Thomas Wouters1b7f8912007-09-19 03:06:30 +0000148import base64 # for DER-to-PEM translation
Antoine Pitroude8cf322010-04-26 17:29:05 +0000149import errno
Steve Dower33bc4a22016-05-26 12:18:12 -0700150import warnings
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000151
Andrew Svetlov0832af62012-12-18 23:10:48 +0200152
153socket_error = OSError # keep that public name in module namespace
154
Antoine Pitroud6494802011-07-21 01:11:30 +0200155if _ssl.HAS_TLS_UNIQUE:
156 CHANNEL_BINDING_TYPES = ['tls-unique']
157else:
158 CHANNEL_BINDING_TYPES = []
Thomas Woutersed03b412007-08-28 21:37:11 +0000159
Christian Heimes03d13c02016-09-06 20:06:47 +0200160
Antoine Pitrou8f85f902012-01-03 22:46:48 +0100161# Disable weak or insecure ciphers by default
162# (OpenSSL's default setting is 'DEFAULT:!aNULL:!eNULL')
Donald Stufft79ccaa22014-03-21 21:33:34 -0400163# Enable a better set of ciphers by default
164# This list has been explicitly chosen to:
165# * Prefer cipher suites that offer perfect forward secrecy (DHE/ECDHE)
166# * Prefer ECDHE over DHE for better performance
Christian Heimes03d13c02016-09-06 20:06:47 +0200167# * Prefer AEAD over CBC for better performance and security
168# * Prefer AES-GCM over ChaCha20 because most platforms have AES-NI
169# (ChaCha20 needs OpenSSL 1.1.0 or patched 1.0.2)
170# * Prefer any AES-GCM and ChaCha20 over any AES-CBC for better
171# performance and security
Donald Stufft79ccaa22014-03-21 21:33:34 -0400172# * Then Use HIGH cipher suites as a fallback
Christian Heimes03d13c02016-09-06 20:06:47 +0200173# * Disable NULL authentication, NULL encryption, 3DES and MD5 MACs
174# for security reasons
Donald Stufft79ccaa22014-03-21 21:33:34 -0400175_DEFAULT_CIPHERS = (
Christian Heimes03d13c02016-09-06 20:06:47 +0200176 'ECDH+AESGCM:ECDH+CHACHA20:DH+AESGCM:DH+CHACHA20:ECDH+AES256:DH+AES256:'
177 'ECDH+AES128:DH+AES:ECDH+HIGH:DH+HIGH:RSA+AESGCM:RSA+AES:RSA+HIGH:'
178 '!aNULL:!eNULL:!MD5:!3DES'
179 )
Antoine Pitrou8f85f902012-01-03 22:46:48 +0100180
Donald Stufft6a2ba942014-03-23 19:05:28 -0400181# Restricted and more secure ciphers for the server side
Donald Stufft79ccaa22014-03-21 21:33:34 -0400182# This list has been explicitly chosen to:
183# * Prefer cipher suites that offer perfect forward secrecy (DHE/ECDHE)
184# * Prefer ECDHE over DHE for better performance
Christian Heimes03d13c02016-09-06 20:06:47 +0200185# * Prefer AEAD over CBC for better performance and security
186# * Prefer AES-GCM over ChaCha20 because most platforms have AES-NI
187# * Prefer any AES-GCM and ChaCha20 over any AES-CBC for better
188# performance and security
Donald Stufft79ccaa22014-03-21 21:33:34 -0400189# * Then Use HIGH cipher suites as a fallback
Christian Heimes03d13c02016-09-06 20:06:47 +0200190# * Disable NULL authentication, NULL encryption, MD5 MACs, DSS, RC4, and
191# 3DES for security reasons
Donald Stufft6a2ba942014-03-23 19:05:28 -0400192_RESTRICTED_SERVER_CIPHERS = (
Christian Heimes03d13c02016-09-06 20:06:47 +0200193 'ECDH+AESGCM:ECDH+CHACHA20:DH+AESGCM:DH+CHACHA20:ECDH+AES256:DH+AES256:'
194 'ECDH+AES128:DH+AES:ECDH+HIGH:DH+HIGH:RSA+AESGCM:RSA+AES:RSA+HIGH:'
195 '!aNULL:!eNULL:!MD5:!DSS:!RC4:!3DES'
Donald Stufft79ccaa22014-03-21 21:33:34 -0400196)
Christian Heimes4c05b472013-11-23 15:58:30 +0100197
Thomas Woutersed03b412007-08-28 21:37:11 +0000198
Antoine Pitrou59fdd672010-10-08 10:37:08 +0000199class CertificateError(ValueError):
200 pass
201
202
Georg Brandl72c98d32013-10-27 07:16:53 +0100203def _dnsname_match(dn, hostname, max_wildcards=1):
204 """Matching according to RFC 6125, section 6.4.3
205
206 http://tools.ietf.org/html/rfc6125#section-6.4.3
207 """
Antoine Pitrou59fdd672010-10-08 10:37:08 +0000208 pats = []
Georg Brandl72c98d32013-10-27 07:16:53 +0100209 if not dn:
210 return False
211
212 leftmost, *remainder = dn.split(r'.')
213
214 wildcards = leftmost.count('*')
215 if wildcards > max_wildcards:
216 # Issue #17980: avoid denials of service by refusing more
Berker Peksagf23530f2014-10-19 18:04:38 +0300217 # than one wildcard per fragment. A survey of established
Georg Brandl72c98d32013-10-27 07:16:53 +0100218 # policy among SSL implementations showed it to be a
219 # reasonable choice.
220 raise CertificateError(
221 "too many wildcards in certificate DNS name: " + repr(dn))
222
223 # speed up common case w/o wildcards
224 if not wildcards:
225 return dn.lower() == hostname.lower()
226
227 # RFC 6125, section 6.4.3, subitem 1.
228 # The client SHOULD NOT attempt to match a presented identifier in which
229 # the wildcard character comprises a label other than the left-most label.
230 if leftmost == '*':
231 # When '*' is a fragment by itself, it matches a non-empty dotless
232 # fragment.
233 pats.append('[^.]+')
234 elif leftmost.startswith('xn--') or hostname.startswith('xn--'):
235 # RFC 6125, section 6.4.3, subitem 3.
236 # The client SHOULD NOT attempt to match a presented identifier
237 # where the wildcard character is embedded within an A-label or
238 # U-label of an internationalized domain name.
239 pats.append(re.escape(leftmost))
240 else:
241 # Otherwise, '*' matches any dotless string, e.g. www*
242 pats.append(re.escape(leftmost).replace(r'\*', '[^.]*'))
243
244 # add the remaining fragments, ignore any wildcards
245 for frag in remainder:
246 pats.append(re.escape(frag))
247
248 pat = re.compile(r'\A' + r'\.'.join(pats) + r'\Z', re.IGNORECASE)
249 return pat.match(hostname)
Antoine Pitrou59fdd672010-10-08 10:37:08 +0000250
251
Antoine Pitrouc481bfb2015-02-15 18:12:20 +0100252def _ipaddress_match(ipname, host_ip):
253 """Exact matching of IP addresses.
254
255 RFC 6125 explicitly doesn't define an algorithm for this
256 (section 1.7.2 - "Out of Scope").
257 """
258 # OpenSSL may add a trailing newline to a subjectAltName's IP address
259 ip = ipaddress.ip_address(ipname.rstrip())
260 return ip == host_ip
261
262
Antoine Pitrou59fdd672010-10-08 10:37:08 +0000263def match_hostname(cert, hostname):
264 """Verify that *cert* (in decoded format as returned by
Georg Brandl72c98d32013-10-27 07:16:53 +0100265 SSLSocket.getpeercert()) matches the *hostname*. RFC 2818 and RFC 6125
266 rules are followed, but IP addresses are not accepted for *hostname*.
Antoine Pitrou59fdd672010-10-08 10:37:08 +0000267
268 CertificateError is raised on failure. On success, the function
269 returns nothing.
270 """
271 if not cert:
Christian Heimes1aa9a752013-12-02 02:41:19 +0100272 raise ValueError("empty or no certificate, match_hostname needs a "
273 "SSL socket or SSL context with either "
274 "CERT_OPTIONAL or CERT_REQUIRED")
Antoine Pitrouc481bfb2015-02-15 18:12:20 +0100275 try:
276 host_ip = ipaddress.ip_address(hostname)
277 except ValueError:
278 # Not an IP address (common case)
279 host_ip = None
Antoine Pitrou59fdd672010-10-08 10:37:08 +0000280 dnsnames = []
281 san = cert.get('subjectAltName', ())
282 for key, value in san:
283 if key == 'DNS':
Antoine Pitrouc481bfb2015-02-15 18:12:20 +0100284 if host_ip is None and _dnsname_match(value, hostname):
285 return
286 dnsnames.append(value)
287 elif key == 'IP Address':
288 if host_ip is not None and _ipaddress_match(value, host_ip):
Antoine Pitrou59fdd672010-10-08 10:37:08 +0000289 return
290 dnsnames.append(value)
Antoine Pitrou1c86b442011-05-06 15:19:49 +0200291 if not dnsnames:
292 # The subject is only checked when there is no dNSName entry
293 # in subjectAltName
Antoine Pitrou59fdd672010-10-08 10:37:08 +0000294 for sub in cert.get('subject', ()):
295 for key, value in sub:
296 # XXX according to RFC 2818, the most specific Common Name
297 # must be used.
298 if key == 'commonName':
Georg Brandl72c98d32013-10-27 07:16:53 +0100299 if _dnsname_match(value, hostname):
Antoine Pitrou59fdd672010-10-08 10:37:08 +0000300 return
301 dnsnames.append(value)
302 if len(dnsnames) > 1:
303 raise CertificateError("hostname %r "
304 "doesn't match either of %s"
305 % (hostname, ', '.join(map(repr, dnsnames))))
306 elif len(dnsnames) == 1:
307 raise CertificateError("hostname %r "
308 "doesn't match %r"
309 % (hostname, dnsnames[0]))
310 else:
311 raise CertificateError("no appropriate commonName or "
312 "subjectAltName fields were found")
313
314
Christian Heimesa6bc95a2013-11-17 19:59:14 +0100315DefaultVerifyPaths = namedtuple("DefaultVerifyPaths",
Christian Heimes6d7ad132013-06-09 18:02:55 +0200316 "cafile capath openssl_cafile_env openssl_cafile openssl_capath_env "
317 "openssl_capath")
318
319def get_default_verify_paths():
320 """Return paths to default cafile and capath.
321 """
322 parts = _ssl.get_default_verify_paths()
323
324 # environment vars shadow paths
325 cafile = os.environ.get(parts[0], parts[1])
326 capath = os.environ.get(parts[2], parts[3])
327
328 return DefaultVerifyPaths(cafile if os.path.isfile(cafile) else None,
329 capath if os.path.isdir(capath) else None,
330 *parts)
331
332
Christian Heimesa6bc95a2013-11-17 19:59:14 +0100333class _ASN1Object(namedtuple("_ASN1Object", "nid shortname longname oid")):
334 """ASN.1 object identifier lookup
335 """
336 __slots__ = ()
337
338 def __new__(cls, oid):
339 return super().__new__(cls, *_txt2obj(oid, name=False))
340
341 @classmethod
342 def fromnid(cls, nid):
343 """Create _ASN1Object from OpenSSL numeric ID
344 """
345 return super().__new__(cls, *_nid2obj(nid))
346
347 @classmethod
348 def fromname(cls, name):
349 """Create _ASN1Object from short name, long name or OID
350 """
351 return super().__new__(cls, *_txt2obj(name, name=True))
352
353
Christian Heimes72d28502013-11-23 13:56:58 +0100354class Purpose(_ASN1Object, _Enum):
355 """SSLContext purpose flags with X509v3 Extended Key Usage objects
356 """
357 SERVER_AUTH = '1.3.6.1.5.5.7.3.1'
358 CLIENT_AUTH = '1.3.6.1.5.5.7.3.2'
359
360
Antoine Pitrou152efa22010-05-16 18:19:27 +0000361class SSLContext(_SSLContext):
362 """An SSLContext holds various SSL-related configuration options and
363 data, such as certificates and possibly a private key."""
364
Antoine Pitrou58ddc9d2013-01-05 21:20:29 +0100365 __slots__ = ('protocol', '__weakref__')
Christian Heimes72d28502013-11-23 13:56:58 +0100366 _windows_cert_stores = ("CA", "ROOT")
Antoine Pitrou152efa22010-05-16 18:19:27 +0000367
Christian Heimes598894f2016-09-05 23:19:05 +0200368 def __new__(cls, protocol=PROTOCOL_TLS, *args, **kwargs):
Antoine Pitrou8f85f902012-01-03 22:46:48 +0100369 self = _SSLContext.__new__(cls, protocol)
370 if protocol != _SSLv2_IF_EXISTS:
371 self.set_ciphers(_DEFAULT_CIPHERS)
372 return self
Antoine Pitrou152efa22010-05-16 18:19:27 +0000373
Christian Heimes598894f2016-09-05 23:19:05 +0200374 def __init__(self, protocol=PROTOCOL_TLS):
Antoine Pitrou152efa22010-05-16 18:19:27 +0000375 self.protocol = protocol
376
377 def wrap_socket(self, sock, server_side=False,
378 do_handshake_on_connect=True,
Antoine Pitroud5323212010-10-22 18:19:07 +0000379 suppress_ragged_eofs=True,
380 server_hostname=None):
Antoine Pitrou152efa22010-05-16 18:19:27 +0000381 return SSLSocket(sock=sock, server_side=server_side,
382 do_handshake_on_connect=do_handshake_on_connect,
383 suppress_ragged_eofs=suppress_ragged_eofs,
Antoine Pitroud5323212010-10-22 18:19:07 +0000384 server_hostname=server_hostname,
Antoine Pitrou152efa22010-05-16 18:19:27 +0000385 _context=self)
386
Antoine Pitroub1fdf472014-10-05 20:41:53 +0200387 def wrap_bio(self, incoming, outgoing, server_side=False,
388 server_hostname=None):
389 sslobj = self._wrap_bio(incoming, outgoing, server_side=server_side,
390 server_hostname=server_hostname)
391 return SSLObject(sslobj)
392
Antoine Pitroud5d17eb2012-03-22 00:23:03 +0100393 def set_npn_protocols(self, npn_protocols):
394 protos = bytearray()
395 for protocol in npn_protocols:
396 b = bytes(protocol, 'ascii')
397 if len(b) == 0 or len(b) > 255:
398 raise SSLError('NPN protocols must be 1 to 255 in length')
399 protos.append(len(b))
400 protos.extend(b)
401
402 self._set_npn_protocols(protos)
403
Benjamin Petersoncca27322015-01-23 16:35:37 -0500404 def set_alpn_protocols(self, alpn_protocols):
405 protos = bytearray()
406 for protocol in alpn_protocols:
407 b = bytes(protocol, 'ascii')
408 if len(b) == 0 or len(b) > 255:
409 raise SSLError('ALPN protocols must be 1 to 255 in length')
410 protos.append(len(b))
411 protos.extend(b)
412
413 self._set_alpn_protocols(protos)
414
Christian Heimes72d28502013-11-23 13:56:58 +0100415 def _load_windows_store_certs(self, storename, purpose):
416 certs = bytearray()
Steve Dower33bc4a22016-05-26 12:18:12 -0700417 try:
418 for cert, encoding, trust in enum_certificates(storename):
419 # CA certs are never PKCS#7 encoded
420 if encoding == "x509_asn":
421 if trust is True or purpose.oid in trust:
422 certs.extend(cert)
423 except PermissionError:
424 warnings.warn("unable to enumerate Windows certificate store")
Steve Dower8dd7aeb2016-03-17 15:02:39 -0700425 if certs:
426 self.load_verify_locations(cadata=certs)
Christian Heimes72d28502013-11-23 13:56:58 +0100427 return certs
428
429 def load_default_certs(self, purpose=Purpose.SERVER_AUTH):
430 if not isinstance(purpose, _ASN1Object):
431 raise TypeError(purpose)
432 if sys.platform == "win32":
433 for storename in self._windows_cert_stores:
434 self._load_windows_store_certs(storename, purpose)
Benjamin Peterson5915b0f2014-10-03 17:27:05 -0400435 self.set_default_verify_paths()
Christian Heimes72d28502013-11-23 13:56:58 +0100436
Antoine Pitrou152efa22010-05-16 18:19:27 +0000437
Christian Heimes4c05b472013-11-23 15:58:30 +0100438def create_default_context(purpose=Purpose.SERVER_AUTH, *, cafile=None,
439 capath=None, cadata=None):
440 """Create a SSLContext object with default settings.
441
442 NOTE: The protocol and settings may change anytime without prior
443 deprecation. The values represent a fair balance between maximum
444 compatibility and security.
445 """
446 if not isinstance(purpose, _ASN1Object):
447 raise TypeError(purpose)
Donald Stufft6a2ba942014-03-23 19:05:28 -0400448
Christian Heimes598894f2016-09-05 23:19:05 +0200449 context = SSLContext(PROTOCOL_TLS)
Donald Stufft6a2ba942014-03-23 19:05:28 -0400450
Christian Heimes4c05b472013-11-23 15:58:30 +0100451 # SSLv2 considered harmful.
452 context.options |= OP_NO_SSLv2
Donald Stufft6a2ba942014-03-23 19:05:28 -0400453
454 # SSLv3 has problematic security and is only required for really old
455 # clients such as IE6 on Windows XP
456 context.options |= OP_NO_SSLv3
457
Christian Heimesdec813f2013-11-28 08:06:54 +0100458 # disable compression to prevent CRIME attacks (OpenSSL 1.0+)
459 context.options |= getattr(_ssl, "OP_NO_COMPRESSION", 0)
Donald Stufft6a2ba942014-03-23 19:05:28 -0400460
Christian Heimes4c05b472013-11-23 15:58:30 +0100461 if purpose == Purpose.SERVER_AUTH:
Donald Stufft6a2ba942014-03-23 19:05:28 -0400462 # verify certs and host name in client mode
Christian Heimes4c05b472013-11-23 15:58:30 +0100463 context.verify_mode = CERT_REQUIRED
Christian Heimes1aa9a752013-12-02 02:41:19 +0100464 context.check_hostname = True
Donald Stufft6a2ba942014-03-23 19:05:28 -0400465 elif purpose == Purpose.CLIENT_AUTH:
466 # Prefer the server's ciphers by default so that we get stronger
467 # encryption
468 context.options |= getattr(_ssl, "OP_CIPHER_SERVER_PREFERENCE", 0)
469
470 # Use single use keys in order to improve forward secrecy
471 context.options |= getattr(_ssl, "OP_SINGLE_DH_USE", 0)
472 context.options |= getattr(_ssl, "OP_SINGLE_ECDH_USE", 0)
473
474 # disallow ciphers with known vulnerabilities
475 context.set_ciphers(_RESTRICTED_SERVER_CIPHERS)
476
Christian Heimes4c05b472013-11-23 15:58:30 +0100477 if cafile or capath or cadata:
478 context.load_verify_locations(cafile, capath, cadata)
479 elif context.verify_mode != CERT_NONE:
480 # no explicit cafile, capath or cadata but the verify mode is
481 # CERT_OPTIONAL or CERT_REQUIRED. Let's try to load default system
482 # root CA certificates for the given purpose. This may fail silently.
483 context.load_default_certs(purpose)
484 return context
485
Christian Heimes598894f2016-09-05 23:19:05 +0200486def _create_unverified_context(protocol=PROTOCOL_TLS, *, cert_reqs=None,
Christian Heimesa02c69a2013-12-02 20:59:28 +0100487 check_hostname=False, purpose=Purpose.SERVER_AUTH,
Christian Heimes67986f92013-11-23 22:43:47 +0100488 certfile=None, keyfile=None,
489 cafile=None, capath=None, cadata=None):
490 """Create a SSLContext object for Python stdlib modules
491
492 All Python stdlib modules shall use this function to create SSLContext
493 objects in order to keep common settings in one place. The configuration
494 is less restrict than create_default_context()'s to increase backward
495 compatibility.
496 """
497 if not isinstance(purpose, _ASN1Object):
498 raise TypeError(purpose)
499
500 context = SSLContext(protocol)
501 # SSLv2 considered harmful.
502 context.options |= OP_NO_SSLv2
Antoine Pitroue4eda4d2014-10-17 19:28:30 +0200503 # SSLv3 has problematic security and is only required for really old
504 # clients such as IE6 on Windows XP
505 context.options |= OP_NO_SSLv3
Christian Heimes67986f92013-11-23 22:43:47 +0100506
507 if cert_reqs is not None:
508 context.verify_mode = cert_reqs
Christian Heimesa02c69a2013-12-02 20:59:28 +0100509 context.check_hostname = check_hostname
Christian Heimes67986f92013-11-23 22:43:47 +0100510
511 if keyfile and not certfile:
512 raise ValueError("certfile must be specified")
513 if certfile or keyfile:
514 context.load_cert_chain(certfile, keyfile)
515
516 # load CA root certs
517 if cafile or capath or cadata:
518 context.load_verify_locations(cafile, capath, cadata)
519 elif context.verify_mode != CERT_NONE:
520 # no explicit cafile, capath or cadata but the verify mode is
521 # CERT_OPTIONAL or CERT_REQUIRED. Let's try to load default system
522 # root CA certificates for the given purpose. This may fail silently.
523 context.load_default_certs(purpose)
524
525 return context
526
Benjamin Peterson4ffb0752014-11-03 14:29:33 -0500527# Used by http.client if no context is explicitly passed.
528_create_default_https_context = create_default_context
529
530
531# Backwards compatibility alias, even though it's not a public name.
532_create_stdlib_context = _create_unverified_context
533
Antoine Pitroub1fdf472014-10-05 20:41:53 +0200534
535class SSLObject:
536 """This class implements an interface on top of a low-level SSL object as
537 implemented by OpenSSL. This object captures the state of an SSL connection
538 but does not provide any network IO itself. IO needs to be performed
539 through separate "BIO" objects which are OpenSSL's IO abstraction layer.
540
541 This class does not have a public constructor. Instances are returned by
542 ``SSLContext.wrap_bio``. This class is typically used by framework authors
543 that want to implement asynchronous IO for SSL through memory buffers.
544
545 When compared to ``SSLSocket``, this object lacks the following features:
546
547 * Any form of network IO incluging methods such as ``recv`` and ``send``.
548 * The ``do_handshake_on_connect`` and ``suppress_ragged_eofs`` machinery.
549 """
550
551 def __init__(self, sslobj, owner=None):
552 self._sslobj = sslobj
553 # Note: _sslobj takes a weak reference to owner
554 self._sslobj.owner = owner or self
555
556 @property
557 def context(self):
558 """The SSLContext that is currently in use."""
559 return self._sslobj.context
560
561 @context.setter
562 def context(self, ctx):
563 self._sslobj.context = ctx
564
565 @property
566 def server_side(self):
567 """Whether this is a server-side socket."""
568 return self._sslobj.server_side
569
570 @property
571 def server_hostname(self):
572 """The currently set server hostname (for SNI), or ``None`` if no
573 server hostame is set."""
574 return self._sslobj.server_hostname
575
Martin Panterf6b1d662016-03-28 00:22:09 +0000576 def read(self, len=1024, buffer=None):
Antoine Pitroub1fdf472014-10-05 20:41:53 +0200577 """Read up to 'len' bytes from the SSL object and return them.
578
579 If 'buffer' is provided, read into this buffer and return the number of
580 bytes read.
581 """
582 if buffer is not None:
583 v = self._sslobj.read(len, buffer)
584 else:
Martin Panterf6b1d662016-03-28 00:22:09 +0000585 v = self._sslobj.read(len)
Antoine Pitroub1fdf472014-10-05 20:41:53 +0200586 return v
587
588 def write(self, data):
589 """Write 'data' to the SSL object and return the number of bytes
590 written.
591
592 The 'data' argument must support the buffer interface.
593 """
594 return self._sslobj.write(data)
595
596 def getpeercert(self, binary_form=False):
597 """Returns a formatted version of the data in the certificate provided
598 by the other end of the SSL channel.
599
600 Return None if no certificate was provided, {} if a certificate was
601 provided, but not validated.
602 """
603 return self._sslobj.peer_certificate(binary_form)
604
605 def selected_npn_protocol(self):
606 """Return the currently selected NPN protocol as a string, or ``None``
607 if a next protocol was not negotiated or if NPN is not supported by one
608 of the peers."""
609 if _ssl.HAS_NPN:
610 return self._sslobj.selected_npn_protocol()
611
Benjamin Petersoncca27322015-01-23 16:35:37 -0500612 def selected_alpn_protocol(self):
613 """Return the currently selected ALPN protocol as a string, or ``None``
614 if a next protocol was not negotiated or if ALPN is not supported by one
615 of the peers."""
616 if _ssl.HAS_ALPN:
617 return self._sslobj.selected_alpn_protocol()
618
Antoine Pitroub1fdf472014-10-05 20:41:53 +0200619 def cipher(self):
620 """Return the currently selected cipher as a 3-tuple ``(name,
621 ssl_version, secret_bits)``."""
622 return self._sslobj.cipher()
623
Benjamin Peterson4cb17812015-01-07 11:14:26 -0600624 def shared_ciphers(self):
Benjamin Petersonc114e7d2015-01-11 15:22:07 -0500625 """Return a list of ciphers shared by the client during the handshake or
626 None if this is not a valid server connection.
Benjamin Peterson5318c7a2015-01-07 11:26:50 -0600627 """
Benjamin Peterson4cb17812015-01-07 11:14:26 -0600628 return self._sslobj.shared_ciphers()
629
Antoine Pitroub1fdf472014-10-05 20:41:53 +0200630 def compression(self):
631 """Return the current compression algorithm in use, or ``None`` if
632 compression was not negotiated or not supported by one of the peers."""
633 return self._sslobj.compression()
634
635 def pending(self):
636 """Return the number of bytes that can be read immediately."""
637 return self._sslobj.pending()
638
Antoine Pitrou3cb93792014-10-06 00:21:09 +0200639 def do_handshake(self):
Antoine Pitroub1fdf472014-10-05 20:41:53 +0200640 """Start the SSL/TLS handshake."""
641 self._sslobj.do_handshake()
642 if self.context.check_hostname:
643 if not self.server_hostname:
644 raise ValueError("check_hostname needs server_hostname "
645 "argument")
646 match_hostname(self.getpeercert(), self.server_hostname)
647
648 def unwrap(self):
649 """Start the SSL shutdown handshake."""
650 return self._sslobj.shutdown()
651
652 def get_channel_binding(self, cb_type="tls-unique"):
653 """Get channel binding data for current connection. Raise ValueError
654 if the requested `cb_type` is not supported. Return bytes of the data
655 or None if the data is not available (e.g. before the handshake)."""
656 if cb_type not in CHANNEL_BINDING_TYPES:
657 raise ValueError("Unsupported channel binding type")
658 if cb_type != "tls-unique":
659 raise NotImplementedError(
660 "{0} channel binding type not implemented"
661 .format(cb_type))
662 return self._sslobj.tls_unique_cb()
663
664 def version(self):
665 """Return a string identifying the protocol version used by the
666 current SSL channel. """
667 return self._sslobj.version()
668
669
Antoine Pitrou152efa22010-05-16 18:19:27 +0000670class SSLSocket(socket):
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000671 """This class implements a subtype of socket.socket that wraps
672 the underlying OS socket in an SSL context when necessary, and
673 provides read and write methods over that channel."""
674
Bill Janssen6e027db2007-11-15 22:23:56 +0000675 def __init__(self, sock=None, keyfile=None, certfile=None,
Thomas Woutersed03b412007-08-28 21:37:11 +0000676 server_side=False, cert_reqs=CERT_NONE,
Christian Heimes598894f2016-09-05 23:19:05 +0200677 ssl_version=PROTOCOL_TLS, ca_certs=None,
Bill Janssen6e027db2007-11-15 22:23:56 +0000678 do_handshake_on_connect=True,
679 family=AF_INET, type=SOCK_STREAM, proto=0, fileno=None,
Antoine Pitroud5d17eb2012-03-22 00:23:03 +0100680 suppress_ragged_eofs=True, npn_protocols=None, ciphers=None,
Antoine Pitroud5323212010-10-22 18:19:07 +0000681 server_hostname=None,
Antoine Pitrou152efa22010-05-16 18:19:27 +0000682 _context=None):
Bill Janssen6e027db2007-11-15 22:23:56 +0000683
Antoine Pitrou152efa22010-05-16 18:19:27 +0000684 if _context:
Antoine Pitrou58ddc9d2013-01-05 21:20:29 +0100685 self._context = _context
Antoine Pitrou152efa22010-05-16 18:19:27 +0000686 else:
Giampaolo Rodolà745ab382010-08-29 19:25:49 +0000687 if server_side and not certfile:
688 raise ValueError("certfile must be specified for server-side "
689 "operations")
Giampaolo Rodolà8b7da622010-08-30 18:28:05 +0000690 if keyfile and not certfile:
691 raise ValueError("certfile must be specified")
Antoine Pitrou152efa22010-05-16 18:19:27 +0000692 if certfile and not keyfile:
693 keyfile = certfile
Antoine Pitrou58ddc9d2013-01-05 21:20:29 +0100694 self._context = SSLContext(ssl_version)
695 self._context.verify_mode = cert_reqs
Antoine Pitrou152efa22010-05-16 18:19:27 +0000696 if ca_certs:
Antoine Pitrou58ddc9d2013-01-05 21:20:29 +0100697 self._context.load_verify_locations(ca_certs)
Antoine Pitrou152efa22010-05-16 18:19:27 +0000698 if certfile:
Antoine Pitrou58ddc9d2013-01-05 21:20:29 +0100699 self._context.load_cert_chain(certfile, keyfile)
Antoine Pitroud5d17eb2012-03-22 00:23:03 +0100700 if npn_protocols:
Antoine Pitrou58ddc9d2013-01-05 21:20:29 +0100701 self._context.set_npn_protocols(npn_protocols)
Antoine Pitrou152efa22010-05-16 18:19:27 +0000702 if ciphers:
Antoine Pitrou58ddc9d2013-01-05 21:20:29 +0100703 self._context.set_ciphers(ciphers)
Antoine Pitrou152efa22010-05-16 18:19:27 +0000704 self.keyfile = keyfile
705 self.certfile = certfile
706 self.cert_reqs = cert_reqs
707 self.ssl_version = ssl_version
708 self.ca_certs = ca_certs
709 self.ciphers = ciphers
Antoine Pitrou3e86ba42013-12-28 17:26:33 +0100710 # Can't use sock.type as other flags (such as SOCK_NONBLOCK) get
711 # mixed in.
712 if sock.getsockopt(SOL_SOCKET, SO_TYPE) != SOCK_STREAM:
713 raise NotImplementedError("only stream sockets are supported")
Antoine Pitroud5323212010-10-22 18:19:07 +0000714 if server_side and server_hostname:
715 raise ValueError("server_hostname can only be specified "
716 "in client mode")
Christian Heimes1aa9a752013-12-02 02:41:19 +0100717 if self._context.check_hostname and not server_hostname:
Benjamin Peterson7243b572014-11-23 17:04:34 -0600718 raise ValueError("check_hostname requires server_hostname")
Giampaolo Rodolà745ab382010-08-29 19:25:49 +0000719 self.server_side = server_side
Antoine Pitroud5323212010-10-22 18:19:07 +0000720 self.server_hostname = server_hostname
Antoine Pitrou152efa22010-05-16 18:19:27 +0000721 self.do_handshake_on_connect = do_handshake_on_connect
722 self.suppress_ragged_eofs = suppress_ragged_eofs
Bill Janssen6e027db2007-11-15 22:23:56 +0000723 if sock is not None:
Bill Janssen54cc54c2007-12-14 22:08:56 +0000724 socket.__init__(self,
725 family=sock.family,
726 type=sock.type,
727 proto=sock.proto,
Antoine Pitroue43f9d02010-08-08 23:24:50 +0000728 fileno=sock.fileno())
Antoine Pitrou40f08742010-04-24 22:04:40 +0000729 self.settimeout(sock.gettimeout())
Antoine Pitrou6e451df2010-08-09 20:39:54 +0000730 sock.detach()
Bill Janssen6e027db2007-11-15 22:23:56 +0000731 elif fileno is not None:
732 socket.__init__(self, fileno=fileno)
733 else:
734 socket.__init__(self, family=family, type=type, proto=proto)
735
Antoine Pitrou242db722013-05-01 20:52:07 +0200736 # See if we are connected
737 try:
738 self.getpeername()
739 except OSError as e:
740 if e.errno != errno.ENOTCONN:
741 raise
742 connected = False
743 else:
744 connected = True
745
Antoine Pitroufa2b9382010-04-26 22:17:47 +0000746 self._closed = False
747 self._sslobj = None
Antoine Pitroue93bf7a2011-02-26 23:24:06 +0000748 self._connected = connected
Antoine Pitroufa2b9382010-04-26 22:17:47 +0000749 if connected:
750 # create the SSL object
Bill Janssen6e027db2007-11-15 22:23:56 +0000751 try:
Antoine Pitroub1fdf472014-10-05 20:41:53 +0200752 sslobj = self._context._wrap_socket(self, server_side,
753 server_hostname)
754 self._sslobj = SSLObject(sslobj, owner=self)
Bill Janssen6e027db2007-11-15 22:23:56 +0000755 if do_handshake_on_connect:
Bill Janssen48dc27c2007-12-05 03:38:10 +0000756 timeout = self.gettimeout()
757 if timeout == 0.0:
758 # non-blocking
759 raise ValueError("do_handshake_on_connect should not be specified for non-blocking sockets")
Bill Janssen6e027db2007-11-15 22:23:56 +0000760 self.do_handshake()
Bill Janssen48dc27c2007-12-05 03:38:10 +0000761
Christian Heimes1aa9a752013-12-02 02:41:19 +0100762 except (OSError, ValueError):
Bill Janssen6e027db2007-11-15 22:23:56 +0000763 self.close()
Christian Heimes1aa9a752013-12-02 02:41:19 +0100764 raise
Antoine Pitrou242db722013-05-01 20:52:07 +0200765
Antoine Pitrou58ddc9d2013-01-05 21:20:29 +0100766 @property
767 def context(self):
768 return self._context
769
770 @context.setter
771 def context(self, ctx):
772 self._context = ctx
773 self._sslobj.context = ctx
Bill Janssen6e027db2007-11-15 22:23:56 +0000774
Guido van Rossumb7b030e2007-11-16 01:28:45 +0000775 def dup(self):
776 raise NotImplemented("Can't dup() %s instances" %
777 self.__class__.__name__)
778
Bill Janssen6e027db2007-11-15 22:23:56 +0000779 def _checkClosed(self, msg=None):
780 # raise an exception here if you wish to check for spurious closes
781 pass
782
Antoine Pitrou242db722013-05-01 20:52:07 +0200783 def _check_connected(self):
784 if not self._connected:
785 # getpeername() will raise ENOTCONN if the socket is really
786 # not connected; note that we can be connected even without
787 # _connected being set, e.g. if connect() first returned
788 # EAGAIN.
789 self.getpeername()
790
Martin Panterf6b1d662016-03-28 00:22:09 +0000791 def read(self, len=1024, buffer=None):
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000792 """Read up to LEN bytes and return them.
793 Return zero-length string on EOF."""
794
Bill Janssen6e027db2007-11-15 22:23:56 +0000795 self._checkClosed()
Antoine Pitrou60a26e02013-07-20 19:35:16 +0200796 if not self._sslobj:
797 raise ValueError("Read on closed or unwrapped SSL socket.")
Bill Janssen6e027db2007-11-15 22:23:56 +0000798 try:
Antoine Pitroub1fdf472014-10-05 20:41:53 +0200799 return self._sslobj.read(len, buffer)
Bill Janssen6e027db2007-11-15 22:23:56 +0000800 except SSLError as x:
801 if x.args[0] == SSL_ERROR_EOF and self.suppress_ragged_eofs:
Antoine Pitrou24e561a2010-09-03 18:38:17 +0000802 if buffer is not None:
Bill Janssen54cc54c2007-12-14 22:08:56 +0000803 return 0
804 else:
805 return b''
Bill Janssen6e027db2007-11-15 22:23:56 +0000806 else:
807 raise
Thomas Woutersed03b412007-08-28 21:37:11 +0000808
809 def write(self, data):
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000810 """Write DATA to the underlying SSL channel. Returns
811 number of bytes of DATA actually transmitted."""
812
Bill Janssen6e027db2007-11-15 22:23:56 +0000813 self._checkClosed()
Antoine Pitrou60a26e02013-07-20 19:35:16 +0200814 if not self._sslobj:
815 raise ValueError("Write on closed or unwrapped SSL socket.")
Thomas Woutersed03b412007-08-28 21:37:11 +0000816 return self._sslobj.write(data)
817
Thomas Wouters1b7f8912007-09-19 03:06:30 +0000818 def getpeercert(self, binary_form=False):
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000819 """Returns a formatted version of the data in the
820 certificate provided by the other end of the SSL channel.
821 Return None if no certificate was provided, {} if a
822 certificate was provided, but not validated."""
823
Bill Janssen6e027db2007-11-15 22:23:56 +0000824 self._checkClosed()
Antoine Pitrou242db722013-05-01 20:52:07 +0200825 self._check_connected()
Antoine Pitroub1fdf472014-10-05 20:41:53 +0200826 return self._sslobj.getpeercert(binary_form)
Thomas Wouters1b7f8912007-09-19 03:06:30 +0000827
Antoine Pitroud5d17eb2012-03-22 00:23:03 +0100828 def selected_npn_protocol(self):
829 self._checkClosed()
830 if not self._sslobj or not _ssl.HAS_NPN:
831 return None
832 else:
833 return self._sslobj.selected_npn_protocol()
834
Benjamin Petersoncca27322015-01-23 16:35:37 -0500835 def selected_alpn_protocol(self):
836 self._checkClosed()
837 if not self._sslobj or not _ssl.HAS_ALPN:
838 return None
839 else:
840 return self._sslobj.selected_alpn_protocol()
841
Guido van Rossum5b8b1552007-11-16 00:06:11 +0000842 def cipher(self):
Bill Janssen6e027db2007-11-15 22:23:56 +0000843 self._checkClosed()
Thomas Wouters1b7f8912007-09-19 03:06:30 +0000844 if not self._sslobj:
845 return None
846 else:
847 return self._sslobj.cipher()
Thomas Woutersed03b412007-08-28 21:37:11 +0000848
Benjamin Peterson4cb17812015-01-07 11:14:26 -0600849 def shared_ciphers(self):
850 self._checkClosed()
851 if not self._sslobj:
852 return None
853 return self._sslobj.shared_ciphers()
854
Antoine Pitrou8abdb8a2011-12-20 10:13:40 +0100855 def compression(self):
856 self._checkClosed()
857 if not self._sslobj:
858 return None
859 else:
860 return self._sslobj.compression()
861
Guido van Rossum5b8b1552007-11-16 00:06:11 +0000862 def send(self, data, flags=0):
Bill Janssen6e027db2007-11-15 22:23:56 +0000863 self._checkClosed()
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000864 if self._sslobj:
865 if flags != 0:
866 raise ValueError(
867 "non-zero flags not allowed in calls to send() on %s" %
868 self.__class__)
Antoine Pitroub4bebda2014-04-29 10:03:28 +0200869 return self._sslobj.write(data)
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000870 else:
871 return socket.send(self, data, flags)
Thomas Woutersed03b412007-08-28 21:37:11 +0000872
Antoine Pitroua468adc2010-09-14 14:43:44 +0000873 def sendto(self, data, flags_or_addr, addr=None):
Bill Janssen6e027db2007-11-15 22:23:56 +0000874 self._checkClosed()
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000875 if self._sslobj:
Bill Janssen980f3142008-06-29 00:05:51 +0000876 raise ValueError("sendto not allowed on instances of %s" %
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000877 self.__class__)
Antoine Pitroua468adc2010-09-14 14:43:44 +0000878 elif addr is None:
879 return socket.sendto(self, data, flags_or_addr)
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000880 else:
Antoine Pitroua468adc2010-09-14 14:43:44 +0000881 return socket.sendto(self, data, flags_or_addr, addr)
Thomas Woutersed03b412007-08-28 21:37:11 +0000882
Nick Coghlan513886a2011-08-28 00:00:27 +1000883 def sendmsg(self, *args, **kwargs):
884 # Ensure programs don't send data unencrypted if they try to
885 # use this method.
886 raise NotImplementedError("sendmsg not allowed on instances of %s" %
887 self.__class__)
888
Guido van Rossum5b8b1552007-11-16 00:06:11 +0000889 def sendall(self, data, flags=0):
Bill Janssen6e027db2007-11-15 22:23:56 +0000890 self._checkClosed()
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000891 if self._sslobj:
Giampaolo Rodolà374f8352010-08-29 12:08:09 +0000892 if flags != 0:
893 raise ValueError(
894 "non-zero flags not allowed in calls to sendall() on %s" %
895 self.__class__)
Bill Janssen6e027db2007-11-15 22:23:56 +0000896 amount = len(data)
897 count = 0
898 while (count < amount):
899 v = self.send(data[count:])
900 count += v
901 return amount
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000902 else:
903 return socket.sendall(self, data, flags)
Thomas Woutersed03b412007-08-28 21:37:11 +0000904
Giampaolo Rodola'915d1412014-06-11 03:54:30 +0200905 def sendfile(self, file, offset=0, count=None):
906 """Send a file, possibly by using os.sendfile() if this is a
907 clear-text socket. Return the total number of bytes sent.
908 """
909 if self._sslobj is None:
910 # os.sendfile() works with plain sockets only
911 return super().sendfile(file, offset, count)
912 else:
913 return self._sendfile_use_send(file, offset, count)
914
Guido van Rossum5b8b1552007-11-16 00:06:11 +0000915 def recv(self, buflen=1024, flags=0):
Bill Janssen6e027db2007-11-15 22:23:56 +0000916 self._checkClosed()
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000917 if self._sslobj:
918 if flags != 0:
919 raise ValueError(
Antoine Pitrou5733c082010-03-22 14:49:10 +0000920 "non-zero flags not allowed in calls to recv() on %s" %
921 self.__class__)
922 return self.read(buflen)
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000923 else:
924 return socket.recv(self, buflen, flags)
Thomas Woutersed03b412007-08-28 21:37:11 +0000925
Guido van Rossum5b8b1552007-11-16 00:06:11 +0000926 def recv_into(self, buffer, nbytes=None, flags=0):
Bill Janssen6e027db2007-11-15 22:23:56 +0000927 self._checkClosed()
928 if buffer and (nbytes is None):
929 nbytes = len(buffer)
930 elif nbytes is None:
931 nbytes = 1024
932 if self._sslobj:
933 if flags != 0:
934 raise ValueError(
Guido van Rossum5b8b1552007-11-16 00:06:11 +0000935 "non-zero flags not allowed in calls to recv_into() on %s" %
936 self.__class__)
Antoine Pitrou5733c082010-03-22 14:49:10 +0000937 return self.read(nbytes, buffer)
Bill Janssen6e027db2007-11-15 22:23:56 +0000938 else:
939 return socket.recv_into(self, buffer, nbytes, flags)
940
Antoine Pitroua468adc2010-09-14 14:43:44 +0000941 def recvfrom(self, buflen=1024, flags=0):
Bill Janssen6e027db2007-11-15 22:23:56 +0000942 self._checkClosed()
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000943 if self._sslobj:
Bill Janssen980f3142008-06-29 00:05:51 +0000944 raise ValueError("recvfrom not allowed on instances of %s" %
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000945 self.__class__)
946 else:
Antoine Pitroua468adc2010-09-14 14:43:44 +0000947 return socket.recvfrom(self, buflen, flags)
Thomas Woutersed03b412007-08-28 21:37:11 +0000948
Bill Janssen58afe4c2008-09-08 16:45:19 +0000949 def recvfrom_into(self, buffer, nbytes=None, flags=0):
950 self._checkClosed()
951 if self._sslobj:
952 raise ValueError("recvfrom_into not allowed on instances of %s" %
953 self.__class__)
954 else:
955 return socket.recvfrom_into(self, buffer, nbytes, flags)
956
Nick Coghlan513886a2011-08-28 00:00:27 +1000957 def recvmsg(self, *args, **kwargs):
958 raise NotImplementedError("recvmsg not allowed on instances of %s" %
959 self.__class__)
960
961 def recvmsg_into(self, *args, **kwargs):
962 raise NotImplementedError("recvmsg_into not allowed on instances of "
963 "%s" % self.__class__)
964
Guido van Rossum5b8b1552007-11-16 00:06:11 +0000965 def pending(self):
Bill Janssen6e027db2007-11-15 22:23:56 +0000966 self._checkClosed()
967 if self._sslobj:
968 return self._sslobj.pending()
969 else:
970 return 0
971
Guido van Rossum5b8b1552007-11-16 00:06:11 +0000972 def shutdown(self, how):
Bill Janssen6e027db2007-11-15 22:23:56 +0000973 self._checkClosed()
Thomas Wouters1b7f8912007-09-19 03:06:30 +0000974 self._sslobj = None
Thomas Wouters47b49bf2007-08-30 22:15:33 +0000975 socket.shutdown(self, how)
Thomas Woutersed03b412007-08-28 21:37:11 +0000976
Ezio Melottidc55e672010-01-18 09:15:14 +0000977 def unwrap(self):
Bill Janssen40a0f662008-08-12 16:56:25 +0000978 if self._sslobj:
Antoine Pitroub1fdf472014-10-05 20:41:53 +0200979 s = self._sslobj.unwrap()
Bill Janssen40a0f662008-08-12 16:56:25 +0000980 self._sslobj = None
981 return s
982 else:
983 raise ValueError("No SSL wrapper around " + str(self))
984
Guido van Rossum5b8b1552007-11-16 00:06:11 +0000985 def _real_close(self):
Thomas Wouters1b7f8912007-09-19 03:06:30 +0000986 self._sslobj = None
Bill Janssen54cc54c2007-12-14 22:08:56 +0000987 socket._real_close(self)
Bill Janssen6e027db2007-11-15 22:23:56 +0000988
Bill Janssen48dc27c2007-12-05 03:38:10 +0000989 def do_handshake(self, block=False):
Bill Janssen6e027db2007-11-15 22:23:56 +0000990 """Perform a TLS/SSL handshake."""
Antoine Pitrou242db722013-05-01 20:52:07 +0200991 self._check_connected()
Bill Janssen48dc27c2007-12-05 03:38:10 +0000992 timeout = self.gettimeout()
Bill Janssen6e027db2007-11-15 22:23:56 +0000993 try:
Bill Janssen48dc27c2007-12-05 03:38:10 +0000994 if timeout == 0.0 and block:
995 self.settimeout(None)
Bill Janssen6e027db2007-11-15 22:23:56 +0000996 self._sslobj.do_handshake()
Bill Janssen48dc27c2007-12-05 03:38:10 +0000997 finally:
998 self.settimeout(timeout)
Thomas Woutersed03b412007-08-28 21:37:11 +0000999
Antoine Pitroub4410db2011-05-18 18:51:06 +02001000 def _real_connect(self, addr, connect_ex):
Giampaolo Rodolà745ab382010-08-29 19:25:49 +00001001 if self.server_side:
1002 raise ValueError("can't connect in server-side mode")
Thomas Woutersed03b412007-08-28 21:37:11 +00001003 # Here we assume that the socket is client-side, and not
1004 # connected at the time of the call. We connect it, then wrap it.
Antoine Pitroue93bf7a2011-02-26 23:24:06 +00001005 if self._connected:
Thomas Wouters1b7f8912007-09-19 03:06:30 +00001006 raise ValueError("attempt to connect already-connected SSLSocket!")
Antoine Pitroub1fdf472014-10-05 20:41:53 +02001007 sslobj = self.context._wrap_socket(self, False, self.server_hostname)
1008 self._sslobj = SSLObject(sslobj, owner=self)
Bill Janssen54cc54c2007-12-14 22:08:56 +00001009 try:
Antoine Pitroub4410db2011-05-18 18:51:06 +02001010 if connect_ex:
1011 rc = socket.connect_ex(self, addr)
Antoine Pitroue93bf7a2011-02-26 23:24:06 +00001012 else:
Antoine Pitroub4410db2011-05-18 18:51:06 +02001013 rc = None
1014 socket.connect(self, addr)
1015 if not rc:
Antoine Pitrou242db722013-05-01 20:52:07 +02001016 self._connected = True
Antoine Pitroub4410db2011-05-18 18:51:06 +02001017 if self.do_handshake_on_connect:
1018 self.do_handshake()
Antoine Pitroub4410db2011-05-18 18:51:06 +02001019 return rc
Christian Heimes1aa9a752013-12-02 02:41:19 +01001020 except (OSError, ValueError):
Antoine Pitroub4410db2011-05-18 18:51:06 +02001021 self._sslobj = None
1022 raise
Antoine Pitroue93bf7a2011-02-26 23:24:06 +00001023
1024 def connect(self, addr):
1025 """Connects to remote ADDR, and then wraps the connection in
1026 an SSL channel."""
1027 self._real_connect(addr, False)
1028
1029 def connect_ex(self, addr):
1030 """Connects to remote ADDR, and then wraps the connection in
1031 an SSL channel."""
1032 return self._real_connect(addr, True)
Thomas Woutersed03b412007-08-28 21:37:11 +00001033
1034 def accept(self):
Thomas Wouters47b49bf2007-08-30 22:15:33 +00001035 """Accepts a new connection from a remote client, and returns
1036 a tuple containing that new connection wrapped with a server-side
1037 SSL channel, and the address of the remote client."""
1038
1039 newsock, addr = socket.accept(self)
Antoine Pitrou5c89b4e2012-11-11 01:25:36 +01001040 newsock = self.context.wrap_socket(newsock,
1041 do_handshake_on_connect=self.do_handshake_on_connect,
1042 suppress_ragged_eofs=self.suppress_ragged_eofs,
1043 server_side=True)
1044 return newsock, addr
Thomas Wouters1b7f8912007-09-19 03:06:30 +00001045
Antoine Pitroud6494802011-07-21 01:11:30 +02001046 def get_channel_binding(self, cb_type="tls-unique"):
1047 """Get channel binding data for current connection. Raise ValueError
1048 if the requested `cb_type` is not supported. Return bytes of the data
1049 or None if the data is not available (e.g. before the handshake).
1050 """
Antoine Pitroud6494802011-07-21 01:11:30 +02001051 if self._sslobj is None:
1052 return None
Antoine Pitroub1fdf472014-10-05 20:41:53 +02001053 return self._sslobj.get_channel_binding(cb_type)
Antoine Pitroud6494802011-07-21 01:11:30 +02001054
Antoine Pitrou47e40422014-09-04 21:00:10 +02001055 def version(self):
1056 """
1057 Return a string identifying the protocol version used by the
1058 current SSL channel, or None if there is no established channel.
1059 """
1060 if self._sslobj is None:
1061 return None
1062 return self._sslobj.version()
1063
Bill Janssen54cc54c2007-12-14 22:08:56 +00001064
Thomas Wouters1b7f8912007-09-19 03:06:30 +00001065def wrap_socket(sock, keyfile=None, certfile=None,
1066 server_side=False, cert_reqs=CERT_NONE,
Christian Heimes598894f2016-09-05 23:19:05 +02001067 ssl_version=PROTOCOL_TLS, ca_certs=None,
Bill Janssen48dc27c2007-12-05 03:38:10 +00001068 do_handshake_on_connect=True,
Antoine Pitroud5d17eb2012-03-22 00:23:03 +01001069 suppress_ragged_eofs=True,
1070 ciphers=None):
Thomas Wouters1b7f8912007-09-19 03:06:30 +00001071
Bill Janssen6e027db2007-11-15 22:23:56 +00001072 return SSLSocket(sock=sock, keyfile=keyfile, certfile=certfile,
Thomas Wouters1b7f8912007-09-19 03:06:30 +00001073 server_side=server_side, cert_reqs=cert_reqs,
Bill Janssen6e027db2007-11-15 22:23:56 +00001074 ssl_version=ssl_version, ca_certs=ca_certs,
Bill Janssen48dc27c2007-12-05 03:38:10 +00001075 do_handshake_on_connect=do_handshake_on_connect,
Antoine Pitrou2d9cb9c2010-04-17 17:40:45 +00001076 suppress_ragged_eofs=suppress_ragged_eofs,
1077 ciphers=ciphers)
Thomas Wouters1b7f8912007-09-19 03:06:30 +00001078
Thomas Woutersed03b412007-08-28 21:37:11 +00001079# some utility functions
1080
1081def cert_time_to_seconds(cert_time):
Antoine Pitrouc695c952014-04-28 20:57:36 +02001082 """Return the time in seconds since the Epoch, given the timestring
1083 representing the "notBefore" or "notAfter" date from a certificate
1084 in ``"%b %d %H:%M:%S %Y %Z"`` strptime format (C locale).
Thomas Wouters47b49bf2007-08-30 22:15:33 +00001085
Antoine Pitrouc695c952014-04-28 20:57:36 +02001086 "notBefore" or "notAfter" dates must use UTC (RFC 5280).
1087
1088 Month is one of: Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec
1089 UTC should be specified as GMT (see ASN1_TIME_print())
1090 """
1091 from time import strptime
1092 from calendar import timegm
1093
1094 months = (
1095 "Jan","Feb","Mar","Apr","May","Jun",
1096 "Jul","Aug","Sep","Oct","Nov","Dec"
1097 )
1098 time_format = ' %d %H:%M:%S %Y GMT' # NOTE: no month, fixed GMT
1099 try:
1100 month_number = months.index(cert_time[:3].title()) + 1
1101 except ValueError:
1102 raise ValueError('time data %r does not match '
1103 'format "%%b%s"' % (cert_time, time_format))
1104 else:
1105 # found valid month
1106 tt = strptime(cert_time[3:], time_format)
1107 # return an integer, the previous mktime()-based implementation
1108 # returned a float (fractional seconds are always zero here).
1109 return timegm((tt[0], month_number) + tt[2:6])
Thomas Woutersed03b412007-08-28 21:37:11 +00001110
Thomas Wouters1b7f8912007-09-19 03:06:30 +00001111PEM_HEADER = "-----BEGIN CERTIFICATE-----"
1112PEM_FOOTER = "-----END CERTIFICATE-----"
1113
1114def DER_cert_to_PEM_cert(der_cert_bytes):
Thomas Wouters1b7f8912007-09-19 03:06:30 +00001115 """Takes a certificate in binary DER format and returns the
1116 PEM version of it as a string."""
1117
Bill Janssen6e027db2007-11-15 22:23:56 +00001118 f = str(base64.standard_b64encode(der_cert_bytes), 'ASCII', 'strict')
1119 return (PEM_HEADER + '\n' +
1120 textwrap.fill(f, 64) + '\n' +
1121 PEM_FOOTER + '\n')
Thomas Wouters1b7f8912007-09-19 03:06:30 +00001122
1123def PEM_cert_to_DER_cert(pem_cert_string):
Thomas Wouters1b7f8912007-09-19 03:06:30 +00001124 """Takes a certificate in ASCII PEM format and returns the
1125 DER-encoded version of it as a byte sequence"""
1126
1127 if not pem_cert_string.startswith(PEM_HEADER):
1128 raise ValueError("Invalid PEM encoding; must start with %s"
1129 % PEM_HEADER)
1130 if not pem_cert_string.strip().endswith(PEM_FOOTER):
1131 raise ValueError("Invalid PEM encoding; must end with %s"
1132 % PEM_FOOTER)
1133 d = pem_cert_string.strip()[len(PEM_HEADER):-len(PEM_FOOTER)]
Georg Brandl706824f2009-06-04 09:42:55 +00001134 return base64.decodebytes(d.encode('ASCII', 'strict'))
Thomas Wouters1b7f8912007-09-19 03:06:30 +00001135
Christian Heimes598894f2016-09-05 23:19:05 +02001136def get_server_certificate(addr, ssl_version=PROTOCOL_TLS, ca_certs=None):
Thomas Wouters1b7f8912007-09-19 03:06:30 +00001137 """Retrieve the certificate from the server at the specified address,
1138 and return it as a PEM-encoded string.
1139 If 'ca_certs' is specified, validate the server cert against it.
1140 If 'ssl_version' is specified, use it in the connection attempt."""
1141
1142 host, port = addr
Christian Heimes67986f92013-11-23 22:43:47 +01001143 if ca_certs is not None:
Thomas Wouters1b7f8912007-09-19 03:06:30 +00001144 cert_reqs = CERT_REQUIRED
1145 else:
1146 cert_reqs = CERT_NONE
Christian Heimes67986f92013-11-23 22:43:47 +01001147 context = _create_stdlib_context(ssl_version,
1148 cert_reqs=cert_reqs,
1149 cafile=ca_certs)
1150 with create_connection(addr) as sock:
1151 with context.wrap_socket(sock) as sslsock:
1152 dercert = sslsock.getpeercert(True)
Thomas Wouters1b7f8912007-09-19 03:06:30 +00001153 return DER_cert_to_PEM_cert(dercert)
1154
Guido van Rossum5b8b1552007-11-16 00:06:11 +00001155def get_protocol_name(protocol_code):
Victor Stinner3de49192011-05-09 00:42:58 +02001156 return _PROTOCOL_NAMES.get(protocol_code, '<unknown>')