Any violation to this guide is allowed if it enhances readability.

Guidelines in this document are informed by discussions carried out among the Dojo core developers. The most weight has been given to considerations that impact external developer interaction with Dojo code and APIs. Rules such as whitespace placement are of a much lower order importance fo Dojo developers, but should be followed in the main in order to improve developer coordination.

Table of core API naming constructs:

Table of constructs that are not visible in the API, and therefore are optional and carry less weight of enforcement.

1. Names representing packages SHOULD be in all lower case.
2. Names representing types (classes) MUST be nouns and written in UpperLower case:

   Account, EventHandler
   	

3. Constants SHOULD be placed within a single object created as a holder for constants, emulating an Enum; the enum SHOULD be named appropriately, and members SHOULD be named using either UpperLower or UPPER_LOWER case:

   var NodeTypes = {
   	Element: 1,
   	DOCUMENT: 2
   }
   	

4. Abbreviations and acronyms SHOULD NOT be uppercase when used as a name:

   getInnerHtml(), getXml(), XmlDocument
   	

5. Names representing methods SHOULD be verbs or verb phrases:

   obj.getSomeValue();
   	

6. Public class variables MUST be written using upperLower case.
7. Private class variables MAY be written using _upperLower (with preceding underscore):

   var MyClass = function() {
   	var _buffer;
   	this.doSomething = function() {
   	};
   }
   	

8. Variables that are intended to be private, but cannot be based on the semantics of Javascript, SHOULD prepended with a "_" (underscore) char:

   this._somePrivateVariable = statement;
   	

   NB Note that the above variable also follows the convention for a private variable.
9. Generic variables SHOULD have the same name as their type:

   setTopic(topic);	// where topic isTypeOf Topic
   	

10. All names SHOULD be written in English.
11. Variables with a large scope SHOULD have globally unambiguious names, ambiguity MAY be distinguished by package membership. Variables with small or private scope MAY be more terse still.
12. The name of the return object is implicit, and SHOULD be avoided in a method name:

    getHandler();	// NOT getEventHandler();
    	

13. Public names SHOULD be as clear as necessary and SHOULD avoid unclear shortenings and contractions:

    MouseEventHandler	// NOT MseEvtHdlr.
    	

    Note that, again, any context that can be determined by package membership SHOULD be used when determing if a variable name is clear. For example, a class that represents a mouse event handler:

    myobj.events.mouse.Handler	// NOT myobj.events.mouse.MouseEventHandler
    	

14. Classes/constructors MAY be named basedon their inheritance pattern, with the base class to the right of the name:

    EventHandler
    UIEventHandler
    MouseEventHandler
    	

    NB The base class CAN be dropped from a name if it is obviously implicit in the name:

    MouseEventHandler	// as opposed to MouseUIEventHandler
    	

1. Ther terms get/set SHOULD NOT used where a field is accessed, unless the variable being accessed is lexically private.
2. "is" prefix SHOULD be used for boolean variables and methods.
   NB, Alternatives include "has", "can" and "should".
3. The term "compute" CAN be used in methods where something is computed.
4. The term "find" CAN be used in methods where something is looked up.
5. Ther terms "initialize" or "init" CAN be used where an object or a concept is established.
6. UI Control variables SHOULD be suffixed by the control type, ie: leftComboBox, topScrollPane.
7. Plural form MUST be used to name collections.
8. "num" prefix or "count" postfix SHOULD be used for variables representing a number of objects.
9. Iterator variables SHOULD be called "i", "j", "k", etc.
10. Compliment names MUST be used for compliment entities. ie: get/set, add/remove, create/destroy, start/stop, insert/delete, begin/end, etc.
11. Abbreviations in names SHOULD be avoided.
12. Negated boolean variable names MUST be avoided:

    isNotError	// are UNACCEPTABLE
    	

13. Exception classes SHOULD be suffixed with "Exception" or "Error"...FIXME (trt) not sure about this?
14. Methods returning an object MAY be named after what they return, and methods returning void after what they do.

1. Class or object-per-file guidelines are not yet determined.
2. Tabs (set to 4 spaces) SHOULD be used for indentation.
3. If your editor supports "file tags", please append the appropriate tag at the end of the file enable others to effortlessly obey the correct indentation guidelines for that file

   // vim:ts=4:note:tw=0:
   	

4. The incompletenes of split line MUST be made obvious:

   var someExpression = Expression1
   	+ Expression2
   	+ Expression3;
   	
   var o = someObject.get (
   		Expression1,
   		Expression2,
   		Expression3
   	);
   	

   Note the indentation for expression continuation is indented relative to the variable name, while indentation for parameters is relative to the method being called.
   
   Note also the position of the parenthesis in the method call; positioning SHOULD be similar to the use of block notation.

1. Variables SHOULD be initialized where they are declared and they SHOULD be declared in the smallest scope possible. A null initialization is acceptable.
2. Variables MUST never have a dual meaning.
3. Related variables of the same type CAN be declared in a common statement; unrelated variables SHOULD NOT be declared in the same statement.
4. Variables SHOULD be kept alive for a short a time as possible.
5. Loops/iterative declarations
   1. Only loop control statements MUST be included in the "for()" construction.
   2. Loop variables SHOULD be initialized immediately before the loop; loop variables in a "for" statement MAY be initialized in the "for" loop construction.
   3. The use of "do...while" loops are acceptable (unlike in java)
   4. The use of "break" and "continue" is not discouraged (unlike in Java)
6. Conditionals
   1. Complex conditional expressions SHOULD be avoided; use temporary boolean variables instead.
   2. The nominal case SHOULD be put in the "if" part and the exception in the "else" part of an "if" statement.
   3. Executable statements in conditionals MUST be avoided.
7. Miscellaneous
   1. The use of magic numbers in the code SHOULD be avoided; they SHOULD be declared using named "constants" instead.
   2. Floating point constants SHOULD ALWAYS be written with decimal point ant at least one decimal.
   3. Floating point constants SHOULD ALWAYS be written with a digit before the decimal point.

1. Block statements
   1. Block layout SHOULD BE as illustrated below:

      while(!isDone) {
      	doSomething();
      	isDone = moreToDo();
      }
      				

   2. If statements SHOULD have the following form:

      if(someCondition) {
      	statements;
      } else if(someOtherCondition) {
      	statements;
      } else {
      	statements;
      }
      				

   3. for statements SHOULD be have the following form:

      for(initialization; condition; update) {
      	statements;
      }
      				

   4. while statement SHOULD follow the form in example VI.A.1
   5. a do...while statement SHOULD have the following form:

      do {
      	statements;
      } while(condition);
      				

   6. a switch statement SHOULD have the following form:

      switch(condition) {
      	case ABC:
      		statements;
      		// fall through
      	case DEF:
      		statements;
      		break;
      	default:
      		statements;
      		break;
      }
      				

   7. a try...catch...finally statement SHOULD have the following form:

      try {
      	statements;
      } catch(ex) {
      	statements;
      } finally {
      	statements;
      }
      				

   8. single statement if-else, while or for MUST NOT be written without brackets, but CAN be written on the same line:

      if(condition) {statement;}
      while(condition) {statement;}
      for(initialization; condition; update) {statement;}
      				

2. Whitespace
   1. Conventional operatiors MAY be surrounded by a space (including ternary operatiors).
   2. Reserved words SHOULD be followed by a space.
   3. Commas SHOULD be followed by a space.
   4. Colons MAY be surrounded by a space.
   5. Semi-colons in for statements SHOULD be followed by a space.
   6. Semi-colons SHOULD NOT be spreceded by a space.
   7. Functions/method calls SHOULD NOT be followed by a space. ie:
      doSomething(someParameter); // NOT doSomething(someParameter)
   8. Logical units within a block SHOULD be seperated by one blank line.
   9. Statements MAY be aligned wherever this enhances readability.
3. Comments
   1. Tricky code SHOULD not be commented, but rewritten.
   2. All comments SHOULD be written in English.
   3. Comments SHOULD be indented relative to their position in the code, preceding or to the right of the code in question.
   4. The declaration of collection variables SHOULD be followed by a comment stating the common type of the elements in the collection.
   5. Comments SHOULD be included to explain BLOCKS of code, to explain the point of the following block.
   6. Comments SHOULD NOT be included for every single line of code.

Introduction

This is an attempt at documenting the undocumented NTLM authentication scheme used by M$'s browsers, proxies, and servers (MSIE & IIS); this scheme is also sometimes referred to as the NT challenge/response (NTCR) scheme. Most of the info here is derived from three sources (see also the References section at the end of this document): Paul Ashton's work on the NTLM security holes, the encryption documentation from Samba, and network snooping. Since most of this info is reverse-engineered it is bound to contain errors; however, at least one client and one server have been implemented according to this data and work successfully in conjunction with M$'s browser, proxies and servers.

Note that this scheme is not as secure as Digest and some other schemes; it is slightly better than the Basic authentication scheme, however.

Also note that this scheme is not an http authentication scheme - it's a connection authentication scheme which happens to (mis-)use http status codes and headers (and even those incorrectly).

HTTP Handshake

When a client needs to authenticate itself to a proxy or server using the NTLM scheme then the following 4-way handshake takes place (only parts of the request and status line and the relevant handers are shown here; "C" is the client, "S" is the server):

Messages

The three messages sent in the handshake are binary structures. Each one is described below as a pseudo-C struct and in a memory layout diagram. byte is an 8-bit field; All fields are unsigned. Numbers are stored in little-endian order. Struct fields named zero contain all zeros. An array length of "*" indicates a variable length field. Hexadecimal numbers and quoted characters in the comments of the struct indicate fixed values for the given field.

The field flags is presumed to contain flags, but their significance is unknown; the values given are just those found in the packet traces.

Type-1 Message

struct {
	byte	protocol[8];	// 'N', 'T', 'L', 'M', 'S', 'S', 'P', '\0'
	byte	type;		// 0x01
	byte	zero[3];
	short	flags;		// 0xb203
	byte	zero[2];
	
	short	dom_len;		// domain string length
	short	dom_len;		// domain string length
	short	dom_off;		// domain string offset
	
	short	host_len;		// host string length
	short	host_len;		// host string length
	short	host_off;		// host string offset (always 0x20)
	byte	zero[2];
	
	byte	host[*];		// host string (ASCII)
	byte	dom[*];		// domain string (ASCII)
} type-1-message;

The host and domain strings are ASCII (or possibly ISO-8859-1), are uppercased, and are not nul-terminated. The host name is only the host name, not the FQDN (e.g. just "GOOFY", not "GOOFY.DISNEY.COM"). The offsets refer to the offset of the specific field within the message, and the lengths are the length of specified field. For example, in the above message host_off = 32 and dom_off = host_off + host_len. Note that the lengths are included twice (for some unfathomable reason).

Type-2 Message

struct {
	byte	protocol[8];	// 'N', 'T', 'L', 'M', 'S', 'S', 'P', '\0'
	byte	type;		// 0x02
	byte	zero[7];
	short	msg_len;		// 0x28
	byte	zero[2];
	short	flags;		// 0x8201
	byte	zero[2];
	
	byte	nonce[8];		// nonce
	byte	zero[8];
} type-2-message;

The nonce is used by the client to create the LanManager and NT responses (see Password Hashes). It is an array of 8 arbitrary bytes. The message length field contains the length of the complete message, which in this case is always 40.

Type-3 Message

struct {
	byte	protocol[8];	// 'N', 'T', 'L', 'M', 'S', 'S', 'P', '\0'
	byte	type;		// 0x03
	byte	zero[3];
	
	short	lm_resp_len;	// LanManager response length (always 0x18)
	short	lm_resp_len;	// LanManager response length (always 0x18)
	short	lm_resp_off;	// LanManager response offset
	byte	zero[2];
	
	short	nt_resp_len;	// NT response length (always 0x18)
	short	nt_resp_len;	// NT response length (always 0x18)
	short	nt_resp_off;	// NT response offset
	byte	zero[2];
	
	short	dom_len;		// domain string length
	short	dom_len;		// domain string length
	short	dom_off;		// domain string offset (always 0x40)
	byte	zero[2];
	
	short	user_len;		// username string length
	short	user_len;		// username string length
	short	user_off;		// username string offset
	byte	zero[2];
	
	short	host_len;		// host string length
	short	host_len;		// host string length
	short	hsot_off;		// host string offset
	byte	zero[6];
	
	short	msg_len;		// message length
	byte	zero[2];
	
	byte	dom[*];		// domain string (unicode UTF-16LE)
	byte	user[*]		// username string (unicode UTF-16LE)
	byte	host[*];		// host string (unicode UTF-16LE)
	byte	lm_resp[*];	// LanManager response
	byte	nt_resp[*];	// NT response
} type-3-message;

The host, domain, and username strings are in Unicode (UTF-16, little-endian) and are not nul-terminated; the host and domain names are in upper case. The lengths of the response strings are 24.

Password Hashes

To calculate the two response strings two password hashes are used: the LanManager password hash and the NT password hash. These are described in detail at the beginning of the Samba ENCRYPTION.html document. However, a few things are not clear (such as what the magic constant for the LanManager hash is), so here is some almost-C code which claculates the two responses. Inputs are passw and nonce, the results are in lm_resp and nt_resp.

// setup LanManager password
char lm_pw[14];
int len = strlen(passwd);

if(14 < len) {
	len = 14;
}

for(idx = 0; idx < len; idx++) {
	lm_pw[idx] = toupper(passwd[idx];
}

for(; idx < 14; idx++) {
	lm_pw[idx] = 0;
}

// create LanManager hashed password
unsigned char magic[] = {0x4B, 0x47, 0x53, 0x21, 0x40, 0x23, 0x24, 0x25};
unsigned char lm_hpw[21];
des_key_schedule ks;

setup_des_key(lm_pw, ks);
des_ecb_encrypt(magic, lm_hw, ks);

setup_des_key(lm_pw + 7, ks);
des_ecb_encrypt(magic, lm_hpw + 8, ks);

memset(lm_hpw + 16, 0, 5);

// create NT hashed password
int len = strlen(passw);
char nt_pw[2 * len];

for(idx=0; idx < len; idx++) {
	nt_pw[2 * idx] = passw[idx];
	nt_pw[2 * idx + 1] = 0;
}

unsigned char nt_hpw[21];
MD4_CTX context;
MD4Init(&context);
MD4Update(&context, nt_pw, 2 * len);
ND4Final(nt_hpw, &context);

memset(nt_hpw + 16, 0, 5);

// create responses
unsinged lm_resp[24], nt_resp[24];
calc_resp(lm_hpw, nonce, lm_resp);
calc_resp(nt_hpw, nonce, nt_resp);

Helpers:
// takes a 21 byte array and treats it as 3 56-bit DES keys. The 8 byte plaintext is encrypted 
// with each key and the resulting 24 bytes are stored in the results array.
void calc_resp(unsigned char* keys, unsigned char* plaintext, unsigned char* results) {
	des_key_schedule ks;
	
	setup_des_key(keys, ks);
	des_ecb_encrypt((des_cblock*)plaintext, (des_cblock*)results, ks, DES_ENCRYPT);
	
	setup_des_key(keys + 7, ks);
	des_ecb_encrypt((des_cblock*)plaintext, (des_cblock*)(results + 8), ks, DES_ENCRYPT);
	
	setup_des_key(keys + 14, ks);
	des_ecb_encrypt((des_cblock*)plaintext, (des_cblock*)(results + 16), ks, DES_ENCRYPT);
}

// turns a 56 bit key into the 64 bit, odd parity key and sets the key.
// The key schedule ks is also set.
void setup_des_key(unsigned char key_56[], des_key_schedule ks) {
	des_cblock key;
	
	key[0] = key_56[0];
	key[1] = ((key_56[0] << 7) & 0xff) | (key _56[1] >> 1);
	key[2] = ((key_56[1] << 6) & 0xff) | (key _56[2] >> 2);
	key[3] = ((key_56[2] << 5) & 0xff) | (key _56[3] >> 3);
	key[1] = ((key_56[3] << 4) & 0xff) | (key _56[4] >> 4);
	key[1] = ((key_56[4] << 3) & 0xff) | (key _56[5] >> 5);
	key[1] = ((key_56[5] << 2) & 0xff) | (key _56[6] >> 6);
	key[1] = (key_56[6] << 1) & 0xff)
	
	des_set_odd_parity(&key);
	des_set_key(&key, ks);
}

Keeping the connection alive

As mentioned above, this scheme authenticates connections, not requests. This mainfests itself in that the network connection must be kept alive during the second part of the handshake, i.e. between the receiving of the type-2 message from the server (step 4) and the sending of the type-3 message (step 5). Each time the connection is closed this second part (steps 3 through 6) must be repeated over the new connection (i.e. it's not enough to just keep sending the last type-3 message). Also, once the connection is authenticated, the Authorization header need not be sent anymore while the connection stays open, no atter what resource is accessed.

For implementations wishing to work with M$'s software this means that they must make sure they use either HTTP/1.0 keep-alive's or HTTP/1.1 persistent connections, and that they must be prepared to do the second part of the handshake each time the connection was closed and is responed. Server implementations must also make sure that HTTP/1.0 responses contain a Content-length header (as otherwise the connection must be closed after the reponse), and that HTTP/1.1 responses either contain a Content-length header or use the chunked transfer encoding.

Example

Here is an actual example of all the message. Assume the host name s "LightCity", the NT domain name is "Ursa-Minor", the username is "Zaphod", the password is "Beeblebrox", and the server sends the nonce "SrvNonce". Then the handshake is:

For reference, the intermediate hashed paswords are:

lm_hpw(LanManager hashed password): 91 90 16 f6 4e c7 b0 0b a2 35 02 8c a5 0c 7a 03 00 00 00 00 00
nt_hpw(NT hashed password) 8c 1b 59 e3 2e 66 6d ad f1 75 74 5f ad 62 c1 33 00 00 00 00 00

Resources

• LM authentication in SMB/CIFS http://www.ubiqx.org/cifs/SMB.html#SMB.8.3
• A document on cracking NTLMv2 authentication http://www.blackhat.com/presentations/win-usa-02/urity-winsec02.ppt
• Squid's NTLM authentication project http://squid.sourceforge.net/ntlm/
• Encryption description for Samba http://de.samba.org/samba/ftp/docs/htmldocs/ENCRYPTION.html
• Info on the MSIE security hole http://oliver.efri.hr/~crv/security/bugs/NT/ie6.html
• FAQ: NT Cryptographic Password Attacks & Defences http://www.ntbugtraq.com/default.asp?sid=1&pid=47&aid=17
• M$'s hotfix to disable the sending of the LanManager response ftp://ftp.microsoft.com/bussys/winnt/winnt-public/fixes/usa/NT40/hotfixes-postSP3/lm-fix
• A description of M$'s hotfix http://www.tryc.on.ca/archives/bugtraq/1997_3/0070.html

Acknowledgements

Special thanks to the following people who helped with the collection and debugging of the above information:

• Jon Lennard
• Paul Ashton
• Jeremy Allison

Ronald Tschalär / 17. June 2003 / ronald@innovation.ch.