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