888 lines
27 KiB
Groff
888 lines
27 KiB
Groff
.Dd July, 1997
|
|
.Dt "libalias" 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm "libalias"
|
|
Packet Aliasing Library. A collection of
|
|
functions for aliasing and de-aliasing
|
|
of IP packets, intended for masquerading and
|
|
network address translation (NAT).
|
|
|
|
.Sh SYNOPSIS
|
|
.Fd #include <sys/types.h>
|
|
.Fd #include <netinet/in.h>
|
|
.Fd #include <alias.h>
|
|
|
|
Function prototypes are given in the main body
|
|
of the text.
|
|
|
|
.Sh CONTENTS
|
|
.Bd -literal -offset left
|
|
1. Introduction
|
|
2. Initialization and Control
|
|
2.1 PacketAliasInit()
|
|
2.2 PacketAliasUninit()
|
|
2.3 PacketAliasSetAddress()
|
|
2.4 PacketAliasSetMode()
|
|
2.5 PacketAliasSetFWBase()
|
|
3. Packet Handling
|
|
3.1 PacketAliasIn()
|
|
3.2 PacketAliasOut()
|
|
4. Port and Address Redirection
|
|
4.1 PacketAliasRedirectPort()
|
|
4.2 PacketAliasRedirectAddr()
|
|
4.3 PacketAliasRedirectDelete()
|
|
4.4 PacketAliasProxyRule()
|
|
4.5 PacketAliasPptp()
|
|
5. Fragment Handling
|
|
5.1 PacketAliasSaveFragment()
|
|
5.2 PacketAliasGetFragment()
|
|
5.3 PacketAliasFragmentIn()
|
|
6. Miscellaneous Functions
|
|
6.1 PacketAliasSetTarget()
|
|
6.2 PacketAliasCheckNewLink()
|
|
6.3 PacketAliasInternetChecksum()
|
|
7. Authors
|
|
8. Acknowledgments
|
|
|
|
Appendix A: Conceptual Background
|
|
A.1 Aliasing Links
|
|
A.2 Static and Dynamic Links
|
|
A.3 Partially Specified Links
|
|
A.4 Dynamic Link Creation
|
|
.Ed
|
|
|
|
.Sh 1. Introduction
|
|
This library is a moderately portable
|
|
set of functions designed to assist
|
|
in the process of IP masquerading and
|
|
network address translation. Outgoing
|
|
packets from a local network with
|
|
unregistered IP addresses can be aliased
|
|
to appear as if they came from an
|
|
accessible IP address. Incoming packets
|
|
are then de-aliased so that they are sent
|
|
to the correct machine on the local network.
|
|
|
|
A certain amount of flexibility is built
|
|
into the packet aliasing engine. In
|
|
the simplest mode of operation, a
|
|
many-to-one address mapping takes place
|
|
between local network and the packet
|
|
aliasing host. This is known as IP
|
|
masquerading. In addition, one-to-one
|
|
mappings between local and public addresses
|
|
can also be implemented, which is known as
|
|
static NAT. In between these extremes,
|
|
different groups of private addresses
|
|
can be linked to different public addresses,
|
|
comprising several distinct many-to-one
|
|
mappings. Also, a given public address
|
|
and port can be statically redirected to
|
|
a private address/port.
|
|
|
|
The packet aliasing engine was designed
|
|
to operate in user space outside of the
|
|
kernel, without any access to private
|
|
kernel data structure, but the source code
|
|
can also be ported to a kernel environment.
|
|
|
|
.Sh 2. Initialization and Control
|
|
Two specific functions, PacketAliasInit()
|
|
and PacketAliasSetAddress(), must always be
|
|
called before any packet handling may be
|
|
performed. In addition, the operating mode
|
|
of the packet aliasing engine can be customized
|
|
by calling PacketAliasSetMode().
|
|
.Ss 2.1 PacketAliasInit()
|
|
|
|
.Ft void
|
|
.Fn PacketAliasInit "void"
|
|
|
|
This function has no argument or return
|
|
value and is used to initialize internal
|
|
data structures. The following mode bits
|
|
are always set after calling
|
|
PacketAliasInit(). See section 2.3 for
|
|
the meaning of these mode bits.
|
|
.Bd -literal -offset indent
|
|
PKT_ALIAS_USE_SAME_PORTS
|
|
PKT_ALIAS_USE_SOCKETS
|
|
PKT_ALIAS_RESET_ON_ADDR_CHANGE
|
|
|
|
.Ed
|
|
This function will always return the packet
|
|
aliasing engine to the same initial state.
|
|
PacketAliasSetAddress() must be called afterwards,
|
|
and any desired changes from the default mode
|
|
bits listed above require a call to
|
|
PacketAliasSetMode().
|
|
|
|
It is mandatory that this function be called
|
|
at the beginning of a program prior to any
|
|
packet handling.
|
|
.Ss 2.2 PacketAliasUninit()
|
|
|
|
.Ft void
|
|
.Fn PacketAliasUninit "void"
|
|
|
|
This function has no argument or return
|
|
value and is used to clear any resources
|
|
attached to internal data structures.
|
|
|
|
This functions should be called when a
|
|
program stop using the aliasing engine;
|
|
it do, among other things, clear out any
|
|
firewall holes. To provide backwards
|
|
compatibility and extra security, it is
|
|
added to the atexit() chain by
|
|
PacketAliasInit(). Calling it multiple
|
|
times is harmless.
|
|
.Ss 2.3 PacketAliasSetAddress()
|
|
|
|
.Ft void
|
|
.Fn PacketAliasSetAddress "struct in_addr addr"
|
|
|
|
This function sets the source address to which
|
|
outgoing packets from the local area network
|
|
are aliased. All outgoing packets are remapped
|
|
to this address unless overridden by a static
|
|
address mapping established by
|
|
PacketAliasRedirectAddr().
|
|
|
|
If the PKT_ALIAS_RESET_ON_ADDR_CHANGE mode bit
|
|
is set (the default mode of operation), then
|
|
the internal aliasing link tables will be reset
|
|
any time the aliasing address changes, as if
|
|
PacketAliasReset() were called. This is useful
|
|
for interfaces such as ppp where the IP
|
|
address may or may not change on successive
|
|
dial-up attempts.
|
|
|
|
If the PKT_ALIAS_RESET_ON_ADDR_CHANGE mode bit
|
|
is set to zero, this function can also be used to
|
|
dynamically change the aliasing address on a
|
|
packet to packet basis (it is a low overhead
|
|
call).
|
|
|
|
It is mandatory that this function be called
|
|
prior to any packet handling.
|
|
.Ss 2.4 PacketAliasSetMode()
|
|
|
|
.Ft unsigned int
|
|
.Fn PacketAliasSetMode "unsigned int mode" "unsigned int mask"
|
|
|
|
This function sets or clears mode bits
|
|
according to the value of
|
|
.Em mode .
|
|
Only bits marked in
|
|
.Em mask
|
|
are affected. The following mode bits are
|
|
defined in alias.h:
|
|
.Bl -hang -offset left
|
|
.It PKT_ALIAS_LOG.
|
|
Enables logging /var/log/alias.log. The log file
|
|
shows total numbers of links (icmp, tcp, udp) each
|
|
time an aliasing link is created or deleted. Mainly
|
|
useful for debugging when the log file is viewed
|
|
continuously with "tail -f".
|
|
.It PKT_ALIAS_DENY_INCOMING.
|
|
If this mode bit is set, all incoming packets
|
|
associated with new TCP connections or new
|
|
UDP transactions will be marked for being
|
|
ignored (PacketAliasIn() return code
|
|
PKT_ALIAS_IGNORED) by the calling program.
|
|
Response packets to connections or transactions
|
|
initiated from the packet aliasing host or
|
|
local network will be unaffected. This mode
|
|
bit is useful for implementing a one-way firewall.
|
|
.It PKT_ALIAS_SAME_PORTS.
|
|
If this mode bit is set, the packet aliasing
|
|
engine will attempt to leave the alias port
|
|
numbers unchanged from the actual local port
|
|
number. This can be done as long as the
|
|
quintuple (proto, alias addr, alias port,
|
|
remote addr, remote port) is unique. If a
|
|
conflict exists, an new aliasing port number is
|
|
chosen even if this mode bit is set.
|
|
.It PKT_ALIAS_USE_SOCKETS.
|
|
This bit should be set when the the packet
|
|
aliasing host originates network traffic as
|
|
well as forwards it. When the packet aliasing
|
|
host is waiting for a connection from an
|
|
unknown host address or unknown port number
|
|
(e.g. an FTP data connection), this mode bit
|
|
specifies that a socket be allocated as a place
|
|
holder to prevent port conflicts. Once a
|
|
connection is established, usually within a
|
|
minute or so, the socket is closed.
|
|
.It PKT_ALIAS_UNREGISTERED_ONLY.
|
|
If this mode bit is set, traffic on the
|
|
local network which does not originate from
|
|
unregistered address spaces will be ignored.
|
|
Standard Class A, B and C unregistered addresses
|
|
are:
|
|
.Bd -literal -offset indent
|
|
10.0.0.0 -> 10.255.255.255 (Class A subnet)
|
|
172.16.0.0 -> 172.31.255.255 (Class B subnets)
|
|
192.168.0.0 -> 192.168.255.255 (Class C subnets)
|
|
|
|
.Ed
|
|
This option is useful in the case that
|
|
packet aliasing host has both registered and
|
|
unregistered subnets on different interfaces.
|
|
The registered subnet is fully accessible to
|
|
the outside world, so traffic from it doesn't
|
|
need to be passed through the packet aliasing
|
|
engine.
|
|
.It PKT_ALIAS_RESET_ON_ADDR_CHANGE.
|
|
When this mode bit is set and
|
|
PacketAliasSetAddress() is called to change
|
|
the aliasing address, the internal link table
|
|
of the packet aliasing engine will be cleared.
|
|
This operating mode is useful for ppp links
|
|
where the interface address can sometimes
|
|
change or remain the same between dial-ups.
|
|
If this mode bit is not set, it the link table
|
|
will never be reset in the event of an
|
|
address change.
|
|
.It PKT_ALIAS_PUNCH_FW.
|
|
This option make libalias `punch holes' in an
|
|
ipfw based firewall for FTP/IRC DCC connections.
|
|
The holes punched are bound by from/to IP address
|
|
and port; it will not be possible to use a hole
|
|
for another connection. A hole is removed when
|
|
the connection that use it die. To cater for
|
|
unexpected death of a program using libalias (e.g
|
|
kill -9), changing the state of the flag will
|
|
clear the entire ipfw range allocated for holes.
|
|
This will also happen on the initial call to
|
|
PacketAliasSetFWBase(). This call must happen
|
|
prior to setting this flag.
|
|
|
|
.El
|
|
|
|
.Ss 2.5 PacketAliasSetFWBase()
|
|
|
|
.Ft void
|
|
.Fn PacketAliasSetFWBase "unsigned int base" "unsigned int num"
|
|
|
|
Set IPFW range allocated for punching firewall holes (with the
|
|
PKT_ALIAS_PUNCH_FW flag). The range will be cleared for all rules on
|
|
initialization.
|
|
|
|
.Sh 3. Packet Handling
|
|
The packet handling functions are used to
|
|
modify incoming (remote->local) and outgoing
|
|
(local->remote) packets. The calling program
|
|
is responsible for receiving and sending
|
|
packets via network interfaces.
|
|
|
|
Along with PacketAliasInit() and PacketAliasSetAddress(),
|
|
the two packet handling functions, PacketAliasIn()
|
|
and PacketAliasOut(), comprise minimal set of functions
|
|
needed for a basic IP masquerading implementation.
|
|
.Ss 3.1 PacketAliasIn()
|
|
|
|
.Ft int
|
|
.Fn PacketAliasIn "char *buffer" "int maxpacketsize"
|
|
|
|
An incoming packet coming from a remote machine to
|
|
the local network is de-aliased by this function.
|
|
The IP packet is pointed to by
|
|
.Em buffer ,
|
|
and
|
|
.Em maxpacketsize
|
|
indicates the size of the data structure containing
|
|
the packet and should be at least as large as the
|
|
actual packet size.
|
|
|
|
Return codes:
|
|
.Bl -hang -offset left
|
|
.It PKT_ALIAS_ERROR.
|
|
An internal error within the packet aliasing
|
|
engine occurred.
|
|
.It PKT_ALIAS_OK.
|
|
The packet aliasing process was successful.
|
|
.It PKT_ALIAS_IGNORED.
|
|
The packet was ignored and not de-aliased.
|
|
This can happen if the protocal is unrecognized,
|
|
possibly an ICMP message type is not handled or
|
|
if incoming packets for new connections are being
|
|
ignored (see PKT_ALIAS_DENY_INCOMING in section
|
|
2.2).
|
|
.It PKT_ALIAS_UNRESOLVED_FRAGMENT.
|
|
This is returned when a fragment cannot be
|
|
resolved because the header fragment has not
|
|
been sent yet. In this situation, fragments
|
|
must be saved with PacketAliasSaveFragment()
|
|
until a header fragment is found.
|
|
.It PKT_ALIAS_FOUND_HEADER_FRAGMENT.
|
|
The packet aliasing process was successful,
|
|
and a header fragment was found. This is a
|
|
signal to retrieve any unresolved fragments
|
|
with PacketAliasGetFragment() and de-alias
|
|
them with PacketAliasFragmentIn().
|
|
.El
|
|
.Ss 3.2 PacketAliasOut()
|
|
|
|
.Ft int
|
|
.Fn PacketAliasOut "char *buffer" "int maxpacketsize"
|
|
|
|
An outgoing packet coming from the local network
|
|
to a remote machine is aliased by this function.
|
|
The IP packet is pointed to by
|
|
.Em buffer r,
|
|
and
|
|
.Em maxpacketsize
|
|
indicates the maximum packet size permissible
|
|
should the packet length be changed. IP encoding
|
|
protocols place address and port information in
|
|
the encapsulated data stream which have to be
|
|
modified and can account for changes in packet
|
|
length. Well known examples of such protocols
|
|
are FTP and IRC DCC.
|
|
|
|
Return codes:
|
|
.Bl -hang -offset left
|
|
.It PKT_ALIAS_ERROR.
|
|
An internal error within the packet aliasing
|
|
engine occurred.
|
|
.It PKT_ALIAS_OK.
|
|
The packet aliasing process was successful.
|
|
.It PKT_ALIAS_IGNORED.
|
|
The packet was ignored and not de-aliased.
|
|
This can happen if the protocal is unrecognized,
|
|
or possibly an ICMP message type is not handled.
|
|
.El
|
|
|
|
.Sh 4. Port and Address Redirection
|
|
The functions described in this section allow machines
|
|
on the local network to be accessible in some degree
|
|
to new incoming connections from the external network.
|
|
Individual ports can be re-mapped or static network
|
|
address translations can be designated.
|
|
.Ss 4.1 PacketAliasRedirectPort()
|
|
|
|
.Ft struct alias_link *
|
|
.Fo PacketAliasRedirectPort
|
|
.Fa "struct in_addr local_addr"
|
|
.Fa "u_short local_port"
|
|
.Fa "struct in_addr remote_addr"
|
|
.Fa "u_short remote_port"
|
|
.Fa "struct in_addr alias_addr"
|
|
.Fa "u_short alias_port"
|
|
.Fa "u_char proto"
|
|
.Fc
|
|
|
|
This function specifies that traffic from a
|
|
given remote address/port to an alias address/port
|
|
be redirected to a specified local address/port.
|
|
The parameter
|
|
.Em proto
|
|
can be either IPPROTO_TCP or IPPROTO_UDP, as
|
|
defined in <netinet/in.h>.
|
|
|
|
If
|
|
.Em local_addr
|
|
or
|
|
.Em alias_addr
|
|
is zero, this indicates that the packet aliasing
|
|
address as established by PacketAliasSetAddress()
|
|
is to be used. Even if PacketAliasAddress() is
|
|
called to change the address after PacketAliasRedirectPort()
|
|
is called, a zero reference will track this change.
|
|
|
|
If
|
|
.Em remote_addr
|
|
is zero, this indicates to redirect packets from
|
|
any remote address. Likewise, if
|
|
.Em remote_port
|
|
is zero, this indicates to redirect packets originating
|
|
from any remote port number. Almost always, the remote
|
|
port specification will be zero, but non-zero remote
|
|
addresses can be sometimes be useful for firewalling.
|
|
If two calls to PacketAliasRedirectPort() overlap in
|
|
their address/port specifications, then the most recent
|
|
call will have precedence.
|
|
|
|
This function returns a pointer which can subsequently
|
|
be used by PacketAliasRedirectDelete(). If NULL is
|
|
returned, then the function call did not complete
|
|
successfully.
|
|
|
|
All port numbers are in network address byte order,
|
|
so it is necessary to use htons() to convert these
|
|
parameters from internally readable numbers to
|
|
network byte order. Addresses are also in network
|
|
byte order, which is implicit in the use of the
|
|
.Em struct in_addr
|
|
data type.
|
|
.Ss 4.2 PacketAliasRedirectAddr()
|
|
|
|
.Ft struct alias_link *
|
|
.Fo PacketAliasRedirectAddr
|
|
.Fa "struct in_addr local_addr"
|
|
.Fa "struct in_addr alias_addr"
|
|
.Fc
|
|
|
|
This function desgnates that all incoming
|
|
traffic to
|
|
.Em alias_addr
|
|
be redirected to
|
|
.Em local_addr.
|
|
Similarly, all outgoing traffic from
|
|
.Em local_addr
|
|
is aliased to
|
|
.Em alias_addr .
|
|
|
|
If
|
|
.Em local_addr
|
|
or
|
|
.Em alias_addr
|
|
is zero, this indicates that the packet aliasing
|
|
address as established by PacketAliasSetAddress()
|
|
is to be used. Even if PacketAliasAddress() is
|
|
called to change the address after PacketAliasRedirectAddr()
|
|
is called, a zero reference will track this change.
|
|
|
|
If subsequent calls to PacketAliasRedirectAddr()
|
|
use the same aliasing address, all new incoming
|
|
traffic to this aliasing address will be redirected
|
|
to the local address made in the last function call,
|
|
but new traffic all of the local machines designated
|
|
in the several function calls will be aliased to
|
|
the same address. Consider the following example:
|
|
.Bd -literal -offset left
|
|
PacketAliasRedirectAddr(inet_aton("192.168.0.2"),
|
|
inet_aton("141.221.254.101"));
|
|
PacketAliasRedirectAddr(inet_aton("192.168.0.3"),
|
|
inet_aton("141.221.254.101"));
|
|
PacketAliasRedirectAddr(inet_aton("192.168.0.4"),
|
|
inet_aton("141.221.254.101"));
|
|
.Ed
|
|
|
|
Any outgoing connections such as telnet or ftp
|
|
from 192.168.0.2, 102.168.0.3, 192.168.0.4 will
|
|
appear to come from 141.221.254.101. Any incoming
|
|
connections to 141.221.254.101 will be directed
|
|
to 192.168.0.4.
|
|
|
|
Any calls to PacketAliasRedirectPort() will
|
|
have precedence over address mappings designated
|
|
by PacketAliasRedirectAddr().
|
|
|
|
This function returns a pointer which can subsequently
|
|
be used by PacketAliasRedirectDelete(). If NULL is
|
|
returned, then the function call did not complete
|
|
successfully.
|
|
.Ss 4.3 PacketAliasRedirectDelete()
|
|
|
|
.Ft void
|
|
.Fn PacketAliasRedirectDelete "struct alias_link *ptr"
|
|
|
|
This function will delete a specific static redirect
|
|
rule entered by PacketAliasRedirectPort() or
|
|
PacketAliasRedirectAddr(). The parameter
|
|
.Em ptr
|
|
is the pointer returned by either of the redirection
|
|
functions. If an invalid pointer is passed to
|
|
PacketAliasRedirectDelete(), then a program crash
|
|
or unpredictable operation could result, so it is
|
|
necessary to be careful using this function.
|
|
|
|
.Sh 5. Fragment Handling
|
|
The functions in this section are used to deal with
|
|
incoming fragments.
|
|
|
|
Outgoing fragments are handled within PacketAliasOut()
|
|
by changing the address according to any
|
|
applicable mapping set by PacketAliasRedirectAddress(),
|
|
or the default aliasing address set by
|
|
PacketAliasSetAddress().
|
|
|
|
Incoming fragments are handled in one of two ways.
|
|
If the header of a fragmented IP packet has already
|
|
been seen, then all subsequent fragments will be
|
|
re-mapped in the same manner the header fragment
|
|
was. Fragments which arrive before the header
|
|
are saved and then retrieved once the header fragment
|
|
has been resolved.
|
|
|
|
.Ss 4.4 PacketAliasProxyRule()
|
|
|
|
.Ft int
|
|
.Fn PacketAliasProxyRule "const char *cmd"
|
|
|
|
The passed
|
|
.Ar cmd
|
|
string consists of one or more pairs of words. The first word in each
|
|
pair is a token and the second is the value that should be applied for
|
|
that token. Tokens and their argument types are as follows:
|
|
|
|
.Bl -tag -offset XXX -width XXX
|
|
.It type encode_ip_hdr|encode_tcp_stream|no_encode
|
|
In order to support transparent proxying, it is necessary to somehow
|
|
pass the original address and port information into the new destination
|
|
server. If
|
|
.Dq encode_ip_hdr
|
|
is specified, the original address and port is passed as an extra IP
|
|
option. If
|
|
.Dq encode_tcp_stream
|
|
is specified, the original address and port is passed as the first
|
|
piece of data in the tcp stream in the format
|
|
.Dq DEST Ar IP port .
|
|
.It port Ar portnum
|
|
Only packets with the destination port
|
|
.Ar portnum
|
|
are proxied.
|
|
.It server Ar host[:portnum]
|
|
This specifies the
|
|
.Ar host
|
|
and
|
|
.Ar portnum
|
|
that the data is to be redirected to.
|
|
.Ar host
|
|
must be an IP address rather than a DNS host name. If
|
|
.Ar portnum
|
|
is not specified, the destination port number is not changed.
|
|
.Pp
|
|
The
|
|
.Ar server
|
|
specification is mandatory unless the
|
|
.Dq delete
|
|
command is being used.
|
|
.It rule Ar index
|
|
Normally, each call to
|
|
.Fn PacketAliasProxyRule
|
|
inserts the next rule at the start of a linear list of rules. If an
|
|
.Ar index
|
|
is specified, the new rule will be checked after all rules with lower
|
|
indices. Calls to
|
|
.Fn PacketAliasProxyRule
|
|
that do not specify a rule are assigned rule 0.
|
|
.It delete Ar index
|
|
This token and its argument must not be used with any other tokens. When
|
|
used, all existing rules with the given
|
|
.Ar index
|
|
are deleted.
|
|
.It proto tcp|udp
|
|
If specified, only packets of the given protocol type are matched.
|
|
.It src Ar IP[/bits]
|
|
If specified, only packets with a source address matching the given
|
|
.Ar IP
|
|
are matched. If
|
|
.Ar bits
|
|
is also specified, then the first
|
|
.Ar bits
|
|
bits of
|
|
.Ar IP
|
|
are taken as a network specification, and all IP addresses from that
|
|
network will be matched.
|
|
.It dest Ar IP[/bits]
|
|
If specified, only packets with a destination address matching the given
|
|
.Ar IP
|
|
are matched. If
|
|
.Ar bits
|
|
is also specified, then the first
|
|
.Ar bits
|
|
bits of
|
|
.Ar IP
|
|
are taken as a network specification, and all IP addresses from that
|
|
network will be matched.
|
|
.El
|
|
|
|
This function is usually used to redirect outgoing connections for
|
|
internal machines that are not permitted certain types of internet
|
|
access, or to restrict access to certain external machines.
|
|
|
|
.Ss 4.5 PacketAliasPptp()
|
|
|
|
.Ft extern int
|
|
.Fn PacketAliasPptp "struct in_addr addr"
|
|
|
|
This function causes any
|
|
.Em G Ns No eneral
|
|
.Em R Ns No outing
|
|
.Em E Ns No encapsulated
|
|
.Pq Dv IPPROTO_GRE
|
|
packets to be aliased using
|
|
.Ar addr
|
|
rather than the address set via
|
|
.Fn PacketAliasSetAddress .
|
|
This allows the uses of the
|
|
.Em P Ns No oint
|
|
to
|
|
.Em P Ns No oint
|
|
.Em T Ns No unneling
|
|
.Em P Ns No rotocol
|
|
on a machine on the internal network.
|
|
.Pp
|
|
If the passed address is
|
|
.Dv INADDR_NONE
|
|
.Pq 255.255.255.255 ,
|
|
.Dv PPTP
|
|
aliasing is disabled.
|
|
|
|
.Ss 5.1 PacketAliasSaveFragment()
|
|
|
|
.Ft int
|
|
.Fn PacketAliasSaveFragment "char *ptr"
|
|
|
|
When PacketAliasIn() returns
|
|
PKT_ALIAS_UNRESOLVED_FRAGMENT, this
|
|
function can be used to save the pointer to
|
|
the unresolved fragment.
|
|
|
|
It is implicitly assumed that
|
|
.Em ptr
|
|
points to a block of memory allocated by
|
|
malloc(). If the fragment is never
|
|
resolved, the packet aliasing engine will
|
|
automatically free the memory after a
|
|
timeout period. [Eventually this function
|
|
should be modified so that a callback
|
|
function for freeing memory is passed as
|
|
an argument.]
|
|
|
|
This function returns PKT_ALIAS_OK if it
|
|
was successful and PKT_ALIAS_ERROR if there
|
|
was an error.
|
|
|
|
.Ss 5.2 PacketAliasGetFragment()
|
|
|
|
.Ft char *
|
|
.Fn PacketAliasGetFragment "char *buffer"
|
|
|
|
This function can be used to retrieve fragment
|
|
pointers saved by PacketAliasSaveFragment().
|
|
The IP header fragment pointed to by
|
|
Em buffer
|
|
is the header fragment indicated when
|
|
PacketAliasIn() returns PKT_ALIAS_FOUND_HEADER_FRAGMENT.
|
|
Once a a fragment pointer is retrieved, it
|
|
becomes the calling program's responsibility
|
|
to free the dynamically allocated memory for
|
|
the fragment.
|
|
|
|
PacketAliasGetFragment() can be called
|
|
sequentially until there are no more fragments
|
|
available, at which time it returns NULL.
|
|
.Ss 5.3 PacketAliasFragmentIn()
|
|
|
|
.Ft void
|
|
.Fn PacketAliasFragmentIn "char *header" "char *fragment"
|
|
|
|
When a fragment is retrieved with
|
|
PacketAliasGetFragment(), it can then be
|
|
de-aliased with a call to PacketAliasFragmentIn().
|
|
.Em header
|
|
is the pointer to a header fragment used as a
|
|
template, and
|
|
.Em fragment
|
|
is the pointer to the packet to be de-aliased.
|
|
|
|
.Sh 6. Miscellaneous Functions
|
|
|
|
.Ss 6.1 PacketAliasSetTarget()
|
|
|
|
.Ft void
|
|
.Fn PacketAliasSetTarget "struct in_addr addr"
|
|
|
|
When an incoming packet not associated with
|
|
any pre-existing aliasing link arrives at the
|
|
host machine, it will be sent to the address
|
|
indicated by a call to PacketAliasSetTarget().
|
|
|
|
If this function is not called, or is called
|
|
with a zero address argument, then all new
|
|
incoming packets go to the address set by
|
|
PacketAliasSetAddress.
|
|
.Ss 6.2 PacketAliasCheckNewLink()
|
|
|
|
.Ft int
|
|
.Fn PacketAliasCheckNewLink "void"
|
|
|
|
This function returns a non-zero value when
|
|
a new aliasing link is created. In circumstances
|
|
where incoming traffic is being sequentially
|
|
sent to different local servers, this function
|
|
can be used to trigger when PacketAliasSetTarget()
|
|
is called to change the default target address.
|
|
.Ss 6.3 PacketAliasInternetChecksum()
|
|
|
|
.Ft u_short
|
|
.Fn PacketAliasInternetChecksum "u_short *buffer" "int nbytes"
|
|
|
|
This is a utility function that does not seem
|
|
to be available elswhere and is included as a
|
|
convenience. It computes the internet checksum,
|
|
which is used in both IP and protocol-specific
|
|
headers (TCP, UDP, ICMP).
|
|
|
|
.Em buffer
|
|
points to the data block to be checksummed, and
|
|
.Em nbytes
|
|
is the number of bytes. The 16-bit checksum
|
|
field should be zeroed before computing the checksum.
|
|
|
|
Checksums can also be verified by operating on a block
|
|
of data including its checksum. If the checksum is
|
|
valid, PacketAliasInternetChecksum() will return zero.
|
|
|
|
.Sh 7. Authors
|
|
Charles Mott (cmott@srv.net), versions 1.0 - 1.8, 2.0 - 2.4.
|
|
|
|
Eivind Eklund (eivind@freebsd.org), versions 1.8b, 1.9 and
|
|
2.5. Added IRC DCC support as well as contributing a number of
|
|
architectural improvements; added the firewall bypass
|
|
for FTP/IRC DCC.
|
|
|
|
.Sh 8. Acknowledgments
|
|
|
|
Listed below, in approximate chronological
|
|
order, are individuals who have provided
|
|
valuable comments and/or debugging assistance.
|
|
|
|
.Bl -inset -compact -offset left
|
|
.It Gary Roberts
|
|
.It Tom Torrance
|
|
.It Reto Burkhalter
|
|
.It Martin Renters
|
|
.It Brian Somers
|
|
.It Paul Traina
|
|
.It Ari Suutari
|
|
.It Dave Remien
|
|
.It J. Fortes
|
|
.It Andrzej Bialeki
|
|
.It Gordon Burditt
|
|
.El
|
|
|
|
.Sh Appendix: Conceptual Background
|
|
This appendix is intended for those who
|
|
are planning to modify the source code or want
|
|
to create somewhat esoteric applications using
|
|
the packet aliasing functions.
|
|
|
|
The conceptual framework under which the
|
|
packet aliasing engine operates is described here.
|
|
Central to the discussion is the idea of an
|
|
"aliasing link" which describes the relationship
|
|
for a given packet transaction between the local
|
|
machine, aliased identity and remote machine. It
|
|
is discussed how such links come into existence
|
|
and are destroyed.
|
|
.Ss A.1 Aliasing Links
|
|
There is a notion of an "aliasing link",
|
|
which is 7-tuple describing a specific
|
|
translation:
|
|
.Bd -literal -offset indent
|
|
(local addr, local port, alias addr, alias port,
|
|
remote addr, remote port, protocol)
|
|
.Ed
|
|
|
|
Outgoing packets have the local address and
|
|
port number replaced with the alias address
|
|
and port number. Incoming packets undergo the
|
|
reverse process. The packet aliasing engine
|
|
attempts to match packets against an internal
|
|
table of aliasing links to determine how to
|
|
modify a given IP packet. Both the IP
|
|
header and protocol dependent headers are
|
|
modified as necessary. Aliasing links are
|
|
created and deleted as necessary according
|
|
to network traffic.
|
|
|
|
Protocols can be TCP, UDP or even ICMP in
|
|
certain circumstances. (Some types of ICMP
|
|
packets can be aliased according to sequence
|
|
or id number which acts as an equivalent port
|
|
number for identifying how individual packets
|
|
should be handled.)
|
|
|
|
Each aliasing link must have a unique
|
|
combination of the following five quantities:
|
|
alias address/port, remote address/port
|
|
and protocol. This ensures that several
|
|
machines on a local network can share the
|
|
same aliased IP address. In cases where
|
|
conflicts might arise, the aliasing port
|
|
is chosen so that uniqueness is maintained.
|
|
.Ss A.2 Static and Dynamic Links
|
|
Aliasing links can either be static or dynamic.
|
|
Static links persist indefinitely and represent
|
|
fixed rules for translating IP packets. Dynamic
|
|
links come into existence for a specific TCP
|
|
connection or UDP transaction or ICMP echo
|
|
sequence. For the case of TCP, the connection
|
|
can be monitored to see when the associated
|
|
aliasing link should be deleted. Aliasing links
|
|
for UDP transactions (and ICMP echo and timestamp
|
|
requests) work on a simple timeout rule. When
|
|
no activity is observed on a dynamic link for
|
|
a certain amount of time it is automatically
|
|
deleted. Timeout rules also apply to TCP
|
|
connections which do not open or close
|
|
properly.
|
|
.Ss A.3 Partially Specified Aliasing Links
|
|
Aliasing links can be partially specified,
|
|
meaning that the remote address and/or remote
|
|
ports are unknown. In this case, when a packet
|
|
matching the incomplete specification is found,
|
|
a fully specified dynamic link is created. If
|
|
the original partially specified link is dynamic,
|
|
it will be deleted after the fully specified link
|
|
is created, otherwise it will persist.
|
|
|
|
For instance, a partially specified link might
|
|
be
|
|
.Bd -literal -offset indent
|
|
(192.168.0.4, 23, 204.228.203.215, 8066, 0, 0, tcp)
|
|
.Ed
|
|
|
|
The zeros denote unspecified components for
|
|
the remote address and port. If this link were
|
|
static it would have the effect of redirecting
|
|
all incoming traffic from port 8066 of
|
|
204.228.203.215 to port 23 (telnet) of machine
|
|
192.168.0.4 on the local network. Each
|
|
individual telnet connection would initiate
|
|
the creation of a distinct dynamic link.
|
|
.Ss A.4 Dynamic Link Creation
|
|
In addition to aliasing links, there are
|
|
also address mappings that can be stored
|
|
within the internal data table of the packet
|
|
aliasing mechanism.
|
|
.Bd -literal -offset indent
|
|
(local addr, alias addr)
|
|
.Ed
|
|
|
|
Address mappings are searched when creating
|
|
new dynamic links.
|
|
|
|
All outgoing packets from the local network
|
|
automatically create a dynamic link if
|
|
they do not match an already existing fully
|
|
specified link. If an address mapping exists
|
|
for the the outgoing packet, this determines
|
|
the alias address to be used. If no mapping
|
|
exists, then a default address, usually the
|
|
address of the packet aliasing host, is used.
|
|
If necessary, this default address can be
|
|
changed as often as each individual packet
|
|
arrives.
|
|
|
|
The aliasing port number is determined
|
|
such that the new dynamic link does not
|
|
conflict with any existing links. In the
|
|
default operating mode, the packet aliasing
|
|
engine attempts to set the aliasing port
|
|
equal to the local port number. If this
|
|
results in a conflict, then port numbers
|
|
are randomly chosen until a unique aliasing
|
|
link can be established. In an alternate
|
|
operating mode, the first choice of an
|
|
aliasing port is also random and unrelated
|
|
to the local port number.
|
|
|