DEFINITION MODULE TLSHandshake;

        (********************************************************)
        (*                                                      *)
        (*                TLS Handshake Protocol                *)
        (*                                                      *)
        (*  Programmer:         P. Moylan                       *)
        (*  Started:            3 July 2023                     *)
        (*  Last edited:        27 July 2025                    *)
        (*  Status:             Recovering after major loss     *)
        (*                                                      *)
        (********************************************************)


FROM SYSTEM IMPORT CAST;
FROM Sockets IMPORT Socket;
FROM TLSRecord IMPORT RLState;
FROM TransLog IMPORT TransactionLogID;


PROCEDURE SetINIname (name: ARRAY OF CHAR);

    (* Takes note of our INI name. *)

PROCEDURE SetBlankDomainLegal;

    (* Makes it legal for a ClientHello handshake message to not        *)
    (* specify a server domain name.  This can be done if the server    *)
    (* uses a single certificate to cover all domains.                  *)

PROCEDURE DoHandshake (S: Socket;  as_server: BOOLEAN;
                            serveraddr: CARDINAL;
                            VAR (*IN*) serverdomain: ARRAY OF CHAR;
                            rlstate: RLState;
                            logID: TransactionLogID;
                            VAR (*OUT*) ConnectionLost: BOOLEAN): BOOLEAN;

    (* Returns TRUE if the handshaking has proceeded to completion      *)
    (* successfully.                                                    *)

    (* If as_server is FALSE, the serverdomain parameter specifies the  *)
    (* domain the client is trying to contact. Otherwise, it specifies  *)
    (* an initial value for the domain the server is hosting, but in    *)
    (* that case it will probably be overwritten by the domain          *)
    (* specified in a ClientHello message.                              *)

    (* A handshake record starts with code 22 (16H) to mean "handshake",*)
    (* then we have a two-byte version code and a two-byte length.      *)
    (* Those initial five bytes are loaded into the appropriate fields  *)
    (* of buffer by procedure GetFragment.  After this we have the      *)
    (* "fragment" field with                                            *)
    (*      HandshakeType (1 byte)                                      *)
    (*      length        (3 bytes)                                     *)
    (*      content       (depends on handshake type)                   *)

    (* The expected sequence, as seen by the server end, is:            *)
    (*      receive client Hello                                        *)
    (*      send server Hello                                           *)
    (*      (maybe) send server certificate                             *)
    (*      (maybe) send server key exchange                            *)
    (*      (maybe) send certificate request from server                *)
    (*      send server HelloDone                                       *)
    (*      (maybe) receive client certificate                          *)
    (*      receive client KeyExchange                                  *)
    (*      (maybe) receive CertificateVerify                           *)
    (*      receive ChangeCipherSpec (not a handshake message)          *)
    (*      receive Finished                                            *)
    (*      send ChangeCipherSpec                                       *)
    (*      send Finished                                               *)
    (* After this, application data can flow.                           *)

    (* From the viewpoint of the client, this is:                       *)
    (*      send client Hello                                           *)
    (*      receive server Hello                                        *)
    (*      (maybe) receive server certificate                          *)
    (*      (maybe) receive server key exchange                         *)
    (*      (maybe) receive certificate request from server             *)
    (*      receive server HelloDone                                    *)
    (*      (maybe) send client certificate                             *)
    (*      send client KeyExchange                                     *)
    (*      (maybe) send CertificateVerify                              *)
    (*      send ChangeCipherSpec (not a handshake message)             *)
    (*      send Finished                                               *)
    (*      receive ChangeCipherSpec                                    *)
    (*      receive Finished                                            *)
    (* After this, application data can flow.                           *)


END TLSHandshake.

