Differential D27882 Diff 82586 sys/netinet/libalias/libalias.3

Changeset View

Standalone View

sys/netinet/libalias/libalias.3

	Show All 19 Lines
	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)			.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT			.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY			.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF			.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	.\" SUCH DAMAGE.			.\" SUCH DAMAGE.
	.\"			.\"
	.\" $FreeBSD$			.\" $FreeBSD$
	.\"			.\"
	.Dd December 25, 2013			.Dd January 1, 2020
	.Dt LIBALIAS 3			.Dt LIBALIAS 3
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm libalias			.Nm libalias
	.Nd packet aliasing library for masquerading and network address translation			.Nd packet aliasing library for masquerading and network address translation
	.Sh SYNOPSIS			.Sh SYNOPSIS
	.In sys/types.h			.In sys/types.h
	.In netinet/in.h			.In netinet/in.h
	▲ Show 20 Lines • Show All 269 Lines • ▼ Show 20 Lines
	the two packet handling functions,			the two packet handling functions,
	.Fn LibAliasIn			.Fn LibAliasIn
	and			and
	.Fn LibAliasOut ,			.Fn LibAliasOut ,
	comprise the minimal set of functions needed for a basic IP masquerading			comprise the minimal set of functions needed for a basic IP masquerading
	implementation.			implementation.
	.Pp			.Pp
	.Ft int			.Ft int
	.Fn LibAliasIn "struct libalias " "char buffer" "int maxpacketsize"			.Fn LibAliasIn "struct libalias " "void buffer" "int maxpacketsize"
	.Bd -ragged -offset indent			.Bd -ragged -offset indent
	An incoming packet coming from a remote machine to the local network is			An incoming packet coming from a remote machine to the local network is
	de-aliased by this function.			de-aliased by this function.
	The IP packet is pointed to by			The IP packet is pointed to by
	.Fa buffer ,			.Fa buffer ,
	and			and
	.Fa maxpacketsize			.Fa maxpacketsize
	indicates the size of the data structure containing the packet and should			indicates the size of the data structure containing the packet and should
	Show All 24 Lines
	and de-alias them with			and de-alias them with
	.Fn LibAliasFragmentIn .			.Fn LibAliasFragmentIn .
	.It Dv PKT_ALIAS_ERROR			.It Dv PKT_ALIAS_ERROR
	An internal error within the packet aliasing engine occurred.			An internal error within the packet aliasing engine occurred.
	.El			.El
	.Ed			.Ed
	.Pp			.Pp
	.Ft int			.Ft int
	.Fn LibAliasOut "struct libalias " "char buffer" "int maxpacketsize"			.Fn LibAliasOut "struct libalias " "void buffer" "int maxpacketsize"
	.Bd -ragged -offset indent			.Bd -ragged -offset indent
	An outgoing packet coming from the local network to a remote machine is			An outgoing packet coming from the local network to a remote machine is
	aliased by this function.			aliased by this function.
	The IP packet is pointed to by			The IP packet is pointed to by
	.Fa buffer ,			.Fa buffer ,
	and			and
	.Fa maxpacketsize			.Fa maxpacketsize
	indicates the maximum packet size permissible should the packet length be			indicates the maximum packet size permissible should the packet length be
	▲ Show 20 Lines • Show All 401 Lines • ▼ Show 20 Lines
	Incoming fragments are handled in one of two ways.			Incoming fragments are handled in one of two ways.
	If the header of a fragmented IP packet has already been seen, then all			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			subsequent fragments will be re-mapped in the same manner the header
	fragment was.			fragment was.
	Fragments which arrive before the header are saved and then retrieved			Fragments which arrive before the header are saved and then retrieved
	once the header fragment has been resolved.			once the header fragment has been resolved.
	.Pp			.Pp
	.Ft int			.Ft int
	.Fn LibAliasSaveFragment "struct libalias " "char ptr"			.Fn LibAliasSaveFragment "struct libalias " "void ptr"
	.Bd -ragged -offset indent			.Bd -ragged -offset indent
	When			When
	.Fn LibAliasIn			.Fn LibAliasIn
	returns			returns
	.Dv PKT_ALIAS_UNRESOLVED_FRAGMENT ,			.Dv PKT_ALIAS_UNRESOLVED_FRAGMENT ,
	this function can be used to save the pointer to the unresolved fragment.			this function can be used to save the pointer to the unresolved fragment.
	.Pp			.Pp
	It is implicitly assumed that			It is implicitly assumed that
	.Fa ptr			.Fa ptr
	points to a block of memory allocated by			points to a block of memory allocated by
	.Xr malloc 3 .			.Xr malloc 3 .
	If the fragment is never resolved, the packet aliasing engine will			If the fragment is never resolved, the packet aliasing engine will
	automatically free the memory after a timeout period.			automatically free the memory after a timeout period.
	[Eventually this function should be modified so that a callback function			[Eventually this function should be modified so that a callback function
	for freeing memory is passed as an argument.]			for freeing memory is passed as an argument.]
	.Pp			.Pp
	This function returns			This function returns
	.Dv PKT_ALIAS_OK			.Dv PKT_ALIAS_OK
	if it was successful and			if it was successful and
	.Dv PKT_ALIAS_ERROR			.Dv PKT_ALIAS_ERROR
	if there was an error.			if there was an error.
	.Ed			.Ed
	.Pp			.Pp
	.Ft char *			.Ft void *
	.Fn LibAliasGetFragment "struct libalias " "char buffer"			.Fn LibAliasGetFragment "struct libalias " "void buffer"
	.Bd -ragged -offset indent			.Bd -ragged -offset indent
	This function can be used to retrieve fragment pointers saved by			This function can be used to retrieve fragment pointers saved by
	.Fn LibAliasSaveFragment .			.Fn LibAliasSaveFragment .
	The IP header fragment pointed to by			The IP header fragment pointed to by
	.Fa buffer			.Fa buffer
	is the header fragment indicated when			is the header fragment indicated when
	.Fn LibAliasIn			.Fn LibAliasIn
	returns			returns
	.Dv PKT_ALIAS_FOUND_HEADER_FRAGMENT .			.Dv PKT_ALIAS_FOUND_HEADER_FRAGMENT .
	Once a fragment pointer is retrieved, it becomes the calling program's			Once a fragment pointer is retrieved, it becomes the calling program's
	responsibility to free the dynamically allocated memory for the fragment.			responsibility to free the dynamically allocated memory for the fragment.
	.Pp			.Pp
	The			The
	.Fn LibAliasGetFragment			.Fn LibAliasGetFragment
	function can be called sequentially until there are no more fragments			function can be called sequentially until there are no more fragments
	available, at which time it returns			available, at which time it returns
	.Dv NULL .			.Dv NULL .
	.Ed			.Ed
	.Pp			.Pp
	.Ft void			.Ft void
	.Fn LibAliasFragmentIn "struct libalias " "char header" "char *fragment"			.Fn LibAliasFragmentIn "struct libalias " "void header" "void *fragment"
	.Bd -ragged -offset indent			.Bd -ragged -offset indent
	When a fragment is retrieved with			When a fragment is retrieved with
	.Fn LibAliasGetFragment ,			.Fn LibAliasGetFragment ,
	it can then be de-aliased with a call to			it can then be de-aliased with a call to
	.Fn LibAliasFragmentIn .			.Fn LibAliasFragmentIn .
	The			The
	.Fa header			.Fa header
	argument is the pointer to a header fragment used as a template, and			argument is the pointer to a header fragment used as a template, and
	▲ Show 20 Lines • Show All 63 Lines • ▼ Show 20 Lines
	Checksums can also be verified by operating on a block of data including			Checksums can also be verified by operating on a block of data including
	its checksum.			its checksum.
	If the checksum is valid,			If the checksum is valid,
	.Fn LibAliasInternetChecksum			.Fn LibAliasInternetChecksum
	will return zero.			will return zero.
	.Ed			.Ed
	.Pp			.Pp
	.Ft int			.Ft int
	.Fn LibAliasUnaliasOut "struct libalias " "char buffer" "int maxpacketsize"			.Fn LibAliasUnaliasOut "struct libalias " "void buffer" "int maxpacketsize"
	.Bd -ragged -offset indent			.Bd -ragged -offset indent
	An outgoing packet, which has already been aliased,			An outgoing packet, which has already been aliased,
	has its private address/port information restored by this function.			has its private address/port information restored by this function.
	The IP packet is pointed to by			The IP packet is pointed to by
	.Fa buffer ,			.Fa buffer ,
	and			and
	.Fa maxpacketsize			.Fa maxpacketsize
	is provided for error checking purposes.			is provided for error checking purposes.
	▲ Show 20 Lines • Show All 584 Lines • Show Last 20 Lines