Home | History | Annotate | Download | only in ssl 
      1 # This Source Code Form is subject to the terms of the Mozilla Public
      2 # License, v. 2.0. If a copy of the MPL was not distributed with this
      3 # file, You can obtain one at http://mozilla.org/MPL/2.0/.
      4 
      5 SSL's Buffers: enumerated and explained.
      6 
      7 ---------------------------------------------------------------------------
      8 incoming:
      9 
     10 gs = ss->gather
     11 hs = ss->ssl3->hs
     12 
     13 gs->inbuf	SSL3 only: incoming (encrypted) ssl records are placed here,
     14 		and then decrypted (or copied) to gs->buf.
     15 
     16 gs->buf		SSL2: incoming SSL records are put here, and then decrypted
     17 		in place.
     18 		SSL3: ssl3_HandleHandshake puts decrypted ssl records here.
     19 
     20 hs.msg_body	(SSL3 only) When an incoming handshake message spans more 
     21 		than one ssl record, the first part(s) of it are accumulated 
     22 		here until it all arrives.
     23 
     24 hs.msgState	(SSL3 only) an alternative set of pointers/lengths for gs->buf.
     25 		Used only when a handleHandshake function returns SECWouldBlock.
     26 		ssl3_HandleHandshake remembers how far it previously got by
     27 		using these pointers instead of gs->buf when it is called 
     28 		after a previous SECWouldBlock return.
     29 
     30 ---------------------------------------------------------------------------
     31 outgoing:
     32 
     33 sec = ss->sec
     34 ci  = ss->sec->ci	/* connect info */
     35 
     36 ci->sendBuf	Outgoing handshake messages are appended to this buffer.
     37 		This buffer will then be sent as a single SSL record.
     38 
     39 sec->writeBuf	outgoing ssl records are constructed here and encrypted in 
     40 		place before being written or copied to pendingBuf.
     41 
     42 ss->pendingBuf	contains outgoing ciphertext that was saved after a write
     43 		attempt to the socket failed, e.g. EWouldBlock. 
     44 		Generally empty with blocking sockets (should be no incomplete
     45 		writes).
     46 
     47 ss->saveBuf	Used only by socks code.  Intended to be used to buffer 
     48 		outgoing data until a socks handshake completes.  However,
     49 		this buffer is always empty.  There is no code to put 
     50 		anything into it.
     51 
     52 ---------------------------------------------------------------------------
     53 
     54 SECWouldBlock means that the function cannot make progress because it is 
     55 waiting for some event OTHER THAN socket I/O completion (e.g. waiting for 
     56 user dialog to finish).  It is not the same as EWOULDBLOCK.
     57 
     58 ---------------------------------------------------------------------------
     59 
     60 Rank (order) of locks
     61 
     62 recvLock ->\ firstHandshake -> recvbuf -> ssl3Handshake -> xmitbuf -> "spec"
     63 sendLock ->/
     64 
     65 crypto and hash Data that must be protected while turning plaintext into
     66 ciphertext:
     67 
     68 SSL2: 	(in ssl2_Send*)
     69 	sec->hash*
     70 	sec->hashcx 	(ptr and data)
     71 	sec->enc
     72 	sec->writecx*	(ptr and content)
     73 	sec->sendSecret*(ptr and content)
     74 	sec->sendSequence		locked by xmitBufLock
     75 	sec->blockSize
     76 	sec->writeBuf*  (ptr & content)	locked by xmitBufLock
     77 	"in"				locked by xmitBufLock
     78 
     79 SSl3:	(in ssl3_SendPlainText)
     80 	ss->ssl3		    (the pointer)
     81 	ss->ssl3->current_write*    (the pointer and the data in the spec
     82 				     and any data referenced by the spec.
     83 
     84 	ss->sec->isServer
     85 	ss->sec->writebuf* (ptr & content) locked by xmitBufLock
     86 	"buf" 				   locked by xmitBufLock
     87 
     88 crypto and hash data that must be protected while turning ciphertext into 
     89 plaintext:
     90 
     91 SSL2:	(in ssl2_GatherData)
     92 	gs->*				(locked by recvBufLock )
     93 	sec->dec
     94 	sec->readcx
     95 	sec->hash* 		(ptr and data)
     96 	sec->hashcx 		(ptr and data)
     97 
     98 SSL3:	(in ssl3_HandleRecord )
     99 	ssl3->current_read*	(the pointer and all data refernced)
    100 	ss->sec->isServer
    101 
    102 
    103 Data that must be protected while being used by a "writer":
    104 
    105 ss->pendingBuf.*
    106 ss->saveBuf.*		(which is dead)
    107 
    108 in ssl3_sendPlainText
    109 
    110 ss->ssl3->current_write-> (spec)
    111 ss->sec->writeBuf.*
    112 ss->sec->isServer 
    113 
    114 in SendBlock
    115 
    116 ss->sec->hash->length
    117 ss->sec->blockSize
    118 ss->sec->writeBuf.*
    119 ss->sec->sendSecret
    120 ss->sec->sendSequence
    121 ss->sec->writecx	*
    122 ss->pendingBuf
    123 
    124 --------------------------------------------------------------------------
    125 
    126 Data variables (not const) protected by the "sslGlobalDataLock".  
    127 Note, this really should be a reader/writer lock.
    128 
    129 allowedByPolicy		sslcon.c
    130 maybeAllowedByPolicy	sslcon.c
    131 chosenPreference	sslcon.c
    132 policyWasSet		sslcon.c
    133 
    134 cipherSuites[] 		ssl3con.c
    135