Exceptions

Unlike native sockets, Cleansocks throws exceptions to report errors. The library has several, all derived from the class socket_error, which is derived from the standard C++ runtime_error. Their inheritance relationships are sketched at the right, with the descendents of socket_tls_error omitted. They are listed below. The socket_error class is the base of any exception detected by this library. There are a few places which throw exceptions of exactly this type. For most purposes, if you need to catch anything, catch socket_error &.

The socket_sys_error exceptions represent errors reported from the basic socket calls. That would include creating sockets, sending, receiving, listening and accepting. The socket_would_block error wraps the system error return of the same type (hence it's a socket_sys_error). This is separated out as a convenience for programs which use non-blocking I/O and will need to handle it separately. (You're probably not doing that.) The socket_db_error is thrown by failures of host or service name performed by lookup_host or lookup_service. This division reflects one in the underlying socket interface. The socket_interface_error is thrown by misuse of the cleansocks interface. The system is designed so that most failures to follow the rules result in type errors reported at compile time, but this exception is here for when I can't figure out how to do that. The cleantlsc package throws socket_tls_error when it detects a problem. These are generally thrown as one of several descendents, which are listed below.

The std::runtime_error class and all its children have a .what() method which returns a descriptive string. The socket_sys_error and socket_db_error also implement a method .code() which returns the integer error code reported by the system. Code values will differ based on the underlying operating system, so you should avoid using .code() without some special reason.

The .what() strings for socket_sys_error and socket_db_error are the error messages provided by the underlying system, and will have different text on different OSes. Error codes for socket_db_error are error return values from the underlying socket functions, mapped to strings by the socket call gai_strerror(). For socket_sys_error, under Unix the codes come from errno and are mapped by strerror_r; on Winsock, they come from WSAGetLastError() and are interpreted by FormatMessage(), a seven-parameter monstrosity that could have come from nowhere but Redmond. For socket_tls_error, some exceptions follow from error reported by OpenSSL, and contain the OpenSSL's error message. Errors detected by logic in the cleantlsc wrapper code provide (supposedly) appropriate messages.

The TLS Exceptions

As promised. All exceptions are directly descended from socket_tls_error, except socket_tls_send_shut which is derived from socket_tls_send.

socket_tls_context_create

OpenSSL reported an error creating the context object. This is shared between all TLS sockets, and is created when the first one is created.

socket_tls_ca_path

No authority file was set with the authority_file method, and regular search did not find one.

socket_tls_set_ca

OpenSSL reported an error when setting the authority file, either the one found by the default search on specified with the authority_file method.

socket_tls_ssl_create

OpenSSL reported an error creating the ssl state object. These are created before TLS is started to hold the state established by the negotiation.

socket_tls_creating_bio

OpenSSL reported an error creating the basic IO object. The basic IO layer is OpenSSL's abstraction of the socket (or other underlying communications facility). Cleantlsc creates these when tls is started.

socket_tls_handshake

OpenSSL reported an error performing the TLS handshake with the server.

socket_tls_send

OpenSSL reported an error performing a send operation.

socket_tls_send_shut

This is a specialation of socket_tls_send, where the reason is that the connection has been shut down.

socket_tls_recv

OpenSSL reported an error performing a recv operation.

socket_tls_bad_cert

OpenSSL was not able to verify a certificate sent by a server. There are several flags to the start_tls method which can limit or disable this check, avoiding the exception.

socket_tls_start_started

User called the start_tls method when the socket had already started TLS.

socket_tls_session_sharing_fail

An attempt to start TLS with a shared session failed, either because the socket whose session was to shared did not have one, or because the OpenSSL reports an error when asked to perform the sharing.