[tor-dev] Exposing onion service errors to Tor Browser

[George Kadianakis]

Hello list,

we've recently been thinking about how to expose onion-service-related
errors to Tor Browser so that we can give more useful error pages to
users.  We currently return "Unable to connect" error pages for any kind
of onion service error, and I think we can do better.

This is a thread to think about the errors we want to expose, how that
should look like, and what options we should give to the users when it
happens. Relevant master tickets are #30022, #30025 and #30000.

We decided (in #14389) that Tor will export these errors through the
SOCKS port, and the relevant spec is proposal 304 [0].

As part of #30090 antonela started making a table of potential
errors. I'm gonna use that in this thread and also add a few more.

Let's go:

= Client-level errors =

These are errors on the user side of things: 

=== 1) Typo error on address ===

    This can be detected by Tor using the checksum or if the address is
    too big or too small.

    TODO: We will need to add a new error code to prop304. Not sure if
    the error code should distinguish between checksum fail or length fail.

    There is no recovery here since the address is busted. The user
    needs to find the right one.

=== 2) Missing Client Authorization ===

    This is prop304's 'F4' error (see #30382), and it means that we
    can't decrypt the descriptor because it requires client auth, but we
    don't have it configured.

    The recovery here is the whole point of #30237 where we make a
    dialog for the user to insert their client auth credentials.

=== 3) Wrong Client Authorization ===

    This is prop304's 'F5' error, and it means that there client auth
    credentials configured for this onion are wrong.

    The user recovery here is unclear but it might be that they need to
    change their client auth credentials. IMO, we should not try to make
    the perfect UX here, and we should just go with something super
    simple.

= Service-level errors =

These are errors on the onion service side:

=== 4) Service Descriptor Can Not be Found ===

    This is prop304's 'F0' error, and it means that we could not find
    the descriptor of the service on the directory servers. This means
    that the service is not up right now (or, more unlikely, that some
    bug has happened somewhere).

    The user recovery here is unclear. The user can try to reconnect in
    case the service got up in the meanwhile, but this is not so likely
    in a small period of time.

    Perhaps we can give the user the option to reconnect every 10
    seconds or so? Does this make sense from a UX PoV?

    Again this equivalent to a "Remote host is down" error and we should
    use it as such.

= Network-level errors =

These are errors caused by the network (directory servers, intro points,
rendezvous points) or even the service itself. It's kinda unclear given
all the hops involved. 

=== 5) Onion Service Descriptor Is Invalid ===

    This is prop304's 'F1' error and it means that we got a descriptor
    back from the directory but it's corrupted.

    This is very unlikely to happen since directory servers do not keep
    corrupted descriptors, so it usually means that some bug happened
    somewhere (or that the directory is bad or confused).

    In terms of recovery and error page, this is kinda an
    "Oops. Internal error." situation where this is rare and weird and
    hence we don't know what's the best recovery option. We can give the
    option to reconnect but it's likely not gonna help much.

    Again this should never really appear, so let's not stress too much
    over it.

=== 6) Onion Service Introduction Failed ===

    This is prop304's 'F2' error and it means that for some reason the
    introduction did not complete. This could be because the onion
    service is not up anymore, or it could be because the network is
    screwed in some way (e.g. the service is DoSed).

    The recovery here might be some 'reconnect' button which could be
    helpful in case of a DoS situation, but it would not help much if
    the service is not up anymore.

=== 7) Onion Service Rendezvous Failed ===

    This is prop304's 'F3' error and it means that the rendezvous did
    not complete. This usually means that the service is having a bad
    time, and is either DoSed or it generally cannot cope.

    The recovery again here is some 'reconnect' button, since if we did
    the introduction successfuly, the service is up, and reconnecting
    might work at some point.

    This one and (6) are very related and perhaps they can be handlded
    identically, since exposing terms like "intro" and "rend" to users
    will not be nice. Still we might want to expose a technical error
    value somewhere for debugging purposes when users come to us.

=======================================================================

I think the above set of errors will satisfy all our needs. In
particular:
- #30022 (typos ticket) needs error (1) from above.
- #30025 (client errors ticket) needs errors (4), (5), (6), (7) from above.
- #30000 (client auth) needs errors (2) and (3) from above.

In terms of error page, I'm not sure how it should look like. Perhaps
along with the error description and the recovery path, we should
provide some education about onion services to the users?

In terms of unsafe paths, I don't see any of these errors being
dangerous in terms of causing security issues if you attempt to
reconnect or anything. The Tor protocol takes care of this in the layer
below. The worst thing you can do is slightly damage the network from
too many reconnects, but I think that's OK since people who use the TB
are legitimate users and not DoS attackers.

===

Hope this was useful!

[0]:
https://github.com/torproject/torspec/blob/master/proposals/304-socks5-extending-hs-error-codes.txt