[Twisted-Python] The role of twisted.internet._sslverify.IOpenSSLTrustRoot

[Glyph Lefkowitz]

> On Dec 25, 2015, at 2:19 PM, Adi Roiban <adi at roiban.ro> wrote:
> 
> Hi,
> 
> On 25 December 2015 at 11:20, Glyph Lefkowitz <glyph at twistedmatrix.com <mailto:glyph at twistedmatrix.com>> wrote:
> 
>> On Dec 20, 2015, at 9:05 AM, Adi Roiban <adi at roiban.ro <mailto:adi at roiban.ro>> wrote:
>> 
>> Hi,
>> 
>> What is the purpose of IOpenSSLTrustRoot ?
> 
> The idea is that we have public functions, mainly `optionsForClientTLS´, which need to take a thing that represents a "trust root".  We want this to be something that can abstractly be described at a high level, but then in reality we need to do with gross implementation details of OpenSSL.  So this interface describes what you pass.
> 
> Reading the docstring of IOpenSSLTrustRoot it does not give any hints about optionsForClientTLS
> 
> So instead of
> 
>     Trust settings for an OpenSSL context.
> 
> Maybe it should be something like:
> 
>    Marker only interface for private implementations of OpenSSL trust root things.

This is incorrect, though.  The term "marker interface" means "interface with no attributes or methods, used to denote a complex property that Interface is insufficiently expressive to describe".

Oh and hey we didn't even invent the term: https://en.wikipedia.org/wiki/Marker_interface_pattern :)

>> It it documented as a private interface, it has only private methods, but then it is exposed in  twisted.internet.ssl.optionsForClientTLS
>> 
>> Why?
> 
> Yes, this is intentional.  It is a private interface, so you can't check if something provides it, you aren't allowed to know what attributes it has, and you can't implement it.  However, you can call a function that is documented to return a value that provides it (such as `twisted.internet.ssl.platformTrust´) and pass that value to a function documented to accept it (such as `twisted.internet.ssl.optionsForClientTLS`).
> 
> It's private because we weren't sure if we'd want to change it.  At the time it was implemented, the only two cases were OpenSSLDefaultPaths and Certificate.  In the case of Certificate, you know what certificate you're adding, but in the case of OpenSSLDefaultPaths, you just call a method on the context object to mutate it, and you can't extract information about which certificates are trusted past that.  The method we came up with, _addCACertsToContext, was a gross compromise which allowed for implementing this but could not be made abstract, because it reflects a bizarre flaw in the OpenSSL API, and it by necessity exposes pyOpenSSL objects, which we are trying to do less of.  For one thing, we'd eventually like to support TLS via OpenSSL using an API provided by Cryptography; for another, we'd like to one day provide TLS from an API that might not be backed by OpenSSL at all.  So reducing the surface area of our public API that touches pyOpenSSL is important.
> 
> Hopefully this thoroughly explains the decision?
> 
> I understand now, but I find it hard to extract this information just from the code... maybe I am a bad code reader, or maybe the  IOpenSSLTrustRoot docstring should inform that it is a gross compromise so that other people will understand that this is not really intentional ... and invited to find something better :)

I think the documentation as it is does maintainers a slight disservice, as the assumption is that you've come to IOpenSSLTrustRoot after having read the docstring for optionsForClientTLS, or platformTrust, or OpenSSLCertificateOptions.  So it could definitely be re-written to take into account the fact that a maintainer might discover this interface first.  Honestly it seems to me that a "@see:" with links to the thing that take it as a parameter would get us 70% of the way there, just so that maintainers could use it as a jumping-off point.  Some of the explanation from these emails would also be useful, of course, to give some context.  It says "things outside of twisted shouldn't implement it" but it doesn't really explain why.

> I am happy to see more backend neutral API but unless we have at least another use case for non OpenSSL backed TLS I don't know if it worth designing an API for that unknown API.

We have definitely made some missteps with this API design (I should probably write a giant "mea culpa" blog post at some point pointing out what many of those errors were).  However, the point of things like IOpenSSLTrustRoot is not to prematurely introduce extra interfaces and functionality where they are not needed - we need such an interface even for a pure OpenSSL-only backend.  The point is to keep those things out of the public interface so that callers are not overly coupled to them.

One thing that's important to remember is that "private" is a social convention in Python, so if needs must, a Twisted application can always just go ahead and implement this interface. 

-glyph
-------------- next part --------------
An HTML attachment was scrubbed...
URL: </pipermail/twisted-python/attachments/20151225/89c5af78/attachment-0002.html>