libalias.3 revision 27864
1.Dd July, 1997 2.Dt "libalias" 3 3.Os 4.Sh NAME 5.Nm "libalias" 6Packet Aliasing Library. A collection of 7functions for aliasing and de-aliasing 8of IP packets, intended for masquerading and 9network address translation (NAT). 10 11.Sh SYNOPSIS 12.Fd #include <netinet/in.h> 13.Fd #include <alias.h> 14 15Function prototypes are given in the main body 16of the text. 17 18.Sh CONTENTS 19.Bd -literal -offset left 201. Introduction 212. Initialization and Control 22 2.1 PacketAliasInit() 23 2.2 PacketAliasSetAddress() 24 2.3 PacketAliasSetMode() 253. Packet Handling 26 3.1 PacketAliasOut() 27 3.2 PacketAliasIn() 284. Port and Address Redirection 29 4.1 PacketAliasRedirectPort() 30 4.2 PacketAliasRedirectAddr() 31 4.3 PacketAliasRedirectDelete() 325. Fragment Handling 33 5.1 PacketAliasSaveFragment() 34 5.2 PacketAliasGetFragment() 35 5.3 PacketAliasFragmentIn() 366. Miscellaneous Functions 37 6.1 PacketAliasSetTarget() 38 6.2 PacketAliasCheckNewLink() 39 6.3 PacketAliasInternetChecksum() 407. Authors 418. Acknowledgments 42 43Appendix A: Conceptual Background 44 A.1 Aliasing Links 45 A.2 Static and Dynamic Links 46 A.3 Partially Specified Links 47 A.4 Dynamic Link Creation 48.Ed 49 50.Sh 1. Introduction 51This library is a moderately portable 52set of functions designed to assist 53in the process of IP masquerading and 54network address translation. Outgoing 55packets from a local network with 56unregistered IP addresses can be aliased 57to appear as if they came from an 58accessible IP address. Incoming packets 59are then de-aliased so that they are sent 60to the correct machine on the local network. 61 62A certain amount of flexibility is built 63into the packet aliasing engine. In 64the simplest mode of operation, a 65many-to-one address mapping takes place 66between local network and the packet 67aliasing host. This is known as IP 68masquerading. In addition, one-to-one 69mappings between local and public addresses 70can also be implemented, which is known as 71static NAT. In between these extremes, 72different groups of private addresses 73can be linked to different public addresses, 74comprising several distinct many-to-one 75mappings. Also, a given public address 76and port can be staticly redirected to 77a private address/port. 78 79The packet aliasing engine was designed 80to operate in user space outside of the 81kernel, without any access to private 82kernel data structure, but the source code 83can also be ported to a kernel environment. 84 85.Sh 2. Initialization and Control 86Two specific functions, PacketAliasInit() 87and PacketAliasSetAddress(), must always be 88called before any packet handling may be 89performed. In addition, the operating mode 90of the packet aliasing engine can be customized 91by calling PacketAliasSetMode(). 92.Ss 2.1 PacketAliasInit() 93 94.Ft void 95.Fn PacketAliasInit "void" 96 97This function has no argument or return 98value and is used to initialize internal 99data structures. The following mode bits 100are always set after calling 101PacketAliasInit(). See section 2.3 for 102the meaning of these mode bits. 103.Bd -literal -offset indent 104 PKT_ALIAS_USE_SAME_PORTS 105 PKT_ALIAS_USE_SOCKETS 106 PKT_ALIAS_RESET_ON_ADDR_CHANGE 107 108.Ed 109This function will always return the packet 110aliasing engine to the same initial state. 111PacketAliasSetAddress() must be called afterwards, 112and any desired changes from the default mode 113bits listed above require a call to 114PacketAliasSetMode(). 115 116It is mandatory that this function be called 117at the beginning of a program prior to any 118packet handling. 119.Ss 2.2 PacketAliasSetAddress() 120 121.Ft void 122.Fn PacketAliasSetAddress "struct in_addr addr" 123 124This function sets the source address to which 125outgoing packets from the local area network 126are aliased. All outgoing packets are remapped 127to this address unless overridden by a static 128address mapping established by 129PacketAliasRedirectAddr(). 130 131If the PKT_ALIAS_RESET_ON_ADDR_CHANGE mode bit 132is set (the default mode of operation), then 133the internal aliasing link tables will be reset 134any time the aliasing address changes, as if 135PacketAliasReset() were called. This is useful 136for interfaces such as ppp where the IP 137address may or may not change on successive 138dial-up attempts. 139 140If the PKT_ALIAS_RESET_ON_ADDR_CHANGE mode bit 141is set to zero, this function can also be used to 142dynamically change the aliasing address on a 143packet to packet basis (it is a low overhead 144call). 145 146It is mandatory that this function be called 147prior to any packet handling. 148.Ss 2.3 PacketAliasSetMode() 149 150.Ft void 151.Fn PacketAliasSetMode "int mode" "int mask" 152 153This function sets or clears mode bits 154according to the value of 155.Em mode . 156Only bits marked in 157.Em mask 158are affected. The following mode bits are 159defined in alias.h: 160.Bl -hang -offset left 161.It PKT_ALIAS_LOG. 162Enables logging /var/log/alias.log. The log file 163shows total numbers of links (icmp, tcp, udp) each 164time an aliasing link is created or deleted. Mainly 165useful for debugging when the log file is viewed 166continuously with "tail -f". 167.It PKT_ALIAS_DENY_INCOMING. 168If this mode bit is set, all incoming packets 169associated with new TCP connections or new 170UDP transactions will be marked for being 171ignored (PacketAliasIn() return code 172PKT_ALIAS_IGNORED) by the calling program. 173Response packets to connections or transactions 174initiated from the packet aliasing host or 175local network will be unaffected. This mode 176bit is useful for implementing a one-way firewall. 177.It PKT_ALIAS_SAME_PORTS. 178If this mode bit is set, the packet aliasing 179engine will attempt to leave the alias port 180numbers unchanged from the actual local port 181number. This can be done as long as the 182quintuple (proto, alias addr, alias port, 183remote addr, remote port) is unique. If a 184conflict exists, an new aliasing port number is 185chosen even if this mode bit is set. 186.It PKT_ALIAS_USE_SOCKETS. 187This bit should be set when the the packet 188aliasing host originates network traffic as 189well as forwards it. When the packet aliasing 190host is waiting for a connection from an 191unknown host address or unknown port number 192(e.g. an FTP data connection), this mode bit 193specifies that a socket be allocated as a place 194holder to prevent port conflicts. Once a 195connection is extablished, usually within a 196minute or so, the socket is closed. 197.It PKT_ALIAS_UNREGISTERED_ONLY. 198If this mode bit is set, traffic on the 199local network which does not originate from 200unregistered address spaces will be ignored. 201Standard Class A, B and C unregistered addresses 202are: 203.Bd -literal -offset indent 204 10.0.0.0 -> 10.255.255.255 (Class A subnet) 205 172.16.0.0 -> 172.31.255.255 (Class B subnets) 206 192.168.0.0 -> 192.168.255.255 (Class C subnets) 207 208.Ed 209This option is useful in the case that 210packet aliasing host has both registered and 211unregistered subnets on different interfaces. 212The registered subnet is fully accessible to 213the outside world, so traffic from it doesn't 214need to be passed through the packet aliasing 215engine. 216.It PKT_ALIAS_RESET_ON_ADDR_CHANGE. 217When this mode bit is set and 218PacketAliasSetAddress() is called to change 219the aliasing address, the internal link table 220of the packet aliasing engine will be cleared. 221This operating mode is useful for ppp links 222where the interface address can sometimes 223change or remain the same between dial-ups. 224If this mode bit is not set, it the link table 225will never be reset in the event of an 226address change. 227.El 228.Sh 3. Packet Handling 229The packet handling functions are used to 230modify incoming (remote->local) and outgoing 231(local->remote) packets. The calling program 232is responsible for receiving and sending 233packets via network interfaces. 234 235Along with PacketAliasInit() and PacketAliasSetAddress(), 236the two packet handling functions, PacketAliasIn() 237and PacketAliasOut(), comprise minimal set of functions 238needed for a basic IP masquerading implementation. 239.Ss 3.1 PacketAliasIn() 240 241.Ft int 242.Fn PacketAliasIn "char *buffer" "int maxpacketsize" 243 244An incoming packet coming from a remote machine to 245the local network is de-aliased by this function. 246The IP packet is pointed to by 247.Em buffer , 248and 249.Em maxpacketsize 250indicates the size of the data structure containing 251the packet and should be at least as large as the 252actual packet size. 253 254Return codes: 255.Bl -hang -offset left 256.It PKT_ALIAS_ERROR. 257An internal error within the packet aliasing 258engine occured. 259.It PKT_ALIAS_OK. 260The packet aliasing process was successful. 261.It PKT_ALIAS_IGNORED. 262The packet was ignored and not de-aliased. 263This can happen if the protocal is unrecognized, 264possibly an ICMP message type is not handled or 265if incoming packets for new connections are being 266ignored (see PKT_ALIAS_DENY_INCOMING in section 2672.2). 268.It PKT_ALIAS_UNRESOLVED_FRAGMENT. 269This is returned when a fragment cannot be 270resolved because the header fragment has not 271been sent yet. In this situation, fragments 272must be saved with PacketAliasSaveFragment() 273until a header fragment is found. 274.It PKT_ALIAS_FOUND_HEADER_FRAGMENT. 275The packet aliasing process was successful, 276and a header fragment was found. This is a 277signal to retrieve any unresolved fragments 278with PacketAliasGetFragment() and de-alias 279them with PacketAliasFragmentIn(). 280.El 281.Ss 3.2 PacketAliasOut() 282 283.Ft int 284.Fn PacketAliasIn "char *buffer" "int maxpacketsize" 285 286An outgoing packet coming from the local network 287to a remote machine is aliased by this function. 288The IP packet is pointed to by 289.Em buffer r, 290and 291.Em maxpacketsize 292indicates the maximum packet size permissable 293should the packet length be changed. IP encoding 294protocols place addresss and port information in 295the encapsulated data stream which have to be 296modified and can account for changes in packet 297length. Well known examples of such protocols 298are FTP and IRC. 299 300Return codes: 301.Bl -hang -offset left 302.It PKT_ALIAS_ERROR. 303An internal error within the packet aliasing 304engine occured. 305.It PKT_ALIAS_OK. 306The packet aliasing process was successful. 307.It PKT_ALIAS_IGNORED. 308The packet was ignored and not de-aliased. 309This can happen if the protocal is unrecognized, 310or possibly an ICMP message type is not handled. 311.El 312 313.Sh 4. Port and Address Redirection 314The functions described in this section allow machines 315on the local network to be accessible in some degree 316to new incoming connections from the external network. 317Individual ports can be re-mapped or static network 318address translations can be designated. 319.Ss 4.1 PacketAliasRedirectPort() 320 321.Ft struct alias_link * 322.Fo PacketAliasRedirectPort 323.Fa "struct in_addr local_addr" 324.Fa "u_short local_port" 325.Fa "struct in_addr remote_addr" 326.Fa "u_short remote_port" 327.Fa "struct in_addr alias_addr" 328.Fa "u_short alias_port" 329.Fa "u_char proto" 330.Fc 331 332This function specifies that traffic from a 333given remote address/port to an alias address/port 334be redirected to a specified local address/port. 335The paramater 336.Em proto 337can be either IPPROTO_TCP or IPPROTO_UDP, as 338defined in <netinet/in.h>. 339 340If 341.Em local_addr 342or 343.Em alias_addr 344is zero, this indicates that the packet aliasing 345address as established by PacketAliasSetAddress() 346is to be used. Even if PacketAliasAddress() is 347called to change the address after PacketAliasRedirectPort() 348is called, a zero reference will track this change. 349 350If 351.Em remote_addr 352is zero, this indicates to redirect packets from 353any remote address. Likewise, if 354.Em remote_port 355is zero, this indicates to redirect packets originating 356from any remote port number. Almost always, the remote 357port specification will be zero, but non-zero remote 358addresses can be sometimes be useful for firewalling. 359If two calls to PacketAliasRedirectPort() overlap in 360their address/port specifications, then the most recent 361call will have precedence. 362 363This function returns a pointer which can subsequently 364be used by PacketAliasRedirectDelete(). If NULL is 365returned, then the function call did not complete 366successfully. 367 368All port numbers are in network address byte order, 369so it is necessary to use htons() to convert these 370parameters from internally readable numbers to 371network byte order. Addresses are also in network 372byte order, which is implicit in the use of the 373.Em struct in_addr 374data type. 375.Ss 4.2 PacketAliasRedirectAddr() 376 377.Ft struct alias_link * 378.Fo PacketAliasRedirectAddress 379.Fa "struct in_addr local_addr" 380.Fa "struct in_addr alias_addr" 381.Fc 382 383This function desgnates that all incoming 384traffic to 385.Em alias_addr 386be redirected to 387.Em local_addr. 388Similarly, all outgoing traffic from 389.Em local_addr 390is aliased to 391.Em alias_addr . 392 393If 394.Em local_addr 395or 396.Em alias_addr 397is zero, this indicates that the packet aliasing 398address as established by PacketAliasSetAddress() 399is to be used. Even if PacketAliasAddress() is 400called to change the address after PacketAliasRedirectAddr() 401is called, a zero reference will track this change. 402 403If subsequent calls to PacketAliasRedirectAddr() 404use the same aliasing address, all new incoming 405traffic to this aliasing address will be redirected 406to the local address made in the last function call, 407but new traffic all of the local machines designated 408in the several function calls will be aliased to 409the same address. Consider the following example: 410.Bd -literal -offset left 411 PacketAliasRedirectAddr(inet_aton("192.168.0.2"), 412 inet_aton("141.221.254.101")); 413 PacketAliasRedirectAddr(inet_aton("192.168.0.3"), 414 inet_aton("141.221.254.101")); 415 PacketAliasRedirectAddr(inet_aton("192.168.0.4"), 416 inet_aton("141.221.254.101")); 417.Ed 418 419Any outgoing connections such as telnet or ftp 420from 192.168.0.2, 102.168.0.3, 192.168.0.4 will 421appear to come from 141.221.254.101. Any incoming 422connections to 141.221.254.101 will be directed 423to 192.168.0.4. 424 425Any calls to PacketAliasRedirectPort() will 426have precedence over address mappings designated 427by PacketAliasRedirectAddr(). 428 429This function returns a pointer which can subsequently 430be used by PacketAliasRedirectDelete(). If NULL is 431returned, then the function call did not complete 432successfully. 433.Ss 4.3 PacketAliasRedirectDelete() 434 435.Ft void 436.Fn PacketAliasRedirectDelete "struct alias_link *ptr" 437 438This function will delete a specific static redirect 439rule entered by PacketAliasRedirectPort() or 440PacketAliasRedirectAddr(). The parameter 441.Em ptr 442is the pointer returned by either of the redirection 443functions. If an invalid pointer is passed to 444PacketAliasRedirectDelete(), then a program crash 445or unpredictable operation could result, so it is 446necessary to be careful using this function. 447 448.Sh 5. Fragment Handling 449The functions in this section are used to deal with 450incoming fragments. 451 452Outgoing fragments are handled within PacketAliasOut() 453by changing the address according to any 454applicable mapping set by PacketAliasRedirectAddress(), 455or the default aliasing address set by 456PacketAliasSetAddress(). 457 458Incoming fragments are handled in one of two ways. 459If the header of a fragmented IP packet has already 460been seen, then all subsequent fragments will be 461re-mapped in the same manner the header fragment 462was. Fragments which arrive before the header 463are saved and then retrieved once the header fragment 464has been resolved. 465.Ss 5.1 PacketAliasSaveFragment() 466 467.Ft int 468.Fn PacketAliasSaveFragment "char *ptr" 469 470When PacketAliasIn() returns 471PKT_ALIAS_UNRESOLVED_FRAGMENT, this 472function can be used to save the pointer to 473the unresolved fragment. 474 475It is implicitly assumed that 476.Em ptr 477points to a block of memory allocated by 478malloc(). If the fragment is never 479resolved, the packet aliasing engine will 480automatically free the memory after a 481timeout period. [Eventually this function 482should be modified so that a callback 483function for freeing memory is passed as 484an argument.] 485 486This function returns PKT_ALIAS_OK if it 487was successful and PKT_ALIAS_ERROR if there 488was an error. 489.Ss 5.2 PacketAliasGetNextFragment() 490 491.Ft char * 492.Fn PacketAliasGetFragment "char *buffer" 493 494This function can be used to retrieve fragment 495pointers saved by PacketAliasSaveFragment(). 496The IP header fragment pointed to by 497Em buffer 498is the header fragment indicated when 499PacketAliasIn() returns PKT_ALIAS_FOUND_HEADER_FRAGMENT. 500Once a a fragment pointer is retrieved, it 501becomes the calling program's responsibility 502to free the dynamically allocated memory for 503the fragment. 504 505PacketAliasGetFragment() can be called 506sequentially until there are no more fragments 507available, at which time it returns NULL. 508.Ss 5.3 PacketAliasFragmentIn() 509 510.Ft void 511.Fn PacketAliasFragmentIn "char *header" "char *fragment" 512 513When a fragment is retrieved with 514PacketAliasGetFragment(), it can then be 515de-aliased with a call to PacketAliasFragmentIn(). 516.Em header 517is the pointer to a header fragment used as a 518template, and 519.Em fragment 520is the pointer to the packet to be de-aliased. 521 522.Sh 6. Miscellaneous Functions 523 524.Ss 6.1 PacketAliasSetTarget() 525 526.Ft void 527.Fn PacketAliasSetTarget "struct in_addr addr" 528 529When an incoming packet not associated with 530any pre-existing aliasing link arrives at the 531host machine, it will be sent to the address 532indicated by a call to PacketAliasSetTarget(). 533 534If this function is not called, or is called 535with a zero address argument, then all new 536incoming packets go to the address set by 537PacketAliasSetAddress. 538.Ss 6.2 PacketAliasCheckNewLink() 539 540.Ft int 541.Fn PacketAliasCheckNewLink "void" 542 543This function returns a non-zero value when 544a new aliasing link is created. In circumstances 545where incoming traffic is being sequentially 546sent to different local servers, this function 547can be used to trigger when PacketAliasSetTarget() 548is called to change the default target address. 549.Ss 6.3 PacketAliasInternetChecksum() 550 551.Ft u_short 552.Fn PacketAliasInternetChecksum "char *buffer" "int nbytes" 553 554This is a utility function that does not seem 555to be available elswhere and is included as a 556convenience. It computes the internet checksum, 557which is used in both IP and protocol-specific 558headers (TCP, UDP, ICMP). 559 560.Em buffer 561points to the data block to be checksummed, and 562.Em nbytes 563is the number of bytes. The 16-bit checksum 564field should be zeroed before computing the checksum. 565 566Checksums can also be verified by operating on a block 567of data including its checksum. If the checksum is 568valid, PacketAliasInternetChecksum() will return zero. 569 570.Sh 7. Authors 571Charles Mott (cmott@srv.net), versions 1.0 - 1.8, 2.0 - 2.2. 572 573Eivind Eiklund (eivind@freebsd.org), versions 1.8b and 1.9. 574Added IRC support as well as contributing a number of 575architectural improvements. 576 577.Sh 8. Acknowledgments 578 579Listed below, in approximate chronological 580order, are individuals who have provided 581valuable comments and/or debugging assistance. 582 583.Bl -inset -compact -offset left 584.It Gary Roberts 585.It Tom Torrance 586.It Reto Burkhalter 587.It Martin Renters 588.It Brian Somers 589.It Paul Traina 590.It Ari Suutari 591.It Dave Remien 592.It J. Fortes 593.It Andrzej Bialeki 594.El 595 596.Sh Appendix: Conceptual Background 597This appendix is intended for those who 598are planning to modify the source code or want 599to create somewhat esoteric applications using 600the packet aliasing functions. 601 602The conceptual framework under which the 603packet aliasing engine operates is described here. 604Central to the discussion is the idea of an 605"aliasing link" which describes the relationship 606for a given packet transaction between the local 607machine, aliased identity and remote machine. It 608is discussed how such links come into existence 609and are destroyed. 610.Ss A.1 Aliasing Links 611There is a notion of an "aliasing link", 612which is 7-tuple describing a specific 613translation: 614.Bd -literal -offset indent 615(local addr, local port, alias addr, alias port, 616 remote addr, remote port, protocol) 617.Ed 618 619Outgoing packets have the local address and 620port number replaced with the alias address 621and port number. Incoming packets undergo the 622reverse process. The packet aliasing engine 623attempts to match packets against an internal 624table of aliasing links to determine how to 625modify a given IP packet. Both the IP 626header and protocol dependent headers are 627modified as necessary. Aliasing links are 628created and deleted as necessary according 629to network traffic. 630 631Protocols can be TCP, UDP or even ICMP in 632certain circumstances. (Some types of ICMP 633packets can be aliased according to sequence 634or id number which acts as an equivalent port 635number for identifying how individual packets 636should be handled.) 637 638Each aliasing link must have a unique 639combination of the following five quanties: 640alias address/port, remote address/port 641and protocol. This ensures that several 642machines on a local network can share the 643same aliased IP address. In cases where 644conflicts might arise, the aliasing port 645is chosen so that uniqueness is maintained. 646.Ss A.2 Static and Dynamic Links 647Aliasing links can either be static or dynamic. 648Static links persist indefinitely and represent 649fixed rules for translating IP packets. Dynamic 650links come into existence for a specific TCP 651connection or UDP transaction or ICMP echo 652sequence. For the case of TCP, the connection 653can be monitored to see when the associated 654aliasing link should be deleted. Aliasing links 655for UDP transactions (and ICMP echo and timestamp 656equests) work on a simple timeout rule. When 657no activity is observed on a dynamic link for 658a certain amount of time it is automatically 659deleted. Timeout rules also apply to TCP 660connections which do not open or close 661properly. 662.Ss A.3 Partially Specified Aliasing Links 663Aliasing links can be partially specified, 664meaning that the remote address and/or remote 665ports are unkown. In this case, when a packet 666matching the incomplete specification is found, 667a fully specified dynamic link is created. If 668the original partially specified link is dynamic, 669it will be deleted after the fully specified link 670is created, otherwise it will persist. 671 672For instance, a partially specified link might 673be 674.Bd -literal -offset indent 675(192.168.0.4, 23, 204.228.203.215, 8066, 0, 0, tcp) 676.Ed 677 678The zeros denote unspecified components for 679the remote address and port. If this link were 680static it would have the effect of redirecting 681all incoming traffic from port 8066 of 682204.228.203.215 to port 23 (telnet) of machine 683192.168.0.4 on the local network. Each 684individual telnet connection would initiate 685the creation of a distinct dynamic link. 686.Ss A.4 Dynamic Link Creation 687In addition to aliasing links, there are 688also address mappings that can be stored 689within the internal data table of the packet 690aliasing mechanism. 691.Bd -literal -offset indent 692(local addr, alias addr) 693.Ed 694 695Address mappings are searched when creating 696new dynamic links. 697 698All outgoing packets from the local network 699automatically create a dynamic link if 700they do not match an already existing fully 701specified link. If an address mapping exists 702for the the outgoing packet, this determines 703the alias address to be used. If no mapping 704exists, then a default address, usually the 705address of the packet aliasing host, is used. 706If necessary, this default address can be 707changed as often as each indvidual packet 708arrives. 709 710The aliasing port number is determined 711such that the new dynamic link does not 712conflict with any existing links. In the 713default operating mode, the packet aliasing 714engine attempts to set the aliasing port 715equal to the local port number. If this 716results in a conflict, then port numbers 717are randomly chosen until a unique aliasing 718link can be established. In an alternate 719operating mode, the first choice of an 720aliasing port is also random and unrelated 721to the local port number. 722 723