8.1.x/doc/challenge.txt

                       Oper Challenge and Response System

   $Id$

   Copyright (c) 2001-2005 by ircd-hybrid team

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

   ircd-hybrid

   In an effort to reduce the damage caused to a network by a hacked O-line,
   Hybrid supports an OpenSSL based challenge-response system. This new
   system allows the admin to remove all oper block passwords from the conf
   file. Authentication is done through a public/private key.

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

                                  Requirements

   The ircd must be compiled with the --enable-openssl option to configure .
   If configure detects a working openssl library, --enable-openssl is
   implicitly enabled.

   oper {} blocks should not have normal passwords, but should contain the
   the name of the private key file. However it is possible for the user to
   use both challenge and normal passwords, but this would defeat the purpose
   of the challenge system.

   m_challenge.so must be loaded.

   The oper has their private key file and an implementation of the RSA
   Respond tool available to be run.

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

                                    Process

   Each oper should have a private key file and a public key file. The keys
   can be generated with the mkkeypair utility provided in tools/. The keys
   are compatible with cryptlink keys.

   The oper keeps their private key file in a safe place, and gives their
   public key file to their admin(s).

   The admin will place an entry for the public key file into a field called
   rsa_public_key_file of each oper's oper {} block in the conf file.

   The oper wishes to obtain their operator status, and issues the CHALLENGE
   command.

   The server will print out a long hexadecimal string, that needs to be fed
   to the respond utility provided in tools/rsa_respond.

   The respond program will generate an answer that is fed back to the
   CHALLENGE command.

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

                            Generating the Key Files

   The keys can be generated with the openssl command as follows:

       openssl genrsa -des3(1) -out rsa.key 1024(2)
       openssl rsa -in rsa.key -pubout -out rsa.pub
   

   (1)
           The -des3 must be included in order to create a key with a
           passphrase. Omitting this option will create a non protected key.
   (2)
           The key size must be 1024 or below. The challenge sent for a
           longer keysize will be too long to fit into the ircd's 512 byte
           line constraint.

   It is highly recommended that you set a password on your private key.

   The tools/mkkeypair utility cannot be used to create a key suitable for
   use in CHALLENGE.

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

                          Using CHALLENGE and respond

     Note: All examples assume the use of the stock respond client included
     with the Hybrid 7 source, run on a UNIX(c) platform.

   The administrator of the server you oper on should remove the password in
   your oper {} block and replace it with an entry for your public key, so
   that /oper will be disabled.

     Note: The public key is a VERY long string.

   The oper will issue /challenge oper_nick, and see something like below:

 *** 56F1FDAE4C590C524CF758917E62C2A2A1376CB9C4C2E7D411BB0AD9C4A
 605A2D05A94E7254197E9D71438B5FB565B6FD35465E462305F35F4A2D45311
 F983B3E062F635912FA155B4B1E18EAA782CC107F4C9DA83092658D16A2E88A
 6BCF9820F5A044A29CDD4C062F05BF509CA3B561375CBC4179BD1CF6026BDE9
 60E52C6B

     Note: The challenge is all on one line.

     Note: With some clients, the oper will have to issue /quote CHALLENGE
     instead of /challenge.

   The oper will then have to feed that challenge to the respond program.

   +------------------------------------------------------------------+
   | The respond utility's syntax is:                                 |
   |                                                                  |
   |$ ./respond private_key_file challenge_from_server                |
   |                                                                  |
   |                                                                  |
   | Example:                                                         |
   |                                                                  |
   |wcampbel@botbay (rsa_respond): ./respond hwy.key \                |
   |56F1FDAE4C590C524CF758917E62C2A2A1376CB9C4C2E7D411BB0AD9C4A605A2D0|
   |5A94E7254197E9D71438B5FB565B6FD35465E462305F35F4A2D45311F983B3E062|
   |F635912FA155B4B1E18EAA782CC107F4C9DA83092658D16A2E88A6BCF9820F5A04|
   |4A29CDD4C062F05BF509CA3B561375CBC4179BD1CF6026BDE960E52C6B        |
   |Keyphrase:                                                        |
   |6B882932DD00F86123869E401F7334B9B0D0018A60F1DE244E90E47246AA87C7  |
   |                                                                  |
   |   Note: The challenge parameter must be on one line.             |
   +------------------------------------------------------------------+

   The keyphrase must be entered properly to get the response. The bottom
   line is the response that must be sent back to the server.

   The oper will issue the following command in order to obtain operator
   status:

   /challenge
   +6B882932DD00F86123869E401F7334B9B0D0018A60F1DE244E90E47246AA87C7

     Note: The '+' is needed

   If successful, the oper will obtain operator status on the server.

   +------------------------------------------------------------------------+
   |                                Warning                                 |
   |------------------------------------------------------------------------|
   | If the CHALLENGE fails, and you use ircII, EPIC, or BX, you may get    |
   | disconnected with the client asking for the server password. This is a |
   | client bug, not an ircd bug.                                           |
   +------------------------------------------------------------------------+

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

                                RSA Respond Tool

   The RSA Respond tool is a vital part of challenge/response system. In
   order to function, the operator must have must have a way to quickly issue
   the respond command, and to copy and paste data to and from the IRC
   client.

   The respond source code is included with the Hybrid 7 source, in the
   tools/rsa_respond directory. A distributable tar file can easily be
   created by issuing make rsa_respond in the root of the source tree. The
   file rsa_respond.tar.gz will be created in the root of the source tree.

   rsa_respond.tar.gz should compile with little or no modifications[1] on
   most UNIX(c) and UNIX-like platforms[2]. The README in the tar archive
   gives more information.

   A copy of the source tar file is available on
   http://www.wohmart.com/ircd/pub/irc_tools/rsa/rsa_respond-src-hyb7.tar.gz

   For Windows platforms, there are two available RSA Respond tools. One is a
   text only port of the stock tool. The binary is available from
   http://www.wohmart.com/ircd/pub/irc_tools/rsa/rsa_respond-bin.tar.gz.
   The other tool is a GUI enabled version[3]. The source tree[4] is available
   from http://www.wohmart.com/ircd/pub/irc_tools/rsa/winrespond-src.tar.gz.
   A binary distribution is available from
   http://www.wohmart.com/ircd/pub/irc_tools/rsa/winrespond-bin.tar.gz.

   With the appropriate version of the RSA Respond tool, any operator can
   protect their privileged access to the server, with little additional
   effort over using standard operator passwords.

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

                                    Benefits

   The greatest benefit of using the challenge/response system is that there
   are no passwords sent over the network in plaintext. There are also no
   credentials left on the server side, as only public keys are kept in the
   conf. The use of public/private key encryption provides far greater
   security over having a single password, and may (if the key is kept
   secure, and has a good passphrase) virtually eliminate hacked O-lines.

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

                                  A. Numerics

 :server 381 user :You have entered... the Twilight Zone!.
 :server 386 user :challenge-text
 :server 464 user :Password Incorrect
 :server 491 user :Only few of mere mortals may try to enter the twilight zone


     Note: The text used can be changed by the server administrator.

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

                                  B. Scripting

   The following script is for EPIC 4 only. It was written by Greg Prosser,
   xyst <gregp@blackened.net>.

   Please note that passphrase protected keys cannot be used in conjunction
   with this script.

   The script is called challange.irc and sits in contrib/. Please review
   it for more details.

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

                                       Notes

   [1] Some platforms may require Makefile changes in order to link in the    
       OpenSSL library. This may change in the future.                        
   [2] Platforms known to function include: Linux, FreeBSD, Solaris, and      
       Cygwin.                                                                
   [3] A screenshot of the program is available on                            
       http://www.wohmart.com/ircd/pub/irc_tools/rsa/winrespond.png .                               
   [4] The winrespond source depends on a working, up to date, Cygwin         
       installation.
Revision:	1028
Committed:	Sun Nov 8 13:03:38 2009 UTC (16 years, 8 months ago) by michael
Content type:	text/plain
Original Path:	*ircd-hybrid/doc/challenge.txt*
File size:	9999 byte(s)
Log Message:	- move ircd-hybrid-7.2 to trunk
#	User	Rev	Content
1	adx	30	Oper Challenge and Response System
2
3	knight	31	$Id$
4	adx	30
5			Copyright (c) 2001-2005 by ircd-hybrid team
6
7			----------------------------------------------------------------------
8
9			ircd-hybrid
10
11			In an effort to reduce the damage caused to a network by a hacked O-line,
12			Hybrid supports an OpenSSL based challenge-response system. This new
13			system allows the admin to remove all oper block passwords from the conf
14			file. Authentication is done through a public/private key.
15
16			----------------------------------------------------------------------
17
18			Requirements
19
20			The ircd must be compiled with the --enable-openssl option to configure .
21			If configure detects a working openssl library, --enable-openssl is
22			implicitly enabled.
23
24			oper {} blocks should not have normal passwords, but should contain the
25			the name of the private key file. However it is possible for the user to
26			use both challenge and normal passwords, but this would defeat the purpose
27			of the challenge system.
28
29			m_challenge.so must be loaded.
30
31			The oper has their private key file and an implementation of the RSA
32			Respond tool available to be run.
33
34			----------------------------------------------------------------------
35
36			Process
37
38			Each oper should have a private key file and a public key file. The keys
39			can be generated with the mkkeypair utility provided in tools/. The keys
40			are compatible with cryptlink keys.
41
42			The oper keeps their private key file in a safe place, and gives their
43			public key file to their admin(s).
44
45			The admin will place an entry for the public key file into a field called
46			rsa_public_key_file of each oper's oper {} block in the conf file.
47
48			The oper wishes to obtain their operator status, and issues the CHALLENGE
49			command.
50
51			The server will print out a long hexadecimal string, that needs to be fed
52			to the respond utility provided in tools/rsa_respond.
53
54			The respond program will generate an answer that is fed back to the
55			CHALLENGE command.
56
57			----------------------------------------------------------------------
58
59			Generating the Key Files
60
61			The keys can be generated with the openssl command as follows:
62
63			openssl genrsa -des3(1) -out rsa.key 1024(2)
64			openssl rsa -in rsa.key -pubout -out rsa.pub
65
66
67			(1)
68			The -des3 must be included in order to create a key with a
69			passphrase. Omitting this option will create a non protected key.
70			(2)
71			The key size must be 1024 or below. The challenge sent for a
72			longer keysize will be too long to fit into the ircd's 512 byte
73			line constraint.
74
75			It is highly recommended that you set a password on your private key.
76
77			The tools/mkkeypair utility cannot be used to create a key suitable for
78			use in CHALLENGE.
79
80			----------------------------------------------------------------------
81
82			Using CHALLENGE and respond
83
84			Note: All examples assume the use of the stock respond client included
85			with the Hybrid 7 source, run on a UNIX(c) platform.
86
87			The administrator of the server you oper on should remove the password in
88			your oper {} block and replace it with an entry for your public key, so
89			that /oper will be disabled.
90
91			Note: The public key is a VERY long string.
92
93			The oper will issue /challenge oper_nick, and see something like below:
94
95			*** 56F1FDAE4C590C524CF758917E62C2A2A1376CB9C4C2E7D411BB0AD9C4A
96			605A2D05A94E7254197E9D71438B5FB565B6FD35465E462305F35F4A2D45311
97			F983B3E062F635912FA155B4B1E18EAA782CC107F4C9DA83092658D16A2E88A
98			6BCF9820F5A044A29CDD4C062F05BF509CA3B561375CBC4179BD1CF6026BDE9
99			60E52C6B
100
101			Note: The challenge is all on one line.
102
103			Note: With some clients, the oper will have to issue /quote CHALLENGE
104			instead of /challenge.
105
106			The oper will then have to feed that challenge to the respond program.
107
108			+------------------------------------------------------------------+
109			\| The respond utility's syntax is: \|
110			\| \|
111			\|$ ./respond private_key_file challenge_from_server \|
112			\| \|
113			\| \|
114			\| Example: \|
115			\| \|
116			\|wcampbel@botbay (rsa_respond): ./respond hwy.key \ \|
117			\|56F1FDAE4C590C524CF758917E62C2A2A1376CB9C4C2E7D411BB0AD9C4A605A2D0\|
118			\|5A94E7254197E9D71438B5FB565B6FD35465E462305F35F4A2D45311F983B3E062\|
119			\|F635912FA155B4B1E18EAA782CC107F4C9DA83092658D16A2E88A6BCF9820F5A04\|
120			\|4A29CDD4C062F05BF509CA3B561375CBC4179BD1CF6026BDE960E52C6B \|
121			\|Keyphrase: \|
122			\|6B882932DD00F86123869E401F7334B9B0D0018A60F1DE244E90E47246AA87C7 \|
123			\| \|
124			\| Note: The challenge parameter must be on one line. \|
125			+------------------------------------------------------------------+
126
127			The keyphrase must be entered properly to get the response. The bottom
128			line is the response that must be sent back to the server.
129
130			The oper will issue the following command in order to obtain operator
131			status:
132
133			/challenge
134			+6B882932DD00F86123869E401F7334B9B0D0018A60F1DE244E90E47246AA87C7
135
136			Note: The '+' is needed
137
138			If successful, the oper will obtain operator status on the server.
139
140			+------------------------------------------------------------------------+
141			\| Warning \|
142			\|------------------------------------------------------------------------\|
143			\| If the CHALLENGE fails, and you use ircII, EPIC, or BX, you may get \|
144			\| disconnected with the client asking for the server password. This is a \|
145			\| client bug, not an ircd bug. \|
146			+------------------------------------------------------------------------+
147
148			----------------------------------------------------------------------
149
150			RSA Respond Tool
151
152			The RSA Respond tool is a vital part of challenge/response system. In
153			order to function, the operator must have must have a way to quickly issue
154			the respond command, and to copy and paste data to and from the IRC
155			client.
156
157			The respond source code is included with the Hybrid 7 source, in the
158			tools/rsa_respond directory. A distributable tar file can easily be
159			created by issuing make rsa_respond in the root of the source tree. The
160			file rsa_respond.tar.gz will be created in the root of the source tree.
161
162			rsa_respond.tar.gz should compile with little or no modifications[1] on
163			most UNIX(c) and UNIX-like platforms[2]. The README in the tar archive
164			gives more information.
165
166			A copy of the source tar file is available on
167			http://www.wohmart.com/ircd/pub/irc_tools/rsa/rsa_respond-src-hyb7.tar.gz
168
169			For Windows platforms, there are two available RSA Respond tools. One is a
170			text only port of the stock tool. The binary is available from
171			http://www.wohmart.com/ircd/pub/irc_tools/rsa/rsa_respond-bin.tar.gz.
172			The other tool is a GUI enabled version[3]. The source tree[4] is available
173			from http://www.wohmart.com/ircd/pub/irc_tools/rsa/winrespond-src.tar.gz.
174			A binary distribution is available from
175			http://www.wohmart.com/ircd/pub/irc_tools/rsa/winrespond-bin.tar.gz.
176
177			With the appropriate version of the RSA Respond tool, any operator can
178			protect their privileged access to the server, with little additional
179			effort over using standard operator passwords.
180
181			----------------------------------------------------------------------
182
183			Benefits
184
185			The greatest benefit of using the challenge/response system is that there
186			are no passwords sent over the network in plaintext. There are also no
187			credentials left on the server side, as only public keys are kept in the
188			conf. The use of public/private key encryption provides far greater
189			security over having a single password, and may (if the key is kept
190			secure, and has a good passphrase) virtually eliminate hacked O-lines.
191
192			----------------------------------------------------------------------
193
194			A. Numerics
195
196			:server 381 user :You have entered... the Twilight Zone!.
197			:server 386 user :challenge-text
198			:server 464 user :Password Incorrect
199			:server 491 user :Only few of mere mortals may try to enter the twilight zone
200
201
202			Note: The text used can be changed by the server administrator.
203
204			----------------------------------------------------------------------
205
206			B. Scripting
207
208			The following script is for EPIC 4 only. It was written by Greg Prosser,
209			xyst <gregp@blackened.net>.
210
211			Please note that passphrase protected keys cannot be used in conjunction
212			with this script.
213
214			The script is called challange.irc and sits in contrib/. Please review
215			it for more details.
216
217			----------------------------------------------------------------------
218
219			Notes
220
221			[1] Some platforms may require Makefile changes in order to link in the
222			OpenSSL library. This may change in the future.
223			[2] Platforms known to function include: Linux, FreeBSD, Solaris, and
224			Cygwin.
225			[3] A screenshot of the program is available on
226			http://www.wohmart.com/ircd/pub/irc_tools/rsa/winrespond.png .
227			[4] The winrespond source depends on a working, up to date, Cygwin
228			installation.