          Copyright (c) mjh-EDV Beratung, 1996-1999
     mjh-EDV Beratung - 63263 Neu-Isenburg - Rosenstrasse 12
          Tel +49 6102 328279 - Fax +49 6102 328278
                Email info@mjh.teddy-net.com

    Author: Jordan Hrycaj <jordan@mjh.teddy-net.com>

   $Id: README.AUTHENTICATION,v 1.3 2000/01/02 18:55:55 jordan Exp $

   This library is free software; you can redistribute it and/or
   modify it under the terms of the GNU Library General Public
   License as published by the Free Software Foundation; either
   version 2 of the License, or (at your option) any later version.

   This library 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
   Library General Public License for more details.

   -----------------------------------------------------------------

Authentication protocol over an untrusted channel:
--------------------------------------------------

Independent from the cipher protocol, there is an authentication protocol
used based on a message signing algorithm imvolving public keys.

       +--------+              |                +--------+
       | client |              |                | server |
       +--------+              *                +--------+
                               |
(1)        ---------- public signature key --------->
                               |
(2)                            *      checks whether this public key 
                               |       makes sense (is long enough)
                               |
(3)                            *     generates random challenge/message
                               |
(4)        <-------- server sends challenge ---------
                               |
(5) signs the challenge        *
                               |
(6)        -------- client sends signature  --------->
                               |
(7)                            *       checks public key against the
                               |          list of known user keys
                               |
(8)                            *        checks the given signature
                               |   
(9)        <----- server sends accepting message -----
                               |
                               |
                     untrusted and insecure
                      commnication channel


Remarks:
 
(1) The public key scheme for signing messages is derived from El Gamal and
    implemented as \0 terminated ASCII-string:

        <idf> <p> <g> <g^a> <crc>

    where

      all the fields are separated by whitespaces

      <idf> ::= the text "peks/x.y:" denoting the current version x.y
                of the cipher protocol

      <p>   ::= a base 64 encoded prime

      <g>   ::= a base 64 encoded generator for the multiplicative
                group {x % p : x != 0} generated by p

      <g^a> ::= the base 64 encoded a-th power of g (mod p) for
                some (random) number a

      <crc> ::= a RIPEMD160 hash over the fields from left to right,
                separated by exactly one blank


(4) The server sends a \0 terminated random challenge

          <ch> <msg>

    where

      all the fields are separated by whitespaces

      <ch>  ::= the text "chl:"

      <msg> ::= a base 64 encoded random text


(6) The client sends a \0 terminated user name and challenge signature

          <idf> <user> <g^b> <sig msg> <crc>

    where

      all the fields are separated by whitespaces

      <idf>      ::= the text "egs/n.m:" denoting the current derivative n.m
                     of the El Gamal signature scheme

      <user>     ::= name of the user to be authenticated

      <g^b>      ::= the base 64 encoded b-th power of g (mod p) for
                     some (random) number b

      <sig msg>  ::= the base 64 message digest for <msg> depending on <g^b> 
                     and the current derivative number m.n

      <crc>      ::= a RIPEMD160 hash over the fields from left to right,
                     separated by exactly one blank


(7) Public keys are stored in a file as \n-terminated lines

        <user-on-host> <p> <g> <g^a> <crc>

    where

      all the fields are separated by whitespaces

      <host-on-host> ::= <user>
                     ||  <user><host>

            <user> ::= name of the user to be authenticated followed
                       by a commercial at '@'

            <host> ::= name or ip-address of the server host followed
                       by a colon ':'

      <p>, <g> and <g^a> are the same as in (1)

      <crc>  ::= a RIPEMD160 hash over the fields from left to right,
                 separated by exactly one blank


(9) The server sends a \0 terminated message

          <result>

    where

      <result>   ::= the text "ok"
                 ||  the text "failed"
                 ||  the text "failed " followed by an explanation
                 ||  the text "next"

    in case the server sent any "failed" message, the protocol stops here.


In case the server sent "redo" in step 9, the protocol goes:

    The client sends either a \0 terminated stop message . (and the
    dialogue stops completely, here) or proceeds as:


       +--------+             |                +--------+
       | client |             |                | server |
       +--------+             *                +--------+
                              |
(6.1)      -------- client sends password digest ---->
                              |
(7.1)                         |               server checks that
                              *                digest against
                              |               the password list
                              |   
(8.1)                         *               server may register
                              |                the public key
                              |                 from step (1)
                              |   
(9.1)      <----- server sends accepting message -----
                              |
                              *
                              |
                          untrusted
                         commnication
                           channel
Remarks:
 
(6.1) The client sends a \0 terminated user name and challenge+password digest:

          <idf> <sig pwd+msg> <crc>

    where

      all the fields are separated by whitespaces

      <idf>          ::= the text "ripemd160" followed by current derivative
                         n.m of the El Gamal signature scheme

      <sig pwd+msg>  ::= the base64 message digest for the concatenation of
                         the user password and the challenge <msg> from step <4>

      <crc>          ::= a hash over the fields from left to right, 
                         separated by exactly one blank


(9.1) The server sends a \0 terminated message

          <result>

    where

      <result>   ::= the text "ok"
                 ||  the text "failed"
                 ||  the text "failed " followed by an explanation

   ============================================================================


Authentication protocol over a trusted channel:
-----------------------------------------------

In case of an encrypted channel (as defined in README.PROTOCOL), there is 
another authentication protocol, used.  In case, the server knows and 
approves the client key, the protocol goes

       +--------+              |                +--------+
       | client |              |                | server |
       +--------+              *                +--------+
                               |
(1)        ------------ public user key ----------->
                               |
(2)                            *     checks whether this public key 
                               |      makes sense (is long enough)
                               |
(3)                            *      checks public key against the
                               |        list of known user keys
	                       |
(4)        <------- rejection/redo message ---------
	                       |
(5)        -------------- password  --------------->
                               |
(6)                            *      generates random session key
                               |
(7)        <----- pub key encrypted session key ----
                               |
(8) makes a new session key as *      makes  new session key as
    a hash using the old key   |      a hash using the old key
     and the new key received  |      and the new key just sent
                               *
(9) a key chance procedure is  |      a key chance procedure is
     started on sender, and    |       started on sender, and
       receiver channel        *            receiver channel
                               |
(10)       <<============= key exchange ==========>>
                               |
                               |
                      trusted and encrypted
                      commnication channel
Remarks:
 
(1) The public user key scheme is derived from El Gamal and implemented
    as a \0 terminated ASCII-string:

        <idf> <user> <p> <g> <g^a> <crc>

    where

      all the fields are separated by whitespaces

      <idf> ::= the text "auth/x.y:" denoting the current version x.y
                of the cipher protocol

      <user> ::= name of the user to be authenticated

      <p>    ::= a base 64 encoded prime

      <g>    ::= a base 64 encoded generator for the multiplicative
                 group {x % p : x != 0} generated by p

      <g^a>  ::= the base 64 encoded a-th power of g (mod p) for
                 some (random) number a

      <crc>  ::= a RIPEMD160 hash over the fields from left to right,
                 separated by exactly one blank


(3) Public keys are stored in a file as \n-terminated lines

        <user-on-host> <p> <g> <g^a> <crc>

    where

      all the fields are separated by whitespaces

      <host-on-host> ::= <user>
                     ||  <user><host>

            <user> ::= name of the user to be authenticated followed
                       by a commercial at '@'

            <host> ::= name or ip-address of the server host followed
                       by a colon ':'

      <p>, <g> and <g^a> are the same as in (1)

      <crc>  ::= a RIPEMD160 hash over the fields from left to right,
                 separated by exactly one blank


(4) The following message is optional and used only, if the server did
    not approve the public user key.  The server sends a \0 terminated
    message text

          <result>

    where

      <result>   ::= the text "ok"
                 ||  the text "failed"
                 ||  the text "failed " followed by an explanation
                 ||  the text "next"

    in case the server sent any "failed" message, the protocol stops here.


(5) The following message is optional and used if and only if the server
    sent a message of type (4).

          <idf> <user> <pass> <crc>

    where

      all the fields are separated by whitespaces

      <idf> ::= the text "pass/x.y:" denoting the current version x.y
                of the cipher protocol

      <user> ::= name of the user to be authenticated (plain text)

      <pass> ::= the base 64 encapsulated pass phrase

      <crc>  ::= a RIPEMD160 hash over the fields from left to right,
                 separated by exactly one blank


(4) The server sends the wrapped session as:

          <idf> <g^b> "A" <k * g^ab> <crc>

    where

      all the fields are separated by whitespaces

      <idf>      ::= the text "elg/x.y:" denoting the current version x.y
                     of the cipher protocol

      <g^b>      ::= the base 64 encoded b-th power of g (mod p) for
                     some (random) number b

      "0"        ::= the digit 0

      <k * g^ab> ::= the base 64 encoded number k, multiplied by the
                     number g^ab (mod p), where g^ab is calculated
                     as the b-th power of g^a (mof p) for some
                     some (random) number b

      <crc>      ::= a RIPEMD160 hash over the fields from left to right,
                     separated by exactly one blank


(8) The new session key is calculated as

      session key ::= RIPEMD160 (session key, session key)

    and used as a master key for both, sender and receiver.


(9) It is assumed, that a new key exchange on the cipher layer will only
    work if the client has the proper private key and can read the public
    key encrypted message from step (7).

(10) If is assumed, that client, and server send a key change request. The
    new ciphet key on either side will be composed by a new random key and
    the (currently updated) session  key.

Was that it? 
jordan

