/*
 * Copyright (c) Likewise Software.  All rights Reserved.
 *
 * This library is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 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 Lesser
 * General Public License for more details.  You should have received a copy
 * of the GNU Lesser General Public License along with this program.  If
 * not, see <http://www.gnu.org/licenses/>.
 *
 * LIKEWISE SOFTWARE MAKES THIS SOFTWARE AVAILABLE UNDER OTHER LICENSING
 * TERMS AS WELL.  IF YOU HAVE ENTERED INTO A SEPARATE LICENSE AGREEMENT
 * WITH LIKEWISE SOFTWARE, THEN YOU MAY ELECT TO USE THE SOFTWARE UNDER THE
 * TERMS OF THAT SOFTWARE LICENSE AGREEMENT INSTEAD OF THE TERMS OF THE GNU
 * LESSER GENERAL PUBLIC LICENSE, NOTWITHSTANDING THE ABOVE NOTICE.  IF YOU
 * HAVE QUESTIONS, OR WISH TO REQUEST A COPY OF THE ALTERNATE LICENSING
 * TERMS OFFERED BY LIKEWISE SOFTWARE, PLEASE CONTACT LIKEWISE SOFTWARE AT
 * license@likewisesoftware.com
 */

/*
 * Module Name:
 *
 *        arch_sess.doxy
 *
 * Abstract:
 *
 *        Architecture documentation
 *        Session management page
 *
 * Authors: Brian Koropoff (bkoropoff@likewisesoftware.com)
 *
 */
/**
@page arch_sess Session Management

@section arch_sess_mgr Sessions

A session is an abstract object which represents and manages the state
of an association between two peers, such as handles and security
information.

Each session has a (probablistically) unique, randomly-generated, 64-bit local
ID.  After establishment, it also stores the remote ID of its peer.

@section arch_sess_assoc Associations

Internally, associations delegate certain state logic to the session:

- Entering into a session with a peer
- Leaving a session with a peer
- Registration of handles
- Deregistration of handles
- Mapping handle IDs to handle pointers and vice versa
- Security

@section arch_sess_conn Connections

During the handshake stage of connection setup, each peer transmits
its local session ID to the other.  Each session is then asked to
connect/accept the security token and remote ID of the peer.
This involves the following:

- Validating the security token of the peer.
- Storing the remote ID of the peer.  If the session was previously
  used and is being reconnected, a change in the remote ID indicates
  that state has been lost, and all extant handles are invalidated.
- Invoking any user callbacks to set up per-session user data and
  perhaps reject the session (e.g. authentication).

@section arch_sess_life Session Lifecycle

Sessions created by a client outlive any particular connection between
the client and server.  If the connection is lost, the session can be
reestablished on the next call attempt.  If session state was lost
by the server in the interim, all handles are marked as invalid and
will not longer be usable in calls, although they can be freed.

Sessions created by a server presently are limited to a particular
connection from a client.  When the connection is lost, all handles
in the session are immediately run down and the session is freed.
Future extensions could attempt to preserve the session state across
reconnects.

@section arch_sess_sec Security

When a session is first asked to connect to or accept
a peer, it stores the security token of the peer.  Attempts
to reconnect a session with an incompatible security token
can be detected, mitigating the effects of collision attacks
against sesssion IDs.

**/