
\style{FILEFRONT}
\output{F:\README.txt}

\header
	JEDI KNIGHT: Jedi Academy
\end

\modinfos
	TITLE    : BaseJKA Security Fix + SOURCE \line
	VERSION    : 1.1 \line
	AUTHOR    : Gamall Wednesday Ida \line
	E-MAIL    : gamall.ida@gmail.com \line
	WEBSITE    : http://gamall-ida.com \line
	\line
	FILENAME Windows    : basejka_Gamalls_fix_11.pk3 \line
	FILENAME Linux    : jampgamei386.so \line
	FILESIZE       : ~ 4 Mo \line
	DATE RELEASED    : October 2007 \line
\end

\section
	INSTALLATION INSTRUCTIONS:  
\end
\body
	Just put the relevant file in your server's base folder.
\end
\section
	DESCRIPTION  
\end
\body
	(version 1.0e, see below for changelog to final 1.1)
\end

\body
	This patch (technically it is a mod, so do not expect it to be compatible with JA+ or anything else)
	corrects the three Denial of Service vulnerabilities I am aware of
	affecting  basejka, and makes the logs more useful to an experienced admin, without attempting to alter
	the gameplay or admin etc in any way. Some random fixes and features were also added at the request of
	users.
\end
\body
	IMPORTANT: My patch only affects the component "jampgame". In order to completely protect a server, 
	you must also use a patched "jampded". Here is one link to ready to use jampdeds :
\end
\verb
	http://jediknight2.filefront.com/file/
	UNOFFICIAL_Patch_for_JA_101_Dedicated_Servers;41652
\end{verb}
\body
	Note that it seems that Windows servers are still vulnerable to targeted attacks on jampded.
	I won't say more since this is out of the scope of this mod.
\end

\section
	CHANGELOG v1.0e -> v1.1
\end
\body
> The help page is now automatically displayed only on the very first connection, as opposed
to connections when you are carried over from a previous map, or at the end of a duel turn. 
\end

\body
	> Names such as "**Spamzor" are automatically converted to "* Spamzor", so a display bug, causing chat
	lines from such a player to be displayed in both the chat box and the server broadcast line, cannot be
	exploited anymore.
\end
\body
	> Fixed a false positive in my bot detection scheme: bots were detected as a fake player attack ;
	although this had no real consequence, it was a source of confusion in the logs.
\end
\body
	> Logs now differentiate connections from bots and from real players.
\end
\body
	> Messages from the dedicated server have been made slightly more visible: the tag is now [SERVER], with
	colors. I would have liked to do the same with the /svsay command, but it can't be altered, as it is hard
	coded into jampded instead of jampgame. Go figure...
\end
\body
	> The IP is now logged each time somebody changes their names.
\end
\body
	> Added the /(t)ime client command, displaying the local time of the server:
\end
\verb
	]\time
	# Server time:
	Sun Sep 09 13:37:03 2007
\end{verb}
\body
	> Added cvar ga_doNotAllowDualKataSpin, default 0, preventing anyone in a dual kata from spinning like a madman. (slightly buggy, as the screen seems to vibrate when moving the mouse, but it works.)
\end
\body
	> Added cvar ga_nameLengthLimit: names will be truncated not to exceed that length. Note that color escape sequences, such as ^1, are not counted.
\end
\body
	> Some ga_* cvars are now marked as serverinfo (external tools can read them).
\end
\body
	> Added the /info client command and ga_serverInfo cvar. /info displays the contents of the cvar. Admins can put rules, etc in there, and any player can read it anytime.
\end
\body
	> Anti model/color change spam/lag: any player can now freely change their info only 50 times per map (unless they reconnect of course). After that, they need to wait for three full seconds between each change. This should not inconvenience any legitimate player, and protects everyone on the server from the lag which can be created by fast and furious sustained userinfo change.
\end
\body
	> Added another log file, ga_ConnectLog.txt, listing every connection and full userinfo, and nothing but that, which is now created by the server: for instance
\end
\verb
	[Sun Sep 16 20:23:02 2007] [========================== SERVER START ==========================]
	
	[Sun Sep 16 20:23:11 2007] Connect :: name(num) = [^5G^7amall ^5W^7ednesday ^5I^7da]( 2) :: ip = [     127.0.0.1] :: userinfo = [COMPLETE USERINFO STRING LOGGED HERE]
\end{verb}
\body
	> The logs now use real time:
\end
\verb
	[Sun Sep 16 20:24:03 2007]  Kill: 2 1 3: ^5G^7amall ^5W^7ednesday ^5I^7da killed Desann by MOD_SABER
	[Sun Sep 16 20:24:07 2007]  say: (1)Desann: Impressive, most impressive... but you are not a Jedi yet!
	[Sun Sep 16 20:24:11 2007]  Kill: 2 4 3: ^5G^7amall ^5W^7ednesday ^5I^7da killed Imperial Saboteur by MOD_SABER
\end{verb}

\section
	SUMMARY OF THE CHANGES in v1.0e:
\end


\subsec
	Client disconnect buffer overflow: fixed trap_SendServerCommand().
\end
\sbody
	The possibility to cause a  DoS disconnecting all clients by sending overlong strings to the server has
	been fixed. Incorrect commands are just ignored.
\end

\subsec
	Ingame buffer overflow (say/tell): fixed Cmd_Say_f() and Cmd_Tell_f().
\end
\sbody
	The possibility to crash the server by using say or tell to pass overlong strings to the server has been
	removed. Incorrect calls are truncated to a decent length (150).
\end

\subsec
	Fake Players Attack: heavily secured, customisable  ClientConnect().
\end
\sbody
	The possibility to lag and even crash the server by sending a great number of fake connection request
	using a third party program such as q3fill has been removed. See below for more information.
\end

\subsec
	Improvement of the log file/server messages.
\end

\sbody
	Each time a client connects, the complete userinfo string is logged, even is the connection is denied.
	This includes the  IP, port, qport, name of the client and much more.
\end

\sbody
	If the connection is denied, a message explaining why is displayed by the server, and relevant
	information is written down in the log file. Since those messages could be used to spam the screen 
	in case of a fake players attack, and in the case you just don't want to know about that, you can
	deactivate the public messages : just set those  cvars to 0 (default = 1):
\end
\verb
	ga_showBadPassClient | 0 or 1 : 
	   -> display a message when a client connects with a bad password.

	ga_showBannedClient  | 0 or 1 : 
	   -> display a message when a banned client connects.
\end{verb}

\sbody

	The "Infostring length exceeded" console error message has been made a tad more explicit. I noticed a bug
	which would cause it to be sent each frame. It is hard to debug if you don't know what caused it ;)
\end

\sbody
	Each time a user changes name, it is written down in the log file.
\end
\sbody
	When a client disconnects, their name is logged.
\end
\sbody
	Each time a client says/tells something, their client number is logged along with their name.
\end

\subsec
	Random unimportant fixes/improvements.
\end
\sbody
	The annoying timelimit when changing name has been dulled down from five seconds to 0.7 second.
\end
\sbody
	The ^0 (black) colour now works properly. If you don't want to see black in names, you can deactivate
	this by setting the following cvar to 0:
\end
\verb
ga_allowBlackInNames 
  | 0 or 1 (default = 1)
\end{verb}

\sbody
	When a player's name is incorrect, it is set to "Padawan" in  basejka, which is annoying, since you end
	up with many "Padawan"s. You can now decide what it will be, and if you so choose, you can add the
	player's client number to their name by typing "%i" in the name.
\end
\verb
ga_defaultName 
  | (default = "^4P^7adawan ^5(^7%i^5)")
\end{verb}
\sbody
	For instance, with the default setting, the client 9 will be renamed to "Padawan (9)". Note that I put
	many spaces between the name and number: normal players can't use more than three spaces in a row, so
	nobody will be able to imitate the default name with the number of someone else, and trick you in kicking
	that other player instead of them...
\end
\sbody
	If you don't like that, you can just change it back to "Padawan".
\end

\sbody
	Insignificant names, such as "Padawan", can be black-listed, which will result in them being replaced by
	the default name.
\end
\verb
ga_nameBlackList 
  | default =  "Padawan;otherunacceptablename"
\end{verb}
\sbody
	Note that the black list is case insensitive, and that spaces, underscores and dashes are ignored. So do
	not put any "_" etc in ga_nameBlackList.
\end

\sbody
	Admins can now close the server and display a message to connecting clients explaining why the server is
	closed, instead of putting a password.
\end
\verb
ga_closeServer      
  | 0 or 1 or 2
ga_closedServerMsg;   
  | default = "^1The server is closed at the moment\n^2Please come back later"
\end{verb}
\sbody
	As you have undoubtedly noticed, you can use colors and line breaks in the message. Try and keep it short
	though.
\end
\sbody
	If ga_closeServer is set to 0, the server is open (normal behaviour). If set to 1, the server is closed,
	and you are notified each time somebody connects to the server. If set to 2, the server is closed, and
	you won't be notified of connecting clients.
\end
\sbody
	Every client can use the /list (or /l) function, displaying information on the connected clients, which
	is useful in order to know who is who. (the server status function is useless as it doesn't always yield
	the correct client number...)
\end

\sbody
	There is also the /help (/h) command, displaying a small help text.
\end

\section
	PROTECTION AGAINST THE FAKE PLAYERS :
\end

\body
There are three different protections against the q3fill attack : When a client connects, three protection layers activate :
\end
\subsec
	Clever Fake Detection
\end

\sbody
	The connection string is checked for a value specific to  JKA players, of which the bots are devoid by
	default. If no such value is found, then the connection is denied, and the  IP can be automatically added
	to the  banlist. 
\end

\sbody
	This aspect is controlled by the following  cvars :
\end

\verb
	ga_cleverFakeDetection | default = "model"
	ga_cleverfakeAutoBan   | default = "1"
\end{verb}
\sbody
	This first protection alone will get rid of 99.99 % of all attacks.  
\end
\sbody
	If the attacker knows what he is doing, he can easily fool that by altering the attack. Most
	script-kiddies do not have that kind of know-how though.
\end
\sbody
	You can deactivate this feature by setting ga_cleverFakeDetection "none".
\end

\subsec
	Hard-Coded Fake Detection
\end

\sbody
	Check for a value specific to bots, that does not appear in legitimate players. This is a viewpoint
	completely opposed to the first layer, but works exactly the same way.
\end
\verb
	ga_hardFakeDetection | default = "cl_guid"
	ga_hardFakeAutoBan   | default = "1"
\end{verb}
\sbody
	To fool this layer is tricky, as the target value is hard-coded into q3fill. The attacker would need to
	alter q3fill's source code in an appropriate way without breaking anything and recompile it... definitely
	not something your average dumb server crasher can do :D
\end
\sbody
	You can deactivate this feature by setting ga_hardFakeDetection "none".
\end

\subsec
	Connect Flood Detection
\end

\sbody
	If the two first layers fail (or are deactivated), then there is no way to tell a genuine player and a
	bot apart. So we must detect them by the speed at which they connect from the same  IP.
\end
\verb
	ga_sameIpNumber 
	  | default = "5"
	ga_sameIpTime 
	  | default = "30"
	ga_sameIpAutoBan 
	  | default = "1"
	ga_sameIpAutoKick 
	  | default = "1"
\end{verb}

\sbody
	With the default settings, the connection of more than 5 players from the same  ip in less than 30
	seconds will be deemed a fake players attack. As usual, the connection will be denied, and the  IP can be
	banned, depending on the  admin's choice. The bots that got in can also been kicked automatically.
\end
\sbody
	Setting ga_sameIpNumber to 0 will deactivate this third layer.
\end

\sbody
	NOTE: Be very careful when playing with ga_hardFakeDetection and ga_cleverFakeDetection. Putting
	incorrect values there may prevent ANY player from entering the game, or in the best case scenario render
	the protection useless. The default values are good. Don't alter them unless you know what you are doing.
\end

\section
	TECHNICALITIES:
\end

\body
	This patch has been compiled with the following compilers:
\end

\subsec
	On Windows:
\end
\sbody
	Visual C++ 2005 (8); \line
	\line
	It is the same compiler Raven Software used to compile the original  jampgame (albeit they used version
	7), and the very same compilation parameters. So there is NO reason at all that the damages/blocks should
	be altered in any way.
\end

\subsec
	On Linux:
\end

\sbody
	GCC 2.96 on a Red Hat Linux release 7.2 (Enigma); \line \line
	
	GCC is a very good compiler, but Raven used ICC, which is a commercial product I don't have. So the
	damages might in theory be slightly altered, although I personally can't tell the difference. \line \line
	
	This would come from the way each compiler handles the computation of float variables. 
\end

\section
	SOURCE CODE:
\end
\body
	I won't be working on that mod anymore, unless a 'real' (as opposed to 'alleged', you know ;) ) unless a real security exploit is brought to my attention, so I chose to make it completely open-source, under the GPL. That way anyone can add or remove features as they please, or use some of my tricks in their own mod if
	they want to.
\end

\body
	A copy of the source code has been shipped with this package. My modifications to raven's source code
	are released under the GNU General Public License (GPL), which means (roughly) that you are free to use
	the code as you please, so long as you release your own work under the GPL. 
\end
\body
	A copy of the GPL has been shipped with this package. You must read and understand it if you intend
	to use the source code.
\end
\body
	In addition, I would appreciate it if anyone using any part of my code took the time to post
	a link to their own project on the fix's thread:
\end
\verb
	http://gamall-ida.com/f/viewtopic.php?f=3&t=120
\end{verb}

\section
	CONTACT / SUPPORT
\end
\body
	If you need  help  or  have  suggestions,  comments,  insults, 
	praise  or  in  general, anything to say about this program that you 
	expect me to read and answer to, please post on  the  program's 
	topic on my website:                          
\end
\verb
	http://gamall-ida.com/f/viewtopic.php?f=3&t=120
\end{verb}

\section
	CREDITS:
\end  
\body
	Kudos to Trimbo for his linux-ready version of the vanilla SDK.
\end

\body
	Warm regards to Luigi Auriemma for his work on JKA and the q3 engine.
\end

\body
	THIS MODIFICATION IS NOT MADE, DISTRIBUTED, OR SUPPORTED BY  ACTIVISION, RAVEN, OR  
	LUCASARTS ENTERTAINMENT COMPANY  LLC. ELEMENTS TM & ©  LUCASARTS  
	ENTERTAINMENT COMPANY  LLC AND/OR ITS  LICENSORS. 
\end