                ___                _     _          ___        
               / __\  ___    ___  | | __(_)  ___   /___\ _ __  
              / /    / _ \  / _ \ | |/ /| | / _ \ //  //| '_ \ 
             / /___ | (_) || (_) ||   < | ||  __// \_// | |_) |
             \____/  \___/  \___/ |_|\_\|_| \___|\___/  | .__/ 
              written.by.kass.lloyd.version.1.6pre11i   |_|    
              ---------------------------------------------------              

README FILE v1.5 6/11/01
------------------------

Welcome to Cookie Op! A fully functional encryption op script for eggdrop. This
script was written for eggdrop 1.5.x and above. It is made to use the SHA-1
module also written by Kass Lloyd, but will work with the built in md5 
functions in eggdrop 1.5.x. 

This script runs independently of a botnet, but is still completely secure. 
For a comprehensive document detailing the cookie generation routines in 
Cookie Op please visit (http://kasslloyd.tripod.com/cookieopdetails2.html). 

Features
---------
  1. Virtually unlimited number of possible cookies for each op. 

  2. Uses SHA-1 module (or md5 if sha-1 isn't installed) to generate the 
     cookie, both are an irreversible encryption algorithm. Rendering an 
     attacker to have to know the text you encrypted to generate the hash. 
     Basically makes it impossible for someone to find out your keys and 
     encryption passwords.

  3. The ability to change how the cookie is generated, thus making it even 
     more impossible for someone to brute force attack your cookies. 

  4. Turning the cookie op on or off from your channels is just as simple 
     as: .chanset #chan +cookieop

  5. Replaces the +autoop channel flag with +cookieautoop

  6. Replaces the +a user flag with +A, does the same function except with 
     cookie ops. And filters the .chattr command to prevent +a's from being
     set.

  7. Has a fully functional time stamping process that uses current NIST time
     from global time servers. Will cause a cookie to truly expire and be
     unusable after a specified time. 

  8. Has a very wide selection of different punishment and modes levels for
     an invalid op.

  9. Requires eggdrop 1.5.x or higher.

 10. Will require a slight modification to any tcls you have running that 
     perform an op function. If you e-mail me your tcls I'll make the 
     modification and if its ok with you post them on my website as 
     compatible scripts.
 
 11. If one bot on the botnet is unable to get the time from the timeserver
     it will request the time from a bot on the botnet that could. 

Changes
-------

 1.6 - Getting close to a FINAL (for real this time!) release.
     - A lot was changed in this one, lots of bug fixes and lots of new 
       bugs added! (hope not) :-P
     - Added +cookieautoop channel flag to replace +autoop
     - Added +A user flag to replace +a
     - Added .chattr filtering to prevent +a user flags (just switches them 
       to +A)
     - Added a complex assortment of punishment levels and modes. 
     - Added .chanset filtering to prevent channel flags that aren't compatible
       with cookie op.
     - Fixed the } nick bugs.
     - Fixed a bug causeing the bot to die if banmask contained [die]
     - The cookies are now time stamped using the current time pulled from NIST
       Internet Time Service (ITS). This makes 1.6 incompatible with older
       releases.
     - fixed it so, it dosn't remove the +a user flags and +autoop channel flags
       it just replaces them with the +A or +cookieautoop flags respectively.
     - added three new dcc commands 
       .cookiestat - will tell you the status of all the bots on the botnet, 
            what there cookie time is and how long its been since they 
	    connected to a time server last.
       .forcetime <bot/*> - will force a bot to connect to a time server.
       .synchtime - to set the cookie time across the botnet the same as the
            time on the bot the command was used on.
     - made the bots set there time according to the servers clock (GMT) at 
       the start, and if they are unable to connect to the time server request
       time from the botnet.
     - Made extensive documentation on the usage of the script (what your
       reading now!)
     - Added alot of different minor settings.
     - changed the cookie format once again, the way the timestamp is 
       displayed.
     - changed and fixed a lot of the botnet commands.
     - added a couple new settings that shouldn't effect the adverage user
       much, just too make the script more flexable.
     - added a small tcl shell script i made to pull random data from 
       Hotbits and automaticly generate your key procs for you. Just run
       the script and copy and paste the procs out of the file it generates
       into your tcl script replaceing the default ones included.
     - made the punishment proc much more extensive and MUCH better takeover
       protection was added. :-)
     - time stamping has been fixed for a week or so now, just been waiting to
       see if new bugs would pop up. Everything looks great!
     - added a nifty windows program made by Killer-Soft.de to randomly 
       generate your key procs. 
  
 1.5 - Fixed a bug in the removal of +a (auto-op) flags at runtime.
 
 1.4 - Fixed the bug where the bots failed to authenticate any
       cookies! (ooops!)
 
 1.3 - Fixed a bug with the "cop_debug" variable. Found by BiLL
 
 1.2 - Fixed the [] nick bugs
 
 1.0 - Fixed many different scattered bugs.
 
 1.0b1 -  First public release of the beta code.


Installing
----------

Just change the setting, and install the tcl on each bot in the channel. Also
you can't use any scripts/modules that do opping, if you want to use them send
to me to have me modify them for you. 

Those that are tcl minded can modify there own tcls, to perform a cookie op
call this proc: cop_op $chan $nick

The proc does not check if the person should have ops or not, so the checks
should be done before this proc is called. It will perform a cookie op in 
channels cookie is turned on and a regular op in channels that its not.

* to use the getrandom.exe that was made by Killer-Soft.de. It's a windows
program, so just run it and set the range of sizes you want your keys to be.
You want them no shorter then 8 chars and you can make them as big as 72 chars.
Its recomended you keep them in the 8-12 range, anything bigger is just crazy.
:-P Also make sure you you leave "Use also symbols ("/" and "."}" checked 
since the script does use them and they are needed.

* To use the getrandom.tcl shell script that I included, upload it to your
server and chmod 700 getrandom.tcl. Then load it up in the text editor you 
like the most and make sure the top line "#! /usr/bin/tclsh" is set to the
correct location of the tclsh program.

Make sure the filename is set to what you want it to be, and that the 
keylen (length of the encryption keys) and fillerlen (length of the second
set of randomd data used in the cookie generation) lengths are set to your
likeing, the default should work just fine for you.

Then just save it and run the script, and if everything goes ok, it will
spit out a bunch of random data to the screen and a line saying that
the file was made correctly. Then your all done, just load it up and cut
and paste. 

Have fun! :-)


Commands
--------

dcc commands.
-------------
.cookiestat
  Will tell you the status of all the bots on the botnet, what there cookie 
  time is and how long its been since they connected to a time server last.

.forcetime <bot>
  Will force a bot to connect to a time server.

.op [nick] [channel]
  If you dont specify anything .op will op you on all the channels your in, if 
  you give a nick and no channel it will op that nick in all the channels its 
  in, and if you specify a channel then it will just op it in that channel. 
  You can't do .op #channel at the moment, if you want i could try to support 
  that later. let me know.

.synchtime
  Will synch the time across the botnet according to the time on the bot the
  command was used on. Use with cation, you won't be able to use this command
  if the bot hasn't connected to a timeserver in the last five minutes.

.setpunish <chan> <reaction level> <banmask type>
  Look below in the settings for how to use this and all the valid settings.


Settings
--------

There are many differnt configureable settings for Cookie Op, below is the 
setting and all relevent information about how to set it, plus examples
if approrate.

>>>>> SETTINGS THAT ARN'T SET IN THE TCL BUT IN PARTYLINE. <<<<<<<<<<<<<<<<<<<<<

To turn on cookie ops!
----------------------

.chanset #channel +cookieop

Pretty simple, to turn it off do.

.chanset #channel -cookieop

Not to hard now is it? heh


Cookie AutoOp channel flag
--------------------------

To use auto ops like the old +autoop flag, set your channel
+cookieautoop

If the channel is +cookieop then it will perform a cookie auto op, 
otherwise it would just perform a regular op.

There is also the +A user flag to replace the old +a auto op flag.
Works the same way as the channel flag setting.


Punishment Level
----------------

* NOTE: this setting has made some major changes since previous versions.
        its no longer set in the tcl, but is now a channel setting that must
	be set on the partyline via .chanset look below for more information
	on how to set this. Things with the | infront are new levels and
	banmasks.

This is where you set how your bots will react to an invalid op, either from
a cookie that failed authentication or from a regular op someone did without
a coookie. This setting has two parts, first is the reaction level, second is
the banmask format to use.

For reaction level 0, 1, 7, and 8 the second setting for the banmask is ignored
since a ban isn't performed during those levels. 

 level 0: no punishment! (whats the point then?)
 level 1: deop only the clients being opped
 level 2: deop both the opper and opped clients.

For level two if it was a bot doing the invalid op, it isn't prevented from
obtaining ops again through whatever method it uses. The next reaction levels
deal with banmasks and they are:

 level 3: deop both the opper and the opped clients, and ban the clients opped 
          but not the opper. 
 level 4: deop both the opper and the opped clients, and ban all of them.
 level 5: deop both the opper and the opped clients, ban all of them, and set
          a permenent ban on the bots for them, removing +o flags if they are 
	  a user on the bot and giving them +d flags. This works on both a 
	  regular user and a bot.
 level 6: same as level 5 except the opping client is delinked from the botnet
          (if they are a bot linked) and prevented from linking again, also 
	  all clients are given the +k userflag if they are users on the bot.

| The next levels deal with kicks with no banmasks, they are:
| 
|  Level 7: deop then kick only the people being opped.
|  Level 8: deop then kick both the opper and opped people.
| 
| The next levels are kicks with bans:
| 
|  level 9:  deop both the opper and the opped clients, kick them, and ban the
|            clients opped but not the opper. 
|  level 10: deop then kick both the opper and the opped clients, and ban
|            all of them.
|  level 11: deop then kick both the opper and the opped clients, ban all of 
|            them, and set a permenent ban on the bots for them, removing +o 
|            flags if they are a user on the bot and giving them +d flags. 
|            This works on both a regular user and a bot.
|  level 12: same as level 11 except the opping client is delinked from the botnet
|            (if they are a bot linked) and prevented from linking again, also 
| 	     all clients are given the +k userflag if they are users on the bot.
|
| The next levels are levels requested by some users:
|
|  level 13: Just kick the client that performed the op, and do not 
             punish the clients that was opped.

The settings for the banmask are as follows:

Origial hostmask was: raeky!lloyd@pm3-1-4.ppp.swau.edu
------------------------------------------------------
  00 = *!lloyd@pm3-1-4.ppp.swau.edu
  01 = *!*lloyd@pm3-1-4.ppp.swau.edu
  02 = *!*@pm3-1-4.ppp.swau.edu
  03 = *!*lloyd@*.swau.edu
  04 = *!*@*.swau.edu
  05 = raeky!lloyd@pm3-1-4.ppp.swau.edu
  06 = raeky!*lloyd@pm3-1-4.ppp.swau.edu
  07 = raeky!*@pm3-1-4.ppp.swau.edu
  08 = raeky!*lloyd@*.swau.edu
  09 = raeky!*@*.swau.edu
  10 = *!lloyd@pm?-?-?.ppp.swau.edu
  11 = *!*lloyd@pm?-?-?.ppp.swau.edu
  12 = *!*@pm?-?-?.ppp.swau.edu
  13 = *!*lloyd@pm?-?-?.ppp.swau.edu
  14 = *!*@pm?-?-?.ppp.swau.edu
  15 = raeky!lloyd@pm?-?-?.ppp.swau.edu
  16 = raeky!*lloyd@pm?-?-?.ppp.swau.edu
  17 = raeky!*@pm?-?-?.ppp.swau.edu
  18 = raeky!*lloyd@pm?-?-?.ppp.swau.edu
  19 = raeky!*@pm?-?-?.ppp.swau.edu
| 20 = *!*lloyd*@*
| 21 = *!*@205.165.192.38
| 22 = *!*@205.165.192.*
| 23 = *!*@205.165.*.*
------------------------------------------------------

A few examples of how to set this setting. If you wanted to use punishment
level 12 with banmask 4 you would issue the following command:

.setpunish #chan 12 4

If you wanted to use punishment level 2 and banmask 21 do:

.setpunish #chan 2 21

If you want to use reaction level 1, (for reaction level0, 1, 7, and 8 the banmask
level is ignored.) Set it the following way.

.setpunish #chan 1 0

Fairly straight forward and simple. Please use the .setpunish to set the
channel specific reaction levels, and everything should be just peachy.


>>>>> BASIC SETTINGS THAT MUST BE CHANGED / CHECKED. <<<<<<<<<<<<<<<<<<<<<<<<<<<<

proc cop_getkey
---------------

* IT is recomended you use the getrandom.exe or getrandom.tcl to make this 
proc. Look above in the Install section for instructions on how to
use them.

This is the tcl function that stores all the possible encryption keys that can
be used to make the cookie. You need to change these from there defaults to
some other random text string. Heres a shortend copy of the proc to be used as
an example of what you need to do.

       proc cop_getkey { char } {
          switch -exact -- $char {
             . { return "........" }
             / { return "////////" }
             0 { return "00000000" }
          }
          return ""
       }

The only thing you need to change is what is in the quotes. And you need to
change them to truely random numbers, not words! The length dosn't matter much
since the encryption dosn't take noticeably more time for a long key comparied 
to a short key. The limit though is 72 characters set by the encryption in
eggdrop. They shouldn't be any shorter then 8 characters as well.

Some good places to get random numbers on the internet is:

http://www.fourmilab.ch/hotbits/generate.html
random data generated by radioative decay. 
  returns only hexadecimal, example "1A4BD206309DA771C817"

http://lavarand.sgi.com/
seeds a pseudo-random number generator with the 7 way SHA-1 cryptographic 
  hash of a digitization of a chaotic system: the digital picture of 6 
  Lava Lite Lamps.

Another good method to get random data is to just randomly smash your keyboard,
makeing sure you get lowercase letters, uppercase letters, numbers, periods,
and forward slashes evenly mixed in your smashing. You dont want to include
any of the shifted numbers, backslash, braces, etc... just letters, numbers,
periods, and forward slashes are acceptable. Once you have alot of data entered
in break it up into chunks the number of characters long you want your keys. 
Then cut and paste into the tcl.

Still another method is to generate md5 sums or sha-1 digests of just random
letter junk in your eggdrop via the partyline commands:

.tcl md5 <junk>
.tcl sha <junk>

You wont be able to use the sha command if you didn't install my SHA-1 module.
Once you did that take the hashs and break them up into the size of chunks you 
want for your random data. 

Once you have your random text insterted into the tcl the proc should look like
this. Again shorted for an example.

       proc cop_getkey { char } {
          switch -exact -- $char {
             . { return "E95d30f5" }
             / { return "2fDBC8e5" }
             0 { return "2CbE64d9" }
          }
          return ""
       }


proc cop_getrand
----------------

* IT is recomended you use the getrandom.exe or getrandom.tcl to make this 
proc. Look above in the Install section for instructions on how to
use them.

This setting is changed exactly like the cop_getkey settings above. With one
minor difference. As you can see the example strings are much larger. This
text is inserted into the encrypted string and isn't used as a encryption key
thus it can be larger then a key would be. 

The random data is used to add another level of unpredictability to your cookie
generation. Making it much much harder for someone to even atempt to fake a 
valid cookie for your channel.


set cop_cookieorder
-------------------

Ok heres the fun part, this is where we set the order of the cookie elements
in your channels op cookies. There are seven differnt keywords that can be
switched arround and interchanged, each representing a type of data that will
be inserted into the cookie. The seven keywords are:

  NICKNAME = the nickname of the person being opped.
  NICKMASK = the hostmask of the person being opped.
  BOTNICK  = the nickname of the bot doing the op.
  BOTMASK  = the hostmask of the bot doing the op.
  CHANNEL  = the channel the op is taking place in.
  RANDOM   = one of the strings of random text (in proc cop_getrand).
  UNIXTIME = the timestamp.

This setting definatly should be changed from the default settings of:

set cop_cookieorder "NICKNAME NICKMASK BOTNICK BOTMASK CHANNEL RANDOM UNIXTIME"

You don't to include all seven keywords in your order, BUT, there is no reason
why you should omit any of them, in fact omitting some of them would weaken 
your cookie strength. So DO NOT omit any of these. They of course can be doubled
you dont have to have just one copy of each keyword in the string you can have
several copies of each if you want. Just a warning, the longer the string is
that your encrypting, the longer the encryption will take. So dont put 10 copys
of the RANDOM keyword in your string, that would result in a LONG string to
encrypt. 

NOTE: all keywords MUST remain capalized!


set cop_kickrsn
---------------

set the custom kick message you want to kick people with if you set 
protection level 7-13.


set cop_globalbans
------------------

should the bans performed during punishment be global or channel?
1 for global, 0 for channel


set cop_bantime
---------------

set the lifetime for bans to live, time is in minutes. Default is one year.
1 year = 525600 minutes
1 week = 10080 mins
1 day  = 1440 minutes


set cop_allownonop
------------------

Do you want to allow +o users to op people that are NOT +o uses via the dcc 
command .op?

  1 = yes
  0 = no

set cop_modestack
-----------------

set the max number of stacked modes your network allows? Like on efnet
its 4. (+oooo nick1 nick2 nick3 nick4), It is IMPORTANT, so set
this right!



>>>>>> MORE ADVANCED SETTING <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
 stop editing here unless you know what your doing!



set cop_usemsgop
----------------
Do you want the msg OP command enabled or not?
valid settings are: 1 is on, 0 is off.


set cop_cuthash
---------------

This is the length that the message digest should be choped too. The full 
length looks messy, default is 40 digits, and it shouldn't be made any smaller
then that. The max you should set it to is 60 which is the largest irc would 
ever allow a banmask.


set cop_gettimetimer
--------------------

The timer length to request the new time from an internet time server. 
to short and you may use to much cpu connecting to the timeserver over and 
over, the default of 20 minutes should be fine. The setting is of course in
minutes. You could even make this longer, and it wouldn't cause much of a
problem. Idealy you should only need to update your time once a day, a 
computer dosn't loose time fast enough to cause a problem with that.



set cop_maxdifference
---------------------

This is the maxium allowed difference in time from the timestamp in the
cookie used to op and the real time stored on the bots checking the cookie.

You MUST account for network lag, and set this accordingly. If your network
experinces alot of lag, like EFnet, then set this to many minutes. This 
setting is in seconds. And default is 10 minutes.


>>>>>>>> EXPERT SETTINGS <<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<<
  only beta testers should be messing in here, you've been warned!.


set cop_debug
-------------
turns on debuging output. Only should be used by beta testers, since normaly
you woulnd't want to see all of this.
1 = on, 0 = off

Default is on for this in the beta releases! So turn it off if you don't
want to see this and use the experimentals!

set cop_display
---------------
Controls how all output from script is displayed to the console flag +o via 
putlog. valid settings are:
  0 : script will have no output even on errors.
  1 : script will just display errors.
  2 : all regular output will be displayed including errors. (a lot of text)

This feature isn't used much, most of the output is in debug. Prolly i'll
migrate some of the messages into the cop_display at a later date.


set cop_usets
-------------

turn the time stamping feature on or off? by default it is on, and it is
recomened you use it, if you have problems then you can disable. But at
least see if it works for you! :-P
1 = on, 0 = off


set cop_usebotnet
-----------------
Do you want to use botnet commands, turn this on if you have a botnet, turn 
it off if its a stand alone bot. I guess not everyone links there bots.. heh
The commands that are turned on and off are:
   - the dcc commands: .cookiestat .forcetime and .synchtime
   - if connection to a timeserver fails the bots will ask for time from
     other bots on the botnet.
  
Valid settings:
  1 = to enable botnet commands and functions.
  0 = to totaly disable botnet commands and functions.


set cop_usedigest
-----------------

do you even want to use a message digest generator to make the cookies?
like SHA-1 or MD5? It is HIGHLY recomended you do, but some people might
not want too so i made this option.
 1 = to use a message digest
 0 = to just use the encrypted text as the cookie. Ignores all settings
     pretaining to message digests. 

note: that if you set this too 0 to not use a message digest, then at
the moment the way its setup is to just encrypt the preset string of
text set below with the encrypted cookie string (what would of been used
to generate a secure hash). Eggdrop only uses the first 72 chars of the
encryption password. So place the more random variable settings in 
the begining of the cop_cookieorder setting. like: UNIXTIME which is the
most random variable and should be the first element, the NICKMASK 
NICKNAME RANDOM are also quite variable and should be tward the front.
Don't put the BOTNICK BOTMASK CHANNEL in the begining since they are 
pretty much static.

I plan on putting a pretty decent no hash cookie function in the 
script soon, just haven't gotten arround to it yet. Since most people
prolly would want to use the secure hash as the cookie, much more SECURE.
:-P


set cop_nodigestpreset
----------------------

if you set cop_usedigest to 0 then you need to set this variable to a random
string of text. The encrypted form of the cookie is used as an encryption 
password to encrypt this text you set here. That is then used as the cookie.
it gives it a more random apperance, and dosn't require that you place
dynamic data at the beginning of the cookie sequence (cop_cookieorder).
 
you want this to be a decently long string, as long as the 
example or longer. It can be random text or a message, dosn't matter no
one will ever see it! :-P


set cop_usemd5
--------------
Set this if you want to manualy override the auto detect for the sha module
and use the md5 even if sha exists. It is recomened that you install the 
sha-1 module (http://kasslloyd.tripod.com/sha.html), valid settings are:
  1 = use md5 only
  0 = autodetect


set cop_indexorder
------------------

This is a meaningless setting that I put in, it specfies which index is first
in your cookie banmask. For deatails of what the indexs are visit 
http://kasslloyd.tripod.com/cookieopdetails2.html

Valid settings are:

  1 = encrypt index first, random index second
  0 = random index first, encrypt index second


Files included in release
-------------------------

README.TXT - this file
knownbugs.txt - a list of knownbugs that were not fixed by release time.

cookieop-A.tcl - the cookie op script

botnetop.tcl - a copy of slennox's botnetop v2.23 thats modified for cookie op.
getops.tcl - Getops 2.2f modified to use cookie op. 

rndstr.c - a unix c program to generate random strings of text
getrandom.exe - windows program made by killer-soft.de to make your key procs!
getrandom.tcl - a unix shell script to make your key procs from random data
                generated by Hotbits, truely random data from radioactive 
		decay!
