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