From: hikari Date: Tue, 21 Sep 2004 15:11:25 +0000 (+0000) Subject: Author: hikari X-Git-Url: http://git.pk910.de/?a=commitdiff_plain;h=e0a020efc1a38766bbb8d53ef8cf766cbb1c41c2;p=ircu2.10.12-pk.git Author: hikari Log message: Added doxygen compatible coments to ircd/ircd_crypt*.c - join the party! The whole source tree needs doing, header files included. bb hikari git-svn-id: file:///home/klmitch/undernet-ircu/undernet-ircu-svn/ircu2/trunk@1156 c9e4aea6-c8fd-4c43-8297-357d70d61c8c --- diff --git a/ircd/ircd_crypt.c b/ircd/ircd_crypt.c index 3f222bc..e64ff13 100644 --- a/ircd/ircd_crypt.c +++ b/ircd/ircd_crypt.c @@ -16,13 +16,16 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. * - * $Id$ */ -/* +/** + * @file + * @brief Core password encryption routines. + * @version $Id$ + * * This is a new look crypto API for ircu, it can handle different - * password formats by the grace of the standard magic tokens at the - * begining of the password e.g. $1 for MD5, $2 for Blowfish, etc. + * password formats by the grace of magic tokens at the begining of the + * password e.g. $SMD5 for Salted MD5, $CRYPT for native crypt(), etc. * * Currently crypt routines are implemented for: the native crypt() * function, Salted MD5 and a plain text mechanism which should only @@ -59,8 +62,12 @@ /* evil global */ crypt_mechs_t* crypt_mechs_root; -/* - * add a crypt mechanism to the list +/** Add a crypt mechanism to the list + * @param mechanism Pointer to the mechanism details struct + * @return 0 on success, anything else on fail. + * + * This routine registers a new crypt mechanism in the loaded mechanisms list, + * making it availabe for comparing passwords. */ int ircd_crypt_register_mech(crypt_mech_t* mechanism) { @@ -101,8 +108,9 @@ crypt_mechs_t* crypt_mech; return 0; } -/* - * remove a crypt mechanism from the list +/** Remove a crypt mechanism from the list + * @param Pointer to the mechanism we want to remove + * @return 0 on success, anything else on fail. */ int ircd_crypt_unregister_mech(crypt_mech_t* mechanism) { @@ -110,9 +118,14 @@ int ircd_crypt_unregister_mech(crypt_mech_t* mechanism) return 0; } -/* - * this is now a wrapper function which attempts to establish the password - * format and funnel it off to the correct handler function. +/** Wrapper for generating a hashed password passed on the supplied password + * @param key Pointer to the password we want crypted + * @param salt Pointer to the password we're comparing to (for the salt) + * @return Pointer to the generated password. + * + * This is a wrapper function which attempts to establish the password + * format and funnel it off to the correct mechanism handler function. The + * returned password is compared in the oper_password_match() routine. */ const char* ircd_crypt(const char* key, const char* salt) { @@ -196,9 +209,14 @@ crypt_mechs_t* crypt_mech; return NULL; } -/* - * some basic init, when we're modular this will be our entry - * function. +/** Some basic init. + * This function loads initalises the crypt mechanisms linked list and + * currently loads the default mechanisms (Salted MD5, Crypt() and PLAIN). + * The last step is only needed while ircu is not properly modular. + * + * When ircu is modular this will be the entry function for the ircd_crypt + * module. + * */ void ircd_crypt_init(void) { diff --git a/ircd/ircd_crypt_native.c b/ircd/ircd_crypt_native.c index 02a1708..1b1037c 100644 --- a/ircd/ircd_crypt_native.c +++ b/ircd/ircd_crypt_native.c @@ -15,8 +15,15 @@ * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. - * - * $Id$ + */ +/** + * @file + * @brief Native crypt() function routines + * @version $Id$ + * + * Routines for handling passwords encrypted with the system's native crypt() + * function (typicaly a DES encryption routine, but can be anything nowdays). + * */ #define _XOPEN_SOURCE #define _XOPEN_VERSION 4 @@ -33,7 +40,16 @@ #include #endif -/* well this bit is (kinda) intact :) -- hikari */ +/** Simple routine that just calls crypt() with the supplied password and salt + * @param key The password we're encrypting. + * @param salt The salt we're using to encrypt key + * @reutrn The encrypted password. + * + * Well this bit is (kinda) intact from the original oper password routines :) + * It's a very simple wrapper routine that just calls crypt and returns the + * result. + * -- hikari + */ const char* ircd_crypt_native(const char* key, const char* salt) { assert(NULL != key); diff --git a/ircd/ircd_crypt_plain.c b/ircd/ircd_crypt_plain.c index 5cb5965..4050a52 100644 --- a/ircd/ircd_crypt_plain.c +++ b/ircd/ircd_crypt_plain.c @@ -16,7 +16,13 @@ * along with this program; if not, write to the Free Software * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. * - * $Id$ + */ +/* + * @file + * @brief Routines for PLAIN passwords + * @version $Id$ + * + * PLAIN text encryption. Oxymoron and a half that. */ #include "config.h" #include "ircd_crypt.h" @@ -27,7 +33,16 @@ #include #include -/* yes I know it's an oxymoron, but still, it's handy for testing */ +/** Just sends back the supplied password. + * @param key The password + * @param salt The salt + * @return The password + * + * Yes I know it's an oxymoron, but still, it's handy for testing. + * + * What you need more help with seeing what this does? + * + */ const char* ircd_crypt_plain(const char* key, const char* salt) { assert(NULL != salt); @@ -41,7 +56,11 @@ const char* ircd_crypt_plain(const char* key, const char* salt) return key; } -/* register ourself with the list of crypt mechanisms -- hikari */ +/** register ourself with the list of crypt mechanisms + * Registers the PLAIN mechanism in the list of available crypt mechanisms. + * When we're modular this will be the entry function for the module. + * + * -- hikari */ void ircd_register_crypt_plain(void) { crypt_mech_t* crypt_mech; diff --git a/ircd/ircd_crypt_smd5.c b/ircd/ircd_crypt_smd5.c index a5d3650..3df750a 100644 --- a/ircd/ircd_crypt_smd5.c +++ b/ircd/ircd_crypt_smd5.c @@ -15,21 +15,13 @@ * You should have received a copy of the GNU General Public License * along with this program; if not, write to the Free Software * Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA. - * - * $Id$ */ -#include "config.h" -#include "ircd_crypt.h" -#include "ircd_crypt_smd5.h" -#include "ircd_md5.h" -#include "s_debug.h" -#include "ircd_alloc.h" - -#include -#include -#include - -/* + +/** + * @file + * @brief Routines for Salted MD5 passwords + * @version $Id$ + * * ircd_crypt_smd5 is largely taken from md5_crypt.c from the Linux PAM * source code. it's been modified to fit in with ircu and some of the * undeeded code has been removed. the source file md5_crypt.c has the @@ -44,10 +36,30 @@ * ---------------------------------------------------------------------------- * */ +#include "config.h" +#include "ircd_crypt.h" +#include "ircd_crypt_smd5.h" +#include "ircd_md5.h" +#include "s_debug.h" +#include "ircd_alloc.h" + +#include +#include +#include static unsigned char itoa64[] = /* 0 ... 63 => ascii - 64 */ "./0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"; +/** Converts a binary value into a BASE64 encoded string. + * @param s Pointer to the output string + * @param v The unsigned long we're working on + * @param n The number of bytes we're working with + * + * This is used to produce the normal MD5 hash everyone is familar with. + * It takes the value v and converts n bytes of it it into an ASCII string in + * 6-bit chunks, the resulting string is put at the address pointed to by s. + * + */ static void to64(char *s, unsigned long v, int n) { while (--n >= 0) { @@ -56,6 +68,18 @@ static void to64(char *s, unsigned long v, int n) } } +/** Produces a Salted MD5 crypt of a password using the supplied salt + * @param key The password we're encrypting + * @param salt The salt we're using to encrypt it + * @return The Salted MD5 password of key and salt + * + * Erm does exactly what the brief comment says. If you think I'm writing a + * description of how MD5 works, you have another thing comming. Go and read + * Applied Cryptopgraphy by Bruce Schneier. The only difference is we use a + * salt at the begining of the password to perturb it so that the same password + * doesn't always produce the same hash. + * + */ const char* ircd_crypt_smd5(const char* key, const char* salt) { const char *magic = "$1$"; @@ -155,6 +179,8 @@ unsigned long l; Debug((DEBUG_DEBUG, "passwd = %s", passwd)); + /* Turn the encrypted binary data into a BASE64 encoded string we can read + * and display -- hikari */ l = (final[0] << 16) | (final[6] << 8) | final[12]; to64(p, l, 4); p += 4; @@ -183,7 +209,11 @@ return passwd; /* end borrowed code */ -/* register ourself with the list of crypt mechanisms */ +/** Register ourself with the list of crypt mechanisms + * Registers the SMD5 mechanism in the list of available crypt mechanisms. When + * we're modular this will be the entry function for the module. + * + */ void ircd_register_crypt_smd5(void) { crypt_mech_t* crypt_mech;