generic-library/openssl
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Refactoring BIO: add wrappers around sockaddr et al

Browse Source 
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>
This commit is contained in:
Richard Levitte
2016-02-02 15:54:57 +01:00
parent ba2de73b18
commit 28a0841bf5
9 changed files with 1165 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

109
doc/crypto/BIO_ADDR.pod Normal file
View File

@@ -0,0 +1,109 @@
=pod
=head1 NAME
BIO_ADDR, BIO_ADDR_new, BIO_ADDR_free, BIO_ADDR_rawmake,
BIO_ADDR_family, BIO_ADDR_rawaddress, BIO_ADDR_rawport,
BIO_ADDR_hostname_string, BIO_ADDR_service_string,
BIO_ADDR_path_string - BIO_ADDR routines
=head1 SYNOPSIS
#include <sys/types.h>
#include <openssl/bio.h>
typedef union bio_addr_st BIO_ADDR;
BIO_ADDR *BIO_ADDR_new(void);
void BIO_ADDR_free(BIO_ADDR *);
int BIO_ADDR_rawmake(BIO_ADDR *ap, int family,
const void *where, size_t wherelen, unsigned short port);
int BIO_ADDR_family(const BIO_ADDR *ap);
int BIO_ADDR_rawaddress(const BIO_ADDR *ap, void *p, size_t *l);
unsigned short BIO_ADDR_rawport(const BIO_ADDR *ap);
char *BIO_ADDR_hostname_string(const BIO_ADDR *ap, int numeric);
char *BIO_ADDR_service_string(const BIO_ADDR *ap, int numeric);
char *BIO_ADDR_path_string(const BIO_ADDR *ap);
=head1 DESCRIPTION
The B<BIO_ADDR> type is a wrapper around all types of socket
addresses that OpenSSL deals with, currently transparently
supporting AF_INET, AF_INET6 and AF_UNIX according to what's
available on the platform at hand.
BIO_ADDR_new() creates a new unfilled B<BIO_ADDR>, to be used
with routines that will fill it with information, such as
BIO_accept_ex().
BIO_ADDR_free() frees a B<BIO_ADDR> created with BIO_ADDR_new().
BIO_ADDR_rawmake() takes a protocol B<family>, an byte array of
size B<wherelen> with an address in network byte order pointed at
by B<where> and a port number in network byte order in B<port> (except
for the B<AF_UNIX> protocol family, where B<port> is meaningless and
therefore ignored) and populates the given B<BIO_ADDR> with them.
In case this creates a B<AF_UNIX> B<BIO_ADDR>, B<wherelen> is expected
to be the length of the path string (not including the terminating
NUL, such as the result of a call to strlen()).
I<Read on about the addresses in L</RAW ADDRESSES> below>.
BIO_ADDR_family() returns the protocol family of the given
B<BIO_ADDR>. The possible non-error results are one of the
constants AF_INET, AF_INET6 and AF_UNIX.
BIO_ADDR_rawaddress() will write the raw address of the given
B<BIO_ADDR> in the area pointed at by B<p> if B<p> is non-NULL,
and will set B<*l> to be the amount of bytes the raw address
takes up if B<l> is non-NULL.
A technique to only find out the size of the address is a call
with B<p> set to B<NULL>. The raw address will be in network byte
order, most significant byte first.
In case this is a B<AF_UNIX> B<BIO_ADDR>, B<l> gets the length of the
path string (not including the terminating NUL, such as the result of
a call to strlen()).
I<Read on about the addresses in L</RAW ADDRESSES> below>.
BIO_ADDR_rawport() returns the raw port of the given B<BIO_ADDR>.
The raw port will be in network byte order.
BIO_ADDR_hostname_string() returns a character string with the
hostname of the given B<BIO_ADDR>. If B<numeric> is 1, the string
will contain the numerical form of the address. This only works for
B<BIO_ADDR> of the protocol families AF_INET and AF_INET6. The
returned string has been allocated on the heap and must be freed
with OPENSSL_free().
BIO_ADDR_service_string() returns a character string with the
service name of the port of the given B<BIO_ADDR>. If B<numeric>
is 1, the string will contain the port number. This only works
for B<BIO_ADDR> of the protocol families AF_INET and AF_INET6. The
returned string has been allocated on the heap and must be freed
with OPENSSL_free().
BIO_ADDR_path_string() returns a character string with the path
of the given B<BIO_ADDR>. This only works for B<BIO_ADDR> of the
protocol family AF_UNIX. The returned string has been allocated
on the heap and must be freed with OPENSSL_free().
=head1 RAW ADDRESSES
Both BIO_ADDR_rawmake() and BIO_ADDR_rawaddress() take a pointer to a
network byte order address of a specific site. Internally, those are
treated as a pointer to B<struct in_addr> (for B<AF_INET>), B<struct
in6_addr> (for B<AF_INET6>) or B<char *> (for B<AF_UNIX>), all
depending on the protocol family the address is for.
=head1 RETURN VALUES
The string producing functions BIO_ADDR_hostname_string(),
BIO_ADDR_service_string() and BIO_ADDR_path_string() will
return B<NULL> on error and leave an error indication on the
OpenSSL error stack.
All other functions described here return 0 or B<NULL> when the
information they should return isn't available.
=head1 SEE ALSO
L<BIO_connect(3)>, L<BIO_s_connect(3)>

82
doc/crypto/BIO_ADDRINFO.pod Normal file
View File

@@ -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)>

62
doc/crypto/BIO_parse_hostserv.pod Normal file
View File

@@ -0,0 +1,62 @@
=pod
=head1 NAME
BIO_parse_hostserv - utility routines to parse a standard host and service
string
=head1 SYNOPSIS
#include <openssl/bio.h>
enum BIO_hostserv_priorities {
BIO_PARSE_PRIO_HOST, BIO_PARSE_PRIO_SERV
};
int BIO_parse_hostserv(const char *hostserv, char **host, char **service,
enum BIO_hostserv_priorities hostserv_prio);
=head1 DESCRIPTION
BIO_parse_hostserv() will parse the information given in B<hostserv>,
create strings with the host name and service name and give those
back via B<host> and B<service>. Those will need to be freed after
they are used. B<hostserv_prio> helps determine if B<hostserv> shall
be interpreted primarly as a host name or a service name in ambiguous
cases.
The syntax the BIO_parse_hostserv() recognises is:
host + ':' + service
host + ':' + '*'
host + ':'
':' + service
'*' + ':' + service
host
service
The host part can be a name or an IP address. If it's a IPv6
address, it MUST be enclosed in brackets, such as '[::1]'.
The service part can be a service name or its port number.
The returned values will depend on the given B<hostserv> string
and B<hostserv_prio>, as follows:
host + ':' + service => *host = "host", *service = "service"
host + ':' + '*' => *host = "host", *service = NULL
host + ':' => *host = "host", *service = NULL
':' + service => *host = NULL, *service = "service"
'*' + ':' + service => *host = NULL, *service = "service"
in case no ':' is present in the string, the result depends on
hostserv_prio, as follows:
when hostserv_prio == BIO_PARSE_PRIO_HOST
host => *host = "host", *service untouched
when hostserv_prio == BIO_PARSE_PRIO_SERV
service => *host untouched, *service = "service"
=head1 SEE ALSO
L<BIO_ADDRINFO(3)>