meejah / txtorcon

Twisted-based asynchronous Tor control protocol implementation. Includes unit-tests, examples, state-tracking code and configuration abstraction.
http://fjblvrw2jrxnhtg67qpbzi45r7ofojaoo3orzykesly2j3c2m3htapid.onion/
MIT License
251 stars 72 forks source link

Hidden/Onion Services API #140

Closed meejah closed 6 years ago

meejah commented 9 years ago

The current HiddenService API is inadequate to encapsulate all the hidden-service options. Which "should" be called Onion Services anyway.

Related tickets: #131, #96, #94

I propose adding a new API and interfaces to wrap over the issues mentioned in the above tickets (especially #131):

class IOnionService(Interface):
    hostname = Attribute("The public hostname, like timaq4ygg2iegci7.onion (str)")
    private_key = Attribute("Private key blob (bytes)")

    def auth_token(self):
        """                                                                                                               
        If this service is authenticated, this returns an authentication                                                  
        token (bytes). Otherwise, it should return None.                                                                  
        """

class IStealthOnionService(Interface):
    clients = Attribute("An iterable of IOnionService instances, one for each key")

    def add_client(self):
        """                                                                                                               
        ??? do we need this?                                                                                              

        Adds an additional client and returns an instance providing an                                                    
        authenticated IOnionService encapsulating it                                                                      
        """

Unfortunately, I can't think of a way to make one interface/API adequate for "normal" services as well as stealth services, mainly because the latter have a different .onion hostname for each "client". For ephemeral vs. "normal" (disk-based) services, the IOnionService is adequate. The following concrete classes would exist:

@implementer(IOnionService)
class OnionService(object):
    def __init__(self, config, thedir, ports,
                 auth=[], ver=2, group_readable=0):

        pass

    # etcetc, basically the old "HiddenService" object                                                                    

@implementer(IOnionService)
class EphemeralOnionService(object):
    def __init__(self, config, privatekey, ports, auth=[], ver=2):
        # XXX do we need version?                                                                                         
        pass

    # Note: auth not yet supported by Tor, for ADD_ONION                                                                  

@implementer(IStealthOnionService)
class StealthOnionService(object):
    def __init__(self, config, thedir, ports, clients=[], ver=2, group_readable=0):
        # XXX do we need version here? probably...                                                                        
        pass

    # basically everything in OnionService, except the only API we                                                        
    # provide is "clients" because there's a separate .onion hostname                                                     
    # and authentication token per client.                                                                                

APIs would be added to create these things (either methods on TorConfig, or methods requiring a TorConfig instance).

meejah commented 9 years ago

Does @david415 have an opinion on these? Am I missing anything?

meejah commented 9 years ago

Actually, it should just be OnionService vs. AuthenticatedOnionService I think; these both then have a list of clients (for non-stealth services, the hostname happens to be the same for each one, but the key will be different). They also need 3 things: hostname, and public/private key attrs.

david415 commented 8 years ago

That sounds good!

meejah commented 8 years ago

So far, the WIP branch for this is: https://github.com/meejah/txtorcon/compare/hidden-service-api.2

meejah commented 6 years ago

A new onion services API has landed on master