xref: /freebsd/sys/netinet/libalias/libalias.3 (revision 1855100f8fddfa51365a54a8feb8b6eca044b4f3)
17f3dea24SPeter Wemm.\" $FreeBSD$
274804d58SMike Pritchard.\"
33efa11bbSBrian Somers.Dd July, 1997
474804d58SMike Pritchard.Dt LIBALIAS 3
53efa11bbSBrian Somers.Os
63efa11bbSBrian Somers.Sh NAME
774804d58SMike Pritchard.Nm libalias
874804d58SMike Pritchard.Nd packet aliasing library for masquerading and address translation (NAT)
93efa11bbSBrian Somers.Sh SYNOPSIS
10442a25bdSBruce Evans.Fd #include <sys/types.h>
113efa11bbSBrian Somers.Fd #include <netinet/in.h>
123efa11bbSBrian Somers.Fd #include <alias.h>
133efa11bbSBrian Somers
143efa11bbSBrian SomersFunction prototypes are given in the main body
153efa11bbSBrian Somersof the text.
1674804d58SMike Pritchard.Sh DESCRIPTION
1774804d58SMike PritchardThe
1874804d58SMike Pritchard.Nm
1974804d58SMike Pritchardlibrary is a collection of
2074804d58SMike Pritchardfunctions for aliasing and de-aliasing
2174804d58SMike Pritchardof IP packets, intended for masquerading and
2274804d58SMike Pritchardnetwork address translation (NAT).
233efa11bbSBrian Somers.Sh CONTENTS
243efa11bbSBrian Somers.Bd -literal -offset left
253efa11bbSBrian Somers1. Introduction
263efa11bbSBrian Somers2. Initialization and Control
273efa11bbSBrian Somers    2.1 PacketAliasInit()
288ddc51bcSEivind Eklund    2.2 PacketAliasUninit()
298ddc51bcSEivind Eklund    2.3 PacketAliasSetAddress()
308ddc51bcSEivind Eklund    2.4 PacketAliasSetMode()
318ddc51bcSEivind Eklund    2.5 PacketAliasSetFWBase()
323efa11bbSBrian Somers3. Packet Handling
33b2052ac8SJohn Polstra    3.1 PacketAliasIn()
34b2052ac8SJohn Polstra    3.2 PacketAliasOut()
353efa11bbSBrian Somers4. Port and Address Redirection
363efa11bbSBrian Somers    4.1 PacketAliasRedirectPort()
373efa11bbSBrian Somers    4.2 PacketAliasRedirectAddr()
383efa11bbSBrian Somers    4.3 PacketAliasRedirectDelete()
39619d1a30SBrian Somers    4.4 PacketAliasProxyRule()
40164928d3SBrian Somers    4.5 PacketAliasPptp()
413efa11bbSBrian Somers5. Fragment Handling
423efa11bbSBrian Somers    5.1 PacketAliasSaveFragment()
433efa11bbSBrian Somers    5.2 PacketAliasGetFragment()
443efa11bbSBrian Somers    5.3 PacketAliasFragmentIn()
453efa11bbSBrian Somers6. Miscellaneous Functions
463efa11bbSBrian Somers    6.1 PacketAliasSetTarget()
473efa11bbSBrian Somers    6.2 PacketAliasCheckNewLink()
483efa11bbSBrian Somers    6.3 PacketAliasInternetChecksum()
493efa11bbSBrian Somers7. Authors
503efa11bbSBrian Somers8. Acknowledgments
513efa11bbSBrian Somers
523efa11bbSBrian SomersAppendix A: Conceptual Background
533efa11bbSBrian Somers    A.1 Aliasing Links
543efa11bbSBrian Somers    A.2 Static and Dynamic Links
553efa11bbSBrian Somers    A.3 Partially Specified Links
563efa11bbSBrian Somers    A.4 Dynamic Link Creation
573efa11bbSBrian Somers.Ed
583efa11bbSBrian Somers.Sh 1. Introduction
593efa11bbSBrian SomersThis library is a moderately portable
603efa11bbSBrian Somersset of functions designed to assist
613efa11bbSBrian Somersin the process of IP masquerading and
623efa11bbSBrian Somersnetwork address translation.  Outgoing
633efa11bbSBrian Somerspackets from a local network with
643efa11bbSBrian Somersunregistered IP addresses can be aliased
653efa11bbSBrian Somersto appear as if they came from an
663efa11bbSBrian Somersaccessible IP address.  Incoming packets
673efa11bbSBrian Somersare then de-aliased so that they are sent
683efa11bbSBrian Somersto the correct machine on the local network.
693efa11bbSBrian Somers
703efa11bbSBrian SomersA certain amount of flexibility is built
713efa11bbSBrian Somersinto the packet aliasing engine.  In
723efa11bbSBrian Somersthe simplest mode of operation, a
733efa11bbSBrian Somersmany-to-one address mapping takes place
743efa11bbSBrian Somersbetween local network and the packet
753efa11bbSBrian Somersaliasing host.  This is known as IP
763efa11bbSBrian Somersmasquerading.  In addition, one-to-one
773efa11bbSBrian Somersmappings between local and public addresses
783efa11bbSBrian Somerscan also be implemented, which is known as
793efa11bbSBrian Somersstatic NAT.  In between these extremes,
803efa11bbSBrian Somersdifferent groups of private addresses
813efa11bbSBrian Somerscan be linked to different public addresses,
823efa11bbSBrian Somerscomprising several distinct many-to-one
833efa11bbSBrian Somersmappings.  Also, a given public address
849c727d2cSJoseph Koshyand port can be statically redirected to
853efa11bbSBrian Somersa private address/port.
863efa11bbSBrian Somers
873efa11bbSBrian SomersThe packet aliasing engine was designed
883efa11bbSBrian Somersto operate in user space outside of the
893efa11bbSBrian Somerskernel, without any access to private
903efa11bbSBrian Somerskernel data structure, but the source code
913efa11bbSBrian Somerscan also be ported to a kernel environment.
923efa11bbSBrian Somers.Sh 2. Initialization and Control
933efa11bbSBrian SomersTwo specific functions, PacketAliasInit()
943efa11bbSBrian Somersand PacketAliasSetAddress(), must always be
953efa11bbSBrian Somerscalled before any packet handling may be
963efa11bbSBrian Somersperformed.  In addition, the operating mode
973efa11bbSBrian Somersof the packet aliasing engine can be customized
983efa11bbSBrian Somersby calling PacketAliasSetMode().
993efa11bbSBrian Somers.Ss 2.1 PacketAliasInit()
1003efa11bbSBrian Somers
1013efa11bbSBrian Somers.Ft void
1023efa11bbSBrian Somers.Fn PacketAliasInit "void"
1033efa11bbSBrian Somers
1043efa11bbSBrian SomersThis function has no argument or return
1053efa11bbSBrian Somersvalue and is used to initialize internal
1063efa11bbSBrian Somersdata structures. The following mode bits
1073efa11bbSBrian Somersare always set after calling
1083efa11bbSBrian SomersPacketAliasInit().  See section 2.3 for
1093efa11bbSBrian Somersthe meaning of these mode bits.
1103efa11bbSBrian Somers.Bd -literal -offset indent
1113efa11bbSBrian Somers    PKT_ALIAS_USE_SAME_PORTS
1123efa11bbSBrian Somers    PKT_ALIAS_USE_SOCKETS
1133efa11bbSBrian Somers    PKT_ALIAS_RESET_ON_ADDR_CHANGE
1143efa11bbSBrian Somers
1153efa11bbSBrian Somers.Ed
1163efa11bbSBrian SomersThis function will always return the packet
1173efa11bbSBrian Somersaliasing engine to the same initial state.
1183efa11bbSBrian SomersPacketAliasSetAddress() must be called afterwards,
1193efa11bbSBrian Somersand any desired changes from the default mode
1203efa11bbSBrian Somersbits listed above require a call to
1213efa11bbSBrian SomersPacketAliasSetMode().
1223efa11bbSBrian Somers
1233efa11bbSBrian SomersIt is mandatory that this function be called
1243efa11bbSBrian Somersat the beginning of a program prior to any
1253efa11bbSBrian Somerspacket handling.
126bf9a92b7SBruce Evans.Ss 2.2 PacketAliasUninit()
1278ddc51bcSEivind Eklund
1288ddc51bcSEivind Eklund.Ft void
129bf9a92b7SBruce Evans.Fn PacketAliasUninit "void"
1308ddc51bcSEivind Eklund
1318ddc51bcSEivind EklundThis function has no argument or return
1328ddc51bcSEivind Eklundvalue and is used to clear any resources
1338ddc51bcSEivind Eklundattached to internal data structures.
1348ddc51bcSEivind Eklund
1358ddc51bcSEivind EklundThis functions should be called when a
1368ddc51bcSEivind Eklundprogram stop using the aliasing engine;
1378ddc51bcSEivind Eklundit do, among other things, clear out any
1388ddc51bcSEivind Eklundfirewall holes.  To provide backwards
1398ddc51bcSEivind Eklundcompatibility and extra security, it is
1408ddc51bcSEivind Eklundadded to the atexit() chain by
1418ddc51bcSEivind EklundPacketAliasInit().  Calling it multiple
1428ddc51bcSEivind Eklundtimes is harmless.
1438ddc51bcSEivind Eklund.Ss 2.3 PacketAliasSetAddress()
1443efa11bbSBrian Somers
1453efa11bbSBrian Somers.Ft void
1463efa11bbSBrian Somers.Fn PacketAliasSetAddress "struct in_addr addr"
1473efa11bbSBrian Somers
1483efa11bbSBrian SomersThis function sets the source address to which
1493efa11bbSBrian Somersoutgoing packets from the local area network
1503efa11bbSBrian Somersare aliased.  All outgoing packets are remapped
1513efa11bbSBrian Somersto this address unless overridden by a static
1523efa11bbSBrian Somersaddress mapping established by
1533efa11bbSBrian SomersPacketAliasRedirectAddr().
1543efa11bbSBrian Somers
1553efa11bbSBrian SomersIf the PKT_ALIAS_RESET_ON_ADDR_CHANGE mode bit
1563efa11bbSBrian Somersis set (the default mode of operation), then
1573efa11bbSBrian Somersthe internal aliasing link tables will be reset
1583efa11bbSBrian Somersany time the aliasing address changes, as if
1593efa11bbSBrian SomersPacketAliasReset() were called.  This is useful
1603efa11bbSBrian Somersfor interfaces such as ppp where the IP
1613efa11bbSBrian Somersaddress may or may not change on successive
1623efa11bbSBrian Somersdial-up attempts.
1633efa11bbSBrian Somers
1643efa11bbSBrian SomersIf the PKT_ALIAS_RESET_ON_ADDR_CHANGE mode bit
1653efa11bbSBrian Somersis set to zero, this function can also be used to
1663efa11bbSBrian Somersdynamically change the aliasing address on a
1673efa11bbSBrian Somerspacket to packet basis (it is a low overhead
1683efa11bbSBrian Somerscall).
1693efa11bbSBrian Somers
1703efa11bbSBrian SomersIt is mandatory that this function be called
1713efa11bbSBrian Somersprior to any packet handling.
1728ddc51bcSEivind Eklund.Ss 2.4 PacketAliasSetMode()
1733efa11bbSBrian Somers
174442a25bdSBruce Evans.Ft unsigned int
175442a25bdSBruce Evans.Fn PacketAliasSetMode "unsigned int mode" "unsigned int mask"
1763efa11bbSBrian Somers
1773efa11bbSBrian SomersThis function sets or clears mode bits
1783efa11bbSBrian Somersaccording to the value of
1793efa11bbSBrian Somers.Em mode .
1803efa11bbSBrian SomersOnly bits marked in
1813efa11bbSBrian Somers.Em mask
1823efa11bbSBrian Somersare affected.  The following mode bits are
1833efa11bbSBrian Somersdefined in alias.h:
1843efa11bbSBrian Somers.Bl -hang -offset left
1853efa11bbSBrian Somers.It PKT_ALIAS_LOG.
1863efa11bbSBrian SomersEnables logging /var/log/alias.log.  The log file
1873efa11bbSBrian Somersshows total numbers of links (icmp, tcp, udp) each
1883efa11bbSBrian Somerstime an aliasing link is created or deleted.  Mainly
1893efa11bbSBrian Somersuseful for debugging when the log file is viewed
1903efa11bbSBrian Somerscontinuously with "tail -f".
1913efa11bbSBrian Somers.It PKT_ALIAS_DENY_INCOMING.
1923efa11bbSBrian SomersIf this mode bit is set, all incoming packets
1933efa11bbSBrian Somersassociated with new TCP connections or new
1943efa11bbSBrian SomersUDP transactions will be marked for being
1953efa11bbSBrian Somersignored (PacketAliasIn() return code
1963efa11bbSBrian SomersPKT_ALIAS_IGNORED) by the calling program.
1973efa11bbSBrian SomersResponse packets to connections or transactions
1983efa11bbSBrian Somersinitiated from the packet aliasing host or
1993efa11bbSBrian Somerslocal network will be unaffected.  This mode
2003efa11bbSBrian Somersbit is useful for implementing a one-way firewall.
2013efa11bbSBrian Somers.It PKT_ALIAS_SAME_PORTS.
2023efa11bbSBrian SomersIf this mode bit is set, the packet aliasing
2033efa11bbSBrian Somersengine will attempt to leave the alias port
2043efa11bbSBrian Somersnumbers unchanged from the actual local port
2053efa11bbSBrian Somersnumber.  This can be done as long as the
2063efa11bbSBrian Somersquintuple (proto, alias addr, alias port,
2073efa11bbSBrian Somersremote addr, remote port) is unique.  If a
2083efa11bbSBrian Somersconflict exists, an new aliasing port number is
2093efa11bbSBrian Somerschosen even if this mode bit is set.
2103efa11bbSBrian Somers.It PKT_ALIAS_USE_SOCKETS.
2113efa11bbSBrian SomersThis bit should be set when the the packet
2123efa11bbSBrian Somersaliasing host originates network traffic as
2133efa11bbSBrian Somerswell as forwards it.  When the packet aliasing
2143efa11bbSBrian Somershost is waiting for a connection from an
2153efa11bbSBrian Somersunknown host address or unknown port number
2163efa11bbSBrian Somers(e.g. an FTP data connection), this mode bit
2173efa11bbSBrian Somersspecifies that a socket be allocated as a place
2183efa11bbSBrian Somersholder to prevent port conflicts.  Once a
2199c727d2cSJoseph Koshyconnection is established, usually within a
2203efa11bbSBrian Somersminute or so, the socket is closed.
2213efa11bbSBrian Somers.It PKT_ALIAS_UNREGISTERED_ONLY.
2223efa11bbSBrian SomersIf this mode bit is set, traffic on the
2233efa11bbSBrian Somerslocal network which does not originate from
2243efa11bbSBrian Somersunregistered address spaces will be ignored.
2253efa11bbSBrian SomersStandard Class A, B and C unregistered addresses
2263efa11bbSBrian Somersare:
2273efa11bbSBrian Somers.Bd -literal -offset indent
2283efa11bbSBrian Somers    10.0.0.0     ->   10.255.255.255   (Class A subnet)
2293efa11bbSBrian Somers    172.16.0.0   ->   172.31.255.255   (Class B subnets)
2303efa11bbSBrian Somers    192.168.0.0  ->   192.168.255.255  (Class C subnets)
2313efa11bbSBrian Somers
2323efa11bbSBrian Somers.Ed
2333efa11bbSBrian SomersThis option is useful in the case that
2343efa11bbSBrian Somerspacket aliasing host has both registered and
2353efa11bbSBrian Somersunregistered subnets on different interfaces.
2363efa11bbSBrian SomersThe registered subnet is fully accessible to
2373efa11bbSBrian Somersthe outside world, so traffic from it doesn't
2383efa11bbSBrian Somersneed to be passed through the packet aliasing
2393efa11bbSBrian Somersengine.
2403efa11bbSBrian Somers.It PKT_ALIAS_RESET_ON_ADDR_CHANGE.
2413efa11bbSBrian SomersWhen this mode bit is set and
2423efa11bbSBrian SomersPacketAliasSetAddress() is called to change
2433efa11bbSBrian Somersthe aliasing address, the internal link table
2443efa11bbSBrian Somersof the packet aliasing engine will be cleared.
2453efa11bbSBrian SomersThis operating mode is useful for ppp links
2463efa11bbSBrian Somerswhere the interface address can sometimes
2473efa11bbSBrian Somerschange or remain the same between dial-ups.
2483efa11bbSBrian SomersIf this mode bit is not set, it the link table
2493efa11bbSBrian Somerswill never be reset in the event of an
2503efa11bbSBrian Somersaddress change.
2518ddc51bcSEivind Eklund.It PKT_ALIAS_PUNCH_FW.
2520622eafcSBrian SomersThis option makes libalias `punch holes' in an
2538ddc51bcSEivind Eklundipfw based firewall for FTP/IRC DCC connections.
2548ddc51bcSEivind EklundThe holes punched are bound by from/to IP address
2558ddc51bcSEivind Eklundand port; it will not be possible to use a hole
2568ddc51bcSEivind Eklundfor another connection.  A hole is removed when
2578ddc51bcSEivind Eklundthe connection that use it die.  To cater for
2588ddc51bcSEivind Eklundunexpected death of a program using libalias (e.g
2598ddc51bcSEivind Eklundkill -9), changing the state of the flag will
2608ddc51bcSEivind Eklundclear the entire ipfw range allocated for holes.
2618ddc51bcSEivind EklundThis will also happen on the initial call to
2628ddc51bcSEivind EklundPacketAliasSetFWBase().  This call must happen
2638ddc51bcSEivind Eklundprior to setting this flag.
2640622eafcSBrian Somers.It PKT_ALIAS_REVERSE.
2650622eafcSBrian SomersThis option makes libalias reverse the way it
2660622eafcSBrian Somershandles incoming and outgoing packets, allowing
2670622eafcSBrian Somersit to be fed data that passes through the internal
2680622eafcSBrian Somersinterface rather than the external one.
2698ddc51bcSEivind Eklund
2703efa11bbSBrian Somers.El
2718ddc51bcSEivind Eklund
2728ddc51bcSEivind Eklund.Ss 2.5 PacketAliasSetFWBase()
2738ddc51bcSEivind Eklund
2748ddc51bcSEivind Eklund.Ft void
2758ddc51bcSEivind Eklund.Fn PacketAliasSetFWBase "unsigned int base" "unsigned int num"
2768ddc51bcSEivind Eklund
2778ddc51bcSEivind EklundSet IPFW range allocated for punching firewall holes (with the
2788ddc51bcSEivind EklundPKT_ALIAS_PUNCH_FW flag).  The range will be cleared for all rules on
2798ddc51bcSEivind Eklundinitialization.
2803efa11bbSBrian Somers.Sh 3. Packet Handling
2813efa11bbSBrian SomersThe packet handling functions are used to
2823efa11bbSBrian Somersmodify incoming (remote->local) and outgoing
2833efa11bbSBrian Somers(local->remote) packets.  The calling program
2843efa11bbSBrian Somersis responsible for receiving and sending
2853efa11bbSBrian Somerspackets via network interfaces.
2863efa11bbSBrian Somers
2873efa11bbSBrian SomersAlong with PacketAliasInit() and PacketAliasSetAddress(),
2883efa11bbSBrian Somersthe two packet handling functions, PacketAliasIn()
2893efa11bbSBrian Somersand PacketAliasOut(), comprise minimal set of functions
2903efa11bbSBrian Somersneeded for a basic IP masquerading implementation.
2913efa11bbSBrian Somers.Ss 3.1 PacketAliasIn()
2923efa11bbSBrian Somers
2933efa11bbSBrian Somers.Ft int
2943efa11bbSBrian Somers.Fn PacketAliasIn "char *buffer" "int maxpacketsize"
2953efa11bbSBrian Somers
2963efa11bbSBrian SomersAn incoming packet coming from a remote machine to
2973efa11bbSBrian Somersthe local network is de-aliased by this function.
2983efa11bbSBrian SomersThe IP packet is pointed to by
2993efa11bbSBrian Somers.Em buffer ,
3003efa11bbSBrian Somersand
3013efa11bbSBrian Somers.Em maxpacketsize
3023efa11bbSBrian Somersindicates the size of the data structure containing
3033efa11bbSBrian Somersthe packet and should be at least as large as the
3043efa11bbSBrian Somersactual packet size.
3053efa11bbSBrian Somers
3063efa11bbSBrian SomersReturn codes:
3073efa11bbSBrian Somers.Bl -hang -offset left
3083efa11bbSBrian Somers.It PKT_ALIAS_ERROR.
3093efa11bbSBrian SomersAn internal error within the packet aliasing
3109c727d2cSJoseph Koshyengine occurred.
3113efa11bbSBrian Somers.It PKT_ALIAS_OK.
3123efa11bbSBrian SomersThe packet aliasing process was successful.
3133efa11bbSBrian Somers.It PKT_ALIAS_IGNORED.
3143efa11bbSBrian SomersThe packet was ignored and not de-aliased.
3153efa11bbSBrian SomersThis can happen if the protocal is unrecognized,
3163efa11bbSBrian Somerspossibly an ICMP message type is not handled or
3173efa11bbSBrian Somersif incoming packets for new connections are being
3183efa11bbSBrian Somersignored (see PKT_ALIAS_DENY_INCOMING in section
3193efa11bbSBrian Somers2.2).
3203efa11bbSBrian Somers.It PKT_ALIAS_UNRESOLVED_FRAGMENT.
3213efa11bbSBrian SomersThis is returned when a fragment cannot be
3223efa11bbSBrian Somersresolved because the header fragment has not
3233efa11bbSBrian Somersbeen sent yet.  In this situation, fragments
3243efa11bbSBrian Somersmust be saved with PacketAliasSaveFragment()
3253efa11bbSBrian Somersuntil a header fragment is found.
3263efa11bbSBrian Somers.It PKT_ALIAS_FOUND_HEADER_FRAGMENT.
3273efa11bbSBrian SomersThe packet aliasing process was successful,
3283efa11bbSBrian Somersand a header fragment was found.  This is a
3293efa11bbSBrian Somerssignal to retrieve any unresolved fragments
3303efa11bbSBrian Somerswith PacketAliasGetFragment() and de-alias
3313efa11bbSBrian Somersthem with PacketAliasFragmentIn().
3323efa11bbSBrian Somers.El
3333efa11bbSBrian Somers.Ss 3.2 PacketAliasOut()
3343efa11bbSBrian Somers
3353efa11bbSBrian Somers.Ft int
336b2052ac8SJohn Polstra.Fn PacketAliasOut "char *buffer" "int maxpacketsize"
3373efa11bbSBrian Somers
3383efa11bbSBrian SomersAn outgoing packet coming from the local network
3393efa11bbSBrian Somersto a remote machine is aliased by this function.
3403efa11bbSBrian SomersThe IP packet is pointed to by
3413efa11bbSBrian Somers.Em buffer r,
3423efa11bbSBrian Somersand
3433efa11bbSBrian Somers.Em maxpacketsize
3449c727d2cSJoseph Koshyindicates the maximum packet size permissible
3453efa11bbSBrian Somersshould the packet length be changed.  IP encoding
3469c727d2cSJoseph Koshyprotocols place address and port information in
3473efa11bbSBrian Somersthe encapsulated data stream which have to be
3483efa11bbSBrian Somersmodified and can account for changes in packet
3493efa11bbSBrian Somerslength.  Well known examples of such protocols
3508ddc51bcSEivind Eklundare FTP and IRC DCC.
3513efa11bbSBrian Somers
3523efa11bbSBrian SomersReturn codes:
3533efa11bbSBrian Somers.Bl -hang -offset left
3543efa11bbSBrian Somers.It PKT_ALIAS_ERROR.
3553efa11bbSBrian SomersAn internal error within the packet aliasing
3569c727d2cSJoseph Koshyengine occurred.
3573efa11bbSBrian Somers.It PKT_ALIAS_OK.
3583efa11bbSBrian SomersThe packet aliasing process was successful.
3593efa11bbSBrian Somers.It PKT_ALIAS_IGNORED.
3603efa11bbSBrian SomersThe packet was ignored and not de-aliased.
3613efa11bbSBrian SomersThis can happen if the protocal is unrecognized,
3623efa11bbSBrian Somersor possibly an ICMP message type is not handled.
3633efa11bbSBrian Somers.El
3643efa11bbSBrian Somers.Sh 4. Port and Address Redirection
3653efa11bbSBrian SomersThe functions described in this section allow machines
3663efa11bbSBrian Somerson the local network to be accessible in some degree
3673efa11bbSBrian Somersto new incoming connections from the external network.
3683efa11bbSBrian SomersIndividual ports can be re-mapped or static network
3693efa11bbSBrian Somersaddress translations can be designated.
3703efa11bbSBrian Somers.Ss 4.1 PacketAliasRedirectPort()
3713efa11bbSBrian Somers
3723efa11bbSBrian Somers.Ft struct alias_link *
3733efa11bbSBrian Somers.Fo PacketAliasRedirectPort
3743efa11bbSBrian Somers.Fa "struct in_addr local_addr"
3753efa11bbSBrian Somers.Fa "u_short local_port"
3763efa11bbSBrian Somers.Fa "struct in_addr remote_addr"
3773efa11bbSBrian Somers.Fa "u_short remote_port"
3783efa11bbSBrian Somers.Fa "struct in_addr alias_addr"
3793efa11bbSBrian Somers.Fa "u_short alias_port"
3803efa11bbSBrian Somers.Fa "u_char proto"
3813efa11bbSBrian Somers.Fc
3823efa11bbSBrian Somers
3833efa11bbSBrian SomersThis function specifies that traffic from a
3843efa11bbSBrian Somersgiven remote address/port to an alias address/port
3853efa11bbSBrian Somersbe redirected to a specified local address/port.
3869c727d2cSJoseph KoshyThe parameter
3873efa11bbSBrian Somers.Em proto
3883efa11bbSBrian Somerscan be either IPPROTO_TCP or IPPROTO_UDP, as
3893efa11bbSBrian Somersdefined in <netinet/in.h>.
3903efa11bbSBrian Somers
3913efa11bbSBrian SomersIf
3923efa11bbSBrian Somers.Em local_addr
3933efa11bbSBrian Somersor
3943efa11bbSBrian Somers.Em alias_addr
3953efa11bbSBrian Somersis zero, this indicates that the packet aliasing
3963efa11bbSBrian Somersaddress as established by PacketAliasSetAddress()
3973efa11bbSBrian Somersis to be used.  Even if PacketAliasAddress() is
3983efa11bbSBrian Somerscalled to change the address after PacketAliasRedirectPort()
3993efa11bbSBrian Somersis called, a zero reference will track this change.
4003efa11bbSBrian Somers
4013efa11bbSBrian SomersIf
4023efa11bbSBrian Somers.Em remote_addr
4033efa11bbSBrian Somersis zero, this indicates to redirect packets from
4043efa11bbSBrian Somersany remote address.  Likewise, if
4053efa11bbSBrian Somers.Em remote_port
4063efa11bbSBrian Somersis zero, this indicates to redirect packets originating
4073efa11bbSBrian Somersfrom any remote port number.  Almost always, the remote
4083efa11bbSBrian Somersport specification will be zero, but non-zero remote
4093efa11bbSBrian Somersaddresses can be sometimes be useful for firewalling.
4103efa11bbSBrian SomersIf two calls to PacketAliasRedirectPort() overlap in
4113efa11bbSBrian Somerstheir address/port specifications, then the most recent
4123efa11bbSBrian Somerscall will have precedence.
4133efa11bbSBrian Somers
4143efa11bbSBrian SomersThis function returns a pointer which can subsequently
4153efa11bbSBrian Somersbe used by PacketAliasRedirectDelete().  If NULL is
4163efa11bbSBrian Somersreturned, then the function call did not complete
4173efa11bbSBrian Somerssuccessfully.
4183efa11bbSBrian Somers
4193efa11bbSBrian SomersAll port numbers are in network address byte order,
4203efa11bbSBrian Somersso it is necessary to use htons() to convert these
4213efa11bbSBrian Somersparameters from internally readable numbers to
4223efa11bbSBrian Somersnetwork byte order.  Addresses are also in network
4233efa11bbSBrian Somersbyte order, which is implicit in the use of the
4243efa11bbSBrian Somers.Em struct in_addr
4253efa11bbSBrian Somersdata type.
4263efa11bbSBrian Somers.Ss 4.2 PacketAliasRedirectAddr()
4273efa11bbSBrian Somers
4283efa11bbSBrian Somers.Ft struct alias_link *
429442a25bdSBruce Evans.Fo PacketAliasRedirectAddr
4303efa11bbSBrian Somers.Fa "struct in_addr local_addr"
4313efa11bbSBrian Somers.Fa "struct in_addr alias_addr"
4323efa11bbSBrian Somers.Fc
4333efa11bbSBrian Somers
4343efa11bbSBrian SomersThis function desgnates that all incoming
4353efa11bbSBrian Somerstraffic to
4363efa11bbSBrian Somers.Em alias_addr
4373efa11bbSBrian Somersbe redirected to
4383efa11bbSBrian Somers.Em local_addr.
4393efa11bbSBrian SomersSimilarly, all outgoing traffic from
4403efa11bbSBrian Somers.Em local_addr
4413efa11bbSBrian Somersis aliased to
4423efa11bbSBrian Somers.Em alias_addr .
4433efa11bbSBrian Somers
4443efa11bbSBrian SomersIf
4453efa11bbSBrian Somers.Em local_addr
4463efa11bbSBrian Somersor
4473efa11bbSBrian Somers.Em alias_addr
4483efa11bbSBrian Somersis zero, this indicates that the packet aliasing
4493efa11bbSBrian Somersaddress as established by PacketAliasSetAddress()
4503efa11bbSBrian Somersis to be used.  Even if PacketAliasAddress() is
4513efa11bbSBrian Somerscalled to change the address after PacketAliasRedirectAddr()
4523efa11bbSBrian Somersis called, a zero reference will track this change.
4533efa11bbSBrian Somers
4543efa11bbSBrian SomersIf subsequent calls to PacketAliasRedirectAddr()
4553efa11bbSBrian Somersuse the same aliasing address, all new incoming
4563efa11bbSBrian Somerstraffic to this aliasing address will be redirected
4573efa11bbSBrian Somersto the local address made in the last function call,
4583efa11bbSBrian Somersbut new traffic all of the local machines designated
4593efa11bbSBrian Somersin the several function calls will be aliased to
4603efa11bbSBrian Somersthe same address.  Consider the following example:
4613efa11bbSBrian Somers.Bd -literal -offset left
4623efa11bbSBrian Somers    PacketAliasRedirectAddr(inet_aton("192.168.0.2"),
4633efa11bbSBrian Somers                            inet_aton("141.221.254.101"));
4643efa11bbSBrian Somers    PacketAliasRedirectAddr(inet_aton("192.168.0.3"),
4653efa11bbSBrian Somers                            inet_aton("141.221.254.101"));
4663efa11bbSBrian Somers    PacketAliasRedirectAddr(inet_aton("192.168.0.4"),
4673efa11bbSBrian Somers                            inet_aton("141.221.254.101"));
4683efa11bbSBrian Somers.Ed
4693efa11bbSBrian Somers
4703efa11bbSBrian SomersAny outgoing connections such as telnet or ftp
471a395af90STim Vanderhoekfrom 192.168.0.2, 192.168.0.3, 192.168.0.4 will
4723efa11bbSBrian Somersappear to come from 141.221.254.101.  Any incoming
4733efa11bbSBrian Somersconnections to 141.221.254.101 will be directed
4743efa11bbSBrian Somersto 192.168.0.4.
4753efa11bbSBrian Somers
4763efa11bbSBrian SomersAny calls to PacketAliasRedirectPort() will
4773efa11bbSBrian Somershave precedence over address mappings designated
4783efa11bbSBrian Somersby PacketAliasRedirectAddr().
4793efa11bbSBrian Somers
4803efa11bbSBrian SomersThis function returns a pointer which can subsequently
4813efa11bbSBrian Somersbe used by PacketAliasRedirectDelete().  If NULL is
4823efa11bbSBrian Somersreturned, then the function call did not complete
4833efa11bbSBrian Somerssuccessfully.
4843efa11bbSBrian Somers.Ss 4.3 PacketAliasRedirectDelete()
4853efa11bbSBrian Somers
4863efa11bbSBrian Somers.Ft void
4873efa11bbSBrian Somers.Fn PacketAliasRedirectDelete "struct alias_link *ptr"
4883efa11bbSBrian Somers
4893efa11bbSBrian SomersThis function will delete a specific static redirect
4903efa11bbSBrian Somersrule entered by PacketAliasRedirectPort() or
4913efa11bbSBrian SomersPacketAliasRedirectAddr().  The parameter
4923efa11bbSBrian Somers.Em ptr
4933efa11bbSBrian Somersis the pointer returned by either of the redirection
4943efa11bbSBrian Somersfunctions.  If an invalid pointer is passed to
4953efa11bbSBrian SomersPacketAliasRedirectDelete(), then a program crash
4963efa11bbSBrian Somersor unpredictable operation could result, so it is
4973efa11bbSBrian Somersnecessary to be careful using this function.
498619d1a30SBrian Somers.Ss 4.4 PacketAliasProxyRule()
499619d1a30SBrian Somers
500619d1a30SBrian Somers.Ft int
50142889ed1SBrian Somers.Fn PacketAliasProxyRule "const char *cmd"
502619d1a30SBrian Somers
503619d1a30SBrian SomersThe passed
504619d1a30SBrian Somers.Ar cmd
505619d1a30SBrian Somersstring consists of one or more pairs of words.  The first word in each
506619d1a30SBrian Somerspair is a token and the second is the value that should be applied for
507619d1a30SBrian Somersthat token.  Tokens and their argument types are as follows:
508619d1a30SBrian Somers
509619d1a30SBrian Somers.Bl -tag -offset XXX -width XXX
510619d1a30SBrian Somers.It type encode_ip_hdr|encode_tcp_stream|no_encode
511619d1a30SBrian SomersIn order to support transparent proxying, it is necessary to somehow
512619d1a30SBrian Somerspass the original address and port information into the new destination
513619d1a30SBrian Somersserver.  If
514619d1a30SBrian Somers.Dq encode_ip_hdr
515619d1a30SBrian Somersis specified, the original address and port is passed as an extra IP
516619d1a30SBrian Somersoption.  If
517619d1a30SBrian Somers.Dq encode_tcp_stream
518619d1a30SBrian Somersis specified, the original address and port is passed as the first
519619d1a30SBrian Somerspiece of data in the tcp stream in the format
520619d1a30SBrian Somers.Dq DEST Ar IP port .
521619d1a30SBrian Somers.It port Ar portnum
522619d1a30SBrian SomersOnly packets with the destination port
523619d1a30SBrian Somers.Ar portnum
524619d1a30SBrian Somersare proxied.
525619d1a30SBrian Somers.It server Ar host[:portnum]
526619d1a30SBrian SomersThis specifies the
527619d1a30SBrian Somers.Ar host
528619d1a30SBrian Somersand
529619d1a30SBrian Somers.Ar portnum
530ac8e3334SBrian Somersthat the data is to be redirected to.
531ac8e3334SBrian Somers.Ar host
532ac8e3334SBrian Somersmust be an IP address rather than a DNS host name.  If
533619d1a30SBrian Somers.Ar portnum
534619d1a30SBrian Somersis not specified, the destination port number is not changed.
535619d1a30SBrian Somers.Pp
536619d1a30SBrian SomersThe
537619d1a30SBrian Somers.Ar server
538619d1a30SBrian Somersspecification is mandatory unless the
539619d1a30SBrian Somers.Dq delete
540619d1a30SBrian Somerscommand is being used.
541619d1a30SBrian Somers.It rule Ar index
542619d1a30SBrian SomersNormally, each call to
543619d1a30SBrian Somers.Fn PacketAliasProxyRule
544619d1a30SBrian Somersinserts the next rule at the start of a linear list of rules.  If an
545619d1a30SBrian Somers.Ar index
546619d1a30SBrian Somersis specified, the new rule will be checked after all rules with lower
547619d1a30SBrian Somersindices.  Calls to
548619d1a30SBrian Somers.Fn PacketAliasProxyRule
549619d1a30SBrian Somersthat do not specify a rule are assigned rule 0.
550619d1a30SBrian Somers.It delete Ar index
551619d1a30SBrian SomersThis token and its argument must not be used with any other tokens.  When
552619d1a30SBrian Somersused, all existing rules with the given
553619d1a30SBrian Somers.Ar index
554619d1a30SBrian Somersare deleted.
555619d1a30SBrian Somers.It proto tcp|udp
556619d1a30SBrian SomersIf specified, only packets of the given protocol type are matched.
557619d1a30SBrian Somers.It src Ar IP[/bits]
558619d1a30SBrian SomersIf specified, only packets with a source address matching the given
559619d1a30SBrian Somers.Ar IP
560619d1a30SBrian Somersare matched.  If
561619d1a30SBrian Somers.Ar bits
562619d1a30SBrian Somersis also specified, then the first
563619d1a30SBrian Somers.Ar bits
564619d1a30SBrian Somersbits of
565619d1a30SBrian Somers.Ar IP
566619d1a30SBrian Somersare taken as a network specification, and all IP addresses from that
567619d1a30SBrian Somersnetwork will be matched.
5682f896967SRuslan Ermilov.It dst Ar IP[/bits]
569619d1a30SBrian SomersIf specified, only packets with a destination address matching the given
570619d1a30SBrian Somers.Ar IP
571619d1a30SBrian Somersare matched.  If
572619d1a30SBrian Somers.Ar bits
573619d1a30SBrian Somersis also specified, then the first
574619d1a30SBrian Somers.Ar bits
575619d1a30SBrian Somersbits of
576619d1a30SBrian Somers.Ar IP
577619d1a30SBrian Somersare taken as a network specification, and all IP addresses from that
578619d1a30SBrian Somersnetwork will be matched.
579619d1a30SBrian Somers.El
580619d1a30SBrian Somers
581619d1a30SBrian SomersThis function is usually used to redirect outgoing connections for
582619d1a30SBrian Somersinternal machines that are not permitted certain types of internet
583619d1a30SBrian Somersaccess, or to restrict access to certain external machines.
584164928d3SBrian Somers.Ss 4.5 PacketAliasPptp()
585164928d3SBrian Somers
586164928d3SBrian Somers.Ft extern int
587164928d3SBrian Somers.Fn PacketAliasPptp "struct in_addr addr"
588164928d3SBrian Somers
589164928d3SBrian SomersThis function causes any
590164928d3SBrian Somers.Em G Ns No eneral
591164928d3SBrian Somers.Em R Ns No outing
592164928d3SBrian Somers.Em E Ns No encapsulated
593164928d3SBrian Somers.Pq Dv IPPROTO_GRE
594164928d3SBrian Somerspackets to be aliased using
595164928d3SBrian Somers.Ar addr
596164928d3SBrian Somersrather than the address set via
597164928d3SBrian Somers.Fn PacketAliasSetAddress .
598164928d3SBrian SomersThis allows the uses of the
599164928d3SBrian Somers.Em P Ns No oint
600164928d3SBrian Somersto
601164928d3SBrian Somers.Em P Ns No oint
602164928d3SBrian Somers.Em T Ns No unneling
603164928d3SBrian Somers.Em P Ns No rotocol
604164928d3SBrian Somerson a machine on the internal network.
605164928d3SBrian Somers.Pp
606164928d3SBrian SomersIf the passed address is
607164928d3SBrian Somers.Dv INADDR_NONE
608164928d3SBrian Somers.Pq 255.255.255.255 ,
609164928d3SBrian Somers.Dv PPTP
610164928d3SBrian Somersaliasing is disabled.
6111855100fSAlexey Zelkin.Sh 5. Fragment Handling
6121855100fSAlexey ZelkinThe functions in this section are used to deal with
6131855100fSAlexey Zelkinincoming fragments.
614164928d3SBrian Somers
6151855100fSAlexey ZelkinOutgoing fragments are handled within PacketAliasOut()
6161855100fSAlexey Zelkinby changing the address according to any
6171855100fSAlexey Zelkinapplicable mapping set by PacketAliasRedirectAddress(),
6181855100fSAlexey Zelkinor the default aliasing address set by
6191855100fSAlexey ZelkinPacketAliasSetAddress().
6201855100fSAlexey Zelkin
6211855100fSAlexey ZelkinIncoming fragments are handled in one of two ways.
6221855100fSAlexey ZelkinIf the header of a fragmented IP packet has already
6231855100fSAlexey Zelkinbeen seen, then all subsequent fragments will be
6241855100fSAlexey Zelkinre-mapped in the same manner the header fragment
6251855100fSAlexey Zelkinwas.  Fragments which arrive before the header
6261855100fSAlexey Zelkinare saved and then retrieved once the header fragment
6271855100fSAlexey Zelkinhas been resolved.
6283efa11bbSBrian Somers.Ss 5.1 PacketAliasSaveFragment()
6293efa11bbSBrian Somers
6303efa11bbSBrian Somers.Ft int
6313efa11bbSBrian Somers.Fn PacketAliasSaveFragment "char *ptr"
6323efa11bbSBrian Somers
6333efa11bbSBrian SomersWhen PacketAliasIn() returns
6343efa11bbSBrian SomersPKT_ALIAS_UNRESOLVED_FRAGMENT, this
6353efa11bbSBrian Somersfunction can be used to save the pointer to
6363efa11bbSBrian Somersthe unresolved fragment.
6373efa11bbSBrian Somers
6383efa11bbSBrian SomersIt is implicitly assumed that
6393efa11bbSBrian Somers.Em ptr
6403efa11bbSBrian Somerspoints to a block of memory allocated by
6413efa11bbSBrian Somersmalloc().  If the fragment is never
6423efa11bbSBrian Somersresolved, the packet aliasing engine will
6433efa11bbSBrian Somersautomatically free the memory after a
6443efa11bbSBrian Somerstimeout period. [Eventually this function
6453efa11bbSBrian Somersshould be modified so that a callback
6463efa11bbSBrian Somersfunction for freeing memory is passed as
6473efa11bbSBrian Somersan argument.]
6483efa11bbSBrian Somers
6493efa11bbSBrian SomersThis function returns PKT_ALIAS_OK if it
6503efa11bbSBrian Somerswas successful and PKT_ALIAS_ERROR if there
6513efa11bbSBrian Somerswas an error.
652619d1a30SBrian Somers
653619d1a30SBrian Somers.Ss 5.2 PacketAliasGetFragment()
6543efa11bbSBrian Somers
6553efa11bbSBrian Somers.Ft char *
6563efa11bbSBrian Somers.Fn PacketAliasGetFragment "char *buffer"
6573efa11bbSBrian Somers
6583efa11bbSBrian SomersThis function can be used to retrieve fragment
6593efa11bbSBrian Somerspointers saved by PacketAliasSaveFragment().
6603efa11bbSBrian SomersThe IP header fragment pointed to by
661f1dfc957SBrian Somers.Em buffer
6623efa11bbSBrian Somersis the header fragment indicated when
6633efa11bbSBrian SomersPacketAliasIn() returns PKT_ALIAS_FOUND_HEADER_FRAGMENT.
6643efa11bbSBrian SomersOnce a a fragment pointer is retrieved, it
6653efa11bbSBrian Somersbecomes the calling program's responsibility
6663efa11bbSBrian Somersto free the dynamically allocated memory for
6673efa11bbSBrian Somersthe fragment.
6683efa11bbSBrian Somers
6693efa11bbSBrian SomersPacketAliasGetFragment() can be called
6703efa11bbSBrian Somerssequentially until there are no more fragments
6713efa11bbSBrian Somersavailable, at which time it returns NULL.
6723efa11bbSBrian Somers.Ss 5.3 PacketAliasFragmentIn()
6733efa11bbSBrian Somers
6743efa11bbSBrian Somers.Ft void
6753efa11bbSBrian Somers.Fn PacketAliasFragmentIn "char *header" "char *fragment"
6763efa11bbSBrian Somers
6773efa11bbSBrian SomersWhen a fragment is retrieved with
6783efa11bbSBrian SomersPacketAliasGetFragment(), it can then be
6793efa11bbSBrian Somersde-aliased with a call to PacketAliasFragmentIn().
6803efa11bbSBrian Somers.Em header
6813efa11bbSBrian Somersis the pointer to a header fragment used as a
6823efa11bbSBrian Somerstemplate, and
6833efa11bbSBrian Somers.Em fragment
6843efa11bbSBrian Somersis the pointer to the packet to be de-aliased.
6853efa11bbSBrian Somers.Sh 6. Miscellaneous Functions
6863efa11bbSBrian Somers
6873efa11bbSBrian Somers.Ss 6.1 PacketAliasSetTarget()
6883efa11bbSBrian Somers
6893efa11bbSBrian Somers.Ft void
6903efa11bbSBrian Somers.Fn PacketAliasSetTarget "struct in_addr addr"
6913efa11bbSBrian Somers
6923efa11bbSBrian SomersWhen an incoming packet not associated with
6933efa11bbSBrian Somersany pre-existing aliasing link arrives at the
6943efa11bbSBrian Somershost machine, it will be sent to the address
6953efa11bbSBrian Somersindicated by a call to PacketAliasSetTarget().
6963efa11bbSBrian Somers
6973efa11bbSBrian SomersIf this function is not called, or is called
6983efa11bbSBrian Somerswith a zero address argument, then all new
6993efa11bbSBrian Somersincoming packets go to the address set by
7003efa11bbSBrian SomersPacketAliasSetAddress.
7013efa11bbSBrian Somers.Ss 6.2 PacketAliasCheckNewLink()
7023efa11bbSBrian Somers
7033efa11bbSBrian Somers.Ft int
7043efa11bbSBrian Somers.Fn PacketAliasCheckNewLink "void"
7053efa11bbSBrian Somers
7063efa11bbSBrian SomersThis function returns a non-zero value when
7073efa11bbSBrian Somersa new aliasing link is created.  In circumstances
7083efa11bbSBrian Somerswhere incoming traffic is being sequentially
7093efa11bbSBrian Somerssent to different local servers, this function
7103efa11bbSBrian Somerscan be used to trigger when PacketAliasSetTarget()
7113efa11bbSBrian Somersis called to change the default target address.
7123efa11bbSBrian Somers.Ss 6.3 PacketAliasInternetChecksum()
7133efa11bbSBrian Somers
7143efa11bbSBrian Somers.Ft u_short
715442a25bdSBruce Evans.Fn PacketAliasInternetChecksum "u_short *buffer" "int nbytes"
7163efa11bbSBrian Somers
7173efa11bbSBrian SomersThis is a utility function that does not seem
7183efa11bbSBrian Somersto be available elswhere and is included as a
7193efa11bbSBrian Somersconvenience.  It computes the internet checksum,
7203efa11bbSBrian Somerswhich is used in both IP and protocol-specific
7213efa11bbSBrian Somersheaders (TCP, UDP, ICMP).
7223efa11bbSBrian Somers
7233efa11bbSBrian Somers.Em buffer
7243efa11bbSBrian Somerspoints to the data block to be checksummed, and
7253efa11bbSBrian Somers.Em nbytes
7263efa11bbSBrian Somersis the number of bytes.  The 16-bit checksum
7273efa11bbSBrian Somersfield should be zeroed before computing the checksum.
7283efa11bbSBrian Somers
7293efa11bbSBrian SomersChecksums can also be verified by operating on a block
7303efa11bbSBrian Somersof data including its checksum.  If the checksum is
7313efa11bbSBrian Somersvalid, PacketAliasInternetChecksum() will return zero.
7323efa11bbSBrian Somers.Sh 7. Authors
73359354a4eSBrian SomersCharles Mott (cmott@srv.net), versions 1.0 - 1.8, 2.0 - 2.4.
7343efa11bbSBrian Somers
7358ddc51bcSEivind EklundEivind Eklund (eivind@freebsd.org), versions 1.8b, 1.9 and
7368ddc51bcSEivind Eklund2.5.  Added IRC DCC support as well as contributing a number of
7378ddc51bcSEivind Eklundarchitectural improvements; added the firewall bypass
7388ddc51bcSEivind Eklundfor FTP/IRC DCC.
7393efa11bbSBrian Somers.Sh 8. Acknowledgments
7403efa11bbSBrian Somers
7413efa11bbSBrian SomersListed below, in approximate chronological
7423efa11bbSBrian Somersorder, are individuals who have provided
7433efa11bbSBrian Somersvaluable comments and/or debugging assistance.
7443efa11bbSBrian Somers
7453efa11bbSBrian Somers.Bl -inset -compact -offset left
7463efa11bbSBrian Somers.It Gary Roberts
7473efa11bbSBrian Somers.It Tom Torrance
7483efa11bbSBrian Somers.It Reto Burkhalter
7493efa11bbSBrian Somers.It Martin Renters
7503efa11bbSBrian Somers.It Brian Somers
7513efa11bbSBrian Somers.It Paul Traina
7523efa11bbSBrian Somers.It Ari Suutari
7533efa11bbSBrian Somers.It Dave Remien
7543efa11bbSBrian Somers.It J. Fortes
7553efa11bbSBrian Somers.It Andrzej Bialeki
7564fe071a9SBrian Somers.It Gordon Burditt
7573efa11bbSBrian Somers.El
7583efa11bbSBrian Somers.Sh Appendix: Conceptual Background
7593efa11bbSBrian SomersThis appendix is intended for those who
7603efa11bbSBrian Somersare planning to modify the source code or want
7613efa11bbSBrian Somersto create somewhat esoteric applications using
7623efa11bbSBrian Somersthe packet aliasing functions.
7633efa11bbSBrian Somers
7643efa11bbSBrian SomersThe conceptual framework under which the
7653efa11bbSBrian Somerspacket aliasing engine operates is described here.
7663efa11bbSBrian SomersCentral to the discussion is the idea of an
7673efa11bbSBrian Somers"aliasing link" which  describes the relationship
7683efa11bbSBrian Somersfor a given packet transaction between the local
7693efa11bbSBrian Somersmachine, aliased identity and remote machine.  It
7703efa11bbSBrian Somersis discussed how such links come into existence
7713efa11bbSBrian Somersand are destroyed.
7723efa11bbSBrian Somers.Ss A.1 Aliasing Links
7733efa11bbSBrian SomersThere is a notion of an "aliasing link",
7743efa11bbSBrian Somerswhich is 7-tuple describing a specific
7753efa11bbSBrian Somerstranslation:
7763efa11bbSBrian Somers.Bd -literal -offset indent
7773efa11bbSBrian Somers(local addr, local port, alias addr, alias port,
7783efa11bbSBrian Somers remote addr, remote port, protocol)
7793efa11bbSBrian Somers.Ed
7803efa11bbSBrian Somers
7813efa11bbSBrian SomersOutgoing packets have the local address and
7823efa11bbSBrian Somersport number replaced with the alias address
7833efa11bbSBrian Somersand port number.  Incoming packets undergo the
7843efa11bbSBrian Somersreverse process.  The packet aliasing engine
7853efa11bbSBrian Somersattempts to match packets against an internal
7863efa11bbSBrian Somerstable of aliasing links to determine how to
7873efa11bbSBrian Somersmodify a given IP packet.  Both the IP
7883efa11bbSBrian Somersheader and protocol dependent headers are
7893efa11bbSBrian Somersmodified as necessary.  Aliasing links are
7903efa11bbSBrian Somerscreated and deleted as necessary according
7913efa11bbSBrian Somersto network traffic.
7923efa11bbSBrian Somers
7933efa11bbSBrian SomersProtocols can be TCP, UDP or even ICMP in
7943efa11bbSBrian Somerscertain circumstances.  (Some types of ICMP
7953efa11bbSBrian Somerspackets can be aliased according to sequence
7963efa11bbSBrian Somersor id number which acts as an equivalent port
7973efa11bbSBrian Somersnumber for identifying how individual packets
7983efa11bbSBrian Somersshould be handled.)
7993efa11bbSBrian Somers
8003efa11bbSBrian SomersEach aliasing link must have a unique
8019c727d2cSJoseph Koshycombination of the following five quantities:
8023efa11bbSBrian Somersalias address/port, remote address/port
8033efa11bbSBrian Somersand protocol.  This ensures that several
8043efa11bbSBrian Somersmachines on a local network can share the
8053efa11bbSBrian Somerssame aliased IP address.  In cases where
8063efa11bbSBrian Somersconflicts might arise, the aliasing port
8073efa11bbSBrian Somersis chosen so that uniqueness is maintained.
8083efa11bbSBrian Somers.Ss A.2 Static and Dynamic Links
8093efa11bbSBrian SomersAliasing links can either be static or dynamic.
8103efa11bbSBrian SomersStatic links persist indefinitely and represent
8113efa11bbSBrian Somersfixed rules for translating IP packets.  Dynamic
8123efa11bbSBrian Somerslinks come into existence for a specific TCP
8133efa11bbSBrian Somersconnection or UDP transaction or ICMP echo
8143efa11bbSBrian Somerssequence.  For the case of TCP, the connection
8153efa11bbSBrian Somerscan be monitored to see when the associated
8163efa11bbSBrian Somersaliasing link should be deleted.  Aliasing links
8173efa11bbSBrian Somersfor UDP transactions (and ICMP echo and timestamp
8189c727d2cSJoseph Koshyrequests) work on a simple timeout rule.  When
8193efa11bbSBrian Somersno activity is observed on a dynamic link for
8203efa11bbSBrian Somersa certain amount of time it is automatically
8213efa11bbSBrian Somersdeleted.  Timeout rules also apply to TCP
8223efa11bbSBrian Somersconnections which do not open or close
8233efa11bbSBrian Somersproperly.
8243efa11bbSBrian Somers.Ss A.3 Partially Specified Aliasing Links
8253efa11bbSBrian SomersAliasing links can be partially specified,
8263efa11bbSBrian Somersmeaning that the remote address and/or remote
8279c727d2cSJoseph Koshyports are unknown.  In this case, when a packet
8283efa11bbSBrian Somersmatching the incomplete specification is found,
8293efa11bbSBrian Somersa fully specified dynamic link is created.  If
8303efa11bbSBrian Somersthe original partially specified link is dynamic,
8313efa11bbSBrian Somersit will be deleted after the fully specified link
8323efa11bbSBrian Somersis created, otherwise it will persist.
8333efa11bbSBrian Somers
8343efa11bbSBrian SomersFor instance, a partially specified link might
8353efa11bbSBrian Somersbe
8363efa11bbSBrian Somers.Bd -literal -offset indent
8373efa11bbSBrian Somers(192.168.0.4, 23, 204.228.203.215, 8066, 0, 0, tcp)
8383efa11bbSBrian Somers.Ed
8393efa11bbSBrian Somers
8403efa11bbSBrian SomersThe zeros denote unspecified components for
8413efa11bbSBrian Somersthe remote address and port.  If this link were
8423efa11bbSBrian Somersstatic it would have the effect of redirecting
8433efa11bbSBrian Somersall incoming traffic from port 8066 of
8443efa11bbSBrian Somers204.228.203.215 to port 23 (telnet) of machine
8453efa11bbSBrian Somers192.168.0.4 on the local network.  Each
8463efa11bbSBrian Somersindividual telnet connection would initiate
8473efa11bbSBrian Somersthe creation of a distinct dynamic link.
8483efa11bbSBrian Somers.Ss A.4 Dynamic Link Creation
8493efa11bbSBrian SomersIn addition to aliasing links, there are
8503efa11bbSBrian Somersalso address mappings that can be stored
8513efa11bbSBrian Somerswithin the internal data table of the packet
8523efa11bbSBrian Somersaliasing mechanism.
8533efa11bbSBrian Somers.Bd -literal -offset indent
8543efa11bbSBrian Somers(local addr, alias addr)
8553efa11bbSBrian Somers.Ed
8563efa11bbSBrian Somers
8573efa11bbSBrian SomersAddress mappings are searched when creating
8583efa11bbSBrian Somersnew dynamic links.
8593efa11bbSBrian Somers
8603efa11bbSBrian SomersAll outgoing packets from the local network
8613efa11bbSBrian Somersautomatically create a dynamic link if
8623efa11bbSBrian Somersthey do not match an already existing fully
8633efa11bbSBrian Somersspecified link.  If an address mapping exists
8643efa11bbSBrian Somersfor the the outgoing packet, this determines
8653efa11bbSBrian Somersthe alias address to be used.  If no mapping
8663efa11bbSBrian Somersexists, then a default address, usually the
8673efa11bbSBrian Somersaddress of the packet aliasing host, is used.
8683efa11bbSBrian SomersIf necessary, this default address can be
8699c727d2cSJoseph Koshychanged as often as each individual packet
8703efa11bbSBrian Somersarrives.
8713efa11bbSBrian Somers
8723efa11bbSBrian SomersThe aliasing port number is determined
8733efa11bbSBrian Somerssuch that the new dynamic link does not
8743efa11bbSBrian Somersconflict with any existing links.  In the
8753efa11bbSBrian Somersdefault operating mode, the packet aliasing
8763efa11bbSBrian Somersengine attempts to set the aliasing port
8773efa11bbSBrian Somersequal to the local port number.  If this
8783efa11bbSBrian Somersresults in a conflict, then port numbers
8793efa11bbSBrian Somersare randomly chosen until a unique aliasing
8803efa11bbSBrian Somerslink can be established.  In an alternate
8813efa11bbSBrian Somersoperating mode, the first choice of an
8823efa11bbSBrian Somersaliasing port is also random and unrelated
8833efa11bbSBrian Somersto the local port number.
8843efa11bbSBrian Somers
885