1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/nss/lib/ssl/notes.txt Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,134 @@
1.4 +# This Source Code Form is subject to the terms of the Mozilla Public
1.5 +# License, v. 2.0. If a copy of the MPL was not distributed with this
1.6 +# file, You can obtain one at http://mozilla.org/MPL/2.0/.
1.7 +
1.8 +SSL's Buffers: enumerated and explained.
1.9 +
1.10 +---------------------------------------------------------------------------
1.11 +incoming:
1.12 +
1.13 +gs = ss->gather
1.14 +hs = ss->ssl3->hs
1.15 +
1.16 +gs->inbuf SSL3 only: incoming (encrypted) ssl records are placed here,
1.17 + and then decrypted (or copied) to gs->buf.
1.18 +
1.19 +gs->buf SSL2: incoming SSL records are put here, and then decrypted
1.20 + in place.
1.21 + SSL3: ssl3_HandleHandshake puts decrypted ssl records here.
1.22 +
1.23 +hs.msg_body (SSL3 only) When an incoming handshake message spans more
1.24 + than one ssl record, the first part(s) of it are accumulated
1.25 + here until it all arrives.
1.26 +
1.27 +hs.msgState (SSL3 only) an alternative set of pointers/lengths for gs->buf.
1.28 + Used only when a handleHandshake function returns SECWouldBlock.
1.29 + ssl3_HandleHandshake remembers how far it previously got by
1.30 + using these pointers instead of gs->buf when it is called
1.31 + after a previous SECWouldBlock return.
1.32 +
1.33 +---------------------------------------------------------------------------
1.34 +outgoing:
1.35 +
1.36 +sec = ss->sec
1.37 +ci = ss->sec->ci /* connect info */
1.38 +
1.39 +ci->sendBuf Outgoing handshake messages are appended to this buffer.
1.40 + This buffer will then be sent as a single SSL record.
1.41 +
1.42 +sec->writeBuf outgoing ssl records are constructed here and encrypted in
1.43 + place before being written or copied to pendingBuf.
1.44 +
1.45 +ss->pendingBuf contains outgoing ciphertext that was saved after a write
1.46 + attempt to the socket failed, e.g. EWouldBlock.
1.47 + Generally empty with blocking sockets (should be no incomplete
1.48 + writes).
1.49 +
1.50 +ss->saveBuf Used only by socks code. Intended to be used to buffer
1.51 + outgoing data until a socks handshake completes. However,
1.52 + this buffer is always empty. There is no code to put
1.53 + anything into it.
1.54 +
1.55 +---------------------------------------------------------------------------
1.56 +
1.57 +SECWouldBlock means that the function cannot make progress because it is
1.58 +waiting for some event OTHER THAN socket I/O completion (e.g. waiting for
1.59 +user dialog to finish). It is not the same as EWOULDBLOCK.
1.60 +
1.61 +---------------------------------------------------------------------------
1.62 +
1.63 +Rank (order) of locks
1.64 +
1.65 +recvLock ->\ firstHandshake -> recvbuf -> ssl3Handshake -> xmitbuf -> "spec"
1.66 +sendLock ->/
1.67 +
1.68 +crypto and hash Data that must be protected while turning plaintext into
1.69 +ciphertext:
1.70 +
1.71 +SSL2: (in ssl2_Send*)
1.72 + sec->hash*
1.73 + sec->hashcx (ptr and data)
1.74 + sec->enc
1.75 + sec->writecx* (ptr and content)
1.76 + sec->sendSecret*(ptr and content)
1.77 + sec->sendSequence locked by xmitBufLock
1.78 + sec->blockSize
1.79 + sec->writeBuf* (ptr & content) locked by xmitBufLock
1.80 + "in" locked by xmitBufLock
1.81 +
1.82 +SSl3: (in ssl3_SendPlainText)
1.83 + ss->ssl3 (the pointer)
1.84 + ss->ssl3->current_write* (the pointer and the data in the spec
1.85 + and any data referenced by the spec.
1.86 +
1.87 + ss->sec->isServer
1.88 + ss->sec->writebuf* (ptr & content) locked by xmitBufLock
1.89 + "buf" locked by xmitBufLock
1.90 +
1.91 +crypto and hash data that must be protected while turning ciphertext into
1.92 +plaintext:
1.93 +
1.94 +SSL2: (in ssl2_GatherData)
1.95 + gs->* (locked by recvBufLock )
1.96 + sec->dec
1.97 + sec->readcx
1.98 + sec->hash* (ptr and data)
1.99 + sec->hashcx (ptr and data)
1.100 +
1.101 +SSL3: (in ssl3_HandleRecord )
1.102 + ssl3->current_read* (the pointer and all data refernced)
1.103 + ss->sec->isServer
1.104 +
1.105 +
1.106 +Data that must be protected while being used by a "writer":
1.107 +
1.108 +ss->pendingBuf.*
1.109 +ss->saveBuf.* (which is dead)
1.110 +
1.111 +in ssl3_sendPlainText
1.112 +
1.113 +ss->ssl3->current_write-> (spec)
1.114 +ss->sec->writeBuf.*
1.115 +ss->sec->isServer
1.116 +
1.117 +in SendBlock
1.118 +
1.119 +ss->sec->hash->length
1.120 +ss->sec->blockSize
1.121 +ss->sec->writeBuf.*
1.122 +ss->sec->sendSecret
1.123 +ss->sec->sendSequence
1.124 +ss->sec->writecx *
1.125 +ss->pendingBuf
1.126 +
1.127 +--------------------------------------------------------------------------
1.128 +
1.129 +Data variables (not const) protected by the "sslGlobalDataLock".
1.130 +Note, this really should be a reader/writer lock.
1.131 +
1.132 +allowedByPolicy sslcon.c
1.133 +maybeAllowedByPolicy sslcon.c
1.134 +chosenPreference sslcon.c
1.135 +policyWasSet sslcon.c
1.136 +
1.137 +cipherSuites[] ssl3con.c
