Some comments added, and slight code clean-ups.

ssl/s3_both.c

@@ -256,6 +256,11 @@ unsigned long ssl3_output_cert_chain(SSL *s, X509 *x)
 	return(l);
 	}
 
+/* Obtain handshake message of message type 'mt' (any if mt == -1),
+ * maximum acceptable body length 'max'.
+ * The first four bytes (msg_type and length) are read in state 'st1',
+ * the body is read in state 'stn'.
+ */
 long ssl3_get_message(SSL *s, int st1, int stn, int mt, long max, int *ok)
 	{
 	unsigned char *p;

ssl/s3_pkt.c

@@ -299,26 +299,26 @@ again:
 			goto f_err;
 			}
 
-		/* now s->rstate == SSL_ST_READ_BODY; */
+		/* now s->rstate == SSL_ST_READ_BODY */
 		}
 
-	/* get and decode the data */
-	if (s->rstate == SSL_ST_READ_BODY)
-		{
+	/* s->rstate == SSL_ST_READ_BODY, get and decode the data */
+
 	if (rr->length > (s->packet_length-SSL3_RT_HEADER_LENGTH))
 		{
+		/* now s->packet_length == SSL3_RT_HEADER_LENGTH */
 		i=rr->length;
 		n=ssl3_read_n(s,i,i,1);
 		if (n <= 0) return(n); /* error or non-blocking io */
-			}
-		s->rstate=SSL_ST_READ_HEADER;
+		/* now n == rr->length,
+		 * and s->packet_length == SSL3_RT_HEADER_LENGTH + rr->length */
 		}
 
-	/* At this point, we have the data in s->packet and there should be
-	 * s->packet_length bytes, we must not 'overrun' this buffer :-)
-	 * One of the following functions will copy the data from the
-	 * s->packet buffer */
+	s->rstate=SSL_ST_READ_HEADER; /* set state for later operations */
 
+	/* At this point, s->packet_length == SSL3_RT_HEADER_LNGTH + rr->length,
+	 * and we have that many bytes in s->packet
+	 */
 	rr->input= &(s->packet[SSL3_RT_HEADER_LENGTH]);
 
 	/* ok, we can now read from 's->packet' data into 'rr'
@@ -328,9 +328,6 @@ again:
 	 * When the data is 'copied' into the rr->data buffer,
 	 * rr->input will be pointed at the new buffer */ 
 
-	/* Set the state for the following operations */
-	s->rstate=SSL_ST_READ_HEADER;
-
 	/* We now have - encrypted [ MAC [ compressed [ plain ] ] ]
 	 * rr->length bytes of encrypted compressed stuff. */
 
@@ -371,7 +368,7 @@ printf("\n");
 			SSLerr(SSL_F_SSL3_GET_RECORD,SSL_R_PRE_MAC_LENGTH_TOO_LONG);
 			goto f_err;
 			}
-		/* check MAC for rr->input' */
+		/* check the MAC for rr->input (it's in mac_size bytes at the tail) */
 		if (rr->length < mac_size)
 			{
 			al=SSL_AD_DECODE_ERROR;
@@ -471,12 +468,12 @@ static int do_compress(SSL *ssl)
 	return(1);
 	}
 
-/* Call this to write data
+/* Call this to write data in records of type 'type'
  * It will return <= 0 if not all data has been sent or non-blocking IO.
  */
-int ssl3_write_bytes(SSL *s, int type, const void *_buf, int len)
+int ssl3_write_bytes(SSL *s, int type, const void *buf_, int len)
 	{
-	const unsigned char *buf=_buf;
+	const unsigned char *buf=buf_;
 	unsigned int tot,n,nw;
 	int i;
 
@@ -800,7 +797,7 @@ start:
 				cb(s,SSL_CB_READ_ALERT,j);
 				}
 
-			if (i == 1)
+			if (i == 1) /* warning */
 				{
 				s->s3->warn_alert=n;
 				if (n == SSL_AD_CLOSE_NOTIFY)
@@ -809,7 +806,7 @@ start:
 					return(0);
 					}
 				}
-			else if (i == 2)
+			else if (i == 2) /* fatal */
 				{
 				char tmp[16];
 
@@ -940,8 +937,11 @@ start:
 				goto f_err;
 				}
 			}
+		/* not reached */
 		}
 
+	/* rr->type == type */
+
 	/* make sure that we are not getting application data when we
 	 * are doing a handshake for the first time */
 	if (SSL_in_init(s) && (type == SSL3_RT_APPLICATION_DATA) &&
@@ -1019,6 +1019,7 @@ static int do_change_cipher_spec(SSL *s)
 	return(1);
 	}
 
+/* send s->init_buf in records of type 'type' */
 int ssl3_do_write(SSL *s, int type)
 	{
 	int ret;

ssl/ssl.h

@@ -595,7 +595,7 @@ struct ssl_st
 	STACK_OF(SSL_CIPHER) *cipher_list;
 	STACK_OF(SSL_CIPHER) *cipher_list_by_id;
 
-	/* These are the ones being used, the ones is SSL_SESSION are
+	/* These are the ones being used, the ones in SSL_SESSION are
 	 * the ones to be 'copied' into these ones */
 
 	EVP_CIPHER_CTX *enc_read_ctx;		/* cryptographic state */
@@ -1108,7 +1108,9 @@ int SSL_version(SSL *ssl);
 int SSL_CTX_set_default_verify_paths(SSL_CTX *ctx);
 int SSL_CTX_load_verify_locations(SSL_CTX *ctx, const char *CAfile,
 	const char *CApath);
+#define SSL_get0_session SSL_get_session /* just peek at pointer */
 SSL_SESSION *SSL_get_session(SSL *ssl);
+SSL_SESSION *SSL_get1_session(SSL *ssl); /* obtain a reference count */
 SSL_CTX *SSL_get_SSL_CTX(SSL *ssl);
 void SSL_set_info_callback(SSL *ssl,void (*cb)());
 void (*SSL_get_info_callback(SSL *ssl))();

ssl/ssl_sess.c

@@ -67,19 +67,14 @@ static int remove_session_lock(SSL_CTX *ctx, SSL_SESSION *c, int lck);
 static int ssl_session_num=0;
 static STACK_OF(CRYPTO_EX_DATA_FUNCS) *ssl_session_meth=NULL;
 
-#if 1 /* traditional SSLeay behaviour */
 SSL_SESSION *SSL_get_session(SSL *ssl)
+/* aka SSL_get0_session; gets 0 objects, just returns a copy of the pointer */
 	{
 	return(ssl->session);
 	}
-#else /* suggested change: increase reference counter so that a session
-       * can later be set in a new SSL object.
-       * Objections:
-       *   -- the modified function should have a new name (or old
-       *      applications, including s_client, leak memory);
-       *   -- the locking seems unnecessary given that SSL structures
-       *      usually cannot be safely shared between threads anyway. */
-SSL_SESSION *SSL_get_session(SSL *ssl)
+
+SSL_SESSION *SSL_get1_session(SSL *ssl)
+/* variant of SSL_get_session: caller really gets something */
 	{
 	SSL_SESSION *sess;
 	/* Need to lock this all up rather than just use CRYPTO_add so that
@@ -92,7 +87,6 @@ SSL_SESSION *SSL_get_session(SSL *ssl)
 	CRYPTO_r_unlock(CRYPTO_LOCK_SSL_SESSION);
 	return(sess);
 	}
-#endif
 
 int SSL_SESSION_get_ex_new_index(long argl, void *argp, CRYPTO_EX_new *new_func,
 	     CRYPTO_EX_dup *dup_func, CRYPTO_EX_free *free_func)

util/ssleay.num

@@ -221,3 +221,4 @@ SSL_CTX_set_purpose                     238
 SSL_set_trust                           239
 SSL_get_finished                        240
 SSL_get_peer_finished                   241
+SSL_get1_session                        242