| 1 | =pod
|
|---|
| 2 |
|
|---|
| 3 | =head1 NAME
|
|---|
| 4 |
|
|---|
| 5 | BIO_lookup_type,
|
|---|
| 6 | BIO_ADDRINFO, BIO_ADDRINFO_next, BIO_ADDRINFO_free,
|
|---|
| 7 | BIO_ADDRINFO_family, BIO_ADDRINFO_socktype, BIO_ADDRINFO_protocol,
|
|---|
| 8 | BIO_ADDRINFO_address,
|
|---|
| 9 | BIO_lookup_ex,
|
|---|
| 10 | BIO_lookup
|
|---|
| 11 | - BIO_ADDRINFO type and routines
|
|---|
| 12 |
|
|---|
| 13 | =head1 SYNOPSIS
|
|---|
| 14 |
|
|---|
| 15 | #include <sys/types.h>
|
|---|
| 16 | #include <openssl/bio.h>
|
|---|
| 17 |
|
|---|
| 18 | typedef union bio_addrinfo_st BIO_ADDRINFO;
|
|---|
| 19 |
|
|---|
| 20 | enum BIO_lookup_type {
|
|---|
| 21 | BIO_LOOKUP_CLIENT, BIO_LOOKUP_SERVER
|
|---|
| 22 | };
|
|---|
| 23 |
|
|---|
| 24 | int BIO_lookup_ex(const char *host, const char *service, int lookup_type,
|
|---|
| 25 | int family, int socktype, int protocol, BIO_ADDRINFO **res);
|
|---|
| 26 | int BIO_lookup(const char *node, const char *service,
|
|---|
| 27 | enum BIO_lookup_type lookup_type,
|
|---|
| 28 | int family, int socktype, BIO_ADDRINFO **res);
|
|---|
| 29 |
|
|---|
| 30 | const BIO_ADDRINFO *BIO_ADDRINFO_next(const BIO_ADDRINFO *bai);
|
|---|
| 31 | int BIO_ADDRINFO_family(const BIO_ADDRINFO *bai);
|
|---|
| 32 | int BIO_ADDRINFO_socktype(const BIO_ADDRINFO *bai);
|
|---|
| 33 | int BIO_ADDRINFO_protocol(const BIO_ADDRINFO *bai);
|
|---|
| 34 | const BIO_ADDR *BIO_ADDRINFO_address(const BIO_ADDRINFO *bai);
|
|---|
| 35 | void BIO_ADDRINFO_free(BIO_ADDRINFO *bai);
|
|---|
| 36 |
|
|---|
| 37 | =head1 DESCRIPTION
|
|---|
| 38 |
|
|---|
| 39 | The B<BIO_ADDRINFO> type is a wrapper for address information
|
|---|
| 40 | types provided on your platform.
|
|---|
| 41 |
|
|---|
| 42 | B<BIO_ADDRINFO> normally forms a chain of several that can be
|
|---|
| 43 | picked at one by one.
|
|---|
| 44 |
|
|---|
| 45 | BIO_lookup_ex() looks up a specified B<host> and B<service>, and
|
|---|
| 46 | uses B<lookup_type> to determine what the default address should
|
|---|
| 47 | be if B<host> is B<NULL>. B<family>, B<socktype> and B<protocol> are used to
|
|---|
| 48 | determine what protocol family, socket type and protocol should be used for
|
|---|
| 49 | the lookup. B<family> can be any of AF_INET, AF_INET6, AF_UNIX and
|
|---|
| 50 | AF_UNSPEC. B<socktype> can be SOCK_STREAM, SOCK_DGRAM or 0. Specifying 0
|
|---|
| 51 | indicates that any type can be used. B<protocol> specifies a protocol such as
|
|---|
| 52 | IPPROTO_TCP, IPPROTO_UDP or IPPORTO_SCTP. If set to 0 than any protocol can be
|
|---|
| 53 | used. B<res> points at a pointer to hold the start of a B<BIO_ADDRINFO>
|
|---|
| 54 | chain.
|
|---|
| 55 |
|
|---|
| 56 | For the family B<AF_UNIX>, BIO_lookup_ex() will ignore the B<service>
|
|---|
| 57 | parameter and expects the B<node> parameter to hold the path to the
|
|---|
| 58 | socket file.
|
|---|
| 59 |
|
|---|
| 60 | BIO_lookup() does the same as BIO_lookup_ex() but does not provide the ability
|
|---|
| 61 | to select based on the protocol (any protocol may be returned).
|
|---|
| 62 |
|
|---|
| 63 | BIO_ADDRINFO_family() returns the family of the given
|
|---|
| 64 | B<BIO_ADDRINFO>. The result will be one of the constants
|
|---|
| 65 | AF_INET, AF_INET6 and AF_UNIX.
|
|---|
| 66 |
|
|---|
| 67 | BIO_ADDRINFO_socktype() returns the socket type of the given
|
|---|
| 68 | B<BIO_ADDRINFO>. The result will be one of the constants
|
|---|
| 69 | SOCK_STREAM and SOCK_DGRAM.
|
|---|
| 70 |
|
|---|
| 71 | BIO_ADDRINFO_protocol() returns the protocol id of the given
|
|---|
| 72 | B<BIO_ADDRINFO>. The result will be one of the constants
|
|---|
| 73 | IPPROTO_TCP and IPPROTO_UDP.
|
|---|
| 74 |
|
|---|
| 75 | BIO_ADDRINFO_address() returns the underlying B<BIO_ADDR>
|
|---|
| 76 | of the given B<BIO_ADDRINFO>.
|
|---|
| 77 |
|
|---|
| 78 | BIO_ADDRINFO_next() returns the next B<BIO_ADDRINFO> in the chain
|
|---|
| 79 | from the given one.
|
|---|
| 80 |
|
|---|
| 81 | BIO_ADDRINFO_free() frees the chain of B<BIO_ADDRINFO> starting
|
|---|
| 82 | with the given one.
|
|---|
| 83 |
|
|---|
| 84 | =head1 RETURN VALUES
|
|---|
| 85 |
|
|---|
| 86 | BIO_lookup_ex() and BIO_lookup() return 1 on success and 0 when an error
|
|---|
| 87 | occurred, and will leave an error indication on the OpenSSL error stack in that
|
|---|
| 88 | case.
|
|---|
| 89 |
|
|---|
| 90 | All other functions described here return 0 or B<NULL> when the
|
|---|
| 91 | information they should return isn't available.
|
|---|
| 92 |
|
|---|
| 93 | =head1 NOTES
|
|---|
| 94 |
|
|---|
| 95 | The BIO_lookup_ex() implementation uses the platform provided getaddrinfo()
|
|---|
| 96 | function. On Linux it is known that specifying 0 for the protocol will not
|
|---|
| 97 | return any SCTP based addresses when calling getaddrinfo(). Therefore, if an SCTP
|
|---|
| 98 | address is required then the B<protocol> parameter to BIO_lookup_ex() should be
|
|---|
| 99 | explicitly set to IPPROTO_SCTP. The same may be true on other platforms.
|
|---|
| 100 |
|
|---|
| 101 | =head1 HISTORY
|
|---|
| 102 |
|
|---|
| 103 | The BIO_lookup_ex() function was added in OpenSSL 1.1.1.
|
|---|
| 104 |
|
|---|
| 105 | =head1 COPYRIGHT
|
|---|
| 106 |
|
|---|
| 107 | Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 108 |
|
|---|
| 109 | Licensed under the OpenSSL license (the "License"). You may not use
|
|---|
| 110 | this file except in compliance with the License. You can obtain a copy
|
|---|
| 111 | in the file LICENSE in the source distribution or at
|
|---|
| 112 | L<https://www.openssl.org/source/license.html>.
|
|---|
| 113 |
|
|---|
| 114 | =cut
|
|---|
