1 /* 2 socket handling interface 3 Copyright (C) 1999-2021, Joe Orton <joe@manyfish.co.uk> 4 5 This library is free software; you can redistribute it and/or 6 modify it under the terms of the GNU Library General Public 7 License as published by the Free Software Foundation; either 8 version 2 of the License, or (at your option) any later version. 9 10 This library is distributed in the hope that it will be useful, 11 but WITHOUT ANY WARRANTY; without even the implied warranty of 12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 13 Library General Public License for more details. 14 15 You should have received a copy of the GNU Library General Public 16 License along with this library; if not, write to the Free 17 Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, 18 MA 02111-1307, USA 19 20 */ 21 22 #ifndef NE_SOCKET_H 23 #define NE_SOCKET_H 24 25 #include <sys/types.h> 26 27 #ifdef WIN32 28 #include <stdlib.h> /* for size_t */ 29 #endif 30 31 #include "ne_defs.h" 32 #include "ne_ssl.h" /* for ne_ssl_context */ 33 34 NE_BEGIN_DECLS 35 36 #define NE_SOCK_ERROR (-1) 37 /* Read/Write timed out */ 38 #define NE_SOCK_TIMEOUT (-2) 39 /* Socket was closed */ 40 #define NE_SOCK_CLOSED (-3) 41 /* Connection was reset (e.g. server crashed) */ 42 #define NE_SOCK_RESET (-4) 43 /* Secure connection was closed without proper SSL shutdown. */ 44 #define NE_SOCK_TRUNC (-5) 45 /* Retry operation later. */ 46 #define NE_SOCK_RETRY (-6) 47 48 /* ne_socket represents a TCP socket. */ 49 typedef struct ne_socket_s ne_socket; 50 51 /* ne_sock_addr represents an address object. */ 52 typedef struct ne_sock_addr_s ne_sock_addr; 53 54 #ifndef NE_INET_ADDR_DEFINED 55 typedef struct ne_inet_addr_s ne_inet_addr; 56 #endif 57 58 /* Perform process-global initialization of any libraries in use. 59 * Returns non-zero on error. */ 60 int ne_sock_init(void); 61 62 /* Perform process-global shutdown of any libraries in use. This 63 * function only has effect when it has been called an equal number of 64 * times to ne_sock_init() for the process. */ 65 void ne_sock_exit(void); 66 67 #define NE_ADDR_CANON (0x01) 68 /* Resolve the given hostname. Hex string IPv6 addresses (e.g. `::1') 69 * may be enclosed in brackets (e.g. `[::1]'). 'flags' should be 70 * zero, or if NE_ADDR_CANON is passed, the canonical name for the 71 * hostname will be determined. */ 72 ne_sock_addr *ne_addr_resolve(const char *hostname, int flags); 73 74 /* Returns zero if name resolution was successful, non-zero on 75 * error. */ 76 int ne_addr_result(const ne_sock_addr *addr); 77 78 /* Returns the first network address associated with the 'addr' 79 * object. Undefined behaviour if ne_addr_result returns non-zero for 80 * 'addr'; otherwise, never returns NULL. */ 81 const ne_inet_addr *ne_addr_first(ne_sock_addr *addr); 82 83 /* Returns the next network address associated with the 'addr' object, 84 * or NULL if there are no more. */ 85 const ne_inet_addr *ne_addr_next(ne_sock_addr *addr); 86 87 /* NB: the pointers returned by ne_addr_first and ne_addr_next are 88 * valid until ne_addr_destroy is called for the corresponding 89 * ne_sock_addr object. They must not be passed to ne_iaddr_free. */ 90 91 /* If name resolution fails, copies the error string into 'buffer', 92 * which is of size 'bufsiz'. 'buffer' is returned. */ 93 char *ne_addr_error(const ne_sock_addr *addr, char *buffer, size_t bufsiz); 94 95 /* Returns the canonical name of the host as a NUL-terminated string, 96 * if NE_ADDR_CANON was used, and name resolution was successful. 97 * Otherwise, returns NULL. */ 98 const char *ne_addr_canonical(const ne_sock_addr *addr); 99 100 /* Destroys an address object created by ne_addr_resolve. */ 101 void ne_addr_destroy(ne_sock_addr *addr); 102 103 /* Network address type; IPv4 or IPv6 */ 104 typedef enum { 105 ne_iaddr_ipv4 = 0, 106 ne_iaddr_ipv6 107 } ne_iaddr_type; 108 109 /* Create a network address object from raw byte representation (in 110 * network byte order) of given type. 'raw' must be four bytes for an 111 * IPv4 address, 16 bytes for an IPv6 address. May return NULL if 112 * address type is not supported. */ 113 ne_inet_addr *ne_iaddr_make(ne_iaddr_type type, const unsigned char *raw); 114 115 /* Compare two network address objects i1 and i2; returns zero if they 116 * are equivalent or non-zero otherwise. */ 117 int ne_iaddr_cmp(const ne_inet_addr *i1, const ne_inet_addr *i2); 118 119 /* Return the type of the given network address object. */ 120 ne_iaddr_type ne_iaddr_typeof(const ne_inet_addr *ia); 121 122 /* Print the string representation of network address 'ia' into the 123 * buffer 'buffer', which is of length 'bufsiz'. Returns 'buffer'. */ 124 char *ne_iaddr_print(const ne_inet_addr *ia, char *buffer, size_t bufsiz); 125 126 /* Dump the raw byte representation (in network byte order) of address 127 * 'ia' into the buffer 'buffer', which must be of a suitable length 128 * (4 bytes for an IPv4 address, 16 bytes for an IPv6 address). 129 * Returns 'buffer'. */ 130 unsigned char *ne_iaddr_raw(const ne_inet_addr *ia, unsigned char *buffer); 131 132 /* Perform the reverse name lookup on network address 'ia', placing 133 * the returned name in the 'buf' buffer (of length 'bufsiz') if 134 * successful. Returns zero on success, or non-zero on error. */ 135 int ne_iaddr_reverse(const ne_inet_addr *ia, char *buf, size_t bufsiz); 136 137 /* Convert network address string 'addr' (for example, "127.0.0.1") 138 * into a network address object. Returns NULL on parse error. If 139 * non-NULL, return value must be freed using ne_iaddr_free. */ 140 ne_inet_addr *ne_iaddr_parse(const char *addr, ne_iaddr_type type); 141 142 /* Destroy a network address object created using ne_iaddr_make or 143 * ne_iaddr_parse. */ 144 void ne_iaddr_free(ne_inet_addr *addr); 145 146 /* Create a socket object; returns NULL on error. */ 147 ne_socket *ne_sock_create(void); 148 149 /* Specify an address to which the local end of the socket will be 150 * bound during a subsequent ne_sock_connect() call. If the address 151 * passed to ne_sock_connect() is of a different type (family) to 152 * 'addr', 'addr' is ignored. Either 'addr' may be NULL, to use the 153 * given port with unspecified address, or 'port' may be 0, to use the 154 * given address with an unspecified port. 155 * 156 * (Note: This function is not equivalent to a BSD socket bind(), it 157 * only takes effect during the _connect() call). */ 158 void ne_sock_prebind(ne_socket *sock, const ne_inet_addr *addr, 159 unsigned int port); 160 161 /* Connect the socket to server at address 'addr' on port 'port'. 162 * Returns zero on success, NE_SOCK_TIMEOUT if a timeout occurs when a 163 * non-zero connect timeout is configured (and is supported), or 164 * NE_SOCK_ERROR on failure. */ 165 int ne_sock_connect(ne_socket *sock, const ne_inet_addr *addr, 166 unsigned int port); 167 168 /* Read up to 'count' bytes from socket into 'buffer'. Returns: 169 * NE_SOCK_* on error, 170 * >0 length of data read into buffer (may be less than 'count') 171 */ 172 ssize_t ne_sock_read(ne_socket *sock, char *buffer, size_t count); 173 174 /* Read up to 'count' bytes into 'buffer', leaving the data available 175 * in the socket buffer to be returned by a subsequent call to 176 * ne_sock_read or ne_sock_peek. Returns: 177 * NE_SOCK_* on error, 178 * >0 length of data read into buffer. 179 */ 180 ssize_t ne_sock_peek(ne_socket *sock, char *buffer, size_t count); 181 182 /* Block for up to 'n' seconds until data becomes available for reading 183 * from the socket. Returns: 184 * NE_SOCK_* on error, 185 * NE_SOCK_TIMEOUT if no data arrives in 'n' seconds, 186 * 0 if data arrived on the socket. 187 */ 188 int ne_sock_block(ne_socket *sock, int n); 189 190 /* Write 'count' bytes of 'data' to the socket. Guarantees to either 191 * write all the bytes or to fail. Returns 0 on success, or NE_SOCK_* 192 * on error. */ 193 int ne_sock_fullwrite(ne_socket *sock, const char *data, size_t count); 194 195 /* I/O vector. */ 196 struct ne_iovec { 197 void *base; 198 size_t len; 199 }; 200 201 /* Writes 'count' blocks described by 'vector' to the socket. 202 * Guarantees to either write all the bytes or to fail. Count must be 203 * greater than zero and smaller than the system-defined maximum 204 * vector limit. Returns 0 on success, or NE_SOCK_* on error. */ 205 int ne_sock_fullwritev(ne_socket *sock, const struct ne_iovec *vector, 206 int count); 207 208 /* Read an LF-terminated line into 'buffer', and NUL-terminate it. 209 * At most 'len' bytes are read (including the NUL terminator). 210 * Returns: 211 * NE_SOCK_* on error, 212 * >0 number of bytes read (including NUL terminator) 213 */ 214 ssize_t ne_sock_readline(ne_socket *sock, char *buffer, size_t len); 215 216 /* Read exactly 'len' bytes into buffer, or fail; returns 0 on 217 * success, NE_SOCK_* on error. */ 218 ssize_t ne_sock_fullread(ne_socket *sock, char *buffer, size_t len); 219 220 /* Accepts a connection from listening socket 'fd' and places the 221 * socket in 'sock'. Returns zero on success or -1 on failure. */ 222 int ne_sock_accept(ne_socket *sock, int fd); 223 224 /* Returns the file descriptor used for socket 'sock'. */ 225 int ne_sock_fd(const ne_socket *sock); 226 227 /* Return address of peer, or NULL on error. The returned address 228 * must be destroyed by caller using ne_iaddr_free. */ 229 ne_inet_addr *ne_sock_peer(ne_socket *sock, unsigned int *port); 230 231 /* Flags for ne_sock_shutdown(): */ 232 #define NE_SOCK_RECV (1) 233 #define NE_SOCK_SEND (2) 234 #define NE_SOCK_BOTH (3) 235 236 /* Shut down the socket in one or both directions, without destroying 237 * the socket object. Flags must be one of NE_SOCK_RECV/SEND/BOTH. 238 * For a non-TLS socket, performs the directional shutdown according 239 * to flags. 240 * For a TLS socket: 241 * - if flags are NE_SOCK_SEND or NE_SOCK_BOTH, sends the TLS 242 * close_notify. Returns NE_SOCK_RETRY if the TLS connection has 243 * not been closed by the peer. 244 * - if flags are NE_SOCK_RECV, returns NE_SOCK_RETRY if the 245 * TLS close_notify has not been closed by the peer. 246 * In NE_SOCK_SEND or NE_SOCK_BOTH is specified, and the bidirectional 247 * TLS shutdown has completed, the TCP shutdown will also be completed 248 * as for a non-TLS socket. 249 */ 250 int ne_sock_shutdown(ne_socket *sock, unsigned int flags); 251 252 /* Close the socket if it is open, and destroy the socket object. If 253 * SSL is in use for the socket, a closure alert is sent to initiate a 254 * clean shutdown, but this function does not wait for the peer's 255 * response. Returns zero on success, or non-zero on failure. */ 256 int ne_sock_close(ne_socket *sock); 257 258 /* Return current error string for socket. */ 259 const char *ne_sock_error(const ne_socket *sock); 260 261 /* Set the error string for the socket; takes printf-like format 262 * string. */ 263 void ne_sock_set_error(ne_socket *sock, const char *format, ...) 264 ne_attribute((format (printf, 2, 3))); 265 266 /* Set read timeout for socket, in seconds; must be a non-zero 267 * positive integer. */ 268 void ne_sock_read_timeout(ne_socket *sock, int timeout); 269 270 /* Set connect timeout for socket, in seconds; must be a positive 271 * integer. If a timeout of 'zero' is used then then no explicit 272 * timeout handling will be used for ne_sock_connect(), and the 273 * connect call will only timeout as dictated by the TCP stack. */ 274 void ne_sock_connect_timeout(ne_socket *sock, int timeout); 275 276 /* Negotiate an SSL connection on socket as an SSL server, using given 277 * SSL context. */ 278 int ne_sock_accept_ssl(ne_socket *sock, ne_ssl_context *ctx); 279 280 /* Negotiate an SSL connection on socket as an SSL client, using given 281 * SSL context. The 'userdata' parameter is associated with the 282 * underlying SSL library's socket structure for use in callbacks. 283 * Returns zero on success, or non-zero on error. */ 284 int ne_sock_connect_ssl(ne_socket *sock, ne_ssl_context *ctx, 285 void *userdata); 286 287 /* Retrieve the session ID of the current SSL session. If 'buf' is 288 * non-NULL, on success, copies at most *buflen bytes to 'buf' and 289 * sets *buflen to the exact number of bytes copied. If 'buf' is 290 * NULL, on success, sets *buflen to the length of the session ID. 291 * Returns zero on success, non-zero on error. */ 292 int ne_sock_sessid(ne_socket *sock, unsigned char *buf, size_t *buflen); 293 294 /* Return human-readable name of SSL/TLS cipher used for connection, 295 * or NULL if none. The format of this string is not intended to be 296 * fixed or parseable, but is informational only. Return value is 297 * NUL-terminated malloc-allocated string if not NULL, which must be 298 * freed by the caller. */ 299 char *ne_sock_cipher(ne_socket *sock); 300 301 /* SOCKS proxy protocol version: */ 302 enum ne_sock_sversion { 303 NE_SOCK_SOCKSV4 = 0, 304 NE_SOCK_SOCKSV4A, 305 NE_SOCK_SOCKSV5 306 }; 307 308 /* Given a socket 'sock' which is connected to a SOCKS proxy, initiate 309 * a connection to a destination server using that proxy, specified 310 * either by network address or hostname, at given port 'port'. 311 * 312 * If 'vers' is NE_SOCKS_V4, addr must be an IPv4 address; hostname 313 * and password are ignored; username must be non-NULL. 314 * 315 * If 'vers' is NE_SOCKS_V4A, hostname must be non-NULL; addr is 316 * ignored; password is ignored; username must be non-NULL. 317 * 318 * If 'vers' is NE_SOCKS_V5, addr may be NULL, in which case hostname 319 * must be non-NULL. addr if non-NULL may be an IPv4 or IPv6 address; 320 * username may be NULL, in which case password is ignored. If 321 * username is non-NULL password must also be non-NULL. 322 * 323 * Returns 0 on success, or NE_SOCK_* on failure - in which case, the 324 * socket error string is set. On failure, the socket must be closed 325 * by the caller. 326 */ 327 int ne_sock_proxy(ne_socket *sock, enum ne_sock_sversion vers, 328 const ne_inet_addr *addr, const char *hostname, 329 unsigned int port, 330 const char *username, const char *password); 331 332 NE_END_DECLS 333 334 #endif /* NE_SOCKET_H */ 335