putty/network.h

/*
 * Networking abstraction in PuTTY.
 *
 * The way this works is: a back end can choose to open any number
 * of sockets - including zero, which might be necessary in some.
 * It can register a bunch of callbacks (most notably for when
 * data is received) for each socket, and it can call the networking
 * abstraction to send data without having to worry about blocking.
 * The stuff behind the abstraction takes care of selects and
 * nonblocking writes and all that sort of painful gubbins.
 */

#ifndef PUTTY_NETWORK_H
#define PUTTY_NETWORK_H

#include "defs.h"

typedef struct SocketVtable SocketVtable;
typedef struct PlugVtable PlugVtable;

struct Socket {
    const struct SocketVtable *vt;
};

struct SocketVtable {
    Plug *(*plug) (Socket *s, Plug *p);
    /* use a different plug (return the old one) */
    /* if p is NULL, it doesn't change the plug */
    /* but it does return the one it's using */
    void (*close) (Socket *s);
    size_t (*write) (Socket *s, const void *data, size_t len);
    size_t (*write_oob) (Socket *s, const void *data, size_t len);
    void (*write_eof) (Socket *s);
    void (*set_frozen) (Socket *s, bool is_frozen);
    /* ignored by tcp, but vital for ssl */
    const char *(*socket_error) (Socket *s);
    SocketEndpointInfo *(*endpoint_info) (Socket *s, bool peer);
};

typedef union { void *p; int i; } accept_ctx_t;
typedef Socket *(*accept_fn_t)(accept_ctx_t ctx, Plug *plug);

struct Plug {
    const struct PlugVtable *vt;
};

typedef enum PlugLogType {
    PLUGLOG_CONNECT_TRYING,
    PLUGLOG_CONNECT_FAILED,
    PLUGLOG_CONNECT_SUCCESS,
    PLUGLOG_PROXY_MSG,
} PlugLogType;

typedef enum PlugCloseType {
    PLUGCLOSE_NORMAL,
    PLUGCLOSE_ERROR,
    PLUGCLOSE_BROKEN_PIPE,
    PLUGCLOSE_USER_ABORT,
} PlugCloseType;

struct PlugVtable {
    /*
     * Passes the client progress reports on the process of setting
     * up the connection.
     *
     *  - PLUGLOG_CONNECT_TRYING means we are about to try to connect
     *    to address `addr' (error_msg and error_code are ignored)
     *
     *  - PLUGLOG_CONNECT_FAILED means we have failed to connect to
     *    address `addr' (error_msg and error_code are supplied). This
     *    is not a fatal error - we may well have other candidate
     *    addresses to fall back to. When it _is_ fatal, the closing()
     *    function will be called.
     *
     *  - PLUGLOG_CONNECT_SUCCESS means we have succeeded in making a
     *    connection. `addr' gives the address we connected to, if
     *    available. (But sometimes, in cases of complicated proxy
     *    setups, it might not be available, so receivers of this log
     *    event should be prepared to deal with addr==NULL.)
     *
     *  - PLUGLOG_PROXY_MSG means that error_msg contains a line of
     *    logging information from whatever the connection is being
     *    proxied through. This will typically be a wodge of
     *    standard-error output from a local proxy command, so the
     *    receiver should probably prefix it to indicate this.
     *
     * Note that sometimes log messages may be sent even to Socket
     * types that don't involve making an outgoing connection, e.g.
     * because the same core implementation (such as Windows handle
     * sockets) is shared between listening and connecting sockets. So
     * all Plugs must implement this method, even if only to ignore
     * the logged events.
     */
    void (*log)(Plug *p, Socket *s, PlugLogType type, SockAddr *addr, int port,
                const char *error_msg, int error_code);

    /*
     * Notifies the Plug that the socket is closing, and something
     * about why.
     *
     *  - PLUGCLOSE_NORMAL means an ordinary non-error closure. In
     *    this case, error_msg should be ignored (and hopefully
     *    callers will have passed NULL).
     *
     *  - PLUGCLOSE_ERROR indicates that an OS error occurred, and
     *    'error_msg' contains a string describing it, for use in
     *    diagnostics. (Ownership of the string is not transferred.)
     *    This error class covers anything other than the special
     *    case below:
     *
     *  - PLUGCLOSE_BROKEN_PIPE behaves like PLUGCLOSE_ERROR (in
     *    particular, there's still an error message provided), but
     *    distinguishes the particular error condition signalled by
     *    EPIPE / ERROR_BROKEN_PIPE, which ssh/sharing.c needs to
     *    recognise and handle specially in one situation.
     *
     *  - PLUGCLOSE_USER_ABORT means that the close has happened as a
     *    result of some kind of deliberate user action (e.g. hitting
     *    ^C at a password prompt presented by a proxy socket setup
     *    phase). This can be used to suppress interactive error
     *    messages sent to the user (such as dialog boxes), on the
     *    grounds that the user already knows. However, 'error_msg'
     *    will still contain some appropriate text, so that
     *    non-interactive error reporting (e.g. event logs) can still
     *    record why the connection terminated.
     */
    void (*closing)(Plug *p, PlugCloseType type, const char *error_msg);

    /*
     * Provides incoming socket data to the Plug. Three cases:
     *
     *  - urgent==0. `data' points to `len' bytes of perfectly
     *    ordinary data.
     *
     *  - urgent==1. `data' points to `len' bytes of data,
     *    which were read from before an Urgent pointer.
     *
     *  - urgent==2. `data' points to `len' bytes of data,
     *    the first of which was the one at the Urgent mark.
     */
    void (*receive) (Plug *p, int urgent, const char *data, size_t len);

    /*
     * Called when the pending send backlog on a socket is cleared or
     * partially cleared. The new backlog size is passed in the
     * `bufsize' parameter.
     */
    void (*sent) (Plug *p, size_t bufsize);

    /*
     * Only called on listener-type sockets, and is passed a
     * constructor function+context that will create a fresh Socket
     * describing the connection. It returns nonzero if it doesn't
     * want the connection for some reason, or 0 on success.
     */
    int (*accepting)(Plug *p, accept_fn_t constructor, accept_ctx_t ctx);
};

/* Proxy indirection layer.
 *
 * Calling new_connection transfers ownership of 'addr': the proxy
 * layer is now responsible for freeing it, and the caller shouldn't
 * assume it exists any more.
 *
 * If calling this from a backend with a Seat, you can also give it a
 * pointer to the backend's Interactor trait. In that situation, it
 * might replace the backend's seat with a temporary seat of its own,
 * and give the real Seat to an Interactor somewhere in the proxy
 * system so that it can ask for passwords (and, in the case of SSH
 * proxying, other prompts like host key checks). If that happens,
 * then the resulting 'temp seat' is the backend's property, and it
 * will have to remember to free it when cleaning up, or after
 * flushing it back into the real seat when the network connection
 * attempt completes.
 *
 * You can free your TempSeat and resume using the real Seat when one
 * of two things happens: either your Plug's closing() method is
 * called (indicating failure to connect), or its log() method is
 * called with PLUGLOG_CONNECT_SUCCESS. In the latter case, you'll
 * probably want to flush the TempSeat's contents into the real Seat,
 * of course.
 */
Socket *new_connection(SockAddr *addr, const char *hostname,
                       int port, bool privport,
                       bool oobinline, bool nodelay, bool keepalive,
                       Plug *plug, Conf *conf, Interactor *interactor);
Socket *new_listener(const char *srcaddr, int port, Plug *plug,
                     bool local_host_only, Conf *conf, int addressfamily);
SockAddr *name_lookup(const char *host, int port, char **canonicalname,
                      Conf *conf, int addressfamily, LogContext *logctx,
                      const char *lookup_reason_for_logging);

/* platform-dependent callback from new_connection() */
/* (same caveat about addr as new_connection()) */
Socket *platform_new_connection(SockAddr *addr, const char *hostname,
                                int port, bool privport,
                                bool oobinline, bool nodelay, bool keepalive,
                                Plug *plug, Conf *conf, Interactor *itr);

/* callback for SSH jump-host proxying */
Socket *sshproxy_new_connection(SockAddr *addr, const char *hostname,
                                int port, bool privport,
                                bool oobinline, bool nodelay, bool keepalive,
                                Plug *plug, Conf *conf, Interactor *itr);

/* socket functions */

void sk_init(void);                    /* called once at program startup */
void sk_cleanup(void);                 /* called just before program exit */

SockAddr *sk_namelookup(const char *host, char **canonicalname, int address_family);
SockAddr *sk_nonamelookup(const char *host);
void sk_getaddr(SockAddr *addr, char *buf, int buflen);
bool sk_addr_needs_port(SockAddr *addr);
bool sk_hostname_is_local(const char *name);
bool sk_address_is_local(SockAddr *addr);
bool sk_address_is_special_local(SockAddr *addr);
int sk_addrtype(SockAddr *addr);
void sk_addrcopy(SockAddr *addr, char *buf);
void sk_addr_free(SockAddr *addr);
/* sk_addr_dup generates another SockAddr which contains the same data
 * as the original one and can be freed independently. May not actually
 * physically _duplicate_ it: incrementing a reference count so that
 * one more free is required before it disappears is an acceptable
 * implementation. */
SockAddr *sk_addr_dup(SockAddr *addr);

/* NB, control of 'addr' is passed via sk_new, which takes responsibility
 * for freeing it, as for new_connection() */
Socket *sk_new(SockAddr *addr, int port, bool privport, bool oobinline,
               bool nodelay, bool keepalive, Plug *p);

Socket *sk_newlistener(const char *srcaddr, int port, Plug *plug,
                       bool local_host_only, int address_family);

static inline Plug *sk_plug(Socket *s, Plug *p)
{ return s->vt->plug(s, p); }
static inline void sk_close(Socket *s)
{ s->vt->close(s); }
static inline size_t sk_write(Socket *s, const void *data, size_t len)
{ return s->vt->write(s, data, len); }
static inline size_t sk_write_oob(Socket *s, const void *data, size_t len)
{ return s->vt->write_oob(s, data, len); }
static inline void sk_write_eof(Socket *s)
{ s->vt->write_eof(s); }

static inline void plug_log(
    Plug *p, Socket *s, int type, SockAddr *addr, int port,
    const char *msg, int code)
{ p->vt->log(p, s, type, addr, port, msg, code); }
static inline void plug_closing(Plug *p, PlugCloseType type, const char *msg)
{ p->vt->closing(p, type, msg); }
static inline void plug_closing_normal(Plug *p)
{ p->vt->closing(p, PLUGCLOSE_NORMAL, NULL); }
static inline void plug_closing_error(Plug *p, const char *msg)
{ p->vt->closing(p, PLUGCLOSE_ERROR, msg); }
static inline void plug_closing_user_abort(Plug *p)
{ p->vt->closing(p, PLUGCLOSE_USER_ABORT, "User aborted connection setup"); }
static inline void plug_receive(Plug *p, int urg, const char *data, size_t len)
{ p->vt->receive(p, urg, data, len); }
static inline void plug_sent (Plug *p, size_t bufsize)
{ p->vt->sent(p, bufsize); }
static inline int plug_accepting(Plug *p, accept_fn_t cons, accept_ctx_t ctx)
{ return p->vt->accepting(p, cons, ctx); }

/*
 * Special error values are returned from sk_namelookup and sk_new
 * if there's a problem. These functions extract an error message,
 * or return NULL if there's no problem.
 */
const char *sk_addr_error(SockAddr *addr);
static inline const char *sk_socket_error(Socket *s)
{ return s->vt->socket_error(s); }

/*
 * Set the `frozen' flag on a socket. A frozen socket is one in
 * which all READABLE notifications are ignored, so that data is
 * not accepted from the peer until the socket is unfrozen. This
 * exists for two purposes:
 *
 *  - Port forwarding: when a local listening port receives a
 *    connection, we do not want to receive data from the new
 *    socket until we have somewhere to send it. Hence, we freeze
 *    the socket until its associated SSH channel is ready; then we
 *    unfreeze it and pending data is delivered.
 *
 *  - Socket buffering: if an SSH channel (or the whole connection)
 *    backs up or presents a zero window, we must freeze the
 *    associated local socket in order to avoid unbounded buffer
 *    growth.
 */
static inline void sk_set_frozen(Socket *s, bool is_frozen)
{ s->vt->set_frozen(s, is_frozen); }

/*
 * Return a structure giving some information about one end of
 * the socket. May be NULL, if nothing is available at all. If it is
 * not NULL, then it is dynamically allocated, and should be freed by
 * a call to sk_free_endpoint_info(). See below for the definition.
 */
static inline SocketEndpointInfo *sk_endpoint_info(Socket *s, bool peer)
{ return s->vt->endpoint_info(s, peer); }
static inline SocketEndpointInfo *sk_peer_info(Socket *s)
{ return sk_endpoint_info(s, true); }

/*
 * The structure returned from sk_endpoint_info, and a function to free
 * one (in utils).
 */
struct SocketEndpointInfo {
    int addressfamily;

    /*
     * Text form of the IPv4 or IPv6 address of the specified end of the
     * socket, if available, in the standard text representation.
     */
    const char *addr_text;

    /*
     * Binary form of the same address. Filled in if and only if
     * addr_text is not NULL. You can tell which branch of the union
     * is used by examining 'addressfamily'.
     */
    union {
        unsigned char ipv6[16];
        unsigned char ipv4[4];
    } addr_bin;

    /*
     * Remote port number, or -1 if not available.
     */
    int port;

    /*
     * Free-form text suitable for putting in log messages. For IP
     * sockets, repeats the address and port information from above.
     * But it can be completely different, e.g. for Unix-domain
     * sockets it gives information about the uid, gid and pid of the
     * connecting process.
     */
    const char *log_text;
};
void sk_free_endpoint_info(SocketEndpointInfo *ei);

/*
 * Simple wrapper on getservbyname(), needed by portfwd.c. Returns the
 * port number, in host byte order (suitable for printf and so on).
 * Returns 0 on failure. Any platform not supporting getservbyname
 * can just return 0 - this function is not required to handle
 * numeric port specifications.
 */
int net_service_lookup(const char *service);

/*
 * Look up the local hostname; return value needs freeing.
 * May return NULL.
 */
char *get_hostname(void);

/*
 * Trivial socket implementation which just stores an error. Found in
 * errsock.c.
 *
 * The consume_string variant takes an already-formatted dynamically
 * allocated string, and takes over ownership of that string.
 */
Socket *new_error_socket_fmt(Plug *plug, const char *fmt, ...)
    PRINTF_LIKE(2, 3);
Socket *new_error_socket_consume_string(Plug *plug, char *errmsg);

/*
 * Trivial plug that does absolutely nothing. Found in nullplug.c.
 */
extern Plug *const nullplug;

/*
 * Some trivial no-op plug functions, also in nullplug.c; exposed here
 * so that other Plug implementations can use them too.
 *
 * In particular, nullplug_log is useful to Plugs that don't need to
 * worry about logging.
 */
void nullplug_log(Plug *plug, Socket *s, PlugLogType type, SockAddr *addr,
                  int port, const char *err_msg, int err_code);
void nullplug_closing(Plug *plug, PlugCloseType type, const char *error_msg);
void nullplug_receive(Plug *plug, int urgent, const char *data, size_t len);
void nullplug_sent(Plug *plug, size_t bufsize);

/*
 * Similar no-op socket function.
 */
SocketEndpointInfo *nullsock_endpoint_info(Socket *s, bool peer);

/* ----------------------------------------------------------------------
 * Functions defined outside the network code, which have to be
 * declared in this header file rather than the main putty.h because
 * they use types defined here.
 */

void backend_socket_log(Seat *seat, LogContext *logctx, Socket *sock,
                        PlugLogType type, SockAddr *addr, int port,
                        const char *error_msg, int error_code, Conf *conf,
                        bool session_started);

typedef struct ProxyStderrBuf {
    char buf[8192];
    size_t size;
    const char *prefix;                /* must be statically allocated */
} ProxyStderrBuf;
void psb_init(ProxyStderrBuf *psb);
void psb_set_prefix(ProxyStderrBuf *psb, const char *prefix);
void log_proxy_stderr(Plug *plug, Socket *sock, ProxyStderrBuf *psb,
                      const void *vdata, size_t len);

/* ----------------------------------------------------------------------
 * The DeferredSocketOpener trait. This is a thing that some Socket
 * implementations may choose to own if they need to delay actually
 * setting up the underlying connection. For example, sockets used in
 * local-proxy handling (Unix FdSocket / Windows HandleSocket) might
 * need to do this if they have to prompt the user interactively for
 * parts of the command they'll run.
 *
 * Mostly, a DeferredSocketOpener implementation will keep to itself,
 * arrange its own callbacks in order to do whatever setup it needs,
 * and when it's ready, call back to its parent Socket via some
 * implementation-specific API of its own. So the shared API here
 * requires almost nothing: the only thing we need is a free function,
 * so that if the owner of a Socket of this kind needs to close it
 * before the deferred connection process is finished, the Socket can
 * also clean up the DeferredSocketOpener dangling off it.
 */

struct DeferredSocketOpener {
    const DeferredSocketOpenerVtable *vt;
};
struct DeferredSocketOpenerVtable {
    void (*free)(DeferredSocketOpener *);
};
static inline void deferred_socket_opener_free(DeferredSocketOpener *dso)
{ dso->vt->free(dso); }

DeferredSocketOpener *null_deferred_socket_opener(void);

#endif