CHALLENGEAUTH and You

This document is aimed at script authors.

Author: Chris Porter <slug a t quakenet.org>

Last updated: 2008-03-23

Purpose

CHALLENGEAUTH allows you/your users to auth with Q without sending your/their passwords in cleartext.

Use

To start authing using CHALLENGEAUTH, you must first request a CHALLENGE from Q with /msg Q@CServe.quakenet.org CHALLENGE, you will then receive a response similar to:

-Q- CHALLENGE 3afabede5c2859fd821e315f889d9a6c HMAC-MD5 HMAC-SHA-1 HMAC-SHA-256 LEGACY-MD5

The red text is a randomly generated value that you should use in the response calculation (used to ensure freshness).

The blue text is a list of algorithms Q accepts for authentication, your script should provide one or more of these. Please note that LEGACY-MD5 will not be documented here as it is deprecated and liable to be removed at any time.

In order to begin sending the response you should first convert the username to lowercase (using standard RFC1459 lowercasing) and truncate the password to 10 characters, you must also select an algorithm that is in the list Q supplied (note all hashes here are returning the digest in hexadecimal).

First calculate the key:

• key = HASH("<username>:" + HASH("<password>"))

This key is then used in the HMAC construction, as specified in RFC 2104:

• response = HMAC-HASH(data){key}

This response can then be sent to Q with: /msg Q@CServe.quakenet.org CHALLENGEAUTH <username> <response> <algorithm>

Worked example with HMAC-SHA-1

My username is [fishking], my password is iLOVEfish12345, I've received the challenge 3afabede5c2859fd821e315f889d9a6c from Q.

• challenge = "3afabede5c2859fd821e315f889d9a6c"
• lowercase_username = "{fishking}"
• truncated_password = "iLOVEfish1"
• password_hash = SHA-1("<truncated password>")
• password_hash = SHA-1("iLOVEfish1")
• password_hash = "15ccbbd456d321ef98fa1b58e724828619b6066e"
• key = SHA-1("<lowercase username>:<password hash>")
• key = SHA-1("{fishking}:15ccbbd456d321ef98fa1b58e724828619b6066e")
• key = "c05587aeb231e8f90a2df8bc66142c2a8b1be908"
• response = HMAC-SHA-1("<challenge>"){"<key>"}
• response = HMAC-SHA-1("3afabede5c2859fd821e315f889d9a6c"){"c05587aeb231e8f90a2df8bc66142c2a8b1be908"}
• response = "e683c83fd16a03b6d690ea231b4f346c32ae0aaa"
• /msg Q@CServe.quakenet.org CHALLENGEAUTH [fishking] e683c83fd16a03b6d690ea231b4f346c32ae0aaa HMAC-SHA-1

Test vectors

These test vectors have been generated using the following python code:

import hmac, hashlib
def challengeauth(lcusername, truncpassword, challenge, digest=hashlib.sha256):
  return hmac.HMAC(digest("%s:%s" % (lcusername, digest(truncpassword).hexdigest())).hexdigest(), challenge, digestmod=digest).hexdigest()

HMAC-MD5

• challengeauth("mooking", "0000000000", "12345678901234567890123456789012", hashlib.md5) = '2ed1a1f1d2cd5487d2e18f27213286b9'
• challengeauth("fishking", "ZZZZZZZZZZ", "12345678901234567890123456789012", hashlib.md5) = '8990cb478218b6c0063daf08dd7e1a72'

HMAC-SHA-1

• challengeauth("mooking", "0000000000", "12345678901234567890123456789012", hashlib.sha1) = 'd0328d41426bd2ace183467ce0a6305445e3d497'
• challengeauth("fishking", "ZZZZZZZZZZ", "12345678901234567890123456789012", hashlib.sha1) = '4de3f1c86dd0f59da44852d507e193c339c4b108'

HMAC-SHA-256

• challengeauth("mooking", "0000000000", "12345678901234567890123456789012", hashlib.sha256) = 'f6eced34321a69c270472d06c50e959c48e9fd323b2c5d3194f44b50a118a7ea'
• challengeauth("fishking", "ZZZZZZZZZZ", "12345678901234567890123456789012", hashlib.sha256) = '504056d53b2fc4fd783dc4f086dabc59f845d201e650b96dfa95dacc8cac2892'

Implementations

mIRC

#help.script is maintaining a script using HMAC-SHA1 at http://script.quakenet.org/wiki/Challenge_auth.

Irssi

Available here.

Note you must have preferably Digest::SHA installed, though Digest::SHA1 or Digest::MD5 will also work.

You can set the script to only auth using a specific digest with /set secureqauth_restrict_digest.

Others

Please feel free to send other implementations to slug a t quakenet.org.