diff -r 000000000000 -r 6474c204b198 security/nss/lib/ssl/notes.txt
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/security/nss/lib/ssl/notes.txt	Wed Dec 31 06:09:35 2014 +0100
@@ -0,0 +1,134 @@
+# This Source Code Form is subject to the terms of the Mozilla Public
+# License, v. 2.0. If a copy of the MPL was not distributed with this
+# file, You can obtain one at http://mozilla.org/MPL/2.0/.
+
+SSL's Buffers: enumerated and explained.
+
+---------------------------------------------------------------------------
+incoming:
+
+gs = ss->gather
+hs = ss->ssl3->hs
+
+gs->inbuf	SSL3 only: incoming (encrypted) ssl records are placed here,
+		and then decrypted (or copied) to gs->buf.
+
+gs->buf		SSL2: incoming SSL records are put here, and then decrypted
+		in place.
+		SSL3: ssl3_HandleHandshake puts decrypted ssl records here.
+
+hs.msg_body	(SSL3 only) When an incoming handshake message spans more 
+		than one ssl record, the first part(s) of it are accumulated 
+		here until it all arrives.
+
+hs.msgState	(SSL3 only) an alternative set of pointers/lengths for gs->buf.
+		Used only when a handleHandshake function returns SECWouldBlock.
+		ssl3_HandleHandshake remembers how far it previously got by
+		using these pointers instead of gs->buf when it is called 
+		after a previous SECWouldBlock return.
+
+---------------------------------------------------------------------------
+outgoing:
+
+sec = ss->sec
+ci  = ss->sec->ci	/* connect info */
+
+ci->sendBuf	Outgoing handshake messages are appended to this buffer.
+		This buffer will then be sent as a single SSL record.
+
+sec->writeBuf	outgoing ssl records are constructed here and encrypted in 
+		place before being written or copied to pendingBuf.
+
+ss->pendingBuf	contains outgoing ciphertext that was saved after a write
+		attempt to the socket failed, e.g. EWouldBlock. 
+		Generally empty with blocking sockets (should be no incomplete
+		writes).
+
+ss->saveBuf	Used only by socks code.  Intended to be used to buffer 
+		outgoing data until a socks handshake completes.  However,
+		this buffer is always empty.  There is no code to put 
+		anything into it.
+
+---------------------------------------------------------------------------
+
+SECWouldBlock means that the function cannot make progress because it is 
+waiting for some event OTHER THAN socket I/O completion (e.g. waiting for 
+user dialog to finish).  It is not the same as EWOULDBLOCK.
+
+---------------------------------------------------------------------------
+
+Rank (order) of locks
+
+recvLock ->\ firstHandshake -> recvbuf -> ssl3Handshake -> xmitbuf -> "spec"
+sendLock ->/
+
+crypto and hash Data that must be protected while turning plaintext into
+ciphertext:
+
+SSL2: 	(in ssl2_Send*)
+	sec->hash*
+	sec->hashcx 	(ptr and data)
+	sec->enc
+	sec->writecx*	(ptr and content)
+	sec->sendSecret*(ptr and content)
+	sec->sendSequence		locked by xmitBufLock
+	sec->blockSize
+	sec->writeBuf*  (ptr & content)	locked by xmitBufLock
+	"in"				locked by xmitBufLock
+
+SSl3:	(in ssl3_SendPlainText)
+	ss->ssl3		    (the pointer)
+	ss->ssl3->current_write*    (the pointer and the data in the spec
+				     and any data referenced by the spec.
+
+	ss->sec->isServer
+	ss->sec->writebuf* (ptr & content) locked by xmitBufLock
+	"buf" 				   locked by xmitBufLock
+
+crypto and hash data that must be protected while turning ciphertext into 
+plaintext:
+
+SSL2:	(in ssl2_GatherData)
+	gs->*				(locked by recvBufLock )
+	sec->dec
+	sec->readcx
+	sec->hash* 		(ptr and data)
+	sec->hashcx 		(ptr and data)
+
+SSL3:	(in ssl3_HandleRecord )
+	ssl3->current_read*	(the pointer and all data refernced)
+	ss->sec->isServer
+
+
+Data that must be protected while being used by a "writer":
+
+ss->pendingBuf.*
+ss->saveBuf.*		(which is dead)
+
+in ssl3_sendPlainText
+
+ss->ssl3->current_write-> (spec)
+ss->sec->writeBuf.*
+ss->sec->isServer 
+
+in SendBlock
+
+ss->sec->hash->length
+ss->sec->blockSize
+ss->sec->writeBuf.*
+ss->sec->sendSecret
+ss->sec->sendSequence
+ss->sec->writecx	*
+ss->pendingBuf
+
+--------------------------------------------------------------------------
+
+Data variables (not const) protected by the "sslGlobalDataLock".  
+Note, this really should be a reader/writer lock.
+
+allowedByPolicy		sslcon.c
+maybeAllowedByPolicy	sslcon.c
+chosenPreference	sslcon.c
+policyWasSet		sslcon.c
+
+cipherSuites[] 		ssl3con.c