1import os 2import socket 3from sys import platform 4from functools import wraps, partial 5from itertools import count, chain 6from weakref import WeakValueDictionary 7from errno import errorcode 8 9from cryptography.utils import deprecated 10 11from six import ( 12 binary_type as _binary_type, integer_types as integer_types, int2byte, 13 indexbytes) 14 15from OpenSSL._util import ( 16 UNSPECIFIED as _UNSPECIFIED, 17 exception_from_error_queue as _exception_from_error_queue, 18 ffi as _ffi, 19 lib as _lib, 20 make_assert as _make_assert, 21 native as _native, 22 path_string as _path_string, 23 text_to_bytes_and_warn as _text_to_bytes_and_warn, 24 no_zero_allocator as _no_zero_allocator, 25) 26 27from OpenSSL.crypto import ( 28 FILETYPE_PEM, _PassphraseHelper, PKey, X509Name, X509, X509Store) 29 30__all__ = [ 31 'OPENSSL_VERSION_NUMBER', 32 'SSLEAY_VERSION', 33 'SSLEAY_CFLAGS', 34 'SSLEAY_PLATFORM', 35 'SSLEAY_DIR', 36 'SSLEAY_BUILT_ON', 37 'SENT_SHUTDOWN', 38 'RECEIVED_SHUTDOWN', 39 'SSLv2_METHOD', 40 'SSLv3_METHOD', 41 'SSLv23_METHOD', 42 'TLSv1_METHOD', 43 'TLSv1_1_METHOD', 44 'TLSv1_2_METHOD', 45 'OP_NO_SSLv2', 46 'OP_NO_SSLv3', 47 'OP_NO_TLSv1', 48 'OP_NO_TLSv1_1', 49 'OP_NO_TLSv1_2', 50 'MODE_RELEASE_BUFFERS', 51 'OP_SINGLE_DH_USE', 52 'OP_SINGLE_ECDH_USE', 53 'OP_EPHEMERAL_RSA', 54 'OP_MICROSOFT_SESS_ID_BUG', 55 'OP_NETSCAPE_CHALLENGE_BUG', 56 'OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG', 57 'OP_SSLREF2_REUSE_CERT_TYPE_BUG', 58 'OP_MICROSOFT_BIG_SSLV3_BUFFER', 59 'OP_MSIE_SSLV2_RSA_PADDING', 60 'OP_SSLEAY_080_CLIENT_DH_BUG', 61 'OP_TLS_D5_BUG', 62 'OP_TLS_BLOCK_PADDING_BUG', 63 'OP_DONT_INSERT_EMPTY_FRAGMENTS', 64 'OP_CIPHER_SERVER_PREFERENCE', 65 'OP_TLS_ROLLBACK_BUG', 66 'OP_PKCS1_CHECK_1', 67 'OP_PKCS1_CHECK_2', 68 'OP_NETSCAPE_CA_DN_BUG', 69 'OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG', 70 'OP_NO_COMPRESSION', 71 'OP_NO_QUERY_MTU', 72 'OP_COOKIE_EXCHANGE', 73 'OP_NO_TICKET', 74 'OP_ALL', 75 'VERIFY_PEER', 76 'VERIFY_FAIL_IF_NO_PEER_CERT', 77 'VERIFY_CLIENT_ONCE', 78 'VERIFY_NONE', 79 'SESS_CACHE_OFF', 80 'SESS_CACHE_CLIENT', 81 'SESS_CACHE_SERVER', 82 'SESS_CACHE_BOTH', 83 'SESS_CACHE_NO_AUTO_CLEAR', 84 'SESS_CACHE_NO_INTERNAL_LOOKUP', 85 'SESS_CACHE_NO_INTERNAL_STORE', 86 'SESS_CACHE_NO_INTERNAL', 87 'SSL_ST_CONNECT', 88 'SSL_ST_ACCEPT', 89 'SSL_ST_MASK', 90 'SSL_CB_LOOP', 91 'SSL_CB_EXIT', 92 'SSL_CB_READ', 93 'SSL_CB_WRITE', 94 'SSL_CB_ALERT', 95 'SSL_CB_READ_ALERT', 96 'SSL_CB_WRITE_ALERT', 97 'SSL_CB_ACCEPT_LOOP', 98 'SSL_CB_ACCEPT_EXIT', 99 'SSL_CB_CONNECT_LOOP', 100 'SSL_CB_CONNECT_EXIT', 101 'SSL_CB_HANDSHAKE_START', 102 'SSL_CB_HANDSHAKE_DONE', 103 'Error', 104 'WantReadError', 105 'WantWriteError', 106 'WantX509LookupError', 107 'ZeroReturnError', 108 'SysCallError', 109 'SSLeay_version', 110 'Session', 111 'Context', 112 'Connection' 113] 114 115try: 116 _buffer = buffer 117except NameError: 118 class _buffer(object): 119 pass 120 121OPENSSL_VERSION_NUMBER = _lib.OPENSSL_VERSION_NUMBER 122SSLEAY_VERSION = _lib.SSLEAY_VERSION 123SSLEAY_CFLAGS = _lib.SSLEAY_CFLAGS 124SSLEAY_PLATFORM = _lib.SSLEAY_PLATFORM 125SSLEAY_DIR = _lib.SSLEAY_DIR 126SSLEAY_BUILT_ON = _lib.SSLEAY_BUILT_ON 127 128SENT_SHUTDOWN = _lib.SSL_SENT_SHUTDOWN 129RECEIVED_SHUTDOWN = _lib.SSL_RECEIVED_SHUTDOWN 130 131SSLv2_METHOD = 1 132SSLv3_METHOD = 2 133SSLv23_METHOD = 3 134TLSv1_METHOD = 4 135TLSv1_1_METHOD = 5 136TLSv1_2_METHOD = 6 137 138OP_NO_SSLv2 = _lib.SSL_OP_NO_SSLv2 139OP_NO_SSLv3 = _lib.SSL_OP_NO_SSLv3 140OP_NO_TLSv1 = _lib.SSL_OP_NO_TLSv1 141OP_NO_TLSv1_1 = _lib.SSL_OP_NO_TLSv1_1 142OP_NO_TLSv1_2 = _lib.SSL_OP_NO_TLSv1_2 143 144MODE_RELEASE_BUFFERS = _lib.SSL_MODE_RELEASE_BUFFERS 145 146OP_SINGLE_DH_USE = _lib.SSL_OP_SINGLE_DH_USE 147OP_SINGLE_ECDH_USE = _lib.SSL_OP_SINGLE_ECDH_USE 148OP_EPHEMERAL_RSA = _lib.SSL_OP_EPHEMERAL_RSA 149OP_MICROSOFT_SESS_ID_BUG = _lib.SSL_OP_MICROSOFT_SESS_ID_BUG 150OP_NETSCAPE_CHALLENGE_BUG = _lib.SSL_OP_NETSCAPE_CHALLENGE_BUG 151OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG = ( 152 _lib.SSL_OP_NETSCAPE_REUSE_CIPHER_CHANGE_BUG 153) 154OP_SSLREF2_REUSE_CERT_TYPE_BUG = _lib.SSL_OP_SSLREF2_REUSE_CERT_TYPE_BUG 155OP_MICROSOFT_BIG_SSLV3_BUFFER = _lib.SSL_OP_MICROSOFT_BIG_SSLV3_BUFFER 156OP_MSIE_SSLV2_RSA_PADDING = _lib.SSL_OP_MSIE_SSLV2_RSA_PADDING 157OP_SSLEAY_080_CLIENT_DH_BUG = _lib.SSL_OP_SSLEAY_080_CLIENT_DH_BUG 158OP_TLS_D5_BUG = _lib.SSL_OP_TLS_D5_BUG 159OP_TLS_BLOCK_PADDING_BUG = _lib.SSL_OP_TLS_BLOCK_PADDING_BUG 160OP_DONT_INSERT_EMPTY_FRAGMENTS = _lib.SSL_OP_DONT_INSERT_EMPTY_FRAGMENTS 161OP_CIPHER_SERVER_PREFERENCE = _lib.SSL_OP_CIPHER_SERVER_PREFERENCE 162OP_TLS_ROLLBACK_BUG = _lib.SSL_OP_TLS_ROLLBACK_BUG 163OP_PKCS1_CHECK_1 = _lib.SSL_OP_PKCS1_CHECK_1 164OP_PKCS1_CHECK_2 = _lib.SSL_OP_PKCS1_CHECK_2 165OP_NETSCAPE_CA_DN_BUG = _lib.SSL_OP_NETSCAPE_CA_DN_BUG 166OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG = ( 167 _lib.SSL_OP_NETSCAPE_DEMO_CIPHER_CHANGE_BUG 168) 169OP_NO_COMPRESSION = _lib.SSL_OP_NO_COMPRESSION 170 171OP_NO_QUERY_MTU = _lib.SSL_OP_NO_QUERY_MTU 172OP_COOKIE_EXCHANGE = _lib.SSL_OP_COOKIE_EXCHANGE 173OP_NO_TICKET = _lib.SSL_OP_NO_TICKET 174 175OP_ALL = _lib.SSL_OP_ALL 176 177VERIFY_PEER = _lib.SSL_VERIFY_PEER 178VERIFY_FAIL_IF_NO_PEER_CERT = _lib.SSL_VERIFY_FAIL_IF_NO_PEER_CERT 179VERIFY_CLIENT_ONCE = _lib.SSL_VERIFY_CLIENT_ONCE 180VERIFY_NONE = _lib.SSL_VERIFY_NONE 181 182SESS_CACHE_OFF = _lib.SSL_SESS_CACHE_OFF 183SESS_CACHE_CLIENT = _lib.SSL_SESS_CACHE_CLIENT 184SESS_CACHE_SERVER = _lib.SSL_SESS_CACHE_SERVER 185SESS_CACHE_BOTH = _lib.SSL_SESS_CACHE_BOTH 186SESS_CACHE_NO_AUTO_CLEAR = _lib.SSL_SESS_CACHE_NO_AUTO_CLEAR 187SESS_CACHE_NO_INTERNAL_LOOKUP = _lib.SSL_SESS_CACHE_NO_INTERNAL_LOOKUP 188SESS_CACHE_NO_INTERNAL_STORE = _lib.SSL_SESS_CACHE_NO_INTERNAL_STORE 189SESS_CACHE_NO_INTERNAL = _lib.SSL_SESS_CACHE_NO_INTERNAL 190 191SSL_ST_CONNECT = _lib.SSL_ST_CONNECT 192SSL_ST_ACCEPT = _lib.SSL_ST_ACCEPT 193SSL_ST_MASK = _lib.SSL_ST_MASK 194if _lib.Cryptography_HAS_SSL_ST: 195 SSL_ST_INIT = _lib.SSL_ST_INIT 196 SSL_ST_BEFORE = _lib.SSL_ST_BEFORE 197 SSL_ST_OK = _lib.SSL_ST_OK 198 SSL_ST_RENEGOTIATE = _lib.SSL_ST_RENEGOTIATE 199 __all__.extend([ 200 'SSL_ST_INIT', 201 'SSL_ST_BEFORE', 202 'SSL_ST_OK', 203 'SSL_ST_RENEGOTIATE', 204 ]) 205 206SSL_CB_LOOP = _lib.SSL_CB_LOOP 207SSL_CB_EXIT = _lib.SSL_CB_EXIT 208SSL_CB_READ = _lib.SSL_CB_READ 209SSL_CB_WRITE = _lib.SSL_CB_WRITE 210SSL_CB_ALERT = _lib.SSL_CB_ALERT 211SSL_CB_READ_ALERT = _lib.SSL_CB_READ_ALERT 212SSL_CB_WRITE_ALERT = _lib.SSL_CB_WRITE_ALERT 213SSL_CB_ACCEPT_LOOP = _lib.SSL_CB_ACCEPT_LOOP 214SSL_CB_ACCEPT_EXIT = _lib.SSL_CB_ACCEPT_EXIT 215SSL_CB_CONNECT_LOOP = _lib.SSL_CB_CONNECT_LOOP 216SSL_CB_CONNECT_EXIT = _lib.SSL_CB_CONNECT_EXIT 217SSL_CB_HANDSHAKE_START = _lib.SSL_CB_HANDSHAKE_START 218SSL_CB_HANDSHAKE_DONE = _lib.SSL_CB_HANDSHAKE_DONE 219 220# Taken from https://golang.org/src/crypto/x509/root_linux.go 221_CERTIFICATE_FILE_LOCATIONS = [ 222 "/etc/ssl/certs/ca-certificates.crt", # Debian/Ubuntu/Gentoo etc. 223 "/etc/pki/tls/certs/ca-bundle.crt", # Fedora/RHEL 6 224 "/etc/ssl/ca-bundle.pem", # OpenSUSE 225 "/etc/pki/tls/cacert.pem", # OpenELEC 226 "/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem", # CentOS/RHEL 7 227] 228 229_CERTIFICATE_PATH_LOCATIONS = [ 230 "/etc/ssl/certs", # SLES10/SLES11 231] 232 233# These values are compared to output from cffi's ffi.string so they must be 234# byte strings. 235_CRYPTOGRAPHY_MANYLINUX1_CA_DIR = b"/opt/pyca/cryptography/openssl/certs" 236_CRYPTOGRAPHY_MANYLINUX1_CA_FILE = b"/opt/pyca/cryptography/openssl/cert.pem" 237 238 239class Error(Exception): 240 """ 241 An error occurred in an `OpenSSL.SSL` API. 242 """ 243 244 245_raise_current_error = partial(_exception_from_error_queue, Error) 246_openssl_assert = _make_assert(Error) 247 248 249class WantReadError(Error): 250 pass 251 252 253class WantWriteError(Error): 254 pass 255 256 257class WantX509LookupError(Error): 258 pass 259 260 261class ZeroReturnError(Error): 262 pass 263 264 265class SysCallError(Error): 266 pass 267 268 269class _CallbackExceptionHelper(object): 270 """ 271 A base class for wrapper classes that allow for intelligent exception 272 handling in OpenSSL callbacks. 273 274 :ivar list _problems: Any exceptions that occurred while executing in a 275 context where they could not be raised in the normal way. Typically 276 this is because OpenSSL has called into some Python code and requires a 277 return value. The exceptions are saved to be raised later when it is 278 possible to do so. 279 """ 280 281 def __init__(self): 282 self._problems = [] 283 284 def raise_if_problem(self): 285 """ 286 Raise an exception from the OpenSSL error queue or that was previously 287 captured whe running a callback. 288 """ 289 if self._problems: 290 try: 291 _raise_current_error() 292 except Error: 293 pass 294 raise self._problems.pop(0) 295 296 297class _VerifyHelper(_CallbackExceptionHelper): 298 """ 299 Wrap a callback such that it can be used as a certificate verification 300 callback. 301 """ 302 303 def __init__(self, callback): 304 _CallbackExceptionHelper.__init__(self) 305 306 @wraps(callback) 307 def wrapper(ok, store_ctx): 308 x509 = _lib.X509_STORE_CTX_get_current_cert(store_ctx) 309 _lib.X509_up_ref(x509) 310 cert = X509._from_raw_x509_ptr(x509) 311 error_number = _lib.X509_STORE_CTX_get_error(store_ctx) 312 error_depth = _lib.X509_STORE_CTX_get_error_depth(store_ctx) 313 314 index = _lib.SSL_get_ex_data_X509_STORE_CTX_idx() 315 ssl = _lib.X509_STORE_CTX_get_ex_data(store_ctx, index) 316 connection = Connection._reverse_mapping[ssl] 317 318 try: 319 result = callback( 320 connection, cert, error_number, error_depth, ok 321 ) 322 except Exception as e: 323 self._problems.append(e) 324 return 0 325 else: 326 if result: 327 _lib.X509_STORE_CTX_set_error(store_ctx, _lib.X509_V_OK) 328 return 1 329 else: 330 return 0 331 332 self.callback = _ffi.callback( 333 "int (*)(int, X509_STORE_CTX *)", wrapper) 334 335 336class _NpnAdvertiseHelper(_CallbackExceptionHelper): 337 """ 338 Wrap a callback such that it can be used as an NPN advertisement callback. 339 """ 340 341 def __init__(self, callback): 342 _CallbackExceptionHelper.__init__(self) 343 344 @wraps(callback) 345 def wrapper(ssl, out, outlen, arg): 346 try: 347 conn = Connection._reverse_mapping[ssl] 348 protos = callback(conn) 349 350 # Join the protocols into a Python bytestring, length-prefixing 351 # each element. 352 protostr = b''.join( 353 chain.from_iterable((int2byte(len(p)), p) for p in protos) 354 ) 355 356 # Save our callback arguments on the connection object. This is 357 # done to make sure that they don't get freed before OpenSSL 358 # uses them. Then, return them appropriately in the output 359 # parameters. 360 conn._npn_advertise_callback_args = [ 361 _ffi.new("unsigned int *", len(protostr)), 362 _ffi.new("unsigned char[]", protostr), 363 ] 364 outlen[0] = conn._npn_advertise_callback_args[0][0] 365 out[0] = conn._npn_advertise_callback_args[1] 366 return 0 367 except Exception as e: 368 self._problems.append(e) 369 return 2 # SSL_TLSEXT_ERR_ALERT_FATAL 370 371 self.callback = _ffi.callback( 372 "int (*)(SSL *, const unsigned char **, unsigned int *, void *)", 373 wrapper 374 ) 375 376 377class _NpnSelectHelper(_CallbackExceptionHelper): 378 """ 379 Wrap a callback such that it can be used as an NPN selection callback. 380 """ 381 382 def __init__(self, callback): 383 _CallbackExceptionHelper.__init__(self) 384 385 @wraps(callback) 386 def wrapper(ssl, out, outlen, in_, inlen, arg): 387 try: 388 conn = Connection._reverse_mapping[ssl] 389 390 # The string passed to us is actually made up of multiple 391 # length-prefixed bytestrings. We need to split that into a 392 # list. 393 instr = _ffi.buffer(in_, inlen)[:] 394 protolist = [] 395 while instr: 396 length = indexbytes(instr, 0) 397 proto = instr[1:length + 1] 398 protolist.append(proto) 399 instr = instr[length + 1:] 400 401 # Call the callback 402 outstr = callback(conn, protolist) 403 404 # Save our callback arguments on the connection object. This is 405 # done to make sure that they don't get freed before OpenSSL 406 # uses them. Then, return them appropriately in the output 407 # parameters. 408 conn._npn_select_callback_args = [ 409 _ffi.new("unsigned char *", len(outstr)), 410 _ffi.new("unsigned char[]", outstr), 411 ] 412 outlen[0] = conn._npn_select_callback_args[0][0] 413 out[0] = conn._npn_select_callback_args[1] 414 return 0 415 except Exception as e: 416 self._problems.append(e) 417 return 2 # SSL_TLSEXT_ERR_ALERT_FATAL 418 419 self.callback = _ffi.callback( 420 ("int (*)(SSL *, unsigned char **, unsigned char *, " 421 "const unsigned char *, unsigned int, void *)"), 422 wrapper 423 ) 424 425 426class _ALPNSelectHelper(_CallbackExceptionHelper): 427 """ 428 Wrap a callback such that it can be used as an ALPN selection callback. 429 """ 430 431 def __init__(self, callback): 432 _CallbackExceptionHelper.__init__(self) 433 434 @wraps(callback) 435 def wrapper(ssl, out, outlen, in_, inlen, arg): 436 try: 437 conn = Connection._reverse_mapping[ssl] 438 439 # The string passed to us is made up of multiple 440 # length-prefixed bytestrings. We need to split that into a 441 # list. 442 instr = _ffi.buffer(in_, inlen)[:] 443 protolist = [] 444 while instr: 445 encoded_len = indexbytes(instr, 0) 446 proto = instr[1:encoded_len + 1] 447 protolist.append(proto) 448 instr = instr[encoded_len + 1:] 449 450 # Call the callback 451 outstr = callback(conn, protolist) 452 453 if not isinstance(outstr, _binary_type): 454 raise TypeError("ALPN callback must return a bytestring.") 455 456 # Save our callback arguments on the connection object to make 457 # sure that they don't get freed before OpenSSL can use them. 458 # Then, return them in the appropriate output parameters. 459 conn._alpn_select_callback_args = [ 460 _ffi.new("unsigned char *", len(outstr)), 461 _ffi.new("unsigned char[]", outstr), 462 ] 463 outlen[0] = conn._alpn_select_callback_args[0][0] 464 out[0] = conn._alpn_select_callback_args[1] 465 return 0 466 except Exception as e: 467 self._problems.append(e) 468 return 2 # SSL_TLSEXT_ERR_ALERT_FATAL 469 470 self.callback = _ffi.callback( 471 ("int (*)(SSL *, unsigned char **, unsigned char *, " 472 "const unsigned char *, unsigned int, void *)"), 473 wrapper 474 ) 475 476 477class _OCSPServerCallbackHelper(_CallbackExceptionHelper): 478 """ 479 Wrap a callback such that it can be used as an OCSP callback for the server 480 side. 481 482 Annoyingly, OpenSSL defines one OCSP callback but uses it in two different 483 ways. For servers, that callback is expected to retrieve some OCSP data and 484 hand it to OpenSSL, and may return only SSL_TLSEXT_ERR_OK, 485 SSL_TLSEXT_ERR_FATAL, and SSL_TLSEXT_ERR_NOACK. For clients, that callback 486 is expected to check the OCSP data, and returns a negative value on error, 487 0 if the response is not acceptable, or positive if it is. These are 488 mutually exclusive return code behaviours, and they mean that we need two 489 helpers so that we always return an appropriate error code if the user's 490 code throws an exception. 491 492 Given that we have to have two helpers anyway, these helpers are a bit more 493 helpery than most: specifically, they hide a few more of the OpenSSL 494 functions so that the user has an easier time writing these callbacks. 495 496 This helper implements the server side. 497 """ 498 499 def __init__(self, callback): 500 _CallbackExceptionHelper.__init__(self) 501 502 @wraps(callback) 503 def wrapper(ssl, cdata): 504 try: 505 conn = Connection._reverse_mapping[ssl] 506 507 # Extract the data if any was provided. 508 if cdata != _ffi.NULL: 509 data = _ffi.from_handle(cdata) 510 else: 511 data = None 512 513 # Call the callback. 514 ocsp_data = callback(conn, data) 515 516 if not isinstance(ocsp_data, _binary_type): 517 raise TypeError("OCSP callback must return a bytestring.") 518 519 # If the OCSP data was provided, we will pass it to OpenSSL. 520 # However, we have an early exit here: if no OCSP data was 521 # provided we will just exit out and tell OpenSSL that there 522 # is nothing to do. 523 if not ocsp_data: 524 return 3 # SSL_TLSEXT_ERR_NOACK 525 526 # OpenSSL takes ownership of this data and expects it to have 527 # been allocated by OPENSSL_malloc. 528 ocsp_data_length = len(ocsp_data) 529 data_ptr = _lib.OPENSSL_malloc(ocsp_data_length) 530 _ffi.buffer(data_ptr, ocsp_data_length)[:] = ocsp_data 531 532 _lib.SSL_set_tlsext_status_ocsp_resp( 533 ssl, data_ptr, ocsp_data_length 534 ) 535 536 return 0 537 except Exception as e: 538 self._problems.append(e) 539 return 2 # SSL_TLSEXT_ERR_ALERT_FATAL 540 541 self.callback = _ffi.callback("int (*)(SSL *, void *)", wrapper) 542 543 544class _OCSPClientCallbackHelper(_CallbackExceptionHelper): 545 """ 546 Wrap a callback such that it can be used as an OCSP callback for the client 547 side. 548 549 Annoyingly, OpenSSL defines one OCSP callback but uses it in two different 550 ways. For servers, that callback is expected to retrieve some OCSP data and 551 hand it to OpenSSL, and may return only SSL_TLSEXT_ERR_OK, 552 SSL_TLSEXT_ERR_FATAL, and SSL_TLSEXT_ERR_NOACK. For clients, that callback 553 is expected to check the OCSP data, and returns a negative value on error, 554 0 if the response is not acceptable, or positive if it is. These are 555 mutually exclusive return code behaviours, and they mean that we need two 556 helpers so that we always return an appropriate error code if the user's 557 code throws an exception. 558 559 Given that we have to have two helpers anyway, these helpers are a bit more 560 helpery than most: specifically, they hide a few more of the OpenSSL 561 functions so that the user has an easier time writing these callbacks. 562 563 This helper implements the client side. 564 """ 565 566 def __init__(self, callback): 567 _CallbackExceptionHelper.__init__(self) 568 569 @wraps(callback) 570 def wrapper(ssl, cdata): 571 try: 572 conn = Connection._reverse_mapping[ssl] 573 574 # Extract the data if any was provided. 575 if cdata != _ffi.NULL: 576 data = _ffi.from_handle(cdata) 577 else: 578 data = None 579 580 # Get the OCSP data. 581 ocsp_ptr = _ffi.new("unsigned char **") 582 ocsp_len = _lib.SSL_get_tlsext_status_ocsp_resp(ssl, ocsp_ptr) 583 if ocsp_len < 0: 584 # No OCSP data. 585 ocsp_data = b'' 586 else: 587 # Copy the OCSP data, then pass it to the callback. 588 ocsp_data = _ffi.buffer(ocsp_ptr[0], ocsp_len)[:] 589 590 valid = callback(conn, ocsp_data, data) 591 592 # Return 1 on success or 0 on error. 593 return int(bool(valid)) 594 595 except Exception as e: 596 self._problems.append(e) 597 # Return negative value if an exception is hit. 598 return -1 599 600 self.callback = _ffi.callback("int (*)(SSL *, void *)", wrapper) 601 602 603def _asFileDescriptor(obj): 604 fd = None 605 if not isinstance(obj, integer_types): 606 meth = getattr(obj, "fileno", None) 607 if meth is not None: 608 obj = meth() 609 610 if isinstance(obj, integer_types): 611 fd = obj 612 613 if not isinstance(fd, integer_types): 614 raise TypeError("argument must be an int, or have a fileno() method.") 615 elif fd < 0: 616 raise ValueError( 617 "file descriptor cannot be a negative integer (%i)" % (fd,)) 618 619 return fd 620 621 622def SSLeay_version(type): 623 """ 624 Return a string describing the version of OpenSSL in use. 625 626 :param type: One of the :const:`SSLEAY_` constants defined in this module. 627 """ 628 return _ffi.string(_lib.SSLeay_version(type)) 629 630 631def _make_requires(flag, error): 632 """ 633 Builds a decorator that ensures that functions that rely on OpenSSL 634 functions that are not present in this build raise NotImplementedError, 635 rather than AttributeError coming out of cryptography. 636 637 :param flag: A cryptography flag that guards the functions, e.g. 638 ``Cryptography_HAS_NEXTPROTONEG``. 639 :param error: The string to be used in the exception if the flag is false. 640 """ 641 def _requires_decorator(func): 642 if not flag: 643 @wraps(func) 644 def explode(*args, **kwargs): 645 raise NotImplementedError(error) 646 return explode 647 else: 648 return func 649 650 return _requires_decorator 651 652 653_requires_npn = _make_requires( 654 _lib.Cryptography_HAS_NEXTPROTONEG, "NPN not available" 655) 656 657 658_requires_alpn = _make_requires( 659 _lib.Cryptography_HAS_ALPN, "ALPN not available" 660) 661 662 663_requires_sni = _make_requires( 664 _lib.Cryptography_HAS_TLSEXT_HOSTNAME, "SNI not available" 665) 666 667 668class Session(object): 669 """ 670 A class representing an SSL session. A session defines certain connection 671 parameters which may be re-used to speed up the setup of subsequent 672 connections. 673 674 .. versionadded:: 0.14 675 """ 676 pass 677 678 679class Context(object): 680 """ 681 :class:`OpenSSL.SSL.Context` instances define the parameters for setting 682 up new SSL connections. 683 684 :param method: One of SSLv2_METHOD, SSLv3_METHOD, SSLv23_METHOD, or 685 TLSv1_METHOD. 686 """ 687 _methods = { 688 SSLv2_METHOD: "SSLv2_method", 689 SSLv3_METHOD: "SSLv3_method", 690 SSLv23_METHOD: "SSLv23_method", 691 TLSv1_METHOD: "TLSv1_method", 692 TLSv1_1_METHOD: "TLSv1_1_method", 693 TLSv1_2_METHOD: "TLSv1_2_method", 694 } 695 _methods = dict( 696 (identifier, getattr(_lib, name)) 697 for (identifier, name) in _methods.items() 698 if getattr(_lib, name, None) is not None) 699 700 def __init__(self, method): 701 if not isinstance(method, integer_types): 702 raise TypeError("method must be an integer") 703 704 try: 705 method_func = self._methods[method] 706 except KeyError: 707 raise ValueError("No such protocol") 708 709 method_obj = method_func() 710 _openssl_assert(method_obj != _ffi.NULL) 711 712 context = _lib.SSL_CTX_new(method_obj) 713 _openssl_assert(context != _ffi.NULL) 714 context = _ffi.gc(context, _lib.SSL_CTX_free) 715 716 # If SSL_CTX_set_ecdh_auto is available then set it so the ECDH curve 717 # will be auto-selected. This function was added in 1.0.2 and made a 718 # noop in 1.1.0+ (where it is set automatically). 719 try: 720 res = _lib.SSL_CTX_set_ecdh_auto(context, 1) 721 _openssl_assert(res == 1) 722 except AttributeError: 723 pass 724 725 self._context = context 726 self._passphrase_helper = None 727 self._passphrase_callback = None 728 self._passphrase_userdata = None 729 self._verify_helper = None 730 self._verify_callback = None 731 self._info_callback = None 732 self._tlsext_servername_callback = None 733 self._app_data = None 734 self._npn_advertise_helper = None 735 self._npn_advertise_callback = None 736 self._npn_select_helper = None 737 self._npn_select_callback = None 738 self._alpn_select_helper = None 739 self._alpn_select_callback = None 740 self._ocsp_helper = None 741 self._ocsp_callback = None 742 self._ocsp_data = None 743 744 self.set_mode(_lib.SSL_MODE_ENABLE_PARTIAL_WRITE) 745 746 def load_verify_locations(self, cafile, capath=None): 747 """ 748 Let SSL know where we can find trusted certificates for the certificate 749 chain. Note that the certificates have to be in PEM format. 750 751 If capath is passed, it must be a directory prepared using the 752 ``c_rehash`` tool included with OpenSSL. Either, but not both, of 753 *pemfile* or *capath* may be :data:`None`. 754 755 :param cafile: In which file we can find the certificates (``bytes`` or 756 ``unicode``). 757 :param capath: In which directory we can find the certificates 758 (``bytes`` or ``unicode``). 759 760 :return: None 761 """ 762 if cafile is None: 763 cafile = _ffi.NULL 764 else: 765 cafile = _path_string(cafile) 766 767 if capath is None: 768 capath = _ffi.NULL 769 else: 770 capath = _path_string(capath) 771 772 load_result = _lib.SSL_CTX_load_verify_locations( 773 self._context, cafile, capath 774 ) 775 if not load_result: 776 _raise_current_error() 777 778 def _wrap_callback(self, callback): 779 @wraps(callback) 780 def wrapper(size, verify, userdata): 781 return callback(size, verify, self._passphrase_userdata) 782 return _PassphraseHelper( 783 FILETYPE_PEM, wrapper, more_args=True, truncate=True) 784 785 def set_passwd_cb(self, callback, userdata=None): 786 """ 787 Set the passphrase callback. This function will be called 788 when a private key with a passphrase is loaded. 789 790 :param callback: The Python callback to use. This must accept three 791 positional arguments. First, an integer giving the maximum length 792 of the passphrase it may return. If the returned passphrase is 793 longer than this, it will be truncated. Second, a boolean value 794 which will be true if the user should be prompted for the 795 passphrase twice and the callback should verify that the two values 796 supplied are equal. Third, the value given as the *userdata* 797 parameter to :meth:`set_passwd_cb`. The *callback* must return 798 a byte string. If an error occurs, *callback* should return a false 799 value (e.g. an empty string). 800 :param userdata: (optional) A Python object which will be given as 801 argument to the callback 802 :return: None 803 """ 804 if not callable(callback): 805 raise TypeError("callback must be callable") 806 807 self._passphrase_helper = self._wrap_callback(callback) 808 self._passphrase_callback = self._passphrase_helper.callback 809 _lib.SSL_CTX_set_default_passwd_cb( 810 self._context, self._passphrase_callback) 811 self._passphrase_userdata = userdata 812 813 def set_default_verify_paths(self): 814 """ 815 Specify that the platform provided CA certificates are to be used for 816 verification purposes. This method has some caveats related to the 817 binary wheels that cryptography (pyOpenSSL's primary dependency) ships: 818 819 * macOS will only load certificates using this method if the user has 820 the ``openssl@1.1`` `Homebrew <https://brew.sh>`_ formula installed 821 in the default location. 822 * Windows will not work. 823 * manylinux1 cryptography wheels will work on most common Linux 824 distributions in pyOpenSSL 17.1.0 and above. pyOpenSSL detects the 825 manylinux1 wheel and attempts to load roots via a fallback path. 826 827 :return: None 828 """ 829 # SSL_CTX_set_default_verify_paths will attempt to load certs from 830 # both a cafile and capath that are set at compile time. However, 831 # it will first check environment variables and, if present, load 832 # those paths instead 833 set_result = _lib.SSL_CTX_set_default_verify_paths(self._context) 834 _openssl_assert(set_result == 1) 835 # After attempting to set default_verify_paths we need to know whether 836 # to go down the fallback path. 837 # First we'll check to see if any env vars have been set. If so, 838 # we won't try to do anything else because the user has set the path 839 # themselves. 840 dir_env_var = _ffi.string( 841 _lib.X509_get_default_cert_dir_env() 842 ).decode("ascii") 843 file_env_var = _ffi.string( 844 _lib.X509_get_default_cert_file_env() 845 ).decode("ascii") 846 if not self._check_env_vars_set(dir_env_var, file_env_var): 847 default_dir = _ffi.string(_lib.X509_get_default_cert_dir()) 848 default_file = _ffi.string(_lib.X509_get_default_cert_file()) 849 # Now we check to see if the default_dir and default_file are set 850 # to the exact values we use in our manylinux1 builds. If they are 851 # then we know to load the fallbacks 852 if ( 853 default_dir == _CRYPTOGRAPHY_MANYLINUX1_CA_DIR and 854 default_file == _CRYPTOGRAPHY_MANYLINUX1_CA_FILE 855 ): 856 # This is manylinux1, let's load our fallback paths 857 self._fallback_default_verify_paths( 858 _CERTIFICATE_FILE_LOCATIONS, 859 _CERTIFICATE_PATH_LOCATIONS 860 ) 861 862 def _check_env_vars_set(self, dir_env_var, file_env_var): 863 """ 864 Check to see if the default cert dir/file environment vars are present. 865 866 :return: bool 867 """ 868 return ( 869 os.environ.get(file_env_var) is not None or 870 os.environ.get(dir_env_var) is not None 871 ) 872 873 def _fallback_default_verify_paths(self, file_path, dir_path): 874 """ 875 Default verify paths are based on the compiled version of OpenSSL. 876 However, when pyca/cryptography is compiled as a manylinux1 wheel 877 that compiled location can potentially be wrong. So, like Go, we 878 will try a predefined set of paths and attempt to load roots 879 from there. 880 881 :return: None 882 """ 883 for cafile in file_path: 884 if os.path.isfile(cafile): 885 self.load_verify_locations(cafile) 886 break 887 888 for capath in dir_path: 889 if os.path.isdir(capath): 890 self.load_verify_locations(None, capath) 891 break 892 893 def use_certificate_chain_file(self, certfile): 894 """ 895 Load a certificate chain from a file. 896 897 :param certfile: The name of the certificate chain file (``bytes`` or 898 ``unicode``). Must be PEM encoded. 899 900 :return: None 901 """ 902 certfile = _path_string(certfile) 903 904 result = _lib.SSL_CTX_use_certificate_chain_file( 905 self._context, certfile 906 ) 907 if not result: 908 _raise_current_error() 909 910 def use_certificate_file(self, certfile, filetype=FILETYPE_PEM): 911 """ 912 Load a certificate from a file 913 914 :param certfile: The name of the certificate file (``bytes`` or 915 ``unicode``). 916 :param filetype: (optional) The encoding of the file, which is either 917 :const:`FILETYPE_PEM` or :const:`FILETYPE_ASN1`. The default is 918 :const:`FILETYPE_PEM`. 919 920 :return: None 921 """ 922 certfile = _path_string(certfile) 923 if not isinstance(filetype, integer_types): 924 raise TypeError("filetype must be an integer") 925 926 use_result = _lib.SSL_CTX_use_certificate_file( 927 self._context, certfile, filetype 928 ) 929 if not use_result: 930 _raise_current_error() 931 932 def use_certificate(self, cert): 933 """ 934 Load a certificate from a X509 object 935 936 :param cert: The X509 object 937 :return: None 938 """ 939 if not isinstance(cert, X509): 940 raise TypeError("cert must be an X509 instance") 941 942 use_result = _lib.SSL_CTX_use_certificate(self._context, cert._x509) 943 if not use_result: 944 _raise_current_error() 945 946 def add_extra_chain_cert(self, certobj): 947 """ 948 Add certificate to chain 949 950 :param certobj: The X509 certificate object to add to the chain 951 :return: None 952 """ 953 if not isinstance(certobj, X509): 954 raise TypeError("certobj must be an X509 instance") 955 956 copy = _lib.X509_dup(certobj._x509) 957 add_result = _lib.SSL_CTX_add_extra_chain_cert(self._context, copy) 958 if not add_result: 959 # TODO: This is untested. 960 _lib.X509_free(copy) 961 _raise_current_error() 962 963 def _raise_passphrase_exception(self): 964 if self._passphrase_helper is not None: 965 self._passphrase_helper.raise_if_problem(Error) 966 967 _raise_current_error() 968 969 def use_privatekey_file(self, keyfile, filetype=_UNSPECIFIED): 970 """ 971 Load a private key from a file 972 973 :param keyfile: The name of the key file (``bytes`` or ``unicode``) 974 :param filetype: (optional) The encoding of the file, which is either 975 :const:`FILETYPE_PEM` or :const:`FILETYPE_ASN1`. The default is 976 :const:`FILETYPE_PEM`. 977 978 :return: None 979 """ 980 keyfile = _path_string(keyfile) 981 982 if filetype is _UNSPECIFIED: 983 filetype = FILETYPE_PEM 984 elif not isinstance(filetype, integer_types): 985 raise TypeError("filetype must be an integer") 986 987 use_result = _lib.SSL_CTX_use_PrivateKey_file( 988 self._context, keyfile, filetype) 989 if not use_result: 990 self._raise_passphrase_exception() 991 992 def use_privatekey(self, pkey): 993 """ 994 Load a private key from a PKey object 995 996 :param pkey: The PKey object 997 :return: None 998 """ 999 if not isinstance(pkey, PKey): 1000 raise TypeError("pkey must be a PKey instance") 1001 1002 use_result = _lib.SSL_CTX_use_PrivateKey(self._context, pkey._pkey) 1003 if not use_result: 1004 self._raise_passphrase_exception() 1005 1006 def check_privatekey(self): 1007 """ 1008 Check if the private key (loaded with :meth:`use_privatekey`) matches 1009 the certificate (loaded with :meth:`use_certificate`) 1010 1011 :return: :data:`None` (raises :exc:`Error` if something's wrong) 1012 """ 1013 if not _lib.SSL_CTX_check_private_key(self._context): 1014 _raise_current_error() 1015 1016 def load_client_ca(self, cafile): 1017 """ 1018 Load the trusted certificates that will be sent to the client. Does 1019 not actually imply any of the certificates are trusted; that must be 1020 configured separately. 1021 1022 :param bytes cafile: The path to a certificates file in PEM format. 1023 :return: None 1024 """ 1025 ca_list = _lib.SSL_load_client_CA_file( 1026 _text_to_bytes_and_warn("cafile", cafile) 1027 ) 1028 _openssl_assert(ca_list != _ffi.NULL) 1029 _lib.SSL_CTX_set_client_CA_list(self._context, ca_list) 1030 1031 def set_session_id(self, buf): 1032 """ 1033 Set the session id to *buf* within which a session can be reused for 1034 this Context object. This is needed when doing session resumption, 1035 because there is no way for a stored session to know which Context 1036 object it is associated with. 1037 1038 :param bytes buf: The session id. 1039 1040 :returns: None 1041 """ 1042 buf = _text_to_bytes_and_warn("buf", buf) 1043 _openssl_assert( 1044 _lib.SSL_CTX_set_session_id_context( 1045 self._context, 1046 buf, 1047 len(buf), 1048 ) == 1 1049 ) 1050 1051 def set_session_cache_mode(self, mode): 1052 """ 1053 Set the behavior of the session cache used by all connections using 1054 this Context. The previously set mode is returned. See 1055 :const:`SESS_CACHE_*` for details about particular modes. 1056 1057 :param mode: One or more of the SESS_CACHE_* flags (combine using 1058 bitwise or) 1059 :returns: The previously set caching mode. 1060 1061 .. versionadded:: 0.14 1062 """ 1063 if not isinstance(mode, integer_types): 1064 raise TypeError("mode must be an integer") 1065 1066 return _lib.SSL_CTX_set_session_cache_mode(self._context, mode) 1067 1068 def get_session_cache_mode(self): 1069 """ 1070 Get the current session cache mode. 1071 1072 :returns: The currently used cache mode. 1073 1074 .. versionadded:: 0.14 1075 """ 1076 return _lib.SSL_CTX_get_session_cache_mode(self._context) 1077 1078 def set_verify(self, mode, callback): 1079 """ 1080 et the verification flags for this Context object to *mode* and specify 1081 that *callback* should be used for verification callbacks. 1082 1083 :param mode: The verify mode, this should be one of 1084 :const:`VERIFY_NONE` and :const:`VERIFY_PEER`. If 1085 :const:`VERIFY_PEER` is used, *mode* can be OR:ed with 1086 :const:`VERIFY_FAIL_IF_NO_PEER_CERT` and 1087 :const:`VERIFY_CLIENT_ONCE` to further control the behaviour. 1088 :param callback: The Python callback to use. This should take five 1089 arguments: A Connection object, an X509 object, and three integer 1090 variables, which are in turn potential error number, error depth 1091 and return code. *callback* should return True if verification 1092 passes and False otherwise. 1093 :return: None 1094 1095 See SSL_CTX_set_verify(3SSL) for further details. 1096 """ 1097 if not isinstance(mode, integer_types): 1098 raise TypeError("mode must be an integer") 1099 1100 if not callable(callback): 1101 raise TypeError("callback must be callable") 1102 1103 self._verify_helper = _VerifyHelper(callback) 1104 self._verify_callback = self._verify_helper.callback 1105 _lib.SSL_CTX_set_verify(self._context, mode, self._verify_callback) 1106 1107 def set_verify_depth(self, depth): 1108 """ 1109 Set the maximum depth for the certificate chain verification that shall 1110 be allowed for this Context object. 1111 1112 :param depth: An integer specifying the verify depth 1113 :return: None 1114 """ 1115 if not isinstance(depth, integer_types): 1116 raise TypeError("depth must be an integer") 1117 1118 _lib.SSL_CTX_set_verify_depth(self._context, depth) 1119 1120 def get_verify_mode(self): 1121 """ 1122 Retrieve the Context object's verify mode, as set by 1123 :meth:`set_verify`. 1124 1125 :return: The verify mode 1126 """ 1127 return _lib.SSL_CTX_get_verify_mode(self._context) 1128 1129 def get_verify_depth(self): 1130 """ 1131 Retrieve the Context object's verify depth, as set by 1132 :meth:`set_verify_depth`. 1133 1134 :return: The verify depth 1135 """ 1136 return _lib.SSL_CTX_get_verify_depth(self._context) 1137 1138 def load_tmp_dh(self, dhfile): 1139 """ 1140 Load parameters for Ephemeral Diffie-Hellman 1141 1142 :param dhfile: The file to load EDH parameters from (``bytes`` or 1143 ``unicode``). 1144 1145 :return: None 1146 """ 1147 dhfile = _path_string(dhfile) 1148 1149 bio = _lib.BIO_new_file(dhfile, b"r") 1150 if bio == _ffi.NULL: 1151 _raise_current_error() 1152 bio = _ffi.gc(bio, _lib.BIO_free) 1153 1154 dh = _lib.PEM_read_bio_DHparams(bio, _ffi.NULL, _ffi.NULL, _ffi.NULL) 1155 dh = _ffi.gc(dh, _lib.DH_free) 1156 _lib.SSL_CTX_set_tmp_dh(self._context, dh) 1157 1158 def set_tmp_ecdh(self, curve): 1159 """ 1160 Select a curve to use for ECDHE key exchange. 1161 1162 :param curve: A curve object to use as returned by either 1163 :meth:`OpenSSL.crypto.get_elliptic_curve` or 1164 :meth:`OpenSSL.crypto.get_elliptic_curves`. 1165 1166 :return: None 1167 """ 1168 _lib.SSL_CTX_set_tmp_ecdh(self._context, curve._to_EC_KEY()) 1169 1170 def set_cipher_list(self, cipher_list): 1171 """ 1172 Set the list of ciphers to be used in this context. 1173 1174 See the OpenSSL manual for more information (e.g. 1175 :manpage:`ciphers(1)`). 1176 1177 :param bytes cipher_list: An OpenSSL cipher string. 1178 :return: None 1179 """ 1180 cipher_list = _text_to_bytes_and_warn("cipher_list", cipher_list) 1181 1182 if not isinstance(cipher_list, bytes): 1183 raise TypeError("cipher_list must be a byte string.") 1184 1185 _openssl_assert( 1186 _lib.SSL_CTX_set_cipher_list(self._context, cipher_list) == 1 1187 ) 1188 # In OpenSSL 1.1.1 setting the cipher list will always return TLS 1.3 1189 # ciphers even if you pass an invalid cipher. Applications (like 1190 # Twisted) have tests that depend on an error being raised if an 1191 # invalid cipher string is passed, but without the following check 1192 # for the TLS 1.3 specific cipher suites it would never error. 1193 tmpconn = Connection(self, None) 1194 _openssl_assert( 1195 tmpconn.get_cipher_list() != [ 1196 'TLS_AES_256_GCM_SHA384', 1197 'TLS_CHACHA20_POLY1305_SHA256', 1198 'TLS_AES_128_GCM_SHA256' 1199 ] 1200 ) 1201 1202 def set_client_ca_list(self, certificate_authorities): 1203 """ 1204 Set the list of preferred client certificate signers for this server 1205 context. 1206 1207 This list of certificate authorities will be sent to the client when 1208 the server requests a client certificate. 1209 1210 :param certificate_authorities: a sequence of X509Names. 1211 :return: None 1212 1213 .. versionadded:: 0.10 1214 """ 1215 name_stack = _lib.sk_X509_NAME_new_null() 1216 _openssl_assert(name_stack != _ffi.NULL) 1217 1218 try: 1219 for ca_name in certificate_authorities: 1220 if not isinstance(ca_name, X509Name): 1221 raise TypeError( 1222 "client CAs must be X509Name objects, not %s " 1223 "objects" % ( 1224 type(ca_name).__name__, 1225 ) 1226 ) 1227 copy = _lib.X509_NAME_dup(ca_name._name) 1228 _openssl_assert(copy != _ffi.NULL) 1229 push_result = _lib.sk_X509_NAME_push(name_stack, copy) 1230 if not push_result: 1231 _lib.X509_NAME_free(copy) 1232 _raise_current_error() 1233 except Exception: 1234 _lib.sk_X509_NAME_free(name_stack) 1235 raise 1236 1237 _lib.SSL_CTX_set_client_CA_list(self._context, name_stack) 1238 1239 def add_client_ca(self, certificate_authority): 1240 """ 1241 Add the CA certificate to the list of preferred signers for this 1242 context. 1243 1244 The list of certificate authorities will be sent to the client when the 1245 server requests a client certificate. 1246 1247 :param certificate_authority: certificate authority's X509 certificate. 1248 :return: None 1249 1250 .. versionadded:: 0.10 1251 """ 1252 if not isinstance(certificate_authority, X509): 1253 raise TypeError("certificate_authority must be an X509 instance") 1254 1255 add_result = _lib.SSL_CTX_add_client_CA( 1256 self._context, certificate_authority._x509) 1257 _openssl_assert(add_result == 1) 1258 1259 def set_timeout(self, timeout): 1260 """ 1261 Set the timeout for newly created sessions for this Context object to 1262 *timeout*. The default value is 300 seconds. See the OpenSSL manual 1263 for more information (e.g. :manpage:`SSL_CTX_set_timeout(3)`). 1264 1265 :param timeout: The timeout in (whole) seconds 1266 :return: The previous session timeout 1267 """ 1268 if not isinstance(timeout, integer_types): 1269 raise TypeError("timeout must be an integer") 1270 1271 return _lib.SSL_CTX_set_timeout(self._context, timeout) 1272 1273 def get_timeout(self): 1274 """ 1275 Retrieve session timeout, as set by :meth:`set_timeout`. The default 1276 is 300 seconds. 1277 1278 :return: The session timeout 1279 """ 1280 return _lib.SSL_CTX_get_timeout(self._context) 1281 1282 def set_info_callback(self, callback): 1283 """ 1284 Set the information callback to *callback*. This function will be 1285 called from time to time during SSL handshakes. 1286 1287 :param callback: The Python callback to use. This should take three 1288 arguments: a Connection object and two integers. The first integer 1289 specifies where in the SSL handshake the function was called, and 1290 the other the return code from a (possibly failed) internal 1291 function call. 1292 :return: None 1293 """ 1294 @wraps(callback) 1295 def wrapper(ssl, where, return_code): 1296 callback(Connection._reverse_mapping[ssl], where, return_code) 1297 self._info_callback = _ffi.callback( 1298 "void (*)(const SSL *, int, int)", wrapper) 1299 _lib.SSL_CTX_set_info_callback(self._context, self._info_callback) 1300 1301 def get_app_data(self): 1302 """ 1303 Get the application data (supplied via :meth:`set_app_data()`) 1304 1305 :return: The application data 1306 """ 1307 return self._app_data 1308 1309 def set_app_data(self, data): 1310 """ 1311 Set the application data (will be returned from get_app_data()) 1312 1313 :param data: Any Python object 1314 :return: None 1315 """ 1316 self._app_data = data 1317 1318 def get_cert_store(self): 1319 """ 1320 Get the certificate store for the context. This can be used to add 1321 "trusted" certificates without using the 1322 :meth:`load_verify_locations` method. 1323 1324 :return: A X509Store object or None if it does not have one. 1325 """ 1326 store = _lib.SSL_CTX_get_cert_store(self._context) 1327 if store == _ffi.NULL: 1328 # TODO: This is untested. 1329 return None 1330 1331 pystore = X509Store.__new__(X509Store) 1332 pystore._store = store 1333 return pystore 1334 1335 def set_options(self, options): 1336 """ 1337 Add options. Options set before are not cleared! 1338 This method should be used with the :const:`OP_*` constants. 1339 1340 :param options: The options to add. 1341 :return: The new option bitmask. 1342 """ 1343 if not isinstance(options, integer_types): 1344 raise TypeError("options must be an integer") 1345 1346 return _lib.SSL_CTX_set_options(self._context, options) 1347 1348 def set_mode(self, mode): 1349 """ 1350 Add modes via bitmask. Modes set before are not cleared! This method 1351 should be used with the :const:`MODE_*` constants. 1352 1353 :param mode: The mode to add. 1354 :return: The new mode bitmask. 1355 """ 1356 if not isinstance(mode, integer_types): 1357 raise TypeError("mode must be an integer") 1358 1359 return _lib.SSL_CTX_set_mode(self._context, mode) 1360 1361 @_requires_sni 1362 def set_tlsext_servername_callback(self, callback): 1363 """ 1364 Specify a callback function to be called when clients specify a server 1365 name. 1366 1367 :param callback: The callback function. It will be invoked with one 1368 argument, the Connection instance. 1369 1370 .. versionadded:: 0.13 1371 """ 1372 @wraps(callback) 1373 def wrapper(ssl, alert, arg): 1374 callback(Connection._reverse_mapping[ssl]) 1375 return 0 1376 1377 self._tlsext_servername_callback = _ffi.callback( 1378 "int (*)(SSL *, int *, void *)", wrapper) 1379 _lib.SSL_CTX_set_tlsext_servername_callback( 1380 self._context, self._tlsext_servername_callback) 1381 1382 def set_tlsext_use_srtp(self, profiles): 1383 """ 1384 Enable support for negotiating SRTP keying material. 1385 1386 :param bytes profiles: A colon delimited list of protection profile 1387 names, like ``b'SRTP_AES128_CM_SHA1_80:SRTP_AES128_CM_SHA1_32'``. 1388 :return: None 1389 """ 1390 if not isinstance(profiles, bytes): 1391 raise TypeError("profiles must be a byte string.") 1392 1393 _openssl_assert( 1394 _lib.SSL_CTX_set_tlsext_use_srtp(self._context, profiles) == 0 1395 ) 1396 1397 @_requires_npn 1398 def set_npn_advertise_callback(self, callback): 1399 """ 1400 Specify a callback function that will be called when offering `Next 1401 Protocol Negotiation 1402 <https://technotes.googlecode.com/git/nextprotoneg.html>`_ as a server. 1403 1404 :param callback: The callback function. It will be invoked with one 1405 argument, the :class:`Connection` instance. It should return a 1406 list of bytestrings representing the advertised protocols, like 1407 ``[b'http/1.1', b'spdy/2']``. 1408 1409 .. versionadded:: 0.15 1410 """ 1411 self._npn_advertise_helper = _NpnAdvertiseHelper(callback) 1412 self._npn_advertise_callback = self._npn_advertise_helper.callback 1413 _lib.SSL_CTX_set_next_protos_advertised_cb( 1414 self._context, self._npn_advertise_callback, _ffi.NULL) 1415 1416 @_requires_npn 1417 def set_npn_select_callback(self, callback): 1418 """ 1419 Specify a callback function that will be called when a server offers 1420 Next Protocol Negotiation options. 1421 1422 :param callback: The callback function. It will be invoked with two 1423 arguments: the Connection, and a list of offered protocols as 1424 bytestrings, e.g. ``[b'http/1.1', b'spdy/2']``. It should return 1425 one of those bytestrings, the chosen protocol. 1426 1427 .. versionadded:: 0.15 1428 """ 1429 self._npn_select_helper = _NpnSelectHelper(callback) 1430 self._npn_select_callback = self._npn_select_helper.callback 1431 _lib.SSL_CTX_set_next_proto_select_cb( 1432 self._context, self._npn_select_callback, _ffi.NULL) 1433 1434 @_requires_alpn 1435 def set_alpn_protos(self, protos): 1436 """ 1437 Specify the protocols that the client is prepared to speak after the 1438 TLS connection has been negotiated using Application Layer Protocol 1439 Negotiation. 1440 1441 :param protos: A list of the protocols to be offered to the server. 1442 This list should be a Python list of bytestrings representing the 1443 protocols to offer, e.g. ``[b'http/1.1', b'spdy/2']``. 1444 """ 1445 # Take the list of protocols and join them together, prefixing them 1446 # with their lengths. 1447 protostr = b''.join( 1448 chain.from_iterable((int2byte(len(p)), p) for p in protos) 1449 ) 1450 1451 # Build a C string from the list. We don't need to save this off 1452 # because OpenSSL immediately copies the data out. 1453 input_str = _ffi.new("unsigned char[]", protostr) 1454 _lib.SSL_CTX_set_alpn_protos(self._context, input_str, len(protostr)) 1455 1456 @_requires_alpn 1457 def set_alpn_select_callback(self, callback): 1458 """ 1459 Specify a callback function that will be called on the server when a 1460 client offers protocols using ALPN. 1461 1462 :param callback: The callback function. It will be invoked with two 1463 arguments: the Connection, and a list of offered protocols as 1464 bytestrings, e.g ``[b'http/1.1', b'spdy/2']``. It should return 1465 one of those bytestrings, the chosen protocol. 1466 """ 1467 self._alpn_select_helper = _ALPNSelectHelper(callback) 1468 self._alpn_select_callback = self._alpn_select_helper.callback 1469 _lib.SSL_CTX_set_alpn_select_cb( 1470 self._context, self._alpn_select_callback, _ffi.NULL) 1471 1472 def _set_ocsp_callback(self, helper, data): 1473 """ 1474 This internal helper does the common work for 1475 ``set_ocsp_server_callback`` and ``set_ocsp_client_callback``, which is 1476 almost all of it. 1477 """ 1478 self._ocsp_helper = helper 1479 self._ocsp_callback = helper.callback 1480 if data is None: 1481 self._ocsp_data = _ffi.NULL 1482 else: 1483 self._ocsp_data = _ffi.new_handle(data) 1484 1485 rc = _lib.SSL_CTX_set_tlsext_status_cb( 1486 self._context, self._ocsp_callback 1487 ) 1488 _openssl_assert(rc == 1) 1489 rc = _lib.SSL_CTX_set_tlsext_status_arg(self._context, self._ocsp_data) 1490 _openssl_assert(rc == 1) 1491 1492 def set_ocsp_server_callback(self, callback, data=None): 1493 """ 1494 Set a callback to provide OCSP data to be stapled to the TLS handshake 1495 on the server side. 1496 1497 :param callback: The callback function. It will be invoked with two 1498 arguments: the Connection, and the optional arbitrary data you have 1499 provided. The callback must return a bytestring that contains the 1500 OCSP data to staple to the handshake. If no OCSP data is available 1501 for this connection, return the empty bytestring. 1502 :param data: Some opaque data that will be passed into the callback 1503 function when called. This can be used to avoid needing to do 1504 complex data lookups or to keep track of what context is being 1505 used. This parameter is optional. 1506 """ 1507 helper = _OCSPServerCallbackHelper(callback) 1508 self._set_ocsp_callback(helper, data) 1509 1510 def set_ocsp_client_callback(self, callback, data=None): 1511 """ 1512 Set a callback to validate OCSP data stapled to the TLS handshake on 1513 the client side. 1514 1515 :param callback: The callback function. It will be invoked with three 1516 arguments: the Connection, a bytestring containing the stapled OCSP 1517 assertion, and the optional arbitrary data you have provided. The 1518 callback must return a boolean that indicates the result of 1519 validating the OCSP data: ``True`` if the OCSP data is valid and 1520 the certificate can be trusted, or ``False`` if either the OCSP 1521 data is invalid or the certificate has been revoked. 1522 :param data: Some opaque data that will be passed into the callback 1523 function when called. This can be used to avoid needing to do 1524 complex data lookups or to keep track of what context is being 1525 used. This parameter is optional. 1526 """ 1527 helper = _OCSPClientCallbackHelper(callback) 1528 self._set_ocsp_callback(helper, data) 1529 1530 1531ContextType = deprecated( 1532 Context, __name__, 1533 "ContextType has been deprecated, use Context instead", DeprecationWarning 1534) 1535 1536 1537class Connection(object): 1538 """ 1539 """ 1540 _reverse_mapping = WeakValueDictionary() 1541 1542 def __init__(self, context, socket=None): 1543 """ 1544 Create a new Connection object, using the given OpenSSL.SSL.Context 1545 instance and socket. 1546 1547 :param context: An SSL Context to use for this connection 1548 :param socket: The socket to use for transport layer 1549 """ 1550 if not isinstance(context, Context): 1551 raise TypeError("context must be a Context instance") 1552 1553 ssl = _lib.SSL_new(context._context) 1554 self._ssl = _ffi.gc(ssl, _lib.SSL_free) 1555 # We set SSL_MODE_AUTO_RETRY to handle situations where OpenSSL returns 1556 # an SSL_ERROR_WANT_READ when processing a non-application data packet 1557 # even though there is still data on the underlying transport. 1558 # See https://github.com/openssl/openssl/issues/6234 for more details. 1559 _lib.SSL_set_mode(self._ssl, _lib.SSL_MODE_AUTO_RETRY) 1560 self._context = context 1561 self._app_data = None 1562 1563 # References to strings used for Next Protocol Negotiation. OpenSSL's 1564 # header files suggest that these might get copied at some point, but 1565 # doesn't specify when, so we store them here to make sure they don't 1566 # get freed before OpenSSL uses them. 1567 self._npn_advertise_callback_args = None 1568 self._npn_select_callback_args = None 1569 1570 # References to strings used for Application Layer Protocol 1571 # Negotiation. These strings get copied at some point but it's well 1572 # after the callback returns, so we have to hang them somewhere to 1573 # avoid them getting freed. 1574 self._alpn_select_callback_args = None 1575 1576 self._reverse_mapping[self._ssl] = self 1577 1578 if socket is None: 1579 self._socket = None 1580 # Don't set up any gc for these, SSL_free will take care of them. 1581 self._into_ssl = _lib.BIO_new(_lib.BIO_s_mem()) 1582 _openssl_assert(self._into_ssl != _ffi.NULL) 1583 1584 self._from_ssl = _lib.BIO_new(_lib.BIO_s_mem()) 1585 _openssl_assert(self._from_ssl != _ffi.NULL) 1586 1587 _lib.SSL_set_bio(self._ssl, self._into_ssl, self._from_ssl) 1588 else: 1589 self._into_ssl = None 1590 self._from_ssl = None 1591 self._socket = socket 1592 set_result = _lib.SSL_set_fd( 1593 self._ssl, _asFileDescriptor(self._socket)) 1594 _openssl_assert(set_result == 1) 1595 1596 def __getattr__(self, name): 1597 """ 1598 Look up attributes on the wrapped socket object if they are not found 1599 on the Connection object. 1600 """ 1601 if self._socket is None: 1602 raise AttributeError("'%s' object has no attribute '%s'" % ( 1603 self.__class__.__name__, name 1604 )) 1605 else: 1606 return getattr(self._socket, name) 1607 1608 def _raise_ssl_error(self, ssl, result): 1609 if self._context._verify_helper is not None: 1610 self._context._verify_helper.raise_if_problem() 1611 if self._context._npn_advertise_helper is not None: 1612 self._context._npn_advertise_helper.raise_if_problem() 1613 if self._context._npn_select_helper is not None: 1614 self._context._npn_select_helper.raise_if_problem() 1615 if self._context._alpn_select_helper is not None: 1616 self._context._alpn_select_helper.raise_if_problem() 1617 if self._context._ocsp_helper is not None: 1618 self._context._ocsp_helper.raise_if_problem() 1619 1620 error = _lib.SSL_get_error(ssl, result) 1621 if error == _lib.SSL_ERROR_WANT_READ: 1622 raise WantReadError() 1623 elif error == _lib.SSL_ERROR_WANT_WRITE: 1624 raise WantWriteError() 1625 elif error == _lib.SSL_ERROR_ZERO_RETURN: 1626 raise ZeroReturnError() 1627 elif error == _lib.SSL_ERROR_WANT_X509_LOOKUP: 1628 # TODO: This is untested. 1629 raise WantX509LookupError() 1630 elif error == _lib.SSL_ERROR_SYSCALL: 1631 if _lib.ERR_peek_error() == 0: 1632 if result < 0: 1633 if platform == "win32": 1634 errno = _ffi.getwinerror()[0] 1635 else: 1636 errno = _ffi.errno 1637 1638 if errno != 0: 1639 raise SysCallError(errno, errorcode.get(errno)) 1640 raise SysCallError(-1, "Unexpected EOF") 1641 else: 1642 # TODO: This is untested. 1643 _raise_current_error() 1644 elif error == _lib.SSL_ERROR_NONE: 1645 pass 1646 else: 1647 _raise_current_error() 1648 1649 def get_context(self): 1650 """ 1651 Retrieve the :class:`Context` object associated with this 1652 :class:`Connection`. 1653 """ 1654 return self._context 1655 1656 def set_context(self, context): 1657 """ 1658 Switch this connection to a new session context. 1659 1660 :param context: A :class:`Context` instance giving the new session 1661 context to use. 1662 """ 1663 if not isinstance(context, Context): 1664 raise TypeError("context must be a Context instance") 1665 1666 _lib.SSL_set_SSL_CTX(self._ssl, context._context) 1667 self._context = context 1668 1669 @_requires_sni 1670 def get_servername(self): 1671 """ 1672 Retrieve the servername extension value if provided in the client hello 1673 message, or None if there wasn't one. 1674 1675 :return: A byte string giving the server name or :data:`None`. 1676 1677 .. versionadded:: 0.13 1678 """ 1679 name = _lib.SSL_get_servername( 1680 self._ssl, _lib.TLSEXT_NAMETYPE_host_name 1681 ) 1682 if name == _ffi.NULL: 1683 return None 1684 1685 return _ffi.string(name) 1686 1687 @_requires_sni 1688 def set_tlsext_host_name(self, name): 1689 """ 1690 Set the value of the servername extension to send in the client hello. 1691 1692 :param name: A byte string giving the name. 1693 1694 .. versionadded:: 0.13 1695 """ 1696 if not isinstance(name, bytes): 1697 raise TypeError("name must be a byte string") 1698 elif b"\0" in name: 1699 raise TypeError("name must not contain NUL byte") 1700 1701 # XXX I guess this can fail sometimes? 1702 _lib.SSL_set_tlsext_host_name(self._ssl, name) 1703 1704 def pending(self): 1705 """ 1706 Get the number of bytes that can be safely read from the SSL buffer 1707 (**not** the underlying transport buffer). 1708 1709 :return: The number of bytes available in the receive buffer. 1710 """ 1711 return _lib.SSL_pending(self._ssl) 1712 1713 def send(self, buf, flags=0): 1714 """ 1715 Send data on the connection. NOTE: If you get one of the WantRead, 1716 WantWrite or WantX509Lookup exceptions on this, you have to call the 1717 method again with the SAME buffer. 1718 1719 :param buf: The string, buffer or memoryview to send 1720 :param flags: (optional) Included for compatibility with the socket 1721 API, the value is ignored 1722 :return: The number of bytes written 1723 """ 1724 # Backward compatibility 1725 buf = _text_to_bytes_and_warn("buf", buf) 1726 1727 if isinstance(buf, memoryview): 1728 buf = buf.tobytes() 1729 if isinstance(buf, _buffer): 1730 buf = str(buf) 1731 if not isinstance(buf, bytes): 1732 raise TypeError("data must be a memoryview, buffer or byte string") 1733 if len(buf) > 2147483647: 1734 raise ValueError("Cannot send more than 2**31-1 bytes at once.") 1735 1736 result = _lib.SSL_write(self._ssl, buf, len(buf)) 1737 self._raise_ssl_error(self._ssl, result) 1738 return result 1739 write = send 1740 1741 def sendall(self, buf, flags=0): 1742 """ 1743 Send "all" data on the connection. This calls send() repeatedly until 1744 all data is sent. If an error occurs, it's impossible to tell how much 1745 data has been sent. 1746 1747 :param buf: The string, buffer or memoryview to send 1748 :param flags: (optional) Included for compatibility with the socket 1749 API, the value is ignored 1750 :return: The number of bytes written 1751 """ 1752 buf = _text_to_bytes_and_warn("buf", buf) 1753 1754 if isinstance(buf, memoryview): 1755 buf = buf.tobytes() 1756 if isinstance(buf, _buffer): 1757 buf = str(buf) 1758 if not isinstance(buf, bytes): 1759 raise TypeError("buf must be a memoryview, buffer or byte string") 1760 1761 left_to_send = len(buf) 1762 total_sent = 0 1763 data = _ffi.new("char[]", buf) 1764 1765 while left_to_send: 1766 # SSL_write's num arg is an int, 1767 # so we cannot send more than 2**31-1 bytes at once. 1768 result = _lib.SSL_write( 1769 self._ssl, 1770 data + total_sent, 1771 min(left_to_send, 2147483647) 1772 ) 1773 self._raise_ssl_error(self._ssl, result) 1774 total_sent += result 1775 left_to_send -= result 1776 1777 def recv(self, bufsiz, flags=None): 1778 """ 1779 Receive data on the connection. 1780 1781 :param bufsiz: The maximum number of bytes to read 1782 :param flags: (optional) The only supported flag is ``MSG_PEEK``, 1783 all other flags are ignored. 1784 :return: The string read from the Connection 1785 """ 1786 buf = _no_zero_allocator("char[]", bufsiz) 1787 if flags is not None and flags & socket.MSG_PEEK: 1788 result = _lib.SSL_peek(self._ssl, buf, bufsiz) 1789 else: 1790 result = _lib.SSL_read(self._ssl, buf, bufsiz) 1791 self._raise_ssl_error(self._ssl, result) 1792 return _ffi.buffer(buf, result)[:] 1793 read = recv 1794 1795 def recv_into(self, buffer, nbytes=None, flags=None): 1796 """ 1797 Receive data on the connection and copy it directly into the provided 1798 buffer, rather than creating a new string. 1799 1800 :param buffer: The buffer to copy into. 1801 :param nbytes: (optional) The maximum number of bytes to read into the 1802 buffer. If not present, defaults to the size of the buffer. If 1803 larger than the size of the buffer, is reduced to the size of the 1804 buffer. 1805 :param flags: (optional) The only supported flag is ``MSG_PEEK``, 1806 all other flags are ignored. 1807 :return: The number of bytes read into the buffer. 1808 """ 1809 if nbytes is None: 1810 nbytes = len(buffer) 1811 else: 1812 nbytes = min(nbytes, len(buffer)) 1813 1814 # We need to create a temporary buffer. This is annoying, it would be 1815 # better if we could pass memoryviews straight into the SSL_read call, 1816 # but right now we can't. Revisit this if CFFI gets that ability. 1817 buf = _no_zero_allocator("char[]", nbytes) 1818 if flags is not None and flags & socket.MSG_PEEK: 1819 result = _lib.SSL_peek(self._ssl, buf, nbytes) 1820 else: 1821 result = _lib.SSL_read(self._ssl, buf, nbytes) 1822 self._raise_ssl_error(self._ssl, result) 1823 1824 # This strange line is all to avoid a memory copy. The buffer protocol 1825 # should allow us to assign a CFFI buffer to the LHS of this line, but 1826 # on CPython 3.3+ that segfaults. As a workaround, we can temporarily 1827 # wrap it in a memoryview. 1828 buffer[:result] = memoryview(_ffi.buffer(buf, result)) 1829 1830 return result 1831 1832 def _handle_bio_errors(self, bio, result): 1833 if _lib.BIO_should_retry(bio): 1834 if _lib.BIO_should_read(bio): 1835 raise WantReadError() 1836 elif _lib.BIO_should_write(bio): 1837 # TODO: This is untested. 1838 raise WantWriteError() 1839 elif _lib.BIO_should_io_special(bio): 1840 # TODO: This is untested. I think io_special means the socket 1841 # BIO has a not-yet connected socket. 1842 raise ValueError("BIO_should_io_special") 1843 else: 1844 # TODO: This is untested. 1845 raise ValueError("unknown bio failure") 1846 else: 1847 # TODO: This is untested. 1848 _raise_current_error() 1849 1850 def bio_read(self, bufsiz): 1851 """ 1852 If the Connection was created with a memory BIO, this method can be 1853 used to read bytes from the write end of that memory BIO. Many 1854 Connection methods will add bytes which must be read in this manner or 1855 the buffer will eventually fill up and the Connection will be able to 1856 take no further actions. 1857 1858 :param bufsiz: The maximum number of bytes to read 1859 :return: The string read. 1860 """ 1861 if self._from_ssl is None: 1862 raise TypeError("Connection sock was not None") 1863 1864 if not isinstance(bufsiz, integer_types): 1865 raise TypeError("bufsiz must be an integer") 1866 1867 buf = _no_zero_allocator("char[]", bufsiz) 1868 result = _lib.BIO_read(self._from_ssl, buf, bufsiz) 1869 if result <= 0: 1870 self._handle_bio_errors(self._from_ssl, result) 1871 1872 return _ffi.buffer(buf, result)[:] 1873 1874 def bio_write(self, buf): 1875 """ 1876 If the Connection was created with a memory BIO, this method can be 1877 used to add bytes to the read end of that memory BIO. The Connection 1878 can then read the bytes (for example, in response to a call to 1879 :meth:`recv`). 1880 1881 :param buf: The string to put into the memory BIO. 1882 :return: The number of bytes written 1883 """ 1884 buf = _text_to_bytes_and_warn("buf", buf) 1885 1886 if self._into_ssl is None: 1887 raise TypeError("Connection sock was not None") 1888 1889 result = _lib.BIO_write(self._into_ssl, buf, len(buf)) 1890 if result <= 0: 1891 self._handle_bio_errors(self._into_ssl, result) 1892 return result 1893 1894 def renegotiate(self): 1895 """ 1896 Renegotiate the session. 1897 1898 :return: True if the renegotiation can be started, False otherwise 1899 :rtype: bool 1900 """ 1901 if not self.renegotiate_pending(): 1902 _openssl_assert(_lib.SSL_renegotiate(self._ssl) == 1) 1903 return True 1904 return False 1905 1906 def do_handshake(self): 1907 """ 1908 Perform an SSL handshake (usually called after :meth:`renegotiate` or 1909 one of :meth:`set_accept_state` or :meth:`set_accept_state`). This can 1910 raise the same exceptions as :meth:`send` and :meth:`recv`. 1911 1912 :return: None. 1913 """ 1914 result = _lib.SSL_do_handshake(self._ssl) 1915 self._raise_ssl_error(self._ssl, result) 1916 1917 def renegotiate_pending(self): 1918 """ 1919 Check if there's a renegotiation in progress, it will return False once 1920 a renegotiation is finished. 1921 1922 :return: Whether there's a renegotiation in progress 1923 :rtype: bool 1924 """ 1925 return _lib.SSL_renegotiate_pending(self._ssl) == 1 1926 1927 def total_renegotiations(self): 1928 """ 1929 Find out the total number of renegotiations. 1930 1931 :return: The number of renegotiations. 1932 :rtype: int 1933 """ 1934 return _lib.SSL_total_renegotiations(self._ssl) 1935 1936 def connect(self, addr): 1937 """ 1938 Call the :meth:`connect` method of the underlying socket and set up SSL 1939 on the socket, using the :class:`Context` object supplied to this 1940 :class:`Connection` object at creation. 1941 1942 :param addr: A remote address 1943 :return: What the socket's connect method returns 1944 """ 1945 _lib.SSL_set_connect_state(self._ssl) 1946 return self._socket.connect(addr) 1947 1948 def connect_ex(self, addr): 1949 """ 1950 Call the :meth:`connect_ex` method of the underlying socket and set up 1951 SSL on the socket, using the Context object supplied to this Connection 1952 object at creation. Note that if the :meth:`connect_ex` method of the 1953 socket doesn't return 0, SSL won't be initialized. 1954 1955 :param addr: A remove address 1956 :return: What the socket's connect_ex method returns 1957 """ 1958 connect_ex = self._socket.connect_ex 1959 self.set_connect_state() 1960 return connect_ex(addr) 1961 1962 def accept(self): 1963 """ 1964 Call the :meth:`accept` method of the underlying socket and set up SSL 1965 on the returned socket, using the Context object supplied to this 1966 :class:`Connection` object at creation. 1967 1968 :return: A *(conn, addr)* pair where *conn* is the new 1969 :class:`Connection` object created, and *address* is as returned by 1970 the socket's :meth:`accept`. 1971 """ 1972 client, addr = self._socket.accept() 1973 conn = Connection(self._context, client) 1974 conn.set_accept_state() 1975 return (conn, addr) 1976 1977 def bio_shutdown(self): 1978 """ 1979 If the Connection was created with a memory BIO, this method can be 1980 used to indicate that *end of file* has been reached on the read end of 1981 that memory BIO. 1982 1983 :return: None 1984 """ 1985 if self._from_ssl is None: 1986 raise TypeError("Connection sock was not None") 1987 1988 _lib.BIO_set_mem_eof_return(self._into_ssl, 0) 1989 1990 def shutdown(self): 1991 """ 1992 Send the shutdown message to the Connection. 1993 1994 :return: True if the shutdown completed successfully (i.e. both sides 1995 have sent closure alerts), False otherwise (in which case you 1996 call :meth:`recv` or :meth:`send` when the connection becomes 1997 readable/writeable). 1998 """ 1999 result = _lib.SSL_shutdown(self._ssl) 2000 if result < 0: 2001 self._raise_ssl_error(self._ssl, result) 2002 elif result > 0: 2003 return True 2004 else: 2005 return False 2006 2007 def get_cipher_list(self): 2008 """ 2009 Retrieve the list of ciphers used by the Connection object. 2010 2011 :return: A list of native cipher strings. 2012 """ 2013 ciphers = [] 2014 for i in count(): 2015 result = _lib.SSL_get_cipher_list(self._ssl, i) 2016 if result == _ffi.NULL: 2017 break 2018 ciphers.append(_native(_ffi.string(result))) 2019 return ciphers 2020 2021 def get_client_ca_list(self): 2022 """ 2023 Get CAs whose certificates are suggested for client authentication. 2024 2025 :return: If this is a server connection, the list of certificate 2026 authorities that will be sent or has been sent to the client, as 2027 controlled by this :class:`Connection`'s :class:`Context`. 2028 2029 If this is a client connection, the list will be empty until the 2030 connection with the server is established. 2031 2032 .. versionadded:: 0.10 2033 """ 2034 ca_names = _lib.SSL_get_client_CA_list(self._ssl) 2035 if ca_names == _ffi.NULL: 2036 # TODO: This is untested. 2037 return [] 2038 2039 result = [] 2040 for i in range(_lib.sk_X509_NAME_num(ca_names)): 2041 name = _lib.sk_X509_NAME_value(ca_names, i) 2042 copy = _lib.X509_NAME_dup(name) 2043 _openssl_assert(copy != _ffi.NULL) 2044 2045 pyname = X509Name.__new__(X509Name) 2046 pyname._name = _ffi.gc(copy, _lib.X509_NAME_free) 2047 result.append(pyname) 2048 return result 2049 2050 def makefile(self, *args, **kwargs): 2051 """ 2052 The makefile() method is not implemented, since there is no dup 2053 semantics for SSL connections 2054 2055 :raise: NotImplementedError 2056 """ 2057 raise NotImplementedError( 2058 "Cannot make file object of OpenSSL.SSL.Connection") 2059 2060 def get_app_data(self): 2061 """ 2062 Retrieve application data as set by :meth:`set_app_data`. 2063 2064 :return: The application data 2065 """ 2066 return self._app_data 2067 2068 def set_app_data(self, data): 2069 """ 2070 Set application data 2071 2072 :param data: The application data 2073 :return: None 2074 """ 2075 self._app_data = data 2076 2077 def get_shutdown(self): 2078 """ 2079 Get the shutdown state of the Connection. 2080 2081 :return: The shutdown state, a bitvector of SENT_SHUTDOWN, 2082 RECEIVED_SHUTDOWN. 2083 """ 2084 return _lib.SSL_get_shutdown(self._ssl) 2085 2086 def set_shutdown(self, state): 2087 """ 2088 Set the shutdown state of the Connection. 2089 2090 :param state: bitvector of SENT_SHUTDOWN, RECEIVED_SHUTDOWN. 2091 :return: None 2092 """ 2093 if not isinstance(state, integer_types): 2094 raise TypeError("state must be an integer") 2095 2096 _lib.SSL_set_shutdown(self._ssl, state) 2097 2098 def get_state_string(self): 2099 """ 2100 Retrieve a verbose string detailing the state of the Connection. 2101 2102 :return: A string representing the state 2103 :rtype: bytes 2104 """ 2105 return _ffi.string(_lib.SSL_state_string_long(self._ssl)) 2106 2107 def server_random(self): 2108 """ 2109 Retrieve the random value used with the server hello message. 2110 2111 :return: A string representing the state 2112 """ 2113 session = _lib.SSL_get_session(self._ssl) 2114 if session == _ffi.NULL: 2115 return None 2116 length = _lib.SSL_get_server_random(self._ssl, _ffi.NULL, 0) 2117 assert length > 0 2118 outp = _no_zero_allocator("unsigned char[]", length) 2119 _lib.SSL_get_server_random(self._ssl, outp, length) 2120 return _ffi.buffer(outp, length)[:] 2121 2122 def client_random(self): 2123 """ 2124 Retrieve the random value used with the client hello message. 2125 2126 :return: A string representing the state 2127 """ 2128 session = _lib.SSL_get_session(self._ssl) 2129 if session == _ffi.NULL: 2130 return None 2131 2132 length = _lib.SSL_get_client_random(self._ssl, _ffi.NULL, 0) 2133 assert length > 0 2134 outp = _no_zero_allocator("unsigned char[]", length) 2135 _lib.SSL_get_client_random(self._ssl, outp, length) 2136 return _ffi.buffer(outp, length)[:] 2137 2138 def master_key(self): 2139 """ 2140 Retrieve the value of the master key for this session. 2141 2142 :return: A string representing the state 2143 """ 2144 session = _lib.SSL_get_session(self._ssl) 2145 if session == _ffi.NULL: 2146 return None 2147 2148 length = _lib.SSL_SESSION_get_master_key(session, _ffi.NULL, 0) 2149 assert length > 0 2150 outp = _no_zero_allocator("unsigned char[]", length) 2151 _lib.SSL_SESSION_get_master_key(session, outp, length) 2152 return _ffi.buffer(outp, length)[:] 2153 2154 def export_keying_material(self, label, olen, context=None): 2155 """ 2156 Obtain keying material for application use. 2157 2158 :param: label - a disambiguating label string as described in RFC 5705 2159 :param: olen - the length of the exported key material in bytes 2160 :param: context - a per-association context value 2161 :return: the exported key material bytes or None 2162 """ 2163 outp = _no_zero_allocator("unsigned char[]", olen) 2164 context_buf = _ffi.NULL 2165 context_len = 0 2166 use_context = 0 2167 if context is not None: 2168 context_buf = context 2169 context_len = len(context) 2170 use_context = 1 2171 success = _lib.SSL_export_keying_material(self._ssl, outp, olen, 2172 label, len(label), 2173 context_buf, context_len, 2174 use_context) 2175 _openssl_assert(success == 1) 2176 return _ffi.buffer(outp, olen)[:] 2177 2178 def sock_shutdown(self, *args, **kwargs): 2179 """ 2180 Call the :meth:`shutdown` method of the underlying socket. 2181 See :manpage:`shutdown(2)`. 2182 2183 :return: What the socket's shutdown() method returns 2184 """ 2185 return self._socket.shutdown(*args, **kwargs) 2186 2187 def get_certificate(self): 2188 """ 2189 Retrieve the local certificate (if any) 2190 2191 :return: The local certificate 2192 """ 2193 cert = _lib.SSL_get_certificate(self._ssl) 2194 if cert != _ffi.NULL: 2195 _lib.X509_up_ref(cert) 2196 return X509._from_raw_x509_ptr(cert) 2197 return None 2198 2199 def get_peer_certificate(self): 2200 """ 2201 Retrieve the other side's certificate (if any) 2202 2203 :return: The peer's certificate 2204 """ 2205 cert = _lib.SSL_get_peer_certificate(self._ssl) 2206 if cert != _ffi.NULL: 2207 return X509._from_raw_x509_ptr(cert) 2208 return None 2209 2210 def get_peer_cert_chain(self): 2211 """ 2212 Retrieve the other side's certificate (if any) 2213 2214 :return: A list of X509 instances giving the peer's certificate chain, 2215 or None if it does not have one. 2216 """ 2217 cert_stack = _lib.SSL_get_peer_cert_chain(self._ssl) 2218 if cert_stack == _ffi.NULL: 2219 return None 2220 2221 result = [] 2222 for i in range(_lib.sk_X509_num(cert_stack)): 2223 # TODO could incref instead of dup here 2224 cert = _lib.X509_dup(_lib.sk_X509_value(cert_stack, i)) 2225 pycert = X509._from_raw_x509_ptr(cert) 2226 result.append(pycert) 2227 return result 2228 2229 def want_read(self): 2230 """ 2231 Checks if more data has to be read from the transport layer to complete 2232 an operation. 2233 2234 :return: True iff more data has to be read 2235 """ 2236 return _lib.SSL_want_read(self._ssl) 2237 2238 def want_write(self): 2239 """ 2240 Checks if there is data to write to the transport layer to complete an 2241 operation. 2242 2243 :return: True iff there is data to write 2244 """ 2245 return _lib.SSL_want_write(self._ssl) 2246 2247 def set_accept_state(self): 2248 """ 2249 Set the connection to work in server mode. The handshake will be 2250 handled automatically by read/write. 2251 2252 :return: None 2253 """ 2254 _lib.SSL_set_accept_state(self._ssl) 2255 2256 def set_connect_state(self): 2257 """ 2258 Set the connection to work in client mode. The handshake will be 2259 handled automatically by read/write. 2260 2261 :return: None 2262 """ 2263 _lib.SSL_set_connect_state(self._ssl) 2264 2265 def get_session(self): 2266 """ 2267 Returns the Session currently used. 2268 2269 :return: An instance of :class:`OpenSSL.SSL.Session` or 2270 :obj:`None` if no session exists. 2271 2272 .. versionadded:: 0.14 2273 """ 2274 session = _lib.SSL_get1_session(self._ssl) 2275 if session == _ffi.NULL: 2276 return None 2277 2278 pysession = Session.__new__(Session) 2279 pysession._session = _ffi.gc(session, _lib.SSL_SESSION_free) 2280 return pysession 2281 2282 def set_session(self, session): 2283 """ 2284 Set the session to be used when the TLS/SSL connection is established. 2285 2286 :param session: A Session instance representing the session to use. 2287 :returns: None 2288 2289 .. versionadded:: 0.14 2290 """ 2291 if not isinstance(session, Session): 2292 raise TypeError("session must be a Session instance") 2293 2294 result = _lib.SSL_set_session(self._ssl, session._session) 2295 if not result: 2296 _raise_current_error() 2297 2298 def _get_finished_message(self, function): 2299 """ 2300 Helper to implement :meth:`get_finished` and 2301 :meth:`get_peer_finished`. 2302 2303 :param function: Either :data:`SSL_get_finished`: or 2304 :data:`SSL_get_peer_finished`. 2305 2306 :return: :data:`None` if the desired message has not yet been 2307 received, otherwise the contents of the message. 2308 :rtype: :class:`bytes` or :class:`NoneType` 2309 """ 2310 # The OpenSSL documentation says nothing about what might happen if the 2311 # count argument given is zero. Specifically, it doesn't say whether 2312 # the output buffer may be NULL in that case or not. Inspection of the 2313 # implementation reveals that it calls memcpy() unconditionally. 2314 # Section 7.1.4, paragraph 1 of the C standard suggests that 2315 # memcpy(NULL, source, 0) is not guaranteed to produce defined (let 2316 # alone desirable) behavior (though it probably does on just about 2317 # every implementation...) 2318 # 2319 # Allocate a tiny buffer to pass in (instead of just passing NULL as 2320 # one might expect) for the initial call so as to be safe against this 2321 # potentially undefined behavior. 2322 empty = _ffi.new("char[]", 0) 2323 size = function(self._ssl, empty, 0) 2324 if size == 0: 2325 # No Finished message so far. 2326 return None 2327 2328 buf = _no_zero_allocator("char[]", size) 2329 function(self._ssl, buf, size) 2330 return _ffi.buffer(buf, size)[:] 2331 2332 def get_finished(self): 2333 """ 2334 Obtain the latest TLS Finished message that we sent. 2335 2336 :return: The contents of the message or :obj:`None` if the TLS 2337 handshake has not yet completed. 2338 :rtype: :class:`bytes` or :class:`NoneType` 2339 2340 .. versionadded:: 0.15 2341 """ 2342 return self._get_finished_message(_lib.SSL_get_finished) 2343 2344 def get_peer_finished(self): 2345 """ 2346 Obtain the latest TLS Finished message that we received from the peer. 2347 2348 :return: The contents of the message or :obj:`None` if the TLS 2349 handshake has not yet completed. 2350 :rtype: :class:`bytes` or :class:`NoneType` 2351 2352 .. versionadded:: 0.15 2353 """ 2354 return self._get_finished_message(_lib.SSL_get_peer_finished) 2355 2356 def get_cipher_name(self): 2357 """ 2358 Obtain the name of the currently used cipher. 2359 2360 :returns: The name of the currently used cipher or :obj:`None` 2361 if no connection has been established. 2362 :rtype: :class:`unicode` or :class:`NoneType` 2363 2364 .. versionadded:: 0.15 2365 """ 2366 cipher = _lib.SSL_get_current_cipher(self._ssl) 2367 if cipher == _ffi.NULL: 2368 return None 2369 else: 2370 name = _ffi.string(_lib.SSL_CIPHER_get_name(cipher)) 2371 return name.decode("utf-8") 2372 2373 def get_cipher_bits(self): 2374 """ 2375 Obtain the number of secret bits of the currently used cipher. 2376 2377 :returns: The number of secret bits of the currently used cipher 2378 or :obj:`None` if no connection has been established. 2379 :rtype: :class:`int` or :class:`NoneType` 2380 2381 .. versionadded:: 0.15 2382 """ 2383 cipher = _lib.SSL_get_current_cipher(self._ssl) 2384 if cipher == _ffi.NULL: 2385 return None 2386 else: 2387 return _lib.SSL_CIPHER_get_bits(cipher, _ffi.NULL) 2388 2389 def get_cipher_version(self): 2390 """ 2391 Obtain the protocol version of the currently used cipher. 2392 2393 :returns: The protocol name of the currently used cipher 2394 or :obj:`None` if no connection has been established. 2395 :rtype: :class:`unicode` or :class:`NoneType` 2396 2397 .. versionadded:: 0.15 2398 """ 2399 cipher = _lib.SSL_get_current_cipher(self._ssl) 2400 if cipher == _ffi.NULL: 2401 return None 2402 else: 2403 version = _ffi.string(_lib.SSL_CIPHER_get_version(cipher)) 2404 return version.decode("utf-8") 2405 2406 def get_protocol_version_name(self): 2407 """ 2408 Retrieve the protocol version of the current connection. 2409 2410 :returns: The TLS version of the current connection, for example 2411 the value for TLS 1.2 would be ``TLSv1.2``or ``Unknown`` 2412 for connections that were not successfully established. 2413 :rtype: :class:`unicode` 2414 """ 2415 version = _ffi.string(_lib.SSL_get_version(self._ssl)) 2416 return version.decode("utf-8") 2417 2418 def get_protocol_version(self): 2419 """ 2420 Retrieve the SSL or TLS protocol version of the current connection. 2421 2422 :returns: The TLS version of the current connection. For example, 2423 it will return ``0x769`` for connections made over TLS version 1. 2424 :rtype: :class:`int` 2425 """ 2426 version = _lib.SSL_version(self._ssl) 2427 return version 2428 2429 @_requires_npn 2430 def get_next_proto_negotiated(self): 2431 """ 2432 Get the protocol that was negotiated by NPN. 2433 2434 :returns: A bytestring of the protocol name. If no protocol has been 2435 negotiated yet, returns an empty string. 2436 2437 .. versionadded:: 0.15 2438 """ 2439 data = _ffi.new("unsigned char **") 2440 data_len = _ffi.new("unsigned int *") 2441 2442 _lib.SSL_get0_next_proto_negotiated(self._ssl, data, data_len) 2443 2444 return _ffi.buffer(data[0], data_len[0])[:] 2445 2446 @_requires_alpn 2447 def set_alpn_protos(self, protos): 2448 """ 2449 Specify the client's ALPN protocol list. 2450 2451 These protocols are offered to the server during protocol negotiation. 2452 2453 :param protos: A list of the protocols to be offered to the server. 2454 This list should be a Python list of bytestrings representing the 2455 protocols to offer, e.g. ``[b'http/1.1', b'spdy/2']``. 2456 """ 2457 # Take the list of protocols and join them together, prefixing them 2458 # with their lengths. 2459 protostr = b''.join( 2460 chain.from_iterable((int2byte(len(p)), p) for p in protos) 2461 ) 2462 2463 # Build a C string from the list. We don't need to save this off 2464 # because OpenSSL immediately copies the data out. 2465 input_str = _ffi.new("unsigned char[]", protostr) 2466 _lib.SSL_set_alpn_protos(self._ssl, input_str, len(protostr)) 2467 2468 @_requires_alpn 2469 def get_alpn_proto_negotiated(self): 2470 """ 2471 Get the protocol that was negotiated by ALPN. 2472 2473 :returns: A bytestring of the protocol name. If no protocol has been 2474 negotiated yet, returns an empty string. 2475 """ 2476 data = _ffi.new("unsigned char **") 2477 data_len = _ffi.new("unsigned int *") 2478 2479 _lib.SSL_get0_alpn_selected(self._ssl, data, data_len) 2480 2481 if not data_len: 2482 return b'' 2483 2484 return _ffi.buffer(data[0], data_len[0])[:] 2485 2486 def request_ocsp(self): 2487 """ 2488 Called to request that the server sends stapled OCSP data, if 2489 available. If this is not called on the client side then the server 2490 will not send OCSP data. Should be used in conjunction with 2491 :meth:`Context.set_ocsp_client_callback`. 2492 """ 2493 rc = _lib.SSL_set_tlsext_status_type( 2494 self._ssl, _lib.TLSEXT_STATUSTYPE_ocsp 2495 ) 2496 _openssl_assert(rc == 1) 2497 2498 2499ConnectionType = deprecated( 2500 Connection, __name__, 2501 "ConnectionType has been deprecated, use Connection instead", 2502 DeprecationWarning 2503) 2504 2505# This is similar to the initialization calls at the end of OpenSSL/crypto.py 2506# but is exercised mostly by the Context initializer. 2507_lib.SSL_library_init() 2508