libtls: expose error codes

[btrask]

First of all, thanks again for the great work on LibreSSL and libtls!

I'm using libtls as part of a HTTP library together with libuv (see previously https://github.com/libressl-portable/portable/issues/146#issuecomment-150015851). libuv can return error codes, which my library mostly just passes through.

libtls returns -1 on error, and provides tls_error and tls_config_error strings, but there is no way to get a more descriptive error code. I could try to parse the error strings, but that would be lunacy (they aren't standardized).

I understand and appreciate that libtls tries to keep its API simple, but I think every library no matter how simple has to support full error handling.

A simple API could mirror tls_error:

int tls_config_errno(struct tls_config *_config);
int tls_errno(struct tls *_ctx);

I understand that tracking error codes would mean touching every error handler in libtls. I would be okay with useful error codes being phased in gradually, and and a default/generic error code being returned in not-yet-supported cases.

I'm not very familiar with libssl so I'm not sure whether its error codes would be appropriate to reuse directly or whether libtls would need to define its own and translate them.

If this would be of interest I could put together a patch to get started.

Thanks again, Ben

[4a6f656c]

I'm not opposed to this and I suspected that it was something that we were likely to want at some point down the track. Parsing the human readable errors is certainly not recommended and machine suitable error codes would be definitely the better alternative. However, that said I'm certainly not going to contemplate anything as awkward as the OpenSSL error handling and associated error stacks.

I'm a little hesitant to use errno in the API names since that may lead to people thinking that they are standard Unix/POSIX errno values, rather than library specific ones... but then again, maybe it is not too much of an issue given the tls_ prefix.

Re actual error codes, we would define these ourselves - the long term goal is to reduce (and eventually remove) the dependency on libssl, so tying ourselves to existing error codes is not a good move.

The actual implementation would not be difficult and would just hook into the existing error call sites - as you suggested, we could do a first pass that adds unspecified error codes, then gradually make them more specific, or we could just set unspecified error codes from the existing error setting functions, then add new variants that took specific error codes.

So that I can get a better understanding of what you're requesting, what type of information is it that you want to be made available? And how specific would you want these error codes to be (for example, we can add an error code for "certificate verification failed", but that does not tell you why it failed - adding the why is obviously possible, but quickly turns a simple API and error interface into a much more complex problem). Also, how would you envisage using these? Would you want to map the error back to a message at some point, or are they just so that you can take different code paths based on the error code?

[btrask]

I have three use cases in mind:

• Debugging. When I originally filed this bug report, I had encountered a server that my libtls client program mysteriously couldn't connect to. The libtls error string was uninformative (something something "context failure" IIRC). I eventually figured out how to get the underlying LibreSSL error using the OpenSSL API, which was good enough for debugging purposes, but of course I wouldn't want to rely on it. (The problem turned out to be the server didn't support the ciphers/protocols I was using, which is one of the big things I'd like to find out.)
• Reporting. For example, writing a cURL-style program that needs to tell the user why a connection failed. The current error strings aren't descriptive enough for this either, and are difficult to adapt (e.g. for localization).
• Wrapping. It should be possible to write a library that wraps libtls and reports TLS errors in a uniform way with other errors (i.e. using error codes). The wrapper doesn't necessarily care what error codes libtls returns, it just passes them through. Right now it's only possible to return one error code, "something TLS-related happened," which is less useful than it could be.

As for the precise granularity, I'm not sure. I'd suggest that there should be corresponding errors for most configuration options, e.g. "bad cipher," "bad protocol version," "cert name mismatch," "cert time mismatch/expired." Basically, anytime the user might've configured libtls wrong, libtls should be able to indicate that.

Also, I think underlying read/write errors should be reported in a useful way (but I'm not sure how).

Thanks for the response!

[Klayflash]

Error codes are helpful for automatic testing also.