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 Netscape are 
Copyright (C) 1994-2000 Netscape Communications Corporation.  All
Rights Reserved.

Contributor(s):

Alternatively, the contents of this file may be used under the
terms of the GNU General Public License Version 2 or later (the
"GPL"), in which case the provisions of the GPL are applicable 
instead of those above.  If you wish to allow use of your 
version of this file only under the terms of the GPL and not to
allow others to use your version of this file under the MPL,
indicate your decision by deleting the provisions above and
replace them with the notice and other provisions required by
the GPL.  If you do not delete the provisions above, a recipient
may use your version of this file under either the MPL or the
GPL.

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