path: root/crypto/heimdal/lib/krb5/krb5_address.3

.\" Copyright (c) 2003, 2005 - 2006 Kungliga Tekniska Högskolan
.\" (Royal Institute of Technology, Stockholm, Sweden).
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\"
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\"
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" 3. Neither the name of the Institute nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $Id: krb5_address.3 17461 2006-05-05 13:13:18Z lha $
.\"
.Dd May  1, 2006
.Dt KRB5_ADDRESS 3
.Os HEIMDAL
.Sh NAME
.Nm krb5_address ,
.Nm krb5_addresses ,
.Nm krb5_sockaddr2address ,
.Nm krb5_sockaddr2port ,
.Nm krb5_addr2sockaddr ,
.Nm krb5_max_sockaddr_size ,
.Nm krb5_sockaddr_uninteresting ,
.Nm krb5_h_addr2sockaddr ,
.Nm krb5_h_addr2addr ,
.Nm krb5_anyaddr ,
.Nm krb5_print_address ,
.Nm krb5_parse_address ,
.Nm krb5_address_order ,
.Nm krb5_address_compare ,
.Nm krb5_address_search ,
.Nm krb5_free_address ,
.Nm krb5_free_addresses ,
.Nm krb5_copy_address ,
.Nm krb5_copy_addresses ,
.Nm krb5_append_addresses ,
.Nm krb5_make_addrport
.Nd mange addresses in Kerberos
.Sh LIBRARY
Kerberos 5 Library (libkrb5, -lkrb5)
.Sh SYNOPSIS
.In krb5.h
.Pp
.Ft krb5_error_code
.Fo krb5_sockaddr2address
.Fa "krb5_context context"
.Fa "const struct sockaddr *sa"
.Fa "krb5_address *addr"
.Fc
.Ft krb5_error_code
.Fo krb5_sockaddr2port
.Fa "krb5_context context"
.Fa "const struct sockaddr *sa"
.Fa "int16_t *port"
.Fc
.Ft krb5_error_code
.Fo krb5_addr2sockaddr
.Fa "krb5_context context"
.Fa "const krb5_address *addr"
.Fa "struct sockaddr *sa"
.Fa "krb5_socklen_t *sa_size"
.Fa "int port"
.Fc
.Ft size_t
.Fo krb5_max_sockaddr_size
.Fa "void"
.Fc
.Ft "krb5_boolean"
.Fo krb5_sockaddr_uninteresting
.Fa "const struct sockaddr *sa"
.Fc
.Ft krb5_error_code
.Fo krb5_h_addr2sockaddr
.Fa "krb5_context context"
.Fa "int af"
.Fa "const char *addr"
.Fa "struct sockaddr *sa"
.Fa "krb5_socklen_t *sa_size"
.Fa "int port"
.Fc
.Ft krb5_error_code
.Fo krb5_h_addr2addr
.Fa "krb5_context context"
.Fa "int af"
.Fa "const char *haddr"
.Fa "krb5_address *addr"
.Fc
.Ft krb5_error_code
.Fo krb5_anyaddr
.Fa "krb5_context context"
.Fa "int af"
.Fa "struct sockaddr *sa"
.Fa "krb5_socklen_t *sa_size"
.Fa "int port"
.Fc
.Ft krb5_error_code
.Fo krb5_print_address
.Fa "const krb5_address *addr"
.Fa "char *str"
.Fa "size_t len"
.Fa "size_t *ret_len"
.Fc
.Ft krb5_error_code
.Fo krb5_parse_address
.Fa "krb5_context context"
.Fa "const char *string"
.Fa "krb5_addresses *addresses"
.Fc
.Ft int
.Fo "krb5_address_order"
.Fa "krb5_context context"
.Fa "const krb5_address *addr1"
.Fa "const krb5_address *addr2"
.Fc
.Ft "krb5_boolean"
.Fo krb5_address_compare
.Fa "krb5_context context"
.Fa "const krb5_address *addr1"
.Fa "const krb5_address *addr2"
.Fc
.Ft "krb5_boolean"
.Fo krb5_address_search
.Fa "krb5_context context"
.Fa "const krb5_address *addr"
.Fa "const krb5_addresses *addrlist"
.Fc
.Ft krb5_error_code
.Fo krb5_free_address
.Fa "krb5_context context"
.Fa "krb5_address *address"
.Fc
.Ft krb5_error_code
.Fo krb5_free_addresses
.Fa "krb5_context context"
.Fa "krb5_addresses *addresses"
.Fc
.Ft krb5_error_code
.Fo krb5_copy_address
.Fa "krb5_context context"
.Fa "const krb5_address *inaddr"
.Fa "krb5_address *outaddr"
.Fc
.Ft krb5_error_code
.Fo krb5_copy_addresses
.Fa "krb5_context context"
.Fa "const krb5_addresses *inaddr"
.Fa "krb5_addresses *outaddr"
.Fc
.Ft krb5_error_code
.Fo krb5_append_addresses
.Fa "krb5_context context"
.Fa "krb5_addresses *dest"
.Fa "const krb5_addresses *source"
.Fc
.Ft krb5_error_code
.Fo krb5_make_addrport
.Fa "krb5_context context"
.Fa "krb5_address **res"
.Fa "const krb5_address *addr"
.Fa "int16_t port"
.Fc
.Sh DESCRIPTION
The
.Li krb5_address
structure holds a address that can be used in Kerberos API
calls. There are help functions to set and extract address information
of the address.
.Pp
The
.Li krb5_addresses
structure holds a set of krb5_address:es.
.Pp
.Fn krb5_sockaddr2address
stores a address a
.Li "struct sockaddr"
.Fa sa
in the krb5_address
.Fa addr .
.Pp
.Fn krb5_sockaddr2port
extracts a
.Fa port
(if possible) from a
.Li "struct sockaddr"
.Fa sa .
.Pp
.Fn krb5_addr2sockaddr
sets the
struct sockaddr
.Fa sockaddr
from
.Fa addr
and
.Fa port .
The argument
.Fa sa_size
should initially contain the size of the
.Fa sa ,
and after the call, it will contain the actual length of the address.
.Pp
.Fn krb5_max_sockaddr_size
returns the max size of the
.Li struct sockaddr
that the Kerberos library will return.
.Pp
.Fn krb5_sockaddr_uninteresting
returns
.Dv TRUE
for all
.Fa sa
that the kerberos library thinks are uninteresting.
One example are link local addresses.
.Pp
.Fn krb5_h_addr2sockaddr
initializes a
.Li "struct sockaddr"
.Fa sa
from
.Fa af
and the
.Li "struct hostent"
(see
.Xr gethostbyname 3 )
.Fa h_addr_list
component.
The argument
.Fa sa_size
should initially contain the size of the
.Fa sa ,
and after the call, it will contain the actual length of the address.
.Pp
.Fn krb5_h_addr2addr
works like
.Fn krb5_h_addr2sockaddr
with the exception that it operates on a
.Li krb5_address
instead of a
.Li struct sockaddr .
.Pp
.Fn krb5_anyaddr
fills in a
.Li "struct sockaddr"
.Fa sa
that can be used to
.Xr bind 2
to.
The argument
.Fa sa_size
should initially contain the size of the
.Fa sa ,
and after the call, it will contain the actual length of the address.
.Pp
.Fn krb5_print_address
prints the address in
.Fa addr
to the string
.Fa string
that have the length
.Fa len .
If
.Fa ret_len
is not
.Dv NULL ,
it will be filled with the length of the string if size were unlimited (not
including the final
.Ql \e0 ) .
.Pp
.Fn krb5_parse_address
Returns the resolved hostname in
.Fa string
to the
.Li krb5_addresses
.Fa addresses .
.Pp
.Fn krb5_address_order
compares the addresses
.Fa addr1
and
.Fa addr2
so that it can be used for sorting addresses. If the addresses are the
same address
.Fa krb5_address_order
will return 0.
.Pp
.Fn krb5_address_compare
compares the addresses
.Fa addr1
and
.Fa addr2 .
Returns
.Dv TRUE
if the two addresses are the same.
.Pp
.Fn krb5_address_search
checks if the address
.Fa addr
is a member of the address set list
.Fa addrlist .
.Pp
.Fn krb5_free_address
frees the data stored in the
.Fa address
that is alloced with any of the krb5_address functions.
.Pp
.Fn krb5_free_addresses
frees the data stored in the
.Fa addresses
that is alloced with any of the krb5_address functions.
.Pp
.Fn krb5_copy_address
copies the content of address
.Fa inaddr
to
.Fa outaddr .
.Pp
.Fn krb5_copy_addresses
copies the content of the address list
.Fa inaddr
to
.Fa outaddr .
.Pp
.Fn krb5_append_addresses
adds the set of addresses in
.Fa source
to
.Fa dest .
While copying the addresses, duplicates are also sorted out.
.Pp
.Fn krb5_make_addrport
allocates and creates an
krb5_address in
.Fa res
of type KRB5_ADDRESS_ADDRPORT from
.Fa ( addr , port ) .
.Sh SEE ALSO
.Xr krb5 3 ,
.Xr krb5.conf 5 ,
.Xr kerberos 8