(**************************************************************************)
(*                                                                        *)
(*  Web server input stream handler                                       *)
(*  Copyright (C) 2025   Peter Moylan                                     *)
(*                                                                        *)
(*  This program is free software: you can redistribute it and/or modify  *)
(*  it under the terms of the GNU General Public License as published by  *)
(*  the Free Software Foundation, either version 3 of the License, or     *)
(*  (at your option) any later version.                                   *)
(*                                                                        *)
(*  This program is distributed in the hope that it will be useful,       *)
(*  but WITHOUT ANY WARRANTY; without even the implied warranty of        *)
(*  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the         *)
(*  GNU General Public License for more details.                          *)
(*                                                                        *)
(*  You should have received a copy of the GNU General Public License     *)
(*  along with this program.  If not, see <http://www.gnu.org/licenses/>. *)
(*                                                                        *)
(*  To contact author:   http://www.pmoylan.org   peter@pmoylan.org       *)
(*                                                                        *)
(**************************************************************************)

DEFINITION MODULE TLSCipherSuites;

        (********************************************************)
        (*                                                      *)
        (*  Interface between TLS and the encryption algorithms *)
        (*                                                      *)
        (*  Programmer:         P. Moylan                       *)
        (*  Started:            27 August 2018                  *)
        (*  Last edited:        13 June 2025                    *)
        (*  Status:             OK                              *)
        (*                                                      *)
        (********************************************************)


FROM SYSTEM IMPORT CARD8;

FROM TLSRecord IMPORT RLState;


TYPE
    (* The cipher suites that I need to know about.  I've omitted the   *)
    (* Diffie-Helman suites, for example, because at the moment I don't *)
    (* have plans to implement them.  The presence of a suite in this   *)
    (* list does not imply that we support it.                          *)

    CipherSuite = (TLS_NULL_WITH_NULL_NULL,
                   TLS_RSA_WITH_NULL_MD5,
                   TLS_RSA_WITH_NULL_SHA,
                   TLS_RSA_WITH_NULL_SHA256,
                   TLS_RSA_WITH_RC4_128_MD5,
                   TLS_RSA_WITH_RC4_128_SHA,
                   TLS_RSA_WITH_3DES_EDE_CBC_SHA,
                   TLS_RSA_WITH_AES_128_CBC_SHA,
                   TLS_RSA_WITH_AES_256_CBC_SHA,
                   TLS_RSA_WITH_AES_128_CBC_SHA256,
                   TLS_RSA_WITH_AES_256_CBC_SHA256
                   );

CONST
    NullSuite = TLS_NULL_WITH_NULL_NULL;


PROCEDURE NameOfSuite (s: CipherSuite;  VAR (*OUT*) name: ARRAY OF CHAR);

    (* Returns name as the name of ciphersuite s. *)

PROCEDURE CodeToCipherSuite (code1, code2: CARD8): CipherSuite;

    (* Translates two-byte code to a CipherSuite. *)

PROCEDURE CipherSuiteToCode (s: CipherSuite;  VAR (*OUT*) code1, code2: CARD8);

    (* Returns the two-byte code for s. *)

PROCEDURE SuiteEnabled (suite: CipherSuite): BOOLEAN;

    (* Returns TRUE iff we support this cipher suite. *)

PROCEDURE AcceptCipherSuite (code1, code2: CARD8): CipherSuite;

    (* Returns result <> NullSuite iff we support this cipher suite. *)

PROCEDURE ServerKeyExchangeNeeded (cs: CipherSuite): BOOLEAN;

    (* Returns TRUE if the initial negotiation requires a key exchange  *)
    (* step.                                                            *)

PROCEDURE KeyBlockSize (cs: CipherSuite): CARDINAL;

    (* Works out how much key material has to be generated. *)

PROCEDURE Commit (sess: RLState;  cs: CipherSuite;  server_write: BOOLEAN;
                                    truncate_MAC: BOOLEAN;
                                    VAR (*IN*) key_block: ARRAY OF CARD8);

    (* The caller has alread calculated the key_block, which has content *)
    (*      client_write_MAC_key[SecurityParameters.mac_key_length]     *)
    (*      server_write_MAC_key[SecurityParameters.mac_key_length]     *)
    (*      client_write_key[SecurityParameters.enc_key_length]         *)
    (*      server_write_key[SecurityParameters.enc_key_length]         *)
    (*      client_write_IV[SecurityParameters.fixed_iv_length]         *)
    (*      server_write_IV[SecurityParameters.fixed_iv_length]         *)
    (* Unused values are empty. We use these data to set the MAC, key,  *)
    (* and IV parameters to the relevant session.                       *)

END TLSCipherSuites.

