Linux: enable building with a local version of libssl.

net/third_party/nss/ssl/notes.txt

Index: net/third_party/nss/ssl/notes.txt
diff --git a/net/third_party/nss/ssl/notes.txt b/net/third_party/nss/ssl/notes.txt
new file mode 100644
index 0000000000000000000000000000000000000000..772da4d589cbc0e112a7ccff7625671ed65d9d98
--- /dev/null
+++ b/net/third_party/nss/ssl/notes.txt
@@ -0,0 +1,166 @@
+***** BEGIN LICENSE BLOCK *****
+Version: MPL 1.1/GPL 2.0/LGPL 2.1
+
+The contents of this file are subject to the Mozilla Public License Version 
+1.1 (the "License"); you may not use this file except in compliance with 
+the License. You may obtain a copy of the License at 
+http://www.mozilla.org/MPL/
+
+Software distributed under the License is distributed on an "AS IS" basis,
+WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
+for the specific language governing rights and limitations under the
+License.
+
+The Original Code is the Netscape security libraries.
+
+The Initial Developer of the Original Code is
+Netscape Communications Corporation.
+Portions created by the Initial Developer are Copyright (C) 1994-2000
+the Initial Developer. All Rights Reserved.
+
+Contributor(s):
+
+Alternatively, the contents of this file may be used under the terms of
+either the GNU General Public License Version 2 or later (the "GPL"), or
+the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
+in which case the provisions of the GPL or the LGPL are applicable instead
+of those above. If you wish to allow use of your version of this file only
+under the terms of either the GPL or the LGPL, and not to allow others to
+use your version of this file under the terms of the MPL, indicate your
+decision by deleting the provisions above and replace them with the notice
+and other provisions required by the GPL or the LGPL. If you do not delete
+the provisions above, a recipient may use your version of this file under
+the terms of any one of the MPL, the GPL or the LGPL.
+
+***** END LICENSE BLOCK *****
+
+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
+
+[ReadLock ->]\ [firstHandshake ->] [ssl3Handshake ->] recvbuf \ -> "spec"
+[WriteLock->]/                                        xmitbuf /
+
+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