This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Provide data for TLS channel binding
Type: enhancement Stage: resolved
Components: Library (Lib) Versions: Python 3.3
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: Jajcus, jcea, pitrou, python-dev
Priority: normal Keywords: patch

Created on 2011-07-13 11:33 by Jajcus, last changed 2022-04-11 14:57 by admin. This issue is now closed.

Files
File name Uploaded Description Edit
tls_channel_binding.patch Jajcus, 2011-07-13 17:55 review
tls_channel_binding.patch Jajcus, 2011-07-14 13:19 Patch updated with Antoine's suggestions review
tls_channel_binding_alt.patch Jajcus, 2011-07-14 13:26 Alternative version, CHANNEL_BINDING_TYPES instead of HAS_TLS_UNIQUE review
Messages (12)
msg140247 - (view) Author: Jacek Konieczny (Jajcus) * Date: 2011-07-13 11:33
Recently IETF encourages using of the SCRAM-SHA-1-PLUS SASL authentication mechanism (5802) in new protocols. That is a requirement e.g. of the current XMPP specification (RFC6120). Any compliant implementation needs to support the 'SCRAM-SHA-1-PLUS' mechanism, and that requires obtaining the 'tls-unique' channel-binding data from a TLS connection used. Python doesn't provide this information and it seems the only detail stopping anyone from fully implementing XMPP or SCRAM-SHA-1-PLUS alone in Python.

The 'tls-unique' channel binding is defined as:

> Description: The first TLS Finished message sent (note: the Finished
> struct, not the TLS record layer message containing it) in the most
> recent TLS handshake of the TLS connection being bound to

…and is (they say), available via OpenSSL API. This should be exposed by the python SSLSocket object too.

The other channel-binding data type, 'tls-server-end-point' can be computed using current Python API, but it is not enough for most uses ('tls-unique' is the required channel binding data in most cases) and still not trivial (one needs to ASN.1-decode the certificate to get the hash function name to compute proper digest).
msg140248 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2011-07-13 11:52
Interestingly (from rfc5929):

      This definition of 'tls-unique' means that a channel's bindings
      data may change over time, which in turn creates a synchronization
      problem should the channel's bindings data change between the time
      that the client initiates authentication with channel binding and
      the time that the server begins to process the client's first
      authentication message.  If that happens, the authentication
      attempt will fail spuriously.

> and is (they say), available via OpenSSL API

Do you happen to know which API? I see no reference to tls-unique or channel binding, in either the OpenSSL website or the latest OpenSSL snapshot.

According to some mailing-list message, we could use SSL_get_finished() and SSL_get_peer_finished(), but that still leaves us to figure out what to do with the info returned by these functions. It would be nice if there was some ready-to-use code (I'm not a crypto expert).
msg140249 - (view) Author: Jacek Konieczny (Jajcus) * Date: 2011-07-13 12:07
> Do you happen to know which API? 

Not yet.

> I see no reference to tls-unique or channel binding, in either the OpenSSL website or the latest OpenSSL snapshot.

Yes, I know it is not directly documented.

> It would be nice if there was some ready-to-use code (I'm not a crypto expert).

_Maybe_ I will try to hack the python SSL code to make this work within my project. I will attach a patch here if it happens and gives any reusable results. As for now I cannot help any more, I am just reporting what is missing.
msg140258 - (view) Author: Jacek Konieczny (Jajcus) * Date: 2011-07-13 14:36
I skim-read the TLS specification, looked at the OpenSSL API and it seems it should be easy to implement. I am getting to work right now…
msg140293 - (view) Author: Jacek Konieczny (Jajcus) * Date: 2011-07-13 17:55
Here is a patch, ready for review. Seems to work, though I still need to check it with some other implementation.

I have chosen not to expose another three OpenSSL functions (SSL_get_finished, SSL_get_peer_finished, SSL_session_reused), but provide API just for getting the channel binding. If OpenSSL provides a better API some day (gnutls already has a dedicated function), we can use that.

The method added to SSLSocket - get_channel_binding() currently can return only the 'tls-unique' channel binding type, but can be easily extended for other types, which also may be easier to get from the C module.
msg140311 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2011-07-13 22:01
Thank you, this looks mostly good.
A couple of nits:

+#if OPENSSL_VERSION_NUMBER >= 0x0090500fL
+# define HAVE_OPENSSL_FINISHED 1
+#else
+# undef HAVE_OPENSSL_FINNISHED
+#endif

you have a typo in the #undef, also it would be more logical to have
  # define HAVE_OPENSSL_FINISHED 0
instead.

_ssl.c will not compile if OpenSSL is too old, because you lack some #if's (or #ifdef's) around PySSL_tls_unique_cb.

Also, it would be nice to expose the availability of tls-unique as a public constant, as we already do for "ssl.HAS_SNI". ssl.HAS_TLS_UNIQUE?

Similarly, you need to skip some of the tests when the functionality isn't available.
And I think get_channel_binding() should raise NotImplementedError in that case.
msg140324 - (view) Author: Jacek Konieczny (Jajcus) * Date: 2011-07-14 07:17
Thanks for the quick review. Most of the problems are my oversights.

I am not sure about that:
> And I think get_channel_binding() should raise NotImplementedError in that case.

As the method is supposed to be extensible and 'tls-unique' may be just one of possible channel-binding types, then I think the same exception should be raised in case 'tls-unique' is requested and not implemented and when other, currently not implemented, channel binding type is requested. The get_channel_binding() method itself is always implemented, that is why I wonder if 'ValueError' is no better. Or 'NotImplementedError' for both 'tls-unique not implemented' and 'unknown channel binding'.
msg140329 - (view) Author: Jacek Konieczny (Jajcus) * Date: 2011-07-14 13:19
This is patch updated according to your suggestions, including raising NotImplementedError when 'tls-unique' is not available and with the ssl.HAS_TLS_UNIQUE constant added.

It also includes an important fix to the data retrieval logic (one condition had to be reverted). 

Now the code is proven to work, by testing with another implementation (SCRAM-SHA-1-PLUS authentication in Isode M-Link 15.1a0).

A alternative patch version will follow.
msg140331 - (view) Author: Jacek Konieczny (Jajcus) * Date: 2011-07-14 13:26
This patch is functionally equivalent, but advertises 'tls-unique' support in a bit different way.

HAS_TLS_UNIQUE is not exposed in the python 'ssl' module, instead a list 'CHANNEL_BINDING_TYPES' is provided (empty when 'tls-unique' is not supported). get_channel_binding raises ValueError if the argument is not on this list. This way the API can be extended to other channel binding types without adding new constants or functions. Adding a new channel binding type would not need any modifications in the API client code (if it is designed to use arbitrary cb types).
msg140450 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2011-07-15 18:14
> This patch is functionally equivalent, but advertises 'tls-unique'
> support in a bit different way.
> 
> HAS_TLS_UNIQUE is not exposed in the python 'ssl' module, instead a
> list 'CHANNEL_BINDING_TYPES' is provided (empty when 'tls-unique' is
> not supported). get_channel_binding raises ValueError if the argument
> is not on this list. This way the API can be extended to other channel
> binding types without adding new constants or functions. Adding a new
> channel binding type would not need any modifications in the API
> client code (if it is designed to use arbitrary cb types).

Thanks, this is a good idea. I'm trying to get advice on the
openssl-users mailing-list about this and will commit if I don't get any
contradicting info soon ;)
msg140767 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-07-20 23:12
New changeset cb44fef5ea1d by Antoine Pitrou in branch 'default':
Issue #12551: Provide a get_channel_binding() method on SSL sockets so as
http://hg.python.org/cpython/rev/cb44fef5ea1d
msg140768 - (view) Author: Antoine Pitrou (pitrou) * (Python committer) Date: 2011-07-20 23:13
Patch is now committed. Thanks for your contribution!
History
Date User Action Args
2022-04-11 14:57:19adminsetgithub: 56760
2011-07-20 23:13:47pitrousetstatus: open -> closed
resolution: fixed
messages: + msg140768

stage: patch review -> resolved
2011-07-20 23:12:49python-devsetnosy: + python-dev
messages: + msg140767
2011-07-15 18:14:23pitrousetmessages: + msg140450
2011-07-14 13:26:02Jajcussetfiles: + tls_channel_binding_alt.patch

messages: + msg140331
2011-07-14 13:19:33Jajcussetfiles: + tls_channel_binding.patch

messages: + msg140329
2011-07-14 07:17:07Jajcussetmessages: + msg140324
2011-07-13 22:01:23pitrousetmessages: + msg140311
stage: needs patch -> patch review
2011-07-13 19:01:49jceasetnosy: + jcea
2011-07-13 17:55:13Jajcussetfiles: + tls_channel_binding.patch
keywords: + patch
messages: + msg140293
2011-07-13 14:36:00Jajcussetmessages: + msg140258
2011-07-13 12:07:42Jajcussetmessages: + msg140249
2011-07-13 11:52:09pitrousetversions: - Python 2.7, Python 3.2, Python 3.4
nosy: + pitrou

messages: + msg140248

stage: needs patch
2011-07-13 11:33:25Jajcuscreate