Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(1)

Side by Side Diff: Doc/library/ssl.rst

Issue 10639: reindent.py converts newlines to platform default
Patch Set: Created 8 years, 8 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « Doc/library/sqlite3.rst ('k') | Doc/library/stat.rst » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 :mod:`ssl` --- TLS/SSL wrapper for socket objects 1 :mod:`ssl` --- TLS/SSL wrapper for socket objects
2 ================================================= 2 =================================================
3 3
4 .. module:: ssl 4 .. module:: ssl
5 :synopsis: TLS/SSL wrapper for socket objects 5 :synopsis: TLS/SSL wrapper for socket objects
6 6
7 .. moduleauthor:: Bill Janssen <bill.janssen@gmail.com> 7 .. moduleauthor:: Bill Janssen <bill.janssen@gmail.com>
8 .. sectionauthor:: Bill Janssen <bill.janssen@gmail.com> 8 .. sectionauthor:: Bill Janssen <bill.janssen@gmail.com>
9 9
10 10
(...skipping 367 matching lines...) Expand 10 before | Expand all | Expand 10 after
378 .. versionadded:: 3.2 378 .. versionadded:: 3.2
379 379
380 .. data:: HAS_SNI 380 .. data:: HAS_SNI
381 381
382 Whether the OpenSSL library has built-in support for the *Server Name 382 Whether the OpenSSL library has built-in support for the *Server Name
383 Indication* extension to the SSLv3 and TLSv1 protocols (as defined in 383 Indication* extension to the SSLv3 and TLSv1 protocols (as defined in
384 :rfc:`4366`). When true, you can use the *server_hostname* argument to 384 :rfc:`4366`). When true, you can use the *server_hostname* argument to
385 :meth:`SSLContext.wrap_socket`. 385 :meth:`SSLContext.wrap_socket`.
386 386
387 .. versionadded:: 3.2 387 .. versionadded:: 3.2
388
389 .. data:: CHANNEL_BINDING_TYPES
390
391 List of supported TLS channel binding types. Strings in this list
392 can be used as arguments to :meth:`SSLSocket.get_channel_binding`.
393
394 .. versionadded:: 3.3
395 388
396 .. data:: OPENSSL_VERSION 389 .. data:: OPENSSL_VERSION
397 390
398 The version string of the OpenSSL library loaded by the interpreter:: 391 The version string of the OpenSSL library loaded by the interpreter::
399 392
400 >>> ssl.OPENSSL_VERSION 393 >>> ssl.OPENSSL_VERSION
401 'OpenSSL 0.9.8k 25 Mar 2009' 394 'OpenSSL 0.9.8k 25 Mar 2009'
402 395
403 .. versionadded:: 3.2 396 .. versionadded:: 3.2
404 397
(...skipping 35 matching lines...) Expand 10 before | Expand all | Expand 10 after
440 - :meth:`~socket.socket.gettimeout()`, :meth:`~socket.socket.settimeout()`, 433 - :meth:`~socket.socket.gettimeout()`, :meth:`~socket.socket.settimeout()`,
441 :meth:`~socket.socket.setblocking()` 434 :meth:`~socket.socket.setblocking()`
442 - :meth:`~socket.socket.listen()` 435 - :meth:`~socket.socket.listen()`
443 - :meth:`~socket.socket.makefile()` 436 - :meth:`~socket.socket.makefile()`
444 - :meth:`~socket.socket.recv()`, :meth:`~socket.socket.recv_into()` 437 - :meth:`~socket.socket.recv()`, :meth:`~socket.socket.recv_into()`
445 (but passing a non-zero ``flags`` argument is not allowed) 438 (but passing a non-zero ``flags`` argument is not allowed)
446 - :meth:`~socket.socket.send()`, :meth:`~socket.socket.sendall()` (with 439 - :meth:`~socket.socket.send()`, :meth:`~socket.socket.sendall()` (with
447 the same limitation) 440 the same limitation)
448 - :meth:`~socket.socket.shutdown()` 441 - :meth:`~socket.socket.shutdown()`
449 442
450 However, since the SSL (and TLS) protocol has its own framing atop 443 They also have the following additional methods and attributes:
451 of TCP, the SSL sockets abstraction can, in certain respects, diverge from
452 the specification of normal, OS-level sockets. See especially the
453 :ref:`notes on non-blocking sockets <ssl-nonblocking>`.
454
455 SSL sockets also have the following additional methods and attributes:
456 444
457 .. method:: SSLSocket.do_handshake() 445 .. method:: SSLSocket.do_handshake()
458 446
459 Perform the SSL setup handshake. 447 Performs the SSL setup handshake. If the socket is non-blocking, this method
448 may raise :exc:`SSLError` with the value of the exception instance's
449 ``args[0]`` being either :const:`SSL_ERROR_WANT_READ` or
450 :const:`SSL_ERROR_WANT_WRITE`, and should be called again until it stops
451 raising those exceptions. Here's an example of how to do that::
452
453 while True:
454 try:
455 sock.do_handshake()
456 break
457 except ssl.SSLError as err:
458 if err.args[0] == ssl.SSL_ERROR_WANT_READ:
459 select.select([sock], [], [])
460 elif err.args[0] == ssl.SSL_ERROR_WANT_WRITE:
461 select.select([], [sock], [])
462 else:
463 raise
460 464
461 .. method:: SSLSocket.getpeercert(binary_form=False) 465 .. method:: SSLSocket.getpeercert(binary_form=False)
462 466
463 If there is no certificate for the peer on the other end of the connection, 467 If there is no certificate for the peer on the other end of the connection,
464 returns ``None``. 468 returns ``None``.
465 469
466 If the parameter ``binary_form`` is :const:`False`, and a certificate was 470 If the parameter ``binary_form`` is :const:`False`, and a certificate was
467 received from the peer, this method returns a :class:`dict` instance. If the 471 received from the peer, this method returns a :class:`dict` instance. If the
468 certificate was not validated, the dict is empty. If the certificate was 472 certificate was not validated, the dict is empty. If the certificate was
469 validated, it returns a dict with the keys ``subject`` (the principal for 473 validated, it returns a dict with the keys ``subject`` (the principal for
(...skipping 25 matching lines...) Expand all
495 .. versionchanged:: 3.2 499 .. versionchanged:: 3.2
496 The returned dictionary includes additional items such as ``issuer`` 500 The returned dictionary includes additional items such as ``issuer``
497 and ``notBefore``. 501 and ``notBefore``.
498 502
499 .. method:: SSLSocket.cipher() 503 .. method:: SSLSocket.cipher()
500 504
501 Returns a three-value tuple containing the name of the cipher being used, the 505 Returns a three-value tuple containing the name of the cipher being used, the
502 version of the SSL protocol that defines its use, and the number of secret 506 version of the SSL protocol that defines its use, and the number of secret
503 bits being used. If no connection has been established, returns ``None``. 507 bits being used. If no connection has been established, returns ``None``.
504 508
505 .. method:: SSLSocket.get_channel_binding(cb_type="tls-unique")
506
507 Get channel binding data for current connection, as a bytes object. Returns
508 ``None`` if not connected or the handshake has not been completed.
509
510 The *cb_type* parameter allow selection of the desired channel binding
511 type. Valid channel binding types are listed in the
512 :data:`CHANNEL_BINDING_TYPES` list. Currently only the 'tls-unique' channel
513 binding, defined by :rfc:`5929`, is supported. :exc:`ValueError` will be
514 raised if an unsupported channel binding type is requested.
515
516 .. versionadded:: 3.3
517 509
518 .. method:: SSLSocket.unwrap() 510 .. method:: SSLSocket.unwrap()
519 511
520 Performs the SSL shutdown handshake, which removes the TLS layer from the 512 Performs the SSL shutdown handshake, which removes the TLS layer from the
521 underlying socket, and returns the underlying socket object. This can be 513 underlying socket, and returns the underlying socket object. This can be
522 used to go from encrypted operation over a connection to unencrypted. The 514 used to go from encrypted operation over a connection to unencrypted. The
523 returned socket should always be used for further communication with the 515 returned socket should always be used for further communication with the
524 other side of the connection, rather than the original socket. 516 other side of the connection, rather than the original socket.
525 517
526 518
(...skipping 421 matching lines...) Expand 10 before | Expand all | Expand 10 after
948 if not do_something(connstream, data): 940 if not do_something(connstream, data):
949 # we'll assume do_something returns False 941 # we'll assume do_something returns False
950 # when we're finished with client 942 # when we're finished with client
951 break 943 break
952 data = connstream.recv(1024) 944 data = connstream.recv(1024)
953 # finished with client 945 # finished with client
954 946
955 And go back to listening for new client connections (of course, a real server 947 And go back to listening for new client connections (of course, a real server
956 would probably handle each client connection in a separate thread, or put 948 would probably handle each client connection in a separate thread, or put
957 the sockets in non-blocking mode and use an event loop). 949 the sockets in non-blocking mode and use an event loop).
958
959
960 .. _ssl-nonblocking:
961
962 Notes on non-blocking sockets
963 -----------------------------
964
965 When working with non-blocking sockets, there are several things you need
966 to be aware of:
967
968 - Calling :func:`~select.select` tells you that the OS-level socket can be
969 read from (or written to), but it does not imply that there is sufficient
970 data at the upper SSL layer. For example, only part of an SSL frame might
971 have arrived. Therefore, you must be ready to handle :meth:`SSLSocket.recv`
972 and :meth:`SSLSocket.send` failures, and retry after another call to
973 :func:`~select.select`.
974
975 (of course, similar provisions apply when using other primitives such as
976 :func:`~select.poll`)
977
978 - The SSL handshake itself will be non-blocking: the
979 :meth:`SSLSocket.do_handshake` method has to be retried until it returns
980 successfully. Here is a synopsis using :func:`~select.select` to wait for
981 the socket's readiness::
982
983 while True:
984 try:
985 sock.do_handshake()
986 break
987 except ssl.SSLError as err:
988 if err.args[0] == ssl.SSL_ERROR_WANT_READ:
989 select.select([sock], [], [])
990 elif err.args[0] == ssl.SSL_ERROR_WANT_WRITE:
991 select.select([], [sock], [])
992 else:
993 raise
994 950
995 951
996 .. _ssl-security: 952 .. _ssl-security:
997 953
998 Security considerations 954 Security considerations
999 ----------------------- 955 -----------------------
1000 956
1001 Verifying certificates 957 Verifying certificates
1002 ^^^^^^^^^^^^^^^^^^^^^^ 958 ^^^^^^^^^^^^^^^^^^^^^^
1003 959
(...skipping 44 matching lines...) Expand 10 before | Expand all | Expand 10 after
1048 Steve Kent 1004 Steve Kent
1049 1005
1050 `RFC 1750: Randomness Recommendations for Security <http://www.ietf.org/rfc/r fc1750>`_ 1006 `RFC 1750: Randomness Recommendations for Security <http://www.ietf.org/rfc/r fc1750>`_
1051 D. Eastlake et. al. 1007 D. Eastlake et. al.
1052 1008
1053 `RFC 3280: Internet X.509 Public Key Infrastructure Certificate and CRL Profi le <http://www.ietf.org/rfc/rfc3280>`_ 1009 `RFC 3280: Internet X.509 Public Key Infrastructure Certificate and CRL Profi le <http://www.ietf.org/rfc/rfc3280>`_
1054 Housley et. al. 1010 Housley et. al.
1055 1011
1056 `RFC 4366: Transport Layer Security (TLS) Extensions <http://www.ietf.org/rfc /rfc4366>`_ 1012 `RFC 4366: Transport Layer Security (TLS) Extensions <http://www.ietf.org/rfc /rfc4366>`_
1057 Blake-Wilson et. al. 1013 Blake-Wilson et. al.
OLDNEW
« no previous file with comments | « Doc/library/sqlite3.rst ('k') | Doc/library/stat.rst » ('j') | no next file with comments »

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+