* 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
/* 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)
{
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)
{
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)
{
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)
{
* 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
#include <crypt.h>
#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);
* 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"
#include <assert.h>
#include <unistd.h>
-/* 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);
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;
* 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 <assert.h>
-#include <string.h>
-#include <unistd.h>
-
-/*
+
+/**
+ * @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
* ----------------------------------------------------------------------------
*
*/
+#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 <assert.h>
+#include <string.h>
+#include <unistd.h>
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) {
}
}
+/** 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$";
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;
/* 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;