Refactoring BIO: add wrappers around sockaddr et al

Because different platforms have different levels of support for IPv6,
different kinds of sockaddr variants, and some have getaddrinfo et al
while others don't, we could end up with a mess if ifdefs, duplicate
code and other maintainance nightmares.

Instead, we're introducing wrappers around the common form for socket
communication:
BIO_ADDR, closely related to struct sockaddr and some of its variants.
BIO_ADDRINFO, closely related to struct addrinfo.

With that comes support routines, both convenient creators and
accessors, plus a few utility functions:

BIO_parse_hostserv, takes a string of the form host:service and
splits it into host and service.  It checks for * in both parts, and
converts any [ipv6-address] syntax to ust the IPv6 address.

BIO_lookup, looks up information on a host.

All routines handle IPv4 (AF_INET) and IPv6 (AF_INET6) addresses, and
there is support for local sockets (AF_UNIX) as well.

Reviewed-by: Kurt Roeckx <kurt@openssl.org>

1 files changed, 82 insertions, 0 deletions

diff --git a/doc/crypto/BIO_ADDRINFO.pod b/doc/crypto/BIO_ADDRINFO.pod
new file mode 100644
index 0000000000..85652add9b
--- /dev/null
+++ b/doc/crypto/BIO_ADDRINFO.pod
@@ -0,0 +1,82 @@
+=pod
+
+=head1 NAME
+
+BIO_ADDRINFO, BIO_ADDRINFO_lookup, BIO_ADDRINFO_next, BIO_ADDRINFO_free,
+BIO_ADDRINFO_family, BIO_ADDRINFO_socktype, BIO_ADDRINFO_protocol,
+BIO_ADDRINFO_sockaddr, BIO_ADDRINFO_sockaddr_size, BIO_ADDRINFO_address
+- BIO_ADDRINFO type and routines
+
+=head1 SYNOPSIS
+
+ #include <sys/types.h>
+ #include <openssl/bio.h>
+
+ typedef union bio_addrinfo_st BIO_ADDRINFO;
+
+ enum BIO_lookup_type {
+     BIO_LOOKUP_CLIENT, BIO_LOOKUP_SERVER
+ };
+ int BIO_lookup(const char *node, const char *service,
+                enum BIO_lookup_type lookup_type,
+                int family, int socktype, BIO_ADDRINFO **res);
+
+ const BIO_ADDRINFO *BIO_ADDRINFO_next(const BIO_ADDRINFO *bai);
+ int BIO_ADDRINFO_family(const BIO_ADDRINFO *bai);
+ int BIO_ADDRINFO_socktype(const BIO_ADDRINFO *bai);
+ int BIO_ADDRINFO_protocol(const BIO_ADDRINFO *bai);
+ const BIO_ADDR *BIO_ADDRINFO_address(const BIO_ADDRINFO *bai);
+ void BIO_ADDRINFO_free(BIO_ADDRINFO *bai);
+
+=head1 DESCRIPTION
+
+The B<BIO_ADDRINFO> type is a wrapper for address information
+types provided on your platform.
+
+B<BIO_ADDRINFO> normally forms a chain of several that can be
+picked at one by one.
+
+BIO_lookup() looks up a specified B<host> and B<service>, and
+uses B<lookup_type> to determine what the default address should
+be if B<host> is B<NULL>.  B<family>, B<socktype> are used to
+determine what protocol family and protocol should be used for
+the lookup.  B<family> can be any of AF_INET, AF_INET6, AF_UNIX and
+AF_UNSPEC, and B<socktype> can be SOCK_STREAM or SOCK_DGRAM.
+B<res> points at a pointer to hold the start of a B<BIO_ADDRINFO>
+chain.
+For the family B<AF_UNIX>, BIO_lookup() will ignore the B<service>
+parameter and expects the B<node> parameter to hold the path to the
+socket file.
+
+BIO_ADDRINFO_family() returns the family of the given
+B<BIO_ADDRINFO>.  The result will be one of the constants
+AF_INET, AF_INET6 and AF_UNIX.
+
+BIO_ADDRINFO_socktype() returns the socket type of the given
+B<BIO_ADDRINFO>.  The result will be one of the constants
+SOCK_STREAM and SOCK_DGRAM.
+
+BIO_ADDRINFO_protocol() returns the protocol id of the given
+B<BIO_ADDRINFO>.  The result will be one of the constants
+IPPROTO_TCP and IPPROTO_UDP.
+
+BIO_ADDRINFO_address() returns the underlying B<BIO_ADDR>
+of the given B<BIO_ADDRINFO>.
+
+BIO_ADDRINFO_next() returns the next B<BIO_ADDRINFO> in the chain
+from the given one.
+
+BIO_ADDRINFO_free() frees the chain of B<BIO_ADDRINFO> starting
+with the given one.
+
+=head1 RETURN VALUES
+
+BIO_lookup() returns 1 on success and 0 when an error occured, and
+will leave an error indicaton on the OpenSSL error stack in that case.
+
+All other functions described here return 0 or B<NULL> when the
+information they should return isn't available.
+
+=head1 SEE ALSO
+
+L<BIO_lookup(3)>