gecko/security/nss/lib/ssl/notes.txt
2008-06-06 08:40:11 -04:00

167 lines
5.4 KiB
Plaintext

***** BEGIN LICENSE BLOCK *****
Version: MPL 1.1/GPL 2.0/LGPL 2.1
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 the Initial Developer are Copyright (C) 1994-2000
the Initial Developer. All Rights Reserved.
Contributor(s):
Alternatively, the contents of this file may be used under the terms of
either the GNU General Public License Version 2 or later (the "GPL"), or
the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
in which case the provisions of the GPL or the LGPL are applicable instead
of those above. If you wish to allow use of your version of this file only
under the terms of either the GPL or the LGPL, and not to allow others to
use your version of this file under the terms of the MPL, indicate your
decision by deleting the provisions above and replace them with the notice
and other provisions required by the GPL or the LGPL. If you do not delete
the provisions above, a recipient may use your version of this file under
the terms of any one of the MPL, the GPL or the LGPL.
***** END LICENSE BLOCK *****
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