Source code:Lib/ssl.py
This module provides access to Transport Layer Security (often known as “SecureSockets Layer”) encryption and peer authentication facilities for networksockets, both client-side and server-side. This module uses the OpenSSLlibrary. It is available on all modern Unix systems, Windows, Mac OS X, andprobably additional platforms, as long as OpenSSL is installed on that platform.
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.
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.
This section documents the objects and functions in thessl module; for moregeneral information about TLS, SSL, and certificates, the reader is referred tothe documents in the “See Also” section at the bottom.
This module provides a class,ssl.SSLSocket, which is derived from thesocket.socket type, and provides a socket-like wrapper that alsoencrypts and decrypts the data going over the socket with SSL. It supportsadditional methods such asgetpeercert(), which retrieves thecertificate of the other side of the connection, andcipher(),whichretrieves the cipher being used for the secure connection.
For more sophisticated applications, thessl.SSLContext classhelps manage settings and certificates, which can then be inheritedby SSL sockets created through theSSLContext.wrap_socket() method.
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.
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.
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.
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.
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.
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.
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.
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.
Raised to signal an error with a certificate (such as mismatchinghostname). Certificate errors detected by OpenSSL, though, raiseanSSLError.
The following function allows for standalone socket creation. Starting fromPython 3.2, it can be more flexible to useSSLContext.wrap_socket()instead.
Takes an instancesock ofsocket.socket, and returns an instanceofssl.SSLSocket, a subtype ofsocket.socket, which wrapsthe underlying socket in an SSL context.sock must be aSOCK_STREAM socket; other socket types are unsupported.
For client-side sockets, the context construction is lazy; if theunderlying socket isn’t connected yet, the context construction will beperformed afterconnect() is called on the socket. Forserver-side sockets, if the socket has no remote peer, it is assumedto be a listening socket, and the server-side SSL wrapping isautomatically performed on client connections accepted via theaccept() method.wrap_socket() may raiseSSLError.
Thekeyfile andcertfile parameters specify optional files whichcontain a certificate to be used to identify the local side of theconnection. See the discussion ofCertificates for moreinformation on how the certificate is stored in thecertfile.
The parameterserver_side is a boolean which identifies whetherserver-side or client-side behavior is desired from this socket.
The parametercert_reqs specifies whether a certificate is required fromthe other side of the connection, and whether it will be validated ifprovided. It must be one of the three valuesCERT_NONE(certificates ignored),CERT_OPTIONAL (not required, but validatedif provided), orCERT_REQUIRED (required and validated). If thevalue of this parameter is notCERT_NONE, then theca_certsparameter must point to a file of CA certificates.
Theca_certs file contains a set of concatenated “certificationauthority” certificates, which are used to validate certificates passed fromthe other end of the connection. See the discussion ofCertificates for more information about how to arrange thecertificates in this file.
The parameterssl_version specifies which version of the SSL protocol touse. Typically, the server chooses a particular protocol version, and theclient must adapt to the server’s choice. Most of the versions are notinteroperable with the other versions. If not specified, the default isPROTOCOL_SSLv23; it provides the most compatibility with otherversions.
Here’s a table showing which versions in a client (down the side) can connectto which versions in a server (along the top):
client /server SSLv2 SSLv3 SSLv23 TLSv1 SSLv2 yes no yes no SSLv3 no yes yes no SSLv23 yes no yes no TLSv1 no no yes yes
Note
Which connections succeed will vary depending on the version ofOpenSSL. For instance, in some older versions of OpenSSL (suchas 0.9.7l on OS X 10.4), an SSLv2 client could not connect to anSSLv23 server. Another example: beginning with OpenSSL 1.0.0,an SSLv23 client will not actually attempt SSLv2 connectionsunless you explicitly enable SSLv2 ciphers; for example, youmight specify"ALL" or"SSLv2" as theciphers parameterto enable them.
Theciphers parameter sets the available ciphers for this SSL object.It should be a string in theOpenSSL cipher list format.
The parameterdo_handshake_on_connect specifies whether to do the SSLhandshake automatically after doing asocket.connect(), or whether theapplication program will call it explicitly, by invoking theSSLSocket.do_handshake() method. CallingSSLSocket.do_handshake() explicitly gives the program control over theblocking behavior of the socket I/O involved in the handshake.
The parametersuppress_ragged_eofs specifies how theSSLSocket.recv() method should signal unexpected EOF from the other endof the connection. If specified asTrue (the default), it returns anormal EOF (an empty bytes object) in response to unexpected EOF errorsraised from the underlying socket; ifFalse, it will raise theexceptions back to the caller.
Changed in version 3.2:New optional argumentciphers.
Returnsnum cryptographically strong pseudo-random bytes. Raises anSSLError if the PRNG has not been seeded with enough data or if theoperation is not supported by the current RAND method.RAND_status()can be used to check the status of the PRNG andRAND_add() can be usedto seed the PRNG.
Read the Wikipedia article,Cryptographically secure pseudorandom numbergenerator (CSPRNG),to get the requirements of a cryptographically generator.
New in version 3.3.
Returns (bytes, is_cryptographic): bytes arenum pseudo-random bytes,is_cryptographic isTrue if the bytes generated are cryptographicallystrong. Raises anSSLError if the operation is not supported by thecurrent RAND method.
Generated pseudo-random byte sequences will be unique if they are ofsufficient length, but are not necessarily unpredictable. They can be usedfor non-cryptographic purposes and for certain purposes in cryptographicprotocols, but usually not for key generation etc.
New in version 3.3.
ReturnsTrue if the SSL pseudo-random number generator has been seeded with‘enough’ randomness, andFalse otherwise. You can usessl.RAND_egd()andssl.RAND_add() to increase the randomness of the pseudo-randomnumber generator.
If you are running an entropy-gathering daemon (EGD) somewhere, andpathis the pathname of a socket connection open to it, this will read 256 bytesof randomness from the socket, and add it to the SSL pseudo-random numbergenerator to increase the security of generated secret keys. This istypically only necessary on systems without better sources of randomness.
Seehttp://egd.sourceforge.net/ orhttp://prngd.sourceforge.net/ for sourcesof entropy-gathering daemons.
Verify thatcert (in decoded format as returned bySSLSocket.getpeercert()) matches the givenhostname. The rulesapplied are those for checking the identity of HTTPS servers as outlinedinRFC 2818 andRFC 6125, except that IP addresses are not currentlysupported. In addition to HTTPS, this function should be suitable forchecking the identity of servers in various SSL-based protocols such asFTPS, IMAPS, POPS and others.
CertificateError is raised on failure. On success, the functionreturns nothing:
>>>cert={'subject':((('commonName','example.com'),),)}>>>ssl.match_hostname(cert,"example.com")>>>ssl.match_hostname(cert,"example.org")Traceback (most recent call last): File"<stdin>", line1, in<module> File"/home/py3k/Lib/ssl.py", line130, inmatch_hostnamessl.CertificateError:hostname 'example.org' doesn't match 'example.com'
New in version 3.2.
Changed in version 3.3.3:The function now followsRFC 6125, section 6.4.3 and does neithermatch multiple wildcards (e.g.*.*.com or*a*.example.org) nora wildcard inside an internationalized domain names (IDN) fragment.IDN A-labels such aswww*.xn--pthon-kva.org are still supported,butx*.python.org no longer matchesxn--tda.python.org.
Returns a floating-point value containing a normal seconds-after-the-epochtime value, given the time-string representing the “notBefore” or “notAfter”date from a certificate.
Here’s an example:
>>>importssl>>>ssl.cert_time_to_seconds("May 9 00:00:00 2007 GMT")1178694000.0>>>importtime>>>time.ctime(ssl.cert_time_to_seconds("May 9 00:00:00 2007 GMT"))'Wed May 9 00:00:00 2007'
Given the addressaddr of an SSL-protected server, as a (hostname,port-number) pair, fetches the server’s certificate, and returns it as aPEM-encoded string. Ifssl_version is specified, uses that version ofthe SSL protocol to attempt to connect to the server. Ifca_certs isspecified, it should be a file containing a list of root certificates, thesame format as used for the same parameter inwrap_socket(). The callwill attempt to validate the server certificate against that set of rootcertificates, and will fail if the validation attempt fails.
Changed in version 3.3:This function is now IPv6-compatible.
Given a certificate as a DER-encoded blob of bytes, returns a PEM-encodedstring version of the same certificate.
Given a certificate as an ASCII PEM string, returns a DER-encoded sequence ofbytes for that same certificate.
Possible value forSSLContext.verify_mode, or thecert_reqsparameter towrap_socket(). In this mode (the default), nocertificates will be required from the other side of the socket connection.If a certificate is received from the other end, no attempt to validate itis made.
See the discussion ofSecurity considerations below.
Possible value forSSLContext.verify_mode, or thecert_reqsparameter towrap_socket(). In this mode no certificates will berequired from the other side of the socket connection; but if theyare provided, validation will be attempted and anSSLErrorwill be raised on failure.
Use of this setting requires a valid set of CA certificates tobe passed, either toSSLContext.load_verify_locations() or as avalue of theca_certs parameter towrap_socket().
Possible value forSSLContext.verify_mode, or thecert_reqsparameter towrap_socket(). In this mode, certificates arerequired from the other side of the socket connection; anSSLErrorwill be raised if no certificate is provided, or if its validation fails.
Use of this setting requires a valid set of CA certificates tobe passed, either toSSLContext.load_verify_locations() or as avalue of theca_certs parameter towrap_socket().
Selects SSL version 2 as the channel encryption protocol.
This protocol is not available if OpenSSL is compiled with OPENSSL_NO_SSL2flag.
Warning
SSL version 2 is insecure. Its use is highly discouraged.
Selects SSL version 2 or 3 as the channel encryption protocol. This is asetting to use with servers for maximum compatibility with the other end ofan SSL connection, but it may cause the specific ciphers chosen for theencryption to be of fairly low quality.
Selects SSL version 3 as the channel encryption protocol. For clients, thisis the maximally compatible SSL variant.
Selects TLS version 1 as the channel encryption protocol. This is the mostmodern version, and probably the best choice for maximum protection, if bothsides can speak it.
Enables workarounds for various bugs present in other SSL implementations.This option is set by default. It does not necessarily set the sameflags as OpenSSL’sSSL_OP_ALL constant.
New in version 3.2.
Prevents an SSLv2 connection. This option is only applicable inconjunction withPROTOCOL_SSLv23. It prevents the peers fromchoosing SSLv2 as the protocol version.
New in version 3.2.
Prevents an SSLv3 connection. This option is only applicable inconjunction withPROTOCOL_SSLv23. It prevents the peers fromchoosing SSLv3 as the protocol version.
New in version 3.2.
Prevents a TLSv1 connection. This option is only applicable inconjunction withPROTOCOL_SSLv23. It prevents the peers fromchoosing TLSv1 as the protocol version.
New in version 3.2.
Use the server’s cipher ordering preference, rather than the client’s.This option has no effect on client sockets and SSLv2 server sockets.
New in version 3.3.
Prevents re-use of the same DH key for distinct SSL sessions. Thisimproves forward secrecy but requires more computational resources.This option only applies to server sockets.
New in version 3.3.
Prevents re-use of the same ECDH key for distinct SSL sessions. Thisimproves forward secrecy but requires more computational resources.This option only applies to server sockets.
New in version 3.3.
Disable compression on the SSL channel. This is useful if the applicationprotocol supports its own compression scheme.
This option is only available with OpenSSL 1.0.0 and later.
New in version 3.3.
Whether the OpenSSL library has built-in support for Elliptic Curve-basedDiffie-Hellman key exchange. This should be true unless the feature wasexplicitly disabled by the distributor.
New in version 3.3.
Whether the OpenSSL library has built-in support for theServer NameIndication extension to the SSLv3 and TLSv1 protocols (as defined inRFC 4366). When true, you can use theserver_hostname argument toSSLContext.wrap_socket().
New in version 3.2.
Whether the OpenSSL library has built-in support forNext ProtocolNegotiation as described in theNPN draft specification. When true,you can use theSSLContext.set_npn_protocols() method to advertisewhich protocols you want to support.
New in version 3.3.
List of supported TLS channel binding types. Strings in this listcan be used as arguments toSSLSocket.get_channel_binding().
New in version 3.3.
The version string of the OpenSSL library loaded by the interpreter:
>>>ssl.OPENSSL_VERSION'OpenSSL 0.9.8k 25 Mar 2009'
New in version 3.2.
A tuple of five integers representing version information about theOpenSSL library:
>>>ssl.OPENSSL_VERSION_INFO(0, 9, 8, 11, 15)
New in version 3.2.
The raw version number of the OpenSSL library, as a single integer:
>>>ssl.OPENSSL_VERSION_NUMBER9470143>>>hex(ssl.OPENSSL_VERSION_NUMBER)'0x9080bf'
New in version 3.2.
SSL sockets provide the following methods ofSocket Objects:
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.
SSL sockets also have the following additional methods and attributes:
Perform the SSL setup handshake.
If there is no certificate for the peer on the other end of the connection,returnsNone.
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:
Changed in version 3.2:The returned dictionary includes additional items such asissuerandnotBefore.
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.
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.
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.
Returns the protocol that was selected during the TLS/SSL handshake. IfSSLContext.set_npn_protocols() was not called, or if the other partydoes not support NPN, or if the handshake has not yet happened, this willreturnNone.
New in version 3.3.
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.
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.
New in version 3.2.
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.
Create a new SSL context. You must passprotocol which must be oneof thePROTOCOL_* constants defined in this module.PROTOCOL_SSLv23 is recommended for maximum interoperability.
SSLContext objects have the following methods and attributes:
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.
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.
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.
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.
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.
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.
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.
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 is False.
New in version 3.3.
See also
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_hostnamewill raise aValueError if the OpenSSL library doesn’t have supportfor it (that is, ifHAS_SNI isFalse). Specifyingserver_hostname will also raise aValueError ifserver_sideis true.
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)
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.
The protocol version chosen when constructing the context. This attributeis read-only.
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.
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-----
The Python files which contain certificates can contain a sequence ofcertificates, sometimes called acertificate chain. This chain should startwith the specific certificate for the principal who “is” the client or server,and then the certificate for the issuer of that certificate, and then thecertificate for the issuer ofthat certificate, and so on up the chain tillyou get to a certificate which isself-signed, that is, a certificate whichhas the same subject and issuer, sometimes called aroot certificate. Thecertificates should just be concatenated together in the certificate file. Forexample, suppose we had a three certificate chain, from our server certificateto the certificate of the certification authority that signed our servercertificate, to the root certificate of the agency which issued thecertification authority’s certificate:
-----BEGINCERTIFICATE-----...(certificateforyourserver)...-----ENDCERTIFICATE----------BEGINCERTIFICATE-----...(thecertificatefortheCA)...-----ENDCERTIFICATE----------BEGINCERTIFICATE-----...(therootcertificatefortheCA's issuer)...-----ENDCERTIFICATE-----
If you are going to require validation of the other side of the connection’scertificate, you need to provide a “CA certs” file, filled with the certificatechains for each issuer you are willing to trust. Again, this file just containsthese chains concatenated together. For validation, Python will use the firstchain it finds in the file which matches. Some “standard” root certificates areavailable from various certification authorities:CACert.org,Thawte,Verisign,Positive SSL(used by python.org),Equifax and GeoTrust.
In general, if you are using SSL3 or TLS1, you don’t need to put the full chainin your “CA certs” file; you only need the root certificates, and the remotepeer is supposed to furnish the other certificates necessary to chain from itscertificate to a root certificate. SeeRFC 4158 for more discussion of theway in which certification chains can be built.
Often the private key is stored in the same file as the certificate; in thiscase, only thecertfile parameter toSSLContext.load_cert_chain()andwrap_socket() needs to be passed. If the private key is storedwith the certificate, it should come before the first certificate inthe certificate chain:
-----BEGINRSAPRIVATEKEY-----...(privatekeyinbase64encoding)...-----ENDRSAPRIVATEKEY----------BEGINCERTIFICATE-----...(certificateinbase64PEMencoding)...-----ENDCERTIFICATE-----
If you are going to create a server that provides SSL-encrypted connectionservices, you will need to acquire a certificate for that service. There aremany ways of acquiring appropriate certificates, such as buying one from acertification authority. Another common practice is to generate a self-signedcertificate. The simplest way to do this is with the OpenSSL package, usingsomething like the following:
%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%
The disadvantage of a self-signed certificate is that it is its own rootcertificate, and no one else will have it in their cache of known (and trusted)root certificates.
To test for the presence of SSL support in a Python installation, user codeshould use the following idiom:
try:importsslexceptImportError:passelse:...# do something that requires SSL support
This example connects to an SSL server and prints the server’s certificate:
importsocket,ssl,pprints=socket.socket(socket.AF_INET,socket.SOCK_STREAM)# require a certificate from the serverssl_sock=ssl.wrap_socket(s,ca_certs="/etc/ca_certs_file",cert_reqs=ssl.CERT_REQUIRED)ssl_sock.connect(('www.verisign.com',443))pprint.pprint(ssl_sock.getpeercert())# note that closing the SSLSocket will also close the underlying socketssl_sock.close()
As of January 6, 2012, the certificate printed by this program looks likethis:
{'issuer':((('countryName','US'),),(('organizationName','VeriSign, Inc.'),),(('organizationalUnitName','VeriSign Trust Network'),),(('organizationalUnitName','Terms of use at https://www.verisign.com/rpa (c)06'),),(('commonName','VeriSign Class 3 Extended Validation SSL SGC CA'),)),'notAfter':'May 25 23:59:59 2012 GMT','notBefore':'May 26 00:00:00 2010 GMT','serialNumber':'53D2BEF924A7245E83CA01E46CAA2477','subject':((('1.3.6.1.4.1.311.60.2.1.3','US'),),(('1.3.6.1.4.1.311.60.2.1.2','Delaware'),),(('businessCategory','V1.0, Clause 5.(b)'),),(('serialNumber','2497886'),),(('countryName','US'),),(('postalCode','94043'),),(('stateOrProvinceName','California'),),(('localityName','Mountain View'),),(('streetAddress','487 East Middlefield Road'),),(('organizationName','VeriSign, Inc.'),),(('organizationalUnitName',' Production Security Services'),),(('commonName','www.verisign.com'),)),'subjectAltName':(('DNS','www.verisign.com'),('DNS','verisign.com'),('DNS','www.verisign.net'),('DNS','verisign.net'),('DNS','www.verisign.mobi'),('DNS','verisign.mobi'),('DNS','www.verisign.eu'),('DNS','verisign.eu')),'version':3}
This other example first creates an SSL context, instructs it to verifycertificates sent by peers, and feeds it a set of recognized certificateauthorities (CA):
>>>context=ssl.SSLContext(ssl.PROTOCOL_SSLv23)>>>context.verify_mode=ssl.CERT_REQUIRED>>>context.load_verify_locations("/etc/ssl/certs/ca-bundle.crt")
(it is assumed your operating system places a bundle of all CA certificatesin/etc/ssl/certs/ca-bundle.crt; if not, you’ll get an error and haveto adjust the location)
When you use the context to connect to a server,CERT_REQUIREDvalidates the server certificate: it ensures that the server certificatewas signed with one of the CA certificates, and checks the signature forcorrectness:
>>>conn=context.wrap_socket(socket.socket(socket.AF_INET))>>>conn.connect(("linuxfr.org",443))
You should then fetch the certificate and check its fields for conformity:
>>>cert=conn.getpeercert()>>>ssl.match_hostname(cert,"linuxfr.org")
Visual inspection shows that the certificate does identify the desired service(that is, the HTTPS hostlinuxfr.org):
>>>pprint.pprint(cert){'issuer': ((('organizationName', 'CAcert Inc.'),), (('organizationalUnitName', 'http://www.CAcert.org'),), (('commonName', 'CAcert Class 3 Root'),)), 'notAfter': 'Jun 7 21:02:24 2013 GMT', 'notBefore': 'Jun 8 21:02:24 2011 GMT', 'serialNumber': 'D3E9', 'subject': ((('commonName', 'linuxfr.org'),),), 'subjectAltName': (('DNS', 'linuxfr.org'), ('othername', '<unsupported>'), ('DNS', 'linuxfr.org'), ('othername', '<unsupported>'), ('DNS', 'dev.linuxfr.org'), ('othername', '<unsupported>'), ('DNS', 'prod.linuxfr.org'), ('othername', '<unsupported>'), ('DNS', 'alpha.linuxfr.org'), ('othername', '<unsupported>'), ('DNS', '*.linuxfr.org'), ('othername', '<unsupported>')), 'version': 3}
Now that you are assured of its authenticity, you can proceed to talk withthe server:
>>>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 302 Found', b'Date: Sun, 16 May 2010 13:43:28 GMT', b'Server: Apache/2.2', b'Location: https://linuxfr.org/pub/', b'Vary: Accept-Encoding', b'Connection: close', b'Content-Type: text/html; charset=iso-8859-1', b'', b'']
See the discussion ofSecurity considerations below.
For server operation, typically you’ll need to have a server certificate, andprivate key, each in a file. You’ll first create a context holding the keyand the certificate, so that clients can check your authenticity. Thenyou’ll open a socket, bind it to a port, calllisten() on it, and startwaiting for clients to connect:
importsocket,sslcontext=ssl.SSLContext(ssl.PROTOCOL_TLSv1)context.load_cert_chain(certfile="mycertfile",keyfile="mykeyfile")bindsocket=socket.socket()bindsocket.bind(('myaddr.mydomain.com',10023))bindsocket.listen(5)
When a client connects, you’ll callaccept() on the socket to get thenew socket from the other end, and use the context’sSSLContext.wrap_socket()method to create a server-side SSL socket for the connection:
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()
Then you’ll read data from theconnstream and do something with it till youare finished with the client (or the client is finished with you):
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
And go back to listening for new client connections (of course, a real serverwould probably handle each client connection in a separate thread, or putthe sockets in non-blocking mode and use an event loop).
When working with non-blocking sockets, there are several things you needto be aware of:
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().
(of course, similar provisions apply when using other primitives such aspoll())
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],[])
CERT_NONE is the default. Since it does not authenticate the otherpeer, it can be insecure, especially in client mode where most of time youwould like to ensure the authenticity of the server you’re talking to.Therefore, when in client mode, it is highly recommended to useCERT_REQUIRED. However, it is in itself not sufficient; you alsohave to check that the server certificate, which can be obtained by callingSSLSocket.getpeercert(), matches the desired service. For manyprotocols and applications, the service can be identified by the hostname;in this case, thematch_hostname() function can be used.
In server mode, if you want to authenticate your clients using the SSL layer(rather than using a higher-level authentication mechanism), you’ll also haveto specifyCERT_REQUIRED and similarly check the client certificate.
Note
In client mode,CERT_OPTIONAL andCERT_REQUIRED areequivalent unless anonymous ciphers are enabled (they are disabledby default).
SSL version 2 is considered insecure and is therefore dangerous to use. Ifyou want maximum compatibility between clients and servers, it is recommendedto usePROTOCOL_SSLv23 as the protocol version and then disableSSLv2 explicitly using theSSLContext.options attribute:
context=ssl.SSLContext(ssl.PROTOCOL_SSLv23)context.options|=ssl.OP_NO_SSLv2
The SSL context created above will allow SSLv3 and TLSv1 connections, butnot SSLv2.
If you have advanced security requirements, fine-tuning of the ciphersenabled when negotiating a SSL session is possible through theSSLContext.set_ciphers() method. Starting from Python 3.2.3, thessl module disables certain weak ciphers by default, but you may wantto further restrict the cipher choice. For example:
context=ssl.SSLContext(ssl.PROTOCOL_TLSv1)context.set_ciphers('HIGH:!aNULL:!eNULL')
The!aNULL:!eNULL part of the cipher spec is necessary to disable cipherswhich don’t provide both encryption and authentication. Be sure to readOpenSSL’s documentation about thecipher listformat.If you want to check which ciphers are enabled by a given cipher list,use theopensslciphers command on your system.
If using this module as part of a multi-processed application (using,for example themultiprocessing orconcurrent.futures modules),be aware that OpenSSL’s internal random number generator does not properlyhandle forked processes. Applications must change the PRNG state of theparent process if they use any SSL feature withos.fork(). Anysuccessful call ofRAND_add(),RAND_bytes() orRAND_pseudo_bytes() is sufficient.
See also
18.1.socket — Low-level networking interface
18.3.asyncore — Asynchronous socket handler
Enter search terms or a module, class or function name.
