ConnOption Fixes (matthewstevenson88#45)

* changed ConnOptions to ConnParameters

* fixed comments

* fixed typo

* fixe comments, pr issues

* changed connOptions to connParameters in comments

* added required status comments

security/s2a/internal/handshaker/handshaker.go

@@ -225,7 +225,7 @@ func (h *s2aHandshaker) setUpSession(req *s2apb.SessionReq) (net.Conn, *s2apb.Se
 		return nil, nil, err
 	}
 	// Create a new TLS record protocol using the Session Result.
-	newConn, err := record.NewConn(&record.ConnOptions{
+	newConn, err := record.NewConn(&record.ConnParameters{
 		NetConn:          h.conn,
 		Ciphersuite:      result.GetState().GetTlsCiphersuite(),
 		TLSVersion:       result.GetState().GetTlsVersion(),

security/s2a/internal/record/record.go

@@ -54,32 +54,39 @@ type conn struct {
 	hsAddr string
 }
 
-// ConnOptions holds the options used for creating a new conn object.
-type ConnOptions struct {
-	// NetConn is the current TLS record.
+// ConnParameters holds the parameters used for creating a new conn object. 
+type ConnParameters struct {
+	// NetConn is the TCP connection to the peer. This parameter is required.
 	NetConn net.Conn
-	// Ciphersuite is the TLS ciphersuite negotiated by the S2A's handshaker
-	// module.
+	// Ciphersuite is the TLS ciphersuite negotiated by the S2A handshaker
+	// service. This parameter is required.
 	Ciphersuite s2apb.Ciphersuite
-	// TLSVersion is the TLS version number that the S2A's handshaker module
-	// used to set up the session.
+	// TLSVersion is the TLS version number negotiated by the S2A handshaker
+	// service. This parameter is required.
 	TLSVersion s2apb.TLSVersion
-	// InTrafficSecret is the key for the in bound direction.
+	// InTrafficSecret is the traffic secret used to derive the session key for
+	// the inbound direction. This parameter is required.
 	InTrafficSecret []byte
-	// OutTrafficSecret is the key for the out bound direction.
+	// OutTrafficSecret is the traffic secret used to derive the session key 
+	// for the outbound direction. This parameter is required.
 	OutTrafficSecret []byte
 	// UnusedBuf is the data read from the network that has not yet been
-	// decrypted.
+	// decrypted. This parameter is optional. If not provided, then no 
+	// application data was sent in the same flight of messages as the final
+	// handshake message.
 	UnusedBuf []byte
-	// InSequence is the sequence number of the next, incoming, TLS record.
+	// InSequence is the sequence number of the next, incoming, TLS record. 
+	// This parameter is required.
 	InSequence uint64
-	// OutSequence is the sequence number of the next, outgoing, TLS record.
+	// OutSequence is the sequence number of the next, outgoing, TLS record. 
+	// This parameter is required.
 	OutSequence uint64
-	// hsAddr stores the address of the S2A handshaker service.
+	// hsAddr stores the address of the S2A handshaker service. This parameter 
+	// is optional. If not provided, then TLS resumption is disabled.
 	HsAddr string
 }
 
-func NewConn(o *ConnOptions) (net.Conn, error) {
+func NewConn(o *ConnParameters) (net.Conn, error) {
 	if o == nil {
 		return nil, errors.New("conn options must not be nil")
 	}

security/s2a/internal/record/record_test.go

@@ -23,7 +23,7 @@ func (c *fakeConn) Close() error                      { return nil }
 func TestNewS2ARecordConn(t *testing.T) {
 	for _, tc := range []struct {
 		desc                     string
-		options                  *ConnOptions
+		options                  *ConnParameters
 		outUnusedBytesBuf        []byte
 		outOverheadSize          int
 		outHandshakerServiceAddr string
@@ -35,7 +35,7 @@ func TestNewS2ARecordConn(t *testing.T) {
 		},
 		{
 			desc: "invalid input traffic secret size",
-			options: &ConnOptions{
+			options: &ConnParameters{
 				NetConn:          &fakeConn{},
 				Ciphersuite:      s2apb.Ciphersuite_AES_256_GCM_SHA384,
 				TLSVersion:       s2apb.TLSVersion_TLS1_3,
@@ -47,7 +47,7 @@ func TestNewS2ARecordConn(t *testing.T) {
 		},
 		{
 			desc: "invalid output traffic secret size",
-			options: &ConnOptions{
+			options: &ConnParameters{
 				NetConn:          &fakeConn{},
 				Ciphersuite:      s2apb.Ciphersuite_AES_256_GCM_SHA384,
 				TLSVersion:       s2apb.TLSVersion_TLS1_3,
@@ -59,7 +59,7 @@ func TestNewS2ARecordConn(t *testing.T) {
 		},
 		{
 			desc: "invalid tls version",
-			options: &ConnOptions{
+			options: &ConnParameters{
 				NetConn:          &fakeConn{},
 				Ciphersuite:      s2apb.Ciphersuite_AES_128_GCM_SHA256,
 				TLSVersion:       s2apb.TLSVersion_TLS1_2,
@@ -71,7 +71,7 @@ func TestNewS2ARecordConn(t *testing.T) {
 		},
 		{
 			desc: "basic with AES-128-GCM-SHA256",
-			options: &ConnOptions{
+			options: &ConnParameters{
 				NetConn:          &fakeConn{},
 				Ciphersuite:      s2apb.Ciphersuite_AES_128_GCM_SHA256,
 				TLSVersion:       s2apb.TLSVersion_TLS1_3,
@@ -86,7 +86,7 @@ func TestNewS2ARecordConn(t *testing.T) {
 		},
 		{
 			desc: "basic with AES-256-GCM-SHA384",
-			options: &ConnOptions{
+			options: &ConnParameters{
 				NetConn:          &fakeConn{},
 				Ciphersuite:      s2apb.Ciphersuite_AES_256_GCM_SHA384,
 				TLSVersion:       s2apb.TLSVersion_TLS1_3,
@@ -101,7 +101,7 @@ func TestNewS2ARecordConn(t *testing.T) {
 		},
 		{
 			desc: "basic with CHACHA20-POLY1305-SHA256",
-			options: &ConnOptions{
+			options: &ConnParameters{
 				NetConn:          &fakeConn{},
 				Ciphersuite:      s2apb.Ciphersuite_CHACHA20_POLY1305_SHA256,
 				TLSVersion:       s2apb.TLSVersion_TLS1_3,
@@ -116,7 +116,7 @@ func TestNewS2ARecordConn(t *testing.T) {
 		},
 		{
 			desc: "basic with unusedBytes",
-			options: &ConnOptions{
+			options: &ConnParameters{
 				NetConn:          &fakeConn{},
 				Ciphersuite:      s2apb.Ciphersuite_CHACHA20_POLY1305_SHA256,
 				TLSVersion:       s2apb.TLSVersion_TLS1_3,