Subject: licensing and other

From: [email-masked]
Date: Fri, 6 Oct 2000 16:11:43 +0400

[To be removed from this list send the message "unsubscribe fwtk-users" in the
BODY of a mail message to [email-masked].]

-----BEGIN PGP SIGNED MESSAGE-----

nuqneH,

Ok, we have major troubles with TIS license. It discourages developers
and is definitely evil ;) So why don't just rewrite the code under BSD
license? The best way for me is "soft" migration - re-creating API 
and configuration functionality to let us use all fwtk add-ons we already
have written. The proxies itself are not a major problem - there are many
programs with similar functionality floating on the net and the code is
relatively small - we can do security audit on it and bring the API we have
in to be compatible.

Anyways - if you don't support that, some of people on the list will probably
get use of what i did: documented the API (current one) and wrote some
style guides drafts. It will ease writing fwtk proxies for people no very 
familliar with the code. It is worth putting on the fwtk.org site ;)

It would be nice if someone converts it to html, man pages, whatever
else format with fancy fonts and formatting you do prefer.

*************************************************************************
fwtk API functions reference manual, revision 0 - original TIS unchanged.
*************************************************************************

authentication-related functions are not described here because TIS
already provided detailed description in fwtk package

- -------------------------------------------------------------------------

	isalldigits() - a frontend to isdigit() function for a string

	int isalldigits(char *s)

description:

	returns 0 if the string is empty or not consisting of digits,
	non-zero otherwise.

- -------------------------------------------------------------------------

	str_to_port() - a getservbyname frontend

	int str_to_port(char *portstr)

description:

	returns atoi of portstr if it is all-digit, tcp port number from
	getservbyname if it is not, and exits with fwtkcfgerr if the service 
	is unknown.

- -------------------------------------------------------------------------

	mapgid() - getgrnam frontend

	int mapgid(char *gnam)

description:

	returns atoi of gnam if it is all-digit, group id if it is not and
	-1 if group does not exist.
 
- -------------------------------------------------------------------------

	mapuid() - getpwnam frontend

	int mapuid(char *user)

description:

	returns atoi of user if it is all-digit, uid if it is not and
	-1 if uid does not exist.

- -------------------------------------------------------------------------

	randomnumber() - get a number from PRNG

	long randomnumber()

description:

	obvious

- -------------------------------------------------------------------------

	getpassword() - get password from stdin tty with no echo

	char* getpassword(char *prompt)

description:

	obvious

- -------------------------------------------------------------------------

	peername() - an advanced frontend to unix getpeername() function

	int peername(int fd,char *lname,char *sname,int z)

description:

	the peername() function performs peer address and dns lookups for
	given socket (fd), performs sanity and security checks to detect
	possibly dangerous connections and dns-driven attacks, and writes
	first z characters of text representation of the resulting ip 
	address and lowercased host fqdn to strings pointed by lname 
	(fqdn) and sname (address). 

	If the name lookup fails or seems to be unreliable, "unknown"
	is returned to lname.

	the function return value is 0 unless getpeername() failed

security conditions:

	ip options are set on socket, 
	action: lname is "unknown", "Connection received using ip options
		(ignored)" securityalert is generated, options are being 
		reset.

	host name lookup failed,
	action: lname is "unknown", a log warning message is generated

	address entry returned by name server after performing reverse
	lookup and then forward lookup again exceeds sizeof appropriate
	structure,
	action: lname is "unknown", "invalid host address length" 
		securityalert is generated.

	hostname returned by reverse lookup does not resolve to ip address,
	action: lname is "unknown", a log warning message is generated

	no ip addresses of hostname returned by reverse lookup match peer,
	action: lname is "unknown", a "possible spoof" securityalert is
	generated 

- -------------------------------------------------------------------------

	hostmatch() - see if given host matches netperm-table host
		      entry (see netperm-table manual for pattern syntax)

	int hostmatch(char *pattern,char *name)

description:

	it is generic host pattern match function used when determining 
	if source or destination addresses match vaules configured in
	netperm-table. 
	name can be fqdn or dot-delimited ip as text string.

	if the name is dot-delimited ip and the pattern is fqdn-based, 
	a reverse lookup and attempt to resolve returned name are performed. 
	if some of those fail, "unknown" is assumed for matching function
	as name. 

	the function returns 0 if host does not match (incuding all
	error conditions, unresolvable name and so on) or 1 if it does.

security conditions:

	name or pattern too long (exceed builtin limit, currently 512
	characters),
	action: fwtkcfgerr is generated, 0 returned

	full host name (after performing lookups) is too long, 
	action: fwtkcfgerr is generated, 0 returned

	address entry returned by name lookup exceeds sizeof appropriate
	structure,
	action: "invalid host address length" securityalert is generated,
		0 returned

	no ip addresses or hostnames returned by lookups match name 
	initially specified,
	action: match as "unknown" is performed, a "possible spoof" 
		securityalert is generated 

- -------------------------------------------------------------------------

	conn_server() - connect to a server by name and port

	int conn_server(char *srv,int portnum,int priv,char *rbuf)

description:

	the functions connects to server srv port portnum, using 
	highest privileged source port if priv is non-zero, and any
	one as regular tcp connection does if it is zero. A socket is
	returned as function return value or a negative value if something 
	fails (-1 if server name does not resolve or invalid, -2 if socket
	failed to create and -3 if connect failed). A failure reason is
	written into string pointed by rbuf, if it is specified. 
	
security conditions:

	address entry returned by name lookup exceeds sizeof appropriate
	structure,
	action: "invalid host address length" securityalert is generated,
		-1 returned.

- -------------------------------------------------------------------------

	maphostname() - inet_ntoa() frontend

	char* maphostname(char *name)

description:

	If the name is ip address or unresolvable, the pointer to it
	is returned. Otherwise an address lookup is done and the returned
	pointer is inet_ntoa function result.

security conditions:

	address entry returned by name lookup exceeds sizeof appropriate
	structure,
	action: "invalid host address length" securityalert is generated,
		"invalid" is returned.

- -------------------------------------------------------------------------

	lock_fd(),lockun_fd(),locktest_fd() - flock/lockf frontend

	int lock_fd(int f)
	int lockun_fd(int f)
	int locktest_fd(int f)

description:

	lock_fd returns		flock(f,LOCK_EX)
	lockun_fd returns 	flock(f,LOCK_UN)
	locktest_fd returns 	flock(f,LOCK_EX|LOCK_NB)

- -------------------------------------------------------------------------

	set_oob_notification() - enable OOB signaling on given socket

	int set_oob_notification(int fd)

description:

	ensures that we can receive OOB signaling and turns it on for
	a socket.
	returns 0 if ok, non-0 if something fails.

- -------------------------------------------------------------------------

	do_daemon() - start acting as daemon on given port

	int do_daemon(int port)

description:

	performs the following algorithm:

	1. fork, parent exits
	2. child binds to the port and 
	3. waits for connection
	4. after a connection is received, fork and make child fd's 1,2,3 
           pointing to the connection socket as inetd does
	5. parent returns to 3, child exits function

- -------------------------------------------------------------------------

	waitwaitwait() - dummy function to read child status change

description:

	signal(SIGCHLD,waitwaitwait) is useful sometimes if you fork and
	don't want to be annoyed by SIGCHLD.

- -------------------------------------------------------------------------

	cfg_read() - read netperm-table rules matching tag (application)
		     name into Cfg type chain.

	Cfg* cfg_read(char *app)

description:

	configuration returned is a chain of Cfg type entries, described
	as following structure:

	typedef struct  cfgrec  {
        	int     flags;          /* see below */
        	int     ln;             /* line# in config file */
        	char    *op;            /* facility name */
        	int     argc;           /* number of arguments */
        	char    **argv;         /* vector */
        	struct  cfgrec  *next;
	} Cfg;

	flags are:

	#define PERM_ALLOW      01
	#define PERM_DENY       02

	the chain ends with next = (Cfg *) 0.

	netperm-table syntax is described in the appropriate man page.

	if a syntax error, too long or malformed line is found,
	a fwtkcfgerror is generated.

	if a fatal error occurs, fwtksyserr is generated and
	(Cfg *)-1 is returned.

	The chain is to be processed later by cfg_get() function.
	
- --------------------------------------------------------------------------

	cfg_get() - get configuration entries by keyword
	
	Cfg* cfg_get(char *fac,Cfg *cp)

description:

	this function gets an entry matching keyword fac from Cfg chain
	cp. If cp == (Cfg *) 0, a next entry matching keyword from the
	same chain is returned. If no more matches, cfg_get returns
	(Cfg *) 0.

- --------------------------------------------------------------------------

	cfg_free() - destroy Cfg chain

	void cfg_free(Cfg *cp)

description:

	cfg_free() frees up memory allocated by cfg_read

- --------------------------------------------------------------------------

	enargv() - convert a string of space-delimited tokens to argv-type
		   array

	int enargv(char *buf,char **av,int avsiz,char *tobuf,int bsiz)

description:

	convert buf string to tokens in array av,
	using tobuf as actual storage, not exceeding the buffer size bsiz 
	and token counter avsiz

- --------------------------------------------------------------------------

	auth_perm() - request extended permissions from authorization 
		      server

	int auth_perm(Cfg *confp,char *name,char *oper,char *host,char **op)

description:

	request if authorization server specified in confp grants right to
	user <name> of application <oper> (originated communication from
	<host>) to perform operations <op>. 
	op usually points to command or operation name in op[0] and
	null-terminated list of parameters in the rest of array.

	the function returns 1 if an error occured or permission is denied,
	-1 if authorization table does not contain corresponding vaule
	(which should be interpreted as deny too) and 0 if permission is
	granted.

- --------------------------------------------------------------------------

*************************************************************************
fwtk proxies command line options style guide
*************************************************************************

- -daemon <port number> should run the proxy as daemon on given port
- -version should dump current version info to stdout
- -as <tag name> should force the proxy to read <tag name> configuration
    from netperm-table instead of one belonging to its own 
    name (if it is not available, revert to original config name) 

*************************************************************************
netperm-table configuration style guide
*************************************************************************

the netperm-table syntax is already described in man page

general option keywords:

welcome-msg <file> 	specify the path to welcome banner file 

denial-msg <file>	specify the path to a file proxy displays
			when it denies access to gateway 

denydest-msg <file>	specify the path to a file proxy displays
			when it denies access to some destination or denies
			some operation that is subject of additional control

help-msg <file>		specify the path to a help file

if any of those are omitted in netperm-table but supported by proxy, 
a builtin banners should appear.

timeout	<seconds>	set the network inactivity timeout value

userid <uid>		specify userid to setuid to (name or number)

groupid <uid>		specify groupid to setgid to (name or number)

directory <path>	specify chroot path or working directory

permit-hosts parameters:

- -auth				 authentication is required

- -authuser <username>		 treat connection as if <username>
				 had pre-authenticated (useful for
				 extended permissions)

- -dest <pattern>			 specify list of allowed destination
- -dest {<pattern1> <pattern2>..}	(pattern can be negated by preceding "!")

- -users <user>			specify list of users allowed to use proxy
- -users {<user1> <user2>..}	(pattern can be negated by preceding "!")
				note: this usually refers to in-protocol
				user information, not to users as subject
				of firewall authentication

- -transparent			a system-dependant transparency engine
				is used to find connection destination

- -plug-to <server>		plug the proxy to a server

- -handoff <server>		synonym to plug-to

- -client-encrypt <algorithm>	enable connection encryption on client side

- -server-encrypt <algorithm>	enable connection encryption on server side

- -client-<hashname>-key <passphrase> - generate shared secret for cleint side
				using passphrase and hash algorithm

- -server-<hashname>-key <passphrase> - generate shared secret for server side
				using passphrase and hash algorithm

*************************************************************************
statistics gathering and logging style guide
*************************************************************************

a proxy should log at least:

all client connections, using the following syntax:

permit host=host.fqdn/1.2.3.4 use of gateway
deny host=host.fqdn/1.2.3.4 use of gateway

all connections originated by proxy or requested by clinet, using the 
following syntax:

permit host=host.fqdn/1.2.3.4 connect to server/port
deny host=host.fqdn/1.2.3.4 connect to server/port

for ip-based authorization and

permit host=host.fqdn/1.2.3.4 connect to server/port user=authuser
deny host=host.fqdn/1.2.3.4 connect to server/port user=authuser

for authorization based on extended permissions,

all user authentications, using the following syntax:

authenticate user=name 

all system-level failures, using "fwtksyserr:" prefix,
all configuration errors, using "fwtkcfgerr:" prefix,
all suspicious conditions, using "securityalert:" prefix,

time online (seconds), destination, bytes transferred in and out on exit,
using the following syntax:

exit host=host.fqdn/1.2.3.4 destination=dest in=1234 out=1234 duration=12

(extra information like user name or something else may contain in this line)

that's all this time.

- ---- 

                                     _     _  _  _  _      _  _
 {::} {::} {::}  CU in Hell          _| o |_ | | _|| |   / _||_|   |_ |_ |_
 (##) (##) (##)        /Arkan#iD    |_  o  _||_| _||_| /   _|  | o |_||_||_|
 [||] [||] [||]            Do i believe in Bible? Hell,man,i've seen one!

---

From: Keith Young <[email-masked]>
Date: Fri, 06 Oct 2000 10:23:07 -0400

> relatively small - we can do security audit on it and bring the API we have

As I mentioned before I'd be willing to host something like this on
fwtk.org, including some kind of limited write access CVS system...

Since I have my first "little one" on the way, I won't have much time
but I'll help whenever I can.... :-)

-- 
--Keith Young
-Director of Customer Care/Support, V-ONE Corp.
[email-masked]