Note

Some behavior may be platform dependent, since calls are made to theoperating system socket APIs. The installed version of OpenSSL may alsocause variations in behavior. For example, TLSv1.1 and TLSv1.2 come withopenssl version 1.0.1.

Warning

Don’t use this module without reading theSecurity considerations. Doing somay lead to a false sense of security, as the default settings of thessl module are not necessarily appropriate for your application.

18.2.1. Functions, Constants, and Exceptions¶

exceptionssl.SSLError¶

Raised to signal an error from the underlying SSL implementation(currently provided by the OpenSSL library). This signifies someproblem in the higher-level encryption and authentication layer that’ssuperimposed on the underlying network connection. This erroris a subtype ofOSError. The error code and message ofSSLError instances are provided by the OpenSSL library.

Changed in version 3.3:SSLError used to be a subtype ofsocket.error.

library¶

A string mnemonic designating the OpenSSL submodule in which the erroroccurred, such asSSL,PEM orX509. The range of possiblevalues depends on the OpenSSL version.

New in version 3.3.

reason¶

A string mnemonic designating the reason this error occurred, forexampleCERTIFICATE_VERIFY_FAILED. The range of possiblevalues depends on the OpenSSL version.

New in version 3.3.

exceptionssl.SSLZeroReturnError¶

A subclass ofSSLError raised when trying to read or write andthe SSL connection has been closed cleanly. Note that this doesn’tmean that the underlying transport (read TCP) has been closed.

New in version 3.3.

exceptionssl.SSLWantReadError¶

A subclass ofSSLError raised by anon-blocking SSL socket when trying to read or write data, but more data needsto be received on the underlying TCP transport before the request can befulfilled.

New in version 3.3.

exceptionssl.SSLWantWriteError¶

A subclass ofSSLError raised by anon-blocking SSL socket when trying to read or write data, but more data needsto be sent on the underlying TCP transport before the request can befulfilled.

New in version 3.3.

exceptionssl.SSLSyscallError¶

A subclass ofSSLError raised when a system error was encounteredwhile trying to fulfill an operation on a SSL socket. Unfortunately,there is no easy way to inspect the original errno number.

New in version 3.3.

exceptionssl.SSLEOFError¶

A subclass ofSSLError raised when the SSL connection has beenterminated abruptly. Generally, you shouldn’t try to reuse the underlyingtransport when this error is encountered.

New in version 3.3.

exceptionssl.CertificateError¶

Raised to signal an error with a certificate (such as mismatchinghostname). Certificate errors detected by OpenSSL, though, raiseanSSLError.

18.2.2. SSL Sockets¶

classssl.SSLSocket(socket.socket)¶

SSL sockets provide the following methods ofSocket Objects:

• accept()
• bind()
• close()
• connect()
• detach()
• fileno()
• getpeername(),getsockname()
• getsockopt(),setsockopt()
• gettimeout(),settimeout(),setblocking()
• listen()
• makefile()
• recv(),recv_into()(but passing a non-zeroflags argument is not allowed)
• send(),sendall() (withthe same limitation)
• sendfile() (butos.sendfile will be usedfor plain-text sockets only, elsesend() will be used)
• shutdown()

However, since the SSL (and TLS) protocol has its own framing atopof TCP, the SSL sockets abstraction can, in certain respects, diverge fromthe specification of normal, OS-level sockets. See especially thenotes on non-blocking sockets.

Usually,SSLSocket are not created directly, but using thewrap_socket() function or theSSLContext.wrap_socket() method.

Changed in version 3.5:Thesendfile() method was added.

Changed in version 3.5:Theshutdown() does not reset the socket timeout each time bytesare received or sent. The socket timeout is now to maximum total durationof the shutdown.

SSL sockets also have the following additional methods and attributes:

SSLSocket.read(len=1024,buffer=None)¶

Read up tolen bytes of data from the SSL socket and return the result asabytes instance. Ifbuffer is specified, then read into the bufferinstead, and return the number of bytes read.

RaiseSSLWantReadError orSSLWantWriteError if the socket isnon-blocking and the read would block.

As at any time a re-negotiation is possible, a call toread() can alsocause write operations.

Changed in version 3.5:The socket timeout is no more reset each time bytes are received or sent.The socket timeout is now to maximum total duration to read up tolenbytes.

SSLSocket.write(buf)¶

Writebuf to the SSL socket and return the number of bytes written. Thebuf argument must be an object supporting the buffer interface.

RaiseSSLWantReadError orSSLWantWriteError if the socket isnon-blocking and the write would block.

As at any time a re-negotiation is possible, a call towrite() canalso cause read operations.

Changed in version 3.5:The socket timeout is no more reset each time bytes are received or sent.The socket timeout is now to maximum total duration to writebuf.

SSLSocket.do_handshake()¶

Perform the SSL setup handshake.

Changed in version 3.4:The handshake method also performsmatch_hostname() when thecheck_hostname attribute of the socket’scontext is true.

Changed in version 3.5:The socket timeout is no more reset each time bytes are received or sent.The socket timeout is now to maximum total duration of the handshake.

SSLSocket.getpeercert(binary_form=False)¶

If there is no certificate for the peer on the other end of the connection,returnNone. If the SSL handshake hasn’t been done yet, raiseValueError.

If thebinary_form parameter isFalse, and a certificate wasreceived from the peer, this method returns adict instance. If thecertificate was not validated, the dict is empty. If the certificate wasvalidated, it returns a dict with several keys, amongst themsubject(the principal for which the certificate was issued) andissuer(the principal issuing the certificate). If a certificate contains aninstance of theSubject Alternative Name extension (seeRFC 3280),there will also be asubjectAltName key in the dictionary.

Thesubject andissuer fields are tuples containing the sequenceof relative distinguished names (RDNs) given in the certificate’s datastructure for the respective fields, and each RDN is a sequence ofname-value pairs. Here is a real-world example:

{'issuer':((('countryName','IL'),),(('organizationName','StartCom Ltd.'),),(('organizationalUnitName','Secure Digital Certificate Signing'),),(('commonName','StartCom Class 2 Primary Intermediate Server CA'),)),'notAfter':'Nov 22 08:15:19 2013 GMT','notBefore':'Nov 21 03:09:52 2011 GMT','serialNumber':'95F0','subject':((('description','571208-SLe257oHY9fVQ07Z'),),(('countryName','US'),),(('stateOrProvinceName','California'),),(('localityName','San Francisco'),),(('organizationName','Electronic Frontier Foundation, Inc.'),),(('commonName','*.eff.org'),),(('emailAddress','hostmaster@eff.org'),)),'subjectAltName':(('DNS','*.eff.org'),('DNS','eff.org')),'version':3}

Note

To validate a certificate for a particular service, you can use thematch_hostname() function.

If thebinary_form parameter isTrue, and a certificate wasprovided, this method returns the DER-encoded form of the entire certificateas a sequence of bytes, orNone if the peer did not provide acertificate. Whether the peer provides a certificate depends on the SSLsocket’s role:

• for a client SSL socket, the server will always provide a certificate,regardless of whether validation was required;
• for a server SSL socket, the client will only provide a certificatewhen requested by the server; thereforegetpeercert() will returnNone if you usedCERT_NONE (rather thanCERT_OPTIONAL orCERT_REQUIRED).

Changed in version 3.2:The returned dictionary includes additional items such asissuerandnotBefore.

Changed in version 3.4:ValueError is raised when the handshake isn’t done.The returned dictionary includes additional X509v3 extension items such ascrlDistributionPoints,caIssuers andOCSP URIs.

SSLSocket.cipher()¶

Returns a three-value tuple containing the name of the cipher being used, theversion of the SSL protocol that defines its use, and the number of secretbits being used. If no connection has been established, returnsNone.

SSLSocket.shared_ciphers()¶

Return the list of ciphers shared by the client during the handshake. Eachentry of the returned list is a three-value tuple containing the name of thecipher, the version of the SSL protocol that defines its use, and the numberof secret bits the cipher uses.shared_ciphers() returnsNone if no connection has been established or the socket is a clientsocket.

New in version 3.5.

SSLSocket.compression()¶

Return the compression algorithm being used as a string, orNoneif the connection isn’t compressed.

If the higher-level protocol supports its own compression mechanism,you can useOP_NO_COMPRESSION to disable SSL-level compression.

New in version 3.3.

SSLSocket.get_channel_binding(cb_type="tls-unique")¶

Get channel binding data for current connection, as a bytes object. ReturnsNone if not connected or the handshake has not been completed.

Thecb_type parameter allow selection of the desired channel bindingtype. Valid channel binding types are listed in theCHANNEL_BINDING_TYPES list. Currently only the ‘tls-unique’ channelbinding, defined byRFC 5929, is supported.ValueError will beraised if an unsupported channel binding type is requested.

New in version 3.3.

SSLSocket.selected_alpn_protocol()¶

Return the protocol that was selected during the TLS handshake. IfSSLContext.set_alpn_protocols() was not called, if the other party doesnot support ALPN, if this socket does not support any of the client’sproposed protocols, or if the handshake has not happened yet,None isreturned.

New in version 3.5.

SSLSocket.selected_npn_protocol()¶

Return the higher-level protocol that was selected during the TLS/SSLhandshake. IfSSLContext.set_npn_protocols() was not called, orif the other party does not support NPN, or if the handshake has not yethappened, this will returnNone.

New in version 3.3.

SSLSocket.unwrap()¶

Performs the SSL shutdown handshake, which removes the TLS layer from theunderlying socket, and returns the underlying socket object. This can beused to go from encrypted operation over a connection to unencrypted. Thereturned socket should always be used for further communication with theother side of the connection, rather than the original socket.

SSLSocket.version()¶

Return the actual SSL protocol version negotiated by the connectionas a string, orNone is no secure connection is established.As of this writing, possible return values include"SSLv2","SSLv3","TLSv1","TLSv1.1" and"TLSv1.2".Recent OpenSSL versions may define more return values.

New in version 3.5.

SSLSocket.pending()¶

Returns the number of already decrypted bytes available for read, pending onthe connection.

SSLSocket.context¶

TheSSLContext object this SSL socket is tied to. If the SSLsocket was created using the top-levelwrap_socket() function(rather thanSSLContext.wrap_socket()), this is a custom contextobject created for this SSL socket.

New in version 3.2.

SSLSocket.server_side¶

A boolean which isTrue for server-side sockets andFalse forclient-side sockets.

New in version 3.2.

SSLSocket.server_hostname¶

Hostname of the server:str type, orNone for server-sidesocket or if the hostname was not specified in the constructor.

New in version 3.2.

18.2.3. SSL Contexts¶

An SSL context holds various data longer-lived than single SSL connections,such as SSL configuration options, certificate(s) and private key(s).It also manages a cache of SSL sessions for server-side sockets, in orderto speed up repeated connections from the same clients.

classssl.SSLContext(protocol=PROTOCOL_TLS)¶

Create a new SSL context. You may passprotocol which must be oneof thePROTOCOL_* constants defined in this module.PROTOCOL_TLS is currently recommended for maximuminteroperability and default value.

See also

create_default_context() lets thessl module choosesecurity settings for a given purpose.

Changed in version 3.5.3:PROTOCOL_TLS is the default value.

SSLContext objects have the following methods and attributes:

SSLContext.cert_store_stats()¶

Get statistics about quantities of loaded X.509 certificates, count ofX.509 certificates flagged as CA certificates and certificate revocationlists as dictionary.

Example for a context with one CA cert and one other cert:

>>>context.cert_store_stats(){'crl': 0, 'x509_ca': 1, 'x509': 2}

New in version 3.4.

SSLContext.load_cert_chain(certfile,keyfile=None,password=None)¶

Load a private key and the corresponding certificate. Thecertfilestring must be the path to a single file in PEM format containing thecertificate as well as any number of CA certificates needed to establishthe certificate’s authenticity. Thekeyfile string, if present, mustpoint to a file containing the private key in. Otherwise the privatekey will be taken fromcertfile as well. See the discussion ofCertificates for more information on how the certificateis stored in thecertfile.

Thepassword argument may be a function to call to get the password fordecrypting the private key. It will only be called if the private key isencrypted and a password is necessary. It will be called with no arguments,and it should return a string, bytes, or bytearray. If the return value isa string it will be encoded as UTF-8 before using it to decrypt the key.Alternatively a string, bytes, or bytearray value may be supplied directlyas thepassword argument. It will be ignored if the private key is notencrypted and no password is needed.

If thepassword argument is not specified and a password is required,OpenSSL’s built-in password prompting mechanism will be used tointeractively prompt the user for a password.

AnSSLError is raised if the private key doesn’tmatch with the certificate.

Changed in version 3.3:New optional argumentpassword.

SSLContext.load_default_certs(purpose=Purpose.SERVER_AUTH)¶

Load a set of default “certification authority” (CA) certificates fromdefault locations. On Windows it loads CA certs from theCA andROOT system stores. On other systems it callsSSLContext.set_default_verify_paths(). In the future the method mayload CA certificates from other locations, too.

Thepurpose flag specifies what kind of CA certificates are loaded. Thedefault settingsPurpose.SERVER_AUTH loads certificates, that areflagged and trusted for TLS web server authentication (client sidesockets).Purpose.CLIENT_AUTH loads CA certificates for clientcertificate verification on the server side.

New in version 3.4.

SSLContext.load_verify_locations(cafile=None,capath=None,cadata=None)¶

Load a set of “certification authority” (CA) certificates used to validateother peers’ certificates whenverify_mode is other thanCERT_NONE. At least one ofcafile orcapath must be specified.

This method can also load certification revocation lists (CRLs) in PEM orDER format. In order to make use of CRLs,SSLContext.verify_flagsmust be configured properly.

Thecafile string, if present, is the path to a file of concatenatedCA certificates in PEM format. See the discussion ofCertificates for more information about how to arrange thecertificates in this file.

Thecapath string, if present, isthe path to a directory containing several CA certificates in PEM format,following anOpenSSL specific layout.

Thecadata object, if present, is either an ASCII string of one or morePEM-encoded certificates or abytes-like object of DER-encodedcertificates. Like withcapath extra lines around PEM-encodedcertificates are ignored but at least one certificate must be present.

Changed in version 3.4:New optional argumentcadata

SSLContext.get_ca_certs(binary_form=False)¶

Get a list of loaded “certification authority” (CA) certificates. If thebinary_form parameter isFalse each listentry is a dict like the output ofSSLSocket.getpeercert(). Otherwisethe method returns a list of DER-encoded certificates. The returned listdoes not contain certificates fromcapath unless a certificate wasrequested and loaded by a SSL connection.

Note

Certificates in a capath directory aren’t loaded unless they havebeen used at least once.

New in version 3.4.

SSLContext.set_default_verify_paths()¶

Load a set of default “certification authority” (CA) certificates froma filesystem path defined when building the OpenSSL library. Unfortunately,there’s no easy way to know whether this method succeeds: no error isreturned if no certificates are to be found. When the OpenSSL library isprovided as part of the operating system, though, it is likely to beconfigured properly.

SSLContext.set_ciphers(ciphers)¶

Set the available ciphers for sockets created with this context.It should be a string in theOpenSSL cipher list format.If no cipher can be selected (because compile-time options or otherconfiguration forbids use of all the specified ciphers), anSSLError will be raised.

Note

when connected, theSSLSocket.cipher() method of SSL sockets willgive the currently selected cipher.

SSLContext.set_alpn_protocols(protocols)¶

Specify which protocols the socket should advertise during the SSL/TLShandshake. It should be a list of ASCII strings, like['http/1.1','spdy/2'], ordered by preference. The selection of a protocol will happenduring the handshake, and will play out according toRFC 7301. After asuccessful handshake, theSSLSocket.selected_alpn_protocol() method willreturn the agreed-upon protocol.

This method will raiseNotImplementedError ifHAS_ALPN isFalse.

OpenSSL 1.1.0+ will abort the handshake and raiseSSLError whenboth sides support ALPN but cannot agree on a protocol.

New in version 3.5.

SSLContext.set_npn_protocols(protocols)¶

Specify which protocols the socket should advertise during the SSL/TLShandshake. It should be a list of strings, like['http/1.1','spdy/2'],ordered by preference. The selection of a protocol will happen during thehandshake, and will play out according to theNPN draft specification. After asuccessful handshake, theSSLSocket.selected_npn_protocol() method willreturn the agreed-upon protocol.

This method will raiseNotImplementedError ifHAS_NPN isFalse.

New in version 3.3.

SSLContext.set_servername_callback(server_name_callback)¶

Register a callback function that will be called after the TLS Client Hellohandshake message has been received by the SSL/TLS server when the TLS clientspecifies a server name indication. The server name indication mechanismis specified inRFC 6066 section 3 - Server Name Indication.

Only one callback can be set perSSLContext. Ifserver_name_callbackisNone then the callback is disabled. Calling this function asubsequent time will disable the previously registered callback.

The callback function,server_name_callback, will be called with threearguments; the first being thessl.SSLSocket, the second is a stringthat represents the server name that the client is intending to communicate(orNone if the TLS Client Hello does not contain a server name)and the third argument is the originalSSLContext. The server nameargument is the IDNA decoded server name.

A typical use of this callback is to change thessl.SSLSocket’sSSLSocket.context attribute to a new object of typeSSLContext representing a certificate chain that matches the servername.

Due to the early negotiation phase of the TLS connection, only limitedmethods and attributes are usable likeSSLSocket.selected_alpn_protocol() andSSLSocket.context.SSLSocket.getpeercert(),SSLSocket.getpeercert(),SSLSocket.cipher() andSSLSocket.compress() methods require thatthe TLS connection has progressed beyond the TLS Client Hello and thereforewill not contain return meaningful values nor can they be called safely.

Theserver_name_callback function must returnNone to allow theTLS negotiation to continue. If a TLS failure is required, a constantALERT_DESCRIPTION_* can bereturned. Other return values will result in a TLS fatal error withALERT_DESCRIPTION_INTERNAL_ERROR.

If there is an IDNA decoding error on the server name, the TLS connectionwill terminate with anALERT_DESCRIPTION_INTERNAL_ERROR fatal TLSalert message to the client.

If an exception is raised from theserver_name_callback function the TLSconnection will terminate with a fatal TLS alert messageALERT_DESCRIPTION_HANDSHAKE_FAILURE.

This method will raiseNotImplementedError if the OpenSSL libraryhad OPENSSL_NO_TLSEXT defined when it was built.

New in version 3.4.

SSLContext.load_dh_params(dhfile)¶

Load the key generation parameters for Diffie-Helman (DH) key exchange.Using DH key exchange improves forward secrecy at the expense ofcomputational resources (both on the server and on the client).Thedhfile parameter should be the path to a file containing DHparameters in PEM format.

This setting doesn’t apply to client sockets. You can also use theOP_SINGLE_DH_USE option to further improve security.

New in version 3.3.

SSLContext.set_ecdh_curve(curve_name)¶

Set the curve name for Elliptic Curve-based Diffie-Hellman (ECDH) keyexchange. ECDH is significantly faster than regular DH while arguablyas secure. Thecurve_name parameter should be a string describinga well-known elliptic curve, for exampleprime256v1 for a widelysupported curve.

This setting doesn’t apply to client sockets. You can also use theOP_SINGLE_ECDH_USE option to further improve security.

This method is not available ifHAS_ECDH isFalse.

New in version 3.3.

See also

SSL/TLS & Perfect Forward Secrecy

Vincent Bernat.

SSLContext.wrap_socket(sock,server_side=False,do_handshake_on_connect=True,suppress_ragged_eofs=True,server_hostname=None)¶

Wrap an existing Python socketsock and return anSSLSocketobject.sock must be aSOCK_STREAM socket; other sockettypes are unsupported.

The returned SSL socket is tied to the context, its settings andcertificates. The parametersserver_side,do_handshake_on_connectandsuppress_ragged_eofs have the same meaning as in the top-levelwrap_socket() function.

On client connections, the optional parameterserver_hostname specifiesthe hostname of the service which we are connecting to. This allows asingle server to host multiple SSL-based services with distinct certificates,quite similarly to HTTP virtual hosts. Specifyingserver_hostname willraise aValueError ifserver_side is true.

Changed in version 3.5:Always allow a server_hostname to be passed, even if OpenSSL does nothave SNI.

SSLContext.wrap_bio(incoming,outgoing,server_side=False,server_hostname=None)¶

Create a newSSLObject instance by wrapping the BIO objectsincoming andoutgoing. The SSL routines will read input data from theincoming BIO and write data to the outgoing BIO.

Theserver_side andserver_hostname parameters have the same meaning asinSSLContext.wrap_socket().

SSLContext.session_stats()¶

Get statistics about the SSL sessions created or managed by this context.A dictionary is returned which maps the names of eachpiece of information to theirnumeric values. For example, here is the total number of hits and missesin the session cache since the context was created:

>>>stats=context.session_stats()>>>stats['hits'],stats['misses'](0, 0)

SSLContext.check_hostname¶

Whether to match the peer cert’s hostname withmatch_hostname() inSSLSocket.do_handshake(). The context’sverify_mode must be set toCERT_OPTIONAL orCERT_REQUIRED, and you must passserver_hostname towrap_socket() in order to match the hostname.

Example:

importsocket,sslcontext=ssl.SSLContext(ssl.PROTOCOL_TLSv1)context.verify_mode=ssl.CERT_REQUIREDcontext.check_hostname=Truecontext.load_default_certs()s=socket.socket(socket.AF_INET,socket.SOCK_STREAM)ssl_sock=context.wrap_socket(s,server_hostname='www.verisign.com')ssl_sock.connect(('www.verisign.com',443))

New in version 3.4.

Note

This features requires OpenSSL 0.9.8f or newer.

SSLContext.options¶

An integer representing the set of SSL options enabled on this context.The default value isOP_ALL, but you can specify other optionssuch asOP_NO_SSLv2 by ORing them together.

Note

With versions of OpenSSL older than 0.9.8m, it is only possibleto set options, not to clear them. Attempting to clear an option(by resetting the corresponding bits) will raise aValueError.

SSLContext.protocol¶

The protocol version chosen when constructing the context. This attributeis read-only.

SSLContext.verify_flags¶

The flags for certificate verification operations. You can set flags likeVERIFY_CRL_CHECK_LEAF by ORing them together. By default OpenSSLdoes neither require nor verify certificate revocation lists (CRLs).Available only with openssl version 0.9.8+.

New in version 3.4.

SSLContext.verify_mode¶

Whether to try to verify other peers’ certificates and how to behaveif verification fails. This attribute must be one ofCERT_NONE,CERT_OPTIONAL orCERT_REQUIRED.

18.2.4. Certificates¶

Certificates in general are part of a public-key / private-key system. In thissystem, eachprincipal, (which may be a machine, or a person, or anorganization) is assigned a unique two-part encryption key. One part of the keyis public, and is called thepublic key; the other part is kept secret, and iscalled theprivate key. The two parts are related, in that if you encrypt amessage with one of the parts, you can decrypt it with the other part, andonly with the other part.

A certificate contains information about two principals. It contains the nameof asubject, and the subject’s public key. It also contains a statement by asecond principal, theissuer, that the subject is who he claims to be, andthat this is indeed the subject’s public key. The issuer’s statement is signedwith the issuer’s private key, which only the issuer knows. However, anyone canverify the issuer’s statement by finding the issuer’s public key, decrypting thestatement with it, and comparing it to the other information in the certificate.The certificate also contains information about the time period over which it isvalid. This is expressed as two fields, called “notBefore” and “notAfter”.

In the Python use of certificates, a client or server can use a certificate toprove who they are. The other side of a network connection can also be requiredto produce a certificate, and that certificate can be validated to thesatisfaction of the client or server that requires such validation. Theconnection attempt can be set to raise an exception if the validation fails.Validation is done automatically, by the underlying OpenSSL framework; theapplication need not concern itself with its mechanics. But the applicationdoes usually need to provide sets of certificates to allow this process to takeplace.

Python uses files to contain certificates. They should be formatted as “PEM”(seeRFC 1422), which is a base-64 encoded form wrapped with a header lineand a footer line:

-----BEGINCERTIFICATE-----...(certificateinbase64PEMencoding)...-----ENDCERTIFICATE-----

-----BEGINCERTIFICATE-----...(certificateforyourserver)...-----ENDCERTIFICATE----------BEGINCERTIFICATE-----...(thecertificatefortheCA)...-----ENDCERTIFICATE----------BEGINCERTIFICATE-----...(therootcertificatefortheCA's issuer)...-----ENDCERTIFICATE-----

-----BEGINRSAPRIVATEKEY-----...(privatekeyinbase64encoding)...-----ENDRSAPRIVATEKEY----------BEGINCERTIFICATE-----...(certificateinbase64PEMencoding)...-----ENDCERTIFICATE-----

%opensslreq-new-x509-days365-nodes-outcert.pem-keyoutcert.pemGeneratinga1024bitRSAprivatekey.......++++++.............................++++++writingnewprivatekeyto'cert.pem'-----Youareabouttobeaskedtoenterinformationthatwillbeincorporatedintoyourcertificaterequest.WhatyouareabouttoenteriswhatiscalledaDistinguishedNameoraDN.TherearequiteafewfieldsbutyoucanleavesomeblankForsomefieldstherewillbeadefaultvalue,Ifyouenter'.',thefieldwillbeleftblank.-----CountryName(2lettercode)[AU]:USStateorProvinceName(fullname)[Some-State]:MyStateLocalityName(eg,city)[]:SomeCityOrganizationName(eg,company)[InternetWidgitsPtyLtd]:MyOrganization,Inc.OrganizationalUnitName(eg,section)[]:MyGroupCommonName(eg,YOURname)[]:myserver.mygroup.myorganization.comEmailAddress[]:ops@myserver.mygroup.myorganization.com%

18.2.5. Examples¶

try:importsslexceptImportError:passelse:...# do something that requires SSL support

>>>context=ssl.create_default_context()

>>>context=ssl.SSLContext(ssl.PROTOCOL_TLS)>>>context.verify_mode=ssl.CERT_REQUIRED>>>context.check_hostname=True>>>context.load_verify_locations("/etc/ssl/certs/ca-bundle.crt")

>>>conn=context.wrap_socket(socket.socket(socket.AF_INET),...server_hostname="www.python.org")>>>conn.connect(("www.python.org",443))

>>>cert=conn.getpeercert()

>>>pprint.pprint(cert){'OCSP': ('http://ocsp.digicert.com',), 'caIssuers': ('http://cacerts.digicert.com/DigiCertSHA2ExtendedValidationServerCA.crt',), 'crlDistributionPoints': ('http://crl3.digicert.com/sha2-ev-server-g1.crl',                           'http://crl4.digicert.com/sha2-ev-server-g1.crl'), 'issuer': ((('countryName', 'US'),),            (('organizationName', 'DigiCert Inc'),),            (('organizationalUnitName', 'www.digicert.com'),),            (('commonName', 'DigiCert SHA2 Extended Validation Server CA'),)), 'notAfter': 'Sep  9 12:00:00 2016 GMT', 'notBefore': 'Sep  5 00:00:00 2014 GMT', 'serialNumber': '01BB6F00122B177F36CAB49CEA8B6B26', 'subject': ((('businessCategory', 'Private Organization'),),             (('1.3.6.1.4.1.311.60.2.1.3', 'US'),),             (('1.3.6.1.4.1.311.60.2.1.2', 'Delaware'),),             (('serialNumber', '3359300'),),             (('streetAddress', '16 Allen Rd'),),             (('postalCode', '03894-4801'),),             (('countryName', 'US'),),             (('stateOrProvinceName', 'NH'),),             (('localityName', 'Wolfeboro,'),),             (('organizationName', 'Python Software Foundation'),),             (('commonName', 'www.python.org'),)), 'subjectAltName': (('DNS', 'www.python.org'),                    ('DNS', 'python.org'),                    ('DNS', 'pypi.python.org'),                    ('DNS', 'docs.python.org'),                    ('DNS', 'testpypi.python.org'),                    ('DNS', 'bugs.python.org'),                    ('DNS', 'wiki.python.org'),                    ('DNS', 'hg.python.org'),                    ('DNS', 'mail.python.org'),                    ('DNS', 'packaging.python.org'),                    ('DNS', 'pythonhosted.org'),                    ('DNS', 'www.pythonhosted.org'),                    ('DNS', 'test.pythonhosted.org'),                    ('DNS', 'us.pycon.org'),                    ('DNS', 'id.python.org')), 'version': 3}

>>>conn.sendall(b"HEAD / HTTP/1.0\r\nHost: linuxfr.org\r\n\r\n")>>>pprint.pprint(conn.recv(1024).split(b"\r\n"))[b'HTTP/1.1 200 OK', b'Date: Sat, 18 Oct 2014 18:27:20 GMT', b'Server: nginx', b'Content-Type: text/html; charset=utf-8', b'X-Frame-Options: SAMEORIGIN', b'Content-Length: 45679', b'Accept-Ranges: bytes', b'Via: 1.1 varnish', b'Age: 2188', b'X-Served-By: cache-lcy1134-LCY', b'X-Cache: HIT', b'X-Cache-Hits: 11', b'Vary: Cookie', b'Strict-Transport-Security: max-age=63072000; includeSubDomains', b'Connection: close', b'', b'']

importsocket,sslcontext=ssl.create_default_context(ssl.Purpose.CLIENT_AUTH)context.load_cert_chain(certfile="mycertfile",keyfile="mykeyfile")bindsocket=socket.socket()bindsocket.bind(('myaddr.mydomain.com',10023))bindsocket.listen(5)

whileTrue:newsocket,fromaddr=bindsocket.accept()connstream=context.wrap_socket(newsocket,server_side=True)try:deal_with_client(connstream)finally:connstream.shutdown(socket.SHUT_RDWR)connstream.close()

defdeal_with_client(connstream):data=connstream.recv(1024)# empty data means the client is finished with uswhiledata:ifnotdo_something(connstream,data):# we'll assume do_something returns False# when we're finished with clientbreakdata=connstream.recv(1024)# finished with client

18.2.6. Notes on non-blocking sockets¶

SSL sockets behave slightly different than regular sockets innon-blocking mode. When working with non-blocking sockets, there arethus several things you need to be aware of:

• MostSSLSocket methods will raise eitherSSLWantWriteError orSSLWantReadError instead ofBlockingIOError if an I/O operation wouldblock.SSLWantReadError will be raised if a read operation onthe underlying socket is necessary, andSSLWantWriteError fora write operation on the underlying socket. Note that attempts towrite to an SSL socket may requirereading from the underlyingsocket first, and attempts toread from the SSL socket may requirea priorwrite to the underlying socket.

  Changed in version 3.5:In earlier Python versions, theSSLSocket.send() methodreturned zero instead of raisingSSLWantWriteError orSSLWantReadError.

• Callingselect() tells you that the OS-level socket can beread from (or written to), but it does not imply that there is sufficientdata at the upper SSL layer. For example, only part of an SSL frame mighthave arrived. Therefore, you must be ready to handleSSLSocket.recv()andSSLSocket.send() failures, and retry after another call toselect().

• Conversely, since the SSL layer has its own framing, a SSL socket maystill have data available for reading withoutselect()being aware of it. Therefore, you should first callSSLSocket.recv() to drain any potentially available data, and thenonly block on aselect() call if still necessary.

  (of course, similar provisions apply when using other primitives such aspoll(), or those in theselectors module)

• The SSL handshake itself will be non-blocking: theSSLSocket.do_handshake() method has to be retried until it returnssuccessfully. Here is a synopsis usingselect() to wait forthe socket’s readiness:

  whileTrue:try:sock.do_handshake()breakexceptssl.SSLWantReadError:select.select([sock],[],[])exceptssl.SSLWantWriteError:select.select([],[sock],[])

18.2.7. Memory BIO Support¶

Ever since the SSL module was introduced in Python 2.6, theSSLSocketclass has provided two related but distinct areas of functionality:

• SSL protocol handling
• Network IO

The network IO API is identical to that provided bysocket.socket,from whichSSLSocket also inherits. This allows an SSL socket to beused as a drop-in replacement for a regular socket, making it very easy to addSSL support to an existing application.

Combining SSL protocol handling and network IO usually works well, but thereare some cases where it doesn’t. An example is async IO frameworks that want touse a different IO multiplexing model than the “select/poll on a filedescriptor” (readiness based) model that is assumed bysocket.socketand by the internal OpenSSL socket IO routines. This is mostly relevant forplatforms like Windows where this model is not efficient. For this purpose, areduced scope variant ofSSLSocket calledSSLObject isprovided.

classssl.SSLObject¶

A reduced-scope variant ofSSLSocket representing an SSL protocolinstance that does not contain any network IO methods. This class istypically used by framework authors that want to implement asynchronous IOfor SSL through memory buffers.

This class implements an interface on top of a low-level SSL object asimplemented by OpenSSL. This object captures the state of an SSL connectionbut does not provide any network IO itself. IO needs to be performed throughseparate “BIO” objects which are OpenSSL’s IO abstraction layer.

AnSSLObject instance can be created using thewrap_bio() method. This method will create theSSLObject instance and bind it to a pair of BIOs. TheincomingBIO is used to pass data from Python to the SSL protocol instance, while theoutgoing BIO is used to pass data the other way around.

The following methods are available:

• context
• server_side
• server_hostname
• read()
• write()
• getpeercert()
• selected_npn_protocol()
• cipher()
• shared_ciphers()
• compression()
• pending()
• do_handshake()
• unwrap()
• get_channel_binding()

When compared toSSLSocket, this object lacks the followingfeatures:

• Any form of network IO incluging methods such asrecv() andsend().
• There is nodo_handshake_on_connect machinery. You must always manuallycalldo_handshake() to start the handshake.
• There is no handling ofsuppress_ragged_eofs. All end-of-file conditionsthat are in violation of the protocol are reported via theSSLEOFError exception.
• The methodunwrap() call does not return anything,unlike for an SSL socket where it returns the underlying socket.
• Theserver_name_callback callback passed toSSLContext.set_servername_callback() will get anSSLObjectinstance instead of aSSLSocket instance as its first parameter.

Some notes related to the use ofSSLObject:

• All IO on anSSLObject isnon-blocking.This means that for exampleread() will raise anSSLWantReadError if it needs more data than the incoming BIO hasavailable.
• There is no module-levelwrap_bio() call like there is forwrap_socket(). AnSSLObject is always createdvia anSSLContext.

An SSLObject communicates with the outside world using memory buffers. TheclassMemoryBIO provides a memory buffer that can be used for thispurpose. It wraps an OpenSSL memory BIO (Basic IO) object:

classssl.MemoryBIO¶

A memory buffer that can be used to pass data between Python and an SSLprotocol instance.

pending¶

Return the number of bytes currently in the memory buffer.

eof¶

A boolean indicating whether the memory BIO is current at the end-of-fileposition.

read(n=-1)¶

Read up ton bytes from the memory buffer. Ifn is not specified ornegative, all bytes are returned.

write(buf)¶

Write the bytes frombuf to the memory BIO. Thebuf argument must be anobject supporting the buffer protocol.

The return value is the number of bytes written, which is always equal tothe length ofbuf.

write_eof()¶

Write an EOF marker to the memory BIO. After this method has been called, itis illegal to callwrite(). The attributeeof willbecome true after all data currently in the buffer has been read.

18.2.8. Security considerations¶

>>>importssl,smtplib>>>smtp=smtplib.SMTP("mail.python.org",port=587)>>>context=ssl.create_default_context()>>>smtp.starttls(context=context)(220, b'2.0.0 Ready to start TLS')

context=ssl.SSLContext(ssl.PROTOCOL_TLS)context.options|=ssl.OP_NO_SSLv2context.options|=ssl.OP_NO_SSLv3context.options|=ssl.OP_NO_TLSv1context.options|=ssl.OP_NO_TLSv1_1