net/third_party/nss/ssl/notes.txt

   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