_____ _________ ________  ___ ___ _________ ________ 
       /  __/ \_  ____/ \       ) | | | | \_  ____/ \       )
       \__ \   |   _)_  | __  _/  | | | |  |   _)_  | __  _/  
       ___\ \  |      \ | | \ \   \ \_/ /  |      \ | | \ \  solutions
       \____/ /_____  / /_/  \ \   \   /  /_____  / /_/  \ \ 
                    \/        \/    \_/         \/        \/ 

           (c) Lada 'Ray' Lostak (c) Orcave (c) 2002-2005
Content:

  Auth specifications

History:

  04/24/2002 Ray        - initial version


1.0 General
-----------
SAuth is based on secret symetric cryptography keys and dictionary. Auth defines 'users' and 'user classes'.
User class have nothing common with access rigths. It is just group of some user class. Both (user/class) have
own secret private key. Class key exists because of prevention DOS attack against dictionary.

Terms:

    KEY_USER    - secret key unique for every user
    KEY_CLASS   - secret key unique for user class
    DICTIONARY  - secret dictionary unique for every user
    USER_ID     - system user ID (20 bits number)
    USER_CLASS  - user class
    TIME        - current time (UTC) - absolute form
    I_RANDOM    - initial random number


The goal is to secure verify, if user being logged is really the one, who should be - from untrusted terminals.
SAuth should use software solution or hardware key.

1.1. SAuth protocol definition
------------------------------
Auth protocol is TCP/IP client/server based connection. Default port is 6526. Communication flows in RAW
form (ASCII). Every line (doesn't care on CR/LF delimiter) holds one 'exchange'.... All numbers are
transfered in 5 bits ascii-encoded mode (0-9a-v). Case is not important. All numbers goes into little-big 
endian order (Intel). Default format for numbers is decimal.

S - server related
C - client related

Server exchanges:

S STATUS [dec_number] [text]

    After every operation server send 'status' to client. Known status codes:

    000 OK
    001 CLOSED              - connection closed (no error)
    100 ERR_ACCESS_DENIED   - doesn't need comment
    101 ERR_UNKNOWN_CMD     - unknown command
    102 ERR_INTERNAL        - internal error
    103 ERR_PROTOCOL        - unexpected/bad response
    104 ERR_TIMEOUT         - operation timeout
    105 ERR_VERSION         - unsupported protocol version

S INIT [5bit_ascii_number]

    Informs client about initial random number - 32 bits


S AUTH [id]

    Server send to client 'auth' id. It is ciphered following 32 bit number:

        31                                0
        ........ ........ ........ ........ 
        00222222 2222222  00111111 11111111

        1 - first offset into 32 bit dictionary
        2 - second offset into 32 bit dictionary

    Cipher key is created by HASH from following struct:

        struct:     int8    KEY_USER[512];  (zero padded key)
                    int32   random;
                    int32   time;           (if known - only MINUTES and above - if not, then zeroes)

S WELCOME

    Client is sucessfully autentificated

S FREEZEDATA [data]
    
    Bunch of datas which fully describes connection

Client exchanges:

C HELLO [protocol_version]

    Informs server about client protocol verion and client side time.

    protocol_verion: 1 (current)

C SET [value_name] [value]

    Client sends additional info to server. Known infos:

    real_time       [time]                  - device is abble to determine realtime and sends to server
                                            - time form: yyyyymmmmddddddhhhhhiiiiiissssss - 32 bit number, bit oriented:

                                                   y - years from 2002  5bits (0....)
                                                   m - monnt            4bits (0..11)
                                                   d - day              6bits (0..31)
                                                   h - hour             5bits (0..23) - 24 hour cycle
                                                   i - minute           6bits (0..59)
                                                   s - second           6bits (0..59)
C READY

    Client is ready for start

C LOGIN

    Client want to log into systen

C USER [id]

    Client sends to server encypted user ID. Its form:

        intl    uid;        user id
        intl    init;       init phase
        intl    time;       if known
        intl    padding;    32 bit reseved

        UsedID:

        20 bits - user ID
        8  bits - class ID
        4  bits - reserved

    Ciphered by KEY_CLASS:

C LOGIN [id]

    Client sends to server 'password' - HASH from ciphered form of following struct:

        struct:     int32   dict1;   
                    int32   dict2;
    

    Cipher key is created by HASH from following struct:

        struct:     int8    KEY_USER[512];  (zero padded key)
                    int32   random;
                    int32   time;           (if known - only MINUTES and above - if not, then zeroes)

C LOGOUT

    client is logout in progress

C CLOSE

    client is closing connection

C APP [class] [app_and_class_dependent]

    client sends additional application depenend things - valid after WELCOME before CLOSE/LOGOUT

C FREEZE

    freeze login progress (valid only after auth)

C CONTINUE [freezedata]

    contie from freezed state

Protocol handshake:

1.  C->S HELLO
2.  S->C STATUS OK (if accept version) 
3.  C->S SET values (if any)
4.  C->S READY
5.  S->C INIT
6.  C->S LOGIN
7.  C->S USER
8.  S->C AUTH
9.  C->S AUTH
10. S->C WELCOME / STATUS err
11. C->S APP if any
12. C->S CLOSE
13. S->C STATUS closed

logout:

6.  C->S LOGOUT
7.  C->S USER
8.  S->C STATUS CLOSED


freeze (6) or (9)
1.  C->S FREEZE
2.  S->C STATUS CLOSED
---(continue)
11. C->S HELLO
12. S->C STATUS OK
13. C->S CONTINUE [data]
14. S->C STATUS
15. goto normal handshake - 9

1.2. Web related
----------------
PHP scripts communicates with SAuth and authorize user. It uses 'freeze/continue' to allow client-side reply. Freeze
should be allowed only from localhost (127.0.0.1).