Optimize tls resumption

[3andne]

Background

In the utls codebase, the management of session-related code has long suffered from a lack of coherence, resulting in various issues and bugs. The current challenges/bugs include:

1. Coexistence of PSK and Session Ticket: Presently, both PSK and Session Ticket extensions can operate concurrently, leading to unintended behavior. Specifically, nonempty PSK and Session Ticket data can both be marshaled. The correct behavior should be that when PSK is valid, the content of the Session Ticket extension should remain empty. This issue emerges due to the independent initialization and configuration of PSK and Session Ticket in disparate places of the codebase.

2. Unable to Disable Session Resumption: In TLS 1.2, configuring disableSessionTicket = true does not adequately deactivate session resumption. This is due to multiple code segments responsible for session reading/loading, with only the crypto/tls loadSession() function assessing the status of session ticket usage disablement. Notably, the initialization of the TLS 1.2 session ticket occurs without precondition verification.

3. Inconsistent Session Override Interfaces: The interfaces for overriding sessions exhibit inconsistencies. While the long-standing method of using uconn.SetSessionState for session overrides exists, improper invocation timing or its application to altering or providing TLS 1.3 sessions can result in unpredictable session states.

4. Missing Session ID: If a client hello doesn't use a session, its session ID won't be set. In contrast, browsers always use a 32-byte session ID under all circumstances.

5. Duplicated Loading of Sessions: If no usable session is available when calling BuildHandshakeState(), the client hello is marshalled without the session ticket / psk. The client hello is then being used by handshake(). If a session becomes available during the handshake(), the client hello might use that session. However, the clientHello.raw isn't supposed to be changed at that point. This could lead to handshake failures.

6. Redundant Session-Related Fields in Multiple Locations: There exists redundancy in session-related fields across several areas including uconn.HandshakeState.Hello, uconn.HandshakeState.State13, uconn.utls, SessionTicketExtension, and PreSharedKeyExtension. The recurrence of fields with the same semantics across different places introduces the potential for inconsistent states, thereby complicating comprehension and maintenance efforts.

7. Incompatible with TLS 1.2 sessions: If the session is a tls 1.2 session, the PSK extension will throw an error. While the PSK extension has the capability to ignore the session and allows for TLS 1.2 resumption, this approach introduces challenges in ensuring proper initialization of the session ticket extension due to a lack of cohesion between the components.

The existence of these bugs shows us a technical debt present in the code. While they can all be fixed independently, it's only through refactoring and addressing the technical debt that we can prevent similar bugs from being introduced in the future, thus permanently resolving such issues.

Refactoring Design

1. Introduce SessionController: Use this abstraction to manage all operations related to sessions.
2. Utilize State Machines for State Management: Due to the complexity of session-related states, relying on simple boolean conditions like session == nil cannot adequately describe all possibilities. In the refactoring process, I've employed state machines to ensure proper handling of each state.
3. Redundant Assertions, Not Data: The previous session design was prone to generating undefined states. Thanks to the refactored state machine, we can use "verbose" assertions to ensure we don't enter unintended states. I've also cleaned up all data related to sessions, ensuring that they are only stored in one place each. Eliminating data redundancy can prevent hard-to-debug state discrepancy issues.
4. Explicit Session Operations: Instead of splitting the loading session, setting session, and update binder processes in ApplyConfig and MarshalClientHello, I've centralized them in two new functions, uLoadSession and uApplyPatch, and explicitly called conn.loadSession() at most once.
5. Optimize PreSharedKeyExtension Interface: To make Psk compatible with the refactored session setup process, I've redesigned the PreSharedKeyExtension interface. The main idea behind this redesign is dependency injection. PreSharedKeyExtension shouldn't fetch sessions on its own; instead, uConn should inject the session to ensure precise control over the session's lifecycle.
6. Optimize PreSharedKeyExtension Code: Currently, both PskExt implementations contain a considerable amount of duplicate code. Code redundancy makes maintenance difficult. For example, during refactoring, I found an error in the implementation of the Len() function in FakePreSharedKeyExtension. The code in UtlsPreSharedKeyExtension is almost identical but doesn't have that error.
7. Minimize Changes to crypto/tls Code, Reuse Functions Whenever Possible: This approach will make future maintenance more convenient by preserving compatibility with the existing crypto/tls codebase.
8. Allow session tickets to be set through SetSessionTicketExtension and PSK to be set through SetPskExtension.

The illustrated workflow

• before

  stateDiagram-v2
    D: clientHandshake
    A: applyPresetByID()
    B: ApplyConfig()
    C: MarshalClientHello()
    E: [loadSession()]
    [*] --> D
    note right of D
           sessions are loaded independently by multiple components.
           lack of centralized session management.
    end note
    state D {
        [*] --> A
        state A {
            A1: SessionTicketExtension<br/>[custom load session #1]
            [*] --> A1
        }
        A --> B
        state B {
            B1: [loadSession()]<br/>partially setting tls1.3 session to hello
            B2: [custom load session #2]<br/>partially setting tls1.3 session to hello
            [*] --> B1: UtlsPreSharedKeyExtension
            [*] --> B2: FakePreSharedKeyExtension
        }
        B --> C
        state C {
            C1: marshal hello to bytes,<br/>[ReadWithRawHello()]<br/>write binders to bytes,<br/>set binders to hello
            C2: [bufferedWriter.ReadFrom(ext)]
            [*] --> C1: PreSharedKeyExtension
            [*] --> C2: Not PreSharedKeyExtension
        }
        C --> E
    }
  

  Loading
• after

  stateDiagram-v2
   D: [clientHandshake()]
   A: [applyPresetByID()]
   B: [ApplyConfig()]
   C: [MarshalClientHello()]
   E: [loadSession()]
   F: [uLoadSession()]
   G: [uApplyPatch()]
   H: restore session from hello and state13
   [*] --> D
   state D {
       [*] --> A
       A --> B
       B --> F
       note left of F
           Either Session ticket or Psk is set.
           Session is loaded solely by loadSession().
           loadSession() will be called at most ONCE.            
       end note
       state F {
           F1: precondition checks
           F2: [loadSession()]
           F3: initialize and set session ticket
           F4: [InitializeByUtls()]
           F5: [setPsk()]
           [*] --> F1
           F1 --> F2: should load session
           F1 --> F3: user-provided tls1.2 session
           F1 --> F5: user-initialized psk
           F2 --> F3: tls 1.2 session
           F2 --> F4: tls 1.3 session
       }
       F --> C
       C --> G
       state G {
           G1: update binders if necessary,<br/>[PatchBuiltHello()]<br/>[setPsk()]
           [*] --> G1
       }
       G --> E: if not called by [uLoadSession()]<br/>HelloGolang
       G --> H: if already being called
       H --> [*]
       E --> [*]
   }
  

  Loading

State machines

Session Controller State

stateDiagram-v2
    A: NoSession
    B: TicketInitialized
    C: TicketAllSet
    D: PskExtInitialized
    E: PskAllSet
    F: locked
    
    [*] --> A
    A --> B: SetSessionState12<br/>called by user
    A --> B: uLoadSession<br/>returns tls 1.2 session
    B --> C: setSessionTicketToUConn()
    C --> F: finalCheck()
    A --> F: finalCheck()
    A --> D: SetSessionState13<br/>called by user
    A --> D: uLoadSession<br/>returns tls 1.3 session
    D --> E: setPskToHandshake()
    E --> F: finalCheck()

Loading

LoadSessionTrackerState

stateDiagram-v2
    A: NeverCalled
    B: UtlsAboutToCall
    C: CalledByULoadSession
    D: CalledByGoTLS
    
    [*] --> A
    A --> B: utlsAboutToLoadSession()<br/>called by uLoadSession
    B --> C: onLoadSessionReturn()
    C --> [*]
    A --> D: clientHandshake()<br/>onLoadSessionReturn()
    D --> [*]

Loading

[gaukas]

Overall this looks legit!

We may not want to break any of the existing interfaces unless we have to. So please consider introducing new interfaces while setting default parameter for the existing interfaces where new required parameters are missing.

[3andne]

New option OmitEmptyPsk introduced (false by default).
see:

        // OmitEmptyPsk determines whether utls will automatically conceal
	// the psk extension when it is empty. When the psk extension is empty, the
	// browser omits it from the client hello. Utls can mimic this behavior,
	// but it deviates from the provided client hello specification, rendering
	// it unsuitable as the default behavior. Users have the option to enable
	// this behavior at their own discretion.
	OmitEmptyPsk bool // [uTLS]

[gaukas]

LGTM!