# 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