1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
|
=pod
=head1 NAME
BIO_ADDR, BIO_ADDR_new, BIO_ADDR_copy, BIO_ADDR_dup, BIO_ADDR_clear,
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);
int BIO_ADDR_copy(BIO_ADDR *dst, const BIO_ADDR *src);
BIO_ADDR *BIO_ADDR_dup(const BIO_ADDR *ap);
void BIO_ADDR_free(BIO_ADDR *ap);
void BIO_ADDR_clear(BIO_ADDR *ap);
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_copy() copies the contents of B<src> into B<dst>. Neither B<src> or
B<dst> can be NULL.
BIO_ADDR_dup() creates a new B<BIO_ADDR>, with a copy of the
address data in B<ap>.
BIO_ADDR_free() frees a B<BIO_ADDR> created with BIO_ADDR_new()
or BIO_ADDR_dup(). If the argument is NULL, nothing is done.
BIO_ADDR_clear() clears any data held within the provided B<BIO_ADDR> and sets
it back to an uninitialised state.
BIO_ADDR_rawmake() takes a protocol B<family>, a 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()).
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. It will also return AF_UNSPEC if the
BIO_ADDR has not been initialised.
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()).
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.
BIO_ADDR_copy() returns 1 on success or 0 on error.
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)>
=head1 HISTORY
BIO_ADDR_copy() and BIO_ADDR_dup() were added in OpenSSL 3.2.
=head1 COPYRIGHT
Copyright 2016-2024 The OpenSSL Project Authors. All Rights Reserved.
Licensed under the Apache License 2.0 (the "License"). You may not use
this file except in compliance with the License. You can obtain a copy
in the file LICENSE in the source distribution or at
L<https://www.openssl.org/source/license.html>.
=cut
|
