Linux: enable building with a local version of libssl.

net/third_party/nss/ssl/notes.txt

+***** 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