doc/challenge.txt

   1 ------------------------------------------------------
   2 -    Oper Challenge/Response System Documentation    -
   3 - Copyright (C) 2006 Lee Hardy <lee -at- leeh.co.uk> -
   4 - Copyright (C) 2006 ircd-ratbox development team    -
   5 ------------------------------------------------------
   6
   7 The challenge/response system allows the ability to oper though public key
   8 authentication, without the insecurity of oper passwords.
   9
  10 The challenge system documented here was redesigned in
  11 ircd-ratbox-2.2/charybdis-1.1 and is not compatible with earlier versions.
  12
  13 This document does not describe the technical details of the challenge
  14 system.  If you are reading this as part of the ircd distribution, the
  15 programs referred to are contained in ratbox-respond, see
  16 http://respond.ircd-ratbox.org for more information and downloads.
  17
  18
  19 - Challenge basics -
  20 --------------------
  21 When a user requests a challenge to oper up, the ircd takes some random
  22 data, encodes it using the opers public key, encodes this output in base64
  23 and sends it to the user as a challenge.  The server then stores a hash of
  24 the original random data.
  25
  26 The user must then decrypt the data using their private key and generate a
  27 hash of the decrypted data.  Then the hash is base64 encoded and sent back
  28 to the server.
  29
  30 If the stored hash the server has matches the reply from the client, they
  31 are opered up.
  32
  33
  34 - Generating a public/private keypair -
  35 ---------------------------------------
  36 The first step is to use the makekeypair script to generate a public and
  37 private key.  The public key is set in the ircd config (operator {};
  38 rsa_public_key_file) instead of a password, and the private key should
  39 be kept secret.  It is highly recommended that the key is generated with
  40 a secure password.  Generating keys without a password is fundamentally
  41 insecure.
  42
  43
  44 The commands used in makekeypair to generate keys are as follows:
  45         openssl genrsa -out private.key -aes256 2048
  46         openssl rsa -in private.key -out public.key -pubout
  47
  48 If aes256 is not available, the following is used instead:
  49         openssl genrsa -out private.key -des3 2048
  50
  51
  52 - Building ratbox-respond -
  53 ---------------------------
  54 If you are using the unix based ratbox-respond this must be built.  For the
  55 windows version, ratbox-winrespond, please see http://respond.ircd-ratbox.org
  56
  57 ratbox-respond takes the challenge from the server, and together with your
  58 private key file generates a response to be sent back.  ratbox-respond
  59 requires the openssl headers (ie, development files) and openssl libraries
  60 are installed for compilation.
  61
  62 Change into the ratbox-respond directory, and run:
  63         ./configure
  64         make
  65
  66 This will generate a 'ratbox-respond' binary, which you may place wherever
  67 you like.  If configure does not detect your openssl installation, you may
  68 pass it the directory where it is installed to via --enable-openssl, this
  69 should be the base directory which has lib/ and include/openssl/ within it:
  70         ./configure --enable-openssl=/path/to/opensslbase
  71
  72
  73 - Opering up -
  74 --------------
  75 Once you have your public key set in ircd and built ratbox-respond, you oper
  76 up by issuing "/challenge <opername>".  You should then run:
  77         /path/to/ratbox-respond /path/to/private.key
  78 and input the challenge.  This will give you a response to paste back to the
  79 server.  The ratbox-respond binary also accepts piped input, see
  80 ratbox-respond/README for more information.
  81
  82 A number of scripts for clients have already been written to automate this
  83 process, see client-scripts/README for more information.
  84
  85 --
  86 $Id: challenge.txt 678 2006-02-03 20:25:01Z jilles $