diff options
Diffstat (limited to 'lib/tsocket/tsocket_guide.txt')
| -rw-r--r-- | lib/tsocket/tsocket_guide.txt | 503 |
1 files changed, 503 insertions, 0 deletions
diff --git a/lib/tsocket/tsocket_guide.txt b/lib/tsocket/tsocket_guide.txt new file mode 100644 index 0000000000..a02fa373fa --- /dev/null +++ b/lib/tsocket/tsocket_guide.txt @@ -0,0 +1,503 @@ + +Basic design of the tsocket abstraction +======================================= + +The tsocket layer is designed to match more or less +the bsd socket layer, but it hides the filedescriptor +within a opaque 'tsocket_context' structure to make virtual +sockets possible. The virtual sockets can be encrypted tunnels +(like TLS, SASL or GSSAPI) or named pipes over smb. + +The tsocket layer is a bit like an abstract class, which defines +common methods to work with sockets in a non blocking fashion. + +The whole library is based on the talloc(3) and 'tevent' libraries. + +The 'tsocket_address' structure is the 2nd abstracted class +which represends the address of a socket endpoint. + +Each different type of socket has its own constructor. + +Typically the constructor for a tsocket_context is attached to +the tsocket_address of the source endpoint. That means +the tsocket_address_create_socket() function takes the +tsocket_address of the local endpoint and creates a tsocket_context +for the communication. + +For some usecases it's possible to wrap an existing socket into a +tsocket_context, e.g. to wrap an existing pipe(2) into +tsocket_context, so that you can use the same functions to +communicate over the pipe. + +The tsocket_address abstraction +=============================== + +The tsocket_address represents an socket endpoint genericly. +As it's like an abstract class it has no specific constructor. +The specific constructors are descripted later sections. + +There's a function get the string representation of the +endpoint for debugging. Callers should not try to parse +the string! The should use additional methods of the specific +tsocket_address implemention to get more details. + + char *tsocket_address_string(const struct tsocket_address *addr, + TALLOC_CTX *mem_ctx); + +There's a function to create a copy of the tsocket_address. +This is useful when before doing modifications to a socket +via additional methods of the specific tsocket_address implementation. + + struct tsocket_address *tsocket_address_copy(const struct tsocket_address *addr, + TALLOC_CTX *mem_ctx); + +There's a function to create a tsocket_context based on the given local +socket endpoint. The return value is 0 on success and -1 on failure +with errno holding the specific error. Specific details are descripted in later +sections. Note not all specific implementation have to implement all socket +types. + + enum tsocket_type { + TSOCKET_TYPE_STREAM = 1, + TSOCKET_TYPE_DGRAM, + TSOCKET_TYPE_MESSAGE + }; + + int tsocket_address_create_socket(const struct tsocket_address *addr, + enum tsocket_type type, + TALLOC_CTX *mem_ctx, + struct tsocket_context **sock); + +The tsocket_context abstraction +=============================== + +The tsocket_context is like an abstract class and represents +a socket similar to bsd style sockets. The methods are more +or less equal to the bsd socket api, while the filedescriptor +is replaced by tsocket_context and sockaddr, socklen_t pairs +are replaced by tsocket_address. The 'bind' operation happens +in the specific constructor as the constructor is typically based +on tsocket_address of local socket endpoint. + +All operations are by design non blocking and can return error +values like EAGAIN, EINPROGRESS, EWOULDBLOCK or EINTR which +indicate that the caller should retry the operation later. +Also read the "The glue to tevent" section. + +The socket can of types: + - TSOCKET_TYPE_STREAM is the equivalent to SOCK_STREAM in the bsd socket api. + - TSOCKET_TYPE_DGRAM is the equivalent to SOCK_DGRAM in the bsd socket api. + - TSOCKET_TYPE_MESSAGE operates on a connected socket and is therefore + like TSOCKET_TYPE_STREAM, but the consumer needs to first read all + data of a message, which was generated by one message 'write' on the sender, + before the consumer gets data of the next message. This matches a bit + like message mode pipes on windows. The concept is to transfer ordered + messages between to endpoints. + +There's a function to connect to a remote endpoint. The behavior +and error codes match the connect(2) function of the bsd socket api. +Maybe the specific tsocket_context implementation speficied some +further details. + + int tsocket_connect(struct tsocket_context *sock, + const struct tsocket_address *remote_addr); + +There's a function to listen for incoming connections. The behavior +and error codes match the listen(2) function of the bsd socket api. +Maybe the specific tsocket_context implementation speficied some +further details. + + int tsocket_listen(struct tsocket_context *sock, + int queue_size); + +There's a function to accept incoming connections. The behavior +and error codes match the accept(2) function of the bsd socket api. +Maybe the specific tsocket_context implementation speficied some +further details. + + int tsocket_accept(struct tsocket_context *sock, + TALLOC_CTX *mem_ctx, + struct tsocket_context **new_sock); + +There's a function to ask how many bytes are in input buffer +of the connection. For sockets of type TSOCKET_TYPE_DGRAM or +TSOCKET_TYPE_MESSAGE the size of the next available dgram/message +is returned. A return value of -1 indicates a socket error +and errno will hold the specific error code. If no data +is available 0 is returned, but retry error codes like +EINTR can also be returned. + + ssize_t tsocket_pending(struct tsocket_context *sock); + +There's a function to read data from the socket. The behavior +and error codes match the readv(3) function, also take a look +at the recv(2) function of the bsd socket api. +Maybe the specific tsocket_context implementation speficied some +further details. + + int tsocket_readv(struct tsocket_context *sock, + const struct iovec *vector, size_t count); + +There's a function to write data from the socket. The behavior +and error codes match the writev(3) function, also take a look +at the send(2) function of the bsd socket api. +Maybe the specific tsocket_context implementation speficied some +further details. + + int tsocket_writev(struct tsocket_context *sock, + const struct iovec *vector, size_t count); + +There's a function to read a datagram from a remote endpoint. +The behavior and error codes match the recvfrom(2) function of +the bsd socket api. As TSOCKET_TYPE_DGRAM sockets can also be +used in connected mode src_addr can be NULL, if the caller don't +want to get the source address. Maybe the specific tsocket_context +implementation speficied some further details. + + ssize_t tsocket_recvfrom(struct tsocket_context *sock, + uint8_t *data, size_t len, + TALLOC_CTX *addr_ctx, + struct tsocket_address **src_addr); + +There's a function to send a datagram to a remote endpoint the socket. +The behavior and error codes match the recvfrom(2) function of the +bsd socket api. As TSOCKET_TYPE_DGRAM sockets can also be used in +connected mode dest_addr must be NULL in connected mode and a valid +tsocket_address otherwise. Maybe the specific tsocket_context +implementation speficied some further details. + + ssize_t tsocket_sendto(struct tsocket_context *sock, + const uint8_t *data, size_t len, + const struct tsocket_address *dest_addr); + +There's a function to get the current status of the socket. +The behavior and error codes match the getsockopt(2) function +of the bsd socket api, with SOL_SOCKET and SO_ERROR as arguments. +Maybe the specific tsocket_context implementation speficied some +further details. + + int tsocket_get_status(const struct tsocket_context *sock); + +There's a function to get tsocket_address of the local endpoint. +The behavior and error codes match the getsockname(2) function +of the bsd socket api. Maybe the specific tsocket_context +implementation speficied some further details. + + int tsocket_get_local_address(const struct tsocket_context *sock, + TALLOC_CTX *mem_ctx, + struct tsocket_address **local_addr); + +There's a function to get tsocket_address of the remote endpoint +of a connected socket. The behavior and error codes match the +getpeername(2) function of the bsd socket api. Maybe the specific +tsocket_context implementation speficied some further details. + + int tsocket_get_remote_address(const struct tsocket_context *sock, + TALLOC_CTX *mem_ctx, + struct tsocket_address **remote_addr, + const char *location); + +There's a function to ask for specific options of the socket. +The behavior and error codes match the getsockopt(2) function +of the bsd socket api. The option and value are represented as string +values, where the 'value' parameter can be NULL is the caller don't want to +get the value. The supported options and values are up to the specific +tsocket_context implementation. + + int tsocket_get_option(const struct tsocket_context *sock, + const char *option, + TALLOC_CTX *mem_ctx, + char **value); + +There's a function to set specific options of the socket. +The behavior and error codes match the setsockopt(2) function +of the bsd socket api. The option and value are represented as string +values, where the 'value' parameter can be NULL. The supported options +and values are up to the specific tsocket_context implementation. +The 'force' parameter specifies whether an error should be returned +for unsupported options. + + int tsocket_set_option(const struct tsocket_context *sock, + const char *option, + bool force, + const char *value); + +There's a function to disconnect the socket. The behavior +and error codes match the close(2) function of the bsd socket api. +Maybe the specific tsocket_context implementation speficied some +further details. + + void tsocket_disconnect(struct tsocket_context *sock); + +The glue to tevent +================== + +As the tsocket library is based on the tevent library, +there need to be functions to let the caller register +callback functions, which are triggered when the socket +is writeable or readable. Typically one would use +tevent fd events, but in order to hide the filedescriptor +the tsocket_context abstraction has their own functions. + +There's a function to set the currently active tevent_context +for the socket. It's important there's only one tevent_context +actively used with the socket. A second call will cancel +all low level events made on the old tevent_context, it will +also resets the send and recv handlers to NULL. If the caller +sets attaches a new event context to the socket, the callback +function also need to be registered again. It's important +that the caller keeps the given tevent_context in memory +and actively calls tsocket_set_event_context(sock, NULL) +before calling talloc_free(event_context). +The function returns 0 on success and -1 together with an errno +on failure. + + int tsocket_set_event_context(struct tsocket_context *sock, + struct tevent_context *ev); + +There's a function to register a callback function which is called +when the socket is readable. If the caller don't want to get notified +anymore the function should be called with NULL as handler. +The function returns 0 on success and -1 together with an errno +on failure. + + typedef void (*tsocket_event_handler_t)(struct tsocket_context *, void *); + int tsocket_set_readable_handler(struct tsocket_context *sock, + tsocket_event_handler_t handler, + void *private_data); + +There's a function to register a callback function which is called +when the socket is writeable. If the caller don't want to get notified +anymore the function should be called with NULL as handler. +The function returns 0 on success and -1 together with an errno +on failure. + + typedef void (*tsocket_event_handler_t)(struct tsocket_context *, void *); + int tsocket_set_writeable_handler(struct tsocket_context *sock, + tsocket_event_handler_t handler, + void *private_data); + +Note: if the socket is readable and writeable, only the writeable + handler is called, this avoids deadlocks at the application level. + +Async helper functions +====================== + +To make the life easier for the callers, there're 'tevent_req' based +helper functions for non-blocking io-operations. For each of this functions +to work the caller must attach the tevent_context to the tsocket_context +with tsocket_set_event_context(). Please remember that attching a new +tevent_context will reset the event state of the socket and should only +be done, when there's no async request is pending on the socket! + +The detailed calling conventions for 'tevent_req' based programming +will be explained in the 'tevent' documentation. + +To receive the next availabe datagram from socket there's a wrapper +for tsocket_recvfrom(). The caller virtually sends its desire to receive +the next available datagram by calling the tsocket_recvfrom_send() function +and attaches a callback function to the returned tevent_req via tevent_req_set_callback(). +The callback function is called when a datagram is available or an error has happened. +The callback function needs to get the result by calling +tsocket_recvfrom_recv(). The return value of tsocket_recvfrom_recv() +matches the return value from tsocket_recvfrom(). A possible errno is delivered +via the perrno parameter instead of the global errno variable. The datagram +buffer and optional the source tsocket_address of the datagram are returned as talloc +childs of the mem_ctx passed to tsocket_recvfrom_recv(). +It's important that the caller garanties that there's only one async +read request on the socket at a time. + + struct tevent_req *tsocket_recvfrom_send(struct tsocket_context *sock, + TALLOC_CTX *mem_ctx); + ssize_t tsocket_recvfrom_recv(struct tevent_req *req, + int *perrno, + TALLOC_CTX *mem_ctx, + uint8_t **buf, + struct tsocket_address **src); + +To send a datagram there's a wrapper for tsocket_sendto(). +The caller calls tsocket_sendto_send() instead of tsocket_sendto() +which returns a tevent_req allocated on the given TALLOC_CTX. +The caller attaches a callback function to the returned tevent_req via +tevent_req_set_callback(). The callback function is called when a datagram was +deliviered into the socket or an error has happened. +The callback function needs to get the result by calling +tsocket_sendto_recv(). The return value of tsocket_sendto_recv() +matches the return value from tsocket_sendto(). A possible errno is delivered +via the perrno parameter instead of the global errno variable. +Normal callers should not use this function directly, they should use +tsocket_sendto_queue_send/recv() instead. + + struct tevent_req *tsocket_sendto_send(struct tsocket_context *sock, + TALLOC_CTX *mem_ctx, + const uint8_t *buf, + size_t len, + const struct tsocket_address *dst); + ssize_t tsocket_sendto_recv(struct tevent_req *req, int *perrno); + +As only one async tsocket_sendto() call should happen at a time, +there's a 'tevent_queue' is used to serialize the sendto requests. + + struct tevent_req *tsocket_sendto_queue_send(TALLOC_CTX *mem_ctx, + struct tsocket_context *sock, + struct tevent_queue *queue, + const uint8_t *buf, + size_t len, + struct tsocket_address *dst); + ssize_t tsocket_sendto_queue_recv(struct tevent_req *req, int *perrno); + +Ther's an async helper for tsocket_connect(), which should be used +to connect TSOCKET_TYPE_STREAM based sockets. +The caller virtually sends its desire to connect to the destination +tsocket_address by calling tsocket_connect_send() and gets back a tevent_req. +The caller sets a callback function via tevent_req_set_callback(). +The callback function is called if the tsocket is connected or an error has happened. +The callback function needs to get the result by calling +tsocket_connect_recv(). The return value of tsocket_connect_recv() +matches the return value from tsocket_connect()/tsocket_get_status(). +A possible errno is delivered via the perrno parameter instead of the global +errno variable. + + struct tevent_req *tsocket_connect_send(struct tsocket_context *sock, + TALLOC_CTX *mem_ctx, + const struct tsocket_address *dst); + int tsocket_connect_recv(struct tevent_req *req, int *perrno); + +To send an 'iovec' there's a wrapper for tsocket_writev(). +The caller calls tsocket_writev_send() instead of tsocket_writev() +which returns a tevent_req allocated on the given TALLOC_CTX. +The caller attaches a callback function to the returned tevent_req via +tevent_req_set_callback(). The callback function is called when the whole iovec +was deliviered into the socket or an error has happened. +The callback function needs to get the result by calling +tsocket_writev_recv(). The return value of tsocket_writev_recv() +matches the return value from tsocket_writev(). A possible errno is delivered +via the perrno parameter instead of the global errno variable. +Normal callers should not use this function directly, they should use +tsocket_writev_queue_send/recv() instead. + + struct tevent_req *tsocket_writev_send(struct tsocket_context *sock, + TALLOC_CTX *mem_ctx, + const struct iovec *vector, + size_t count); + int tsocket_writev_recv(struct tevent_req *req, int *perrno); + +As only one async tsocket_writev() call should happen at a time, +there's a 'tevent_queue' is used to serialize the writev requests. + + struct tevent_req *tsocket_writev_queue_send(TALLOC_CTX *mem_ctx, + struct tsocket_context *sock, + struct tevent_queue *queue, + const struct iovec *vector, + size_t count); + int tsocket_writev_queue_recv(struct tevent_req *req, int *perrno); + +For TSOCKET_TYPE_STREAM sockets, it's typically desired to split the stream +into PDUs. That's why the helper function for tsocket_readv() is a bit +different compared to the other helper functions. The general rule +is still to get a tevent_req, set a callback which gets called when the +operation is done. The callback function needs to get the result by +calling tsocket_readv_recv(). The 'next_iovec' callback function +makes the difference to the other helper function. +The tsocket_writev_send/recv() logic asks the caller via the +next_iovec_fn for an iovec array, which will be filled completely +with bytes from the socket, then the next_iovec_fn is called for +the next iovec array to fill, untill the next_iovec_fn returns an empty +iovec array. That next_iovec_fn should allocate the array as child of the +passed mem_ctx, while the buffers the array referr to belong to the caller. +The tsocket_writev_send/recv() engine will modify and free the given array! +The basic idea is that the caller allocates and maintains the real buffers. +The next_iovec_fn should report error by returning -1 and setting errno to +the specific error code. The engine will pass the error to the caller +via tsocket_readv_recv(). + +typedef int (*tsocket_readv_next_iovec_t)(struct tsocket_context *sock, + void *private_data, + TALLOC_CTX *mem_ctx, + struct iovec **vector, + size_t *count); +struct tevent_req *tsocket_readv_send(struct tsocket_context *sock, + TALLOC_CTX *mem_ctx, + tsocket_readv_next_iovec_t next_iovec_fn, + void *private_data); +int tsocket_readv_recv(struct tevent_req *req, int *perrno); + +Wrapper for BSD style sockets +============================= + +Support for BSD style sockets of AF_INET, AF_INET6 and AF_UNIX +are part of the main tsocket library. + +To wrap an existing fd into a tsocket_context the function +tsocket_context_bsd_wrap_existing() can be used. +The caller needs to make sure the fd is marked as non-blocking! +Normaly the tsocket_disconnect() function would close the fd, +but the caller can influence this behavior based on the close_on_disconnect +parameter. The caller should also make sure that the socket is only +accessed via the tsocket_context wrapper after the call to +tsocket_context_bsd_wrap_existing(). + + int tsocket_context_bsd_wrap_existing(TALLOC_CTX *mem_ctx, + int fd, bool close_on_disconnect, + struct tsocket_context **_sock); + +To create a tsocket_address for an inet address you need to use +the tsocket_address_inet_from_strings() function. It takes the family +as parameter which can be "ipv4", "ipv6" or "ip", where "ip" autodetects +"ipv4" or "ipv6", based on the given address string. Depending on the +operating system, "ipv6" may not be supported. Note: NULL as address +is mapped to "0.0.0.0" or "::" based on the given family. +The address parameter only accepts valid ipv4 or ipv6 address strings +and no names! The caller need to resolve names before using this function. + + int tsocket_address_inet_from_strings(TALLOC_CTX *mem_ctx, + const char *family, + const char *address, + uint16_t port, + struct tsocket_address **addr); + +To get the address of the inet tsocket_address as string the +tsocket_address_inet_addr_string() function should be used. +The caller should not try to parse the tsocket_address_string() output! + + char *tsocket_address_inet_addr_string(const struct tsocket_address *addr, + TALLOC_CTX *mem_ctx); + +To get the port number of the inet tsocket_address the +tsocket_address_inet_port() function should be used. +The caller should not try to parse the tsocket_address_string() output! + + uint16_t tsocket_address_inet_port(const struct tsocket_address *addr); + +To alter the port number of an inet tsocket_address the +tsocket_address_inet_set_port() function can be used. +This is usefull if the caller gets the address from +tsocket_address_copy(), tsocket_context_remote_address() or +tsocket_context_remote_address() instead of tsocket_address_inet_from_strings(). + + int tsocket_address_inet_set_port(struct tsocket_address *addr, + uint16_t port); + +If the caller wants to create a broadcast socket, with the SO_BROADCAST +socket option, the broadcast option needs to be set with the +tsocket_address_inet_set_broadcast() function before calling +tsocket_address_create_socket(). + + void tsocket_address_inet_set_broadcast(struct tsocket_address *addr, + bool broadcast); + +To create a tsocket_address for AF_UNIX style sockets the +tsocket_address_unix_from_path() should be used. +NULL as path is handled like "". + + int tsocket_address_unix_from_path(TALLOC_CTX *mem_ctx, + const char *path, + struct tsocket_address **addr); + +To get the unix path of an existing unix tsocket_address +the tsocket_address_unix_path() should be used. +The caller should not try to parse the tsocket_address_string() output! + + char *tsocket_address_unix_path(const struct tsocket_address *addr, + TALLOC_CTX *mem_ctx); + |