Context:

  Proposal:

    For encapsulating security information, a security
    context is created and associated with a context (aka
    session handle).  The security context can hold
    information about X509 certificates, privat/public keys,
    username/password, kerberos tickets etc., and provides
    these information to the SAGA implementation as needed.
    
    A SAGA implementaqtion MAY be able to attache more than
    one security context to one context.

+-------------------------------------------------------------+

Summary:
========

  The Context provides the functionality of a session
  handle.  A context is created, and used as parameter to
  ALL object instanciations.  Multiple contexts can
  co-exist.  A single context can be shared between threads.
  SAGA Objects created from other SAGA Objects inherit its
  context.

  A implementation CAN implement various types of Security
  contexts.  or just one type.  The type of context to be
  created is specified by a enum which is the only argument
  to the Context constructor.  

  Every context has a specific set of attributes which can
  be set/get via the SAGA attribute interface.  Exactly what
  attributes a Context offers depends on its type.  A
  context MUST issue an error if attributes not
  corresponding to its type are set or requested.

+-------------------------------------------------------------+

Use Cases:
==========

  Not applicable here;  this is a general design decision.

+-------------------------------------------------------------+


API Summary:
============

API Summary:

  package SAGA version 0.1 {

    enum contextType {
      X509            = 0,
      SSH             = 1,
      Kerberos        = 2,
      UserPass        = 3
    };

    interface Context extends-all SAGA.Attribute {
      
      constructor (in  contextType type);
      getType     (out contextType type);
      
    }
  }

+-------------------------------------------------------------+


API Detail:
===========

  interface Context:

    - constructor:
      Purpose: create a security context
      Format:  create               (in  contextType type);
      Inputs:  type                  type of context to 
                                     create
      Outputs: none
      Throws:  BadParameter:         context type is not 
                                     supported.
      
    - getType:
      Purpose: query the context type
      Format:  getType              (out contextType type);
      Inputs:  none
      Outputs: type                  type of context
      Throws:  nothing
      
+-------------------------------------------------------------+


Examples:
=========

  Context context;
  File    file (context);

  File file2 = file.copy (location);
  
+-------------------------------------------------------------+

Notes:
======

  - Following attributes MUST be supported by the
    correponding context types:

      X509:
        X509_Proxy          (/tmp/x509...)
        X509_CertDir        (/etc/grid-security/certificates/)
    
      SSH
        SSH_PrivKey         ($HOME/.ssh/id_dsa)
        SSH_PublKey         ($HOME/.ssh/id_dsa.pub)
      
      Kerberos
        Kerberos_Ticket     (/tmp/kticket...) ?
      
      UserPass
        UserPass_UserName   (anonymous)
        UserPass_Password   (anon)
    
      - Other types MAY be specified by a SAGA
        implementation.
      
      - Default values can be specified by a SAGA
        implementation.

  - Should we also specify the default values?  Mostly
    simple I guess.  But then the defaults may  differ per
    platform and installation, so leaving that to the
    implementation gives more flexibility...

+-------------------------------------------------------------+


Examples:
=========

  Context context_1 (SSH);  // default attribs apply
  Context context_2 (UserPass);

  context_2.setAttribute (UserName, "andre");
  context_2.setAttribute (Password, "secret");

  Session session;
  session.addContext (context_1);
  session.addContext (context_2);
  
  File file (session);