GSI authentication

[Reagan Moore]

At SDSC we have worked with both a C library and Java library version 
of the Grid Security Infrastructure.  It turns out that they use 
slightly different security protocols (set of messages exchanged 
during authentication).

Wayne Schroeder has written a aid library to simplify interactions 
with the GSI environment.  A description of the library is given 
below.

Reagan Moore

/* Copyright   1999   The Regents of the University of California
  * All Rights Reserved
  *
  * Permission to use, copy, modify and distribute any part of this
  * Storage Resource Broker (SRB) software package, for educational,
  * research and non-profit purposes, without fee, and without a
  * written agreement is hereby granted, provided that the above
  * copyright notice, this paragraph and the following three paragraphs
  * appear in all copies.  Those desiring to incorporate this SRB
  * software into commercial products or use for commercial purposes
  * should contact the Technology Transfer Office, University of
  * California, San Diego, 9500 Gilman Drive, La Jolla, CA 92093-0910,
  * Ph: (619) 534-5815, FAX: (619) 534-7345.
  *
  * IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY
  * PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL
  * DAMAGES, INCLUDING LOST PROFITS, ARISING OUT OF THE USE OF THIS SRB
  * SOFTWARE, EVEN IF THE UNIVERSITY OF CALIFORNIA HAS BEEN ADVISED OF
  * THE POSSIBILITY OF SUCH DAMAGE.
  *
  * THE SRB SOFTWARE PROVIDED HEREIN IS ON AN "AS IS" BASIS, AND THE
  * UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO PROVIDE MAINTENANCE,
  * SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.  THE UNIVERSITY
  * OF CALIFORNIA MAKES NO REPRESENTATIONS AND EXTENDS NO WARRANTIES OF
  * ANY KIND, EITHER IMPLIED OR EXPRESS, INCLUDING, BUT NOT LIMITED TO,
  * THE IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A
  * PARTICULAR PURPOSE, OR THAT THE USE OF THE SRB SOFTWARE WILL NOT
  * INFRINGE ANY PATENT, TRADEMARK OR OTHER RIGHTS.  */

/*

  ---------------
  This AID library is now being integrated into the SRB source tree
  rather than maintained as a separate library so that we can better
  support GSI.  In the process, aid.c has been modified a little to fit
  (GSI for #ifdefs is now GSI_AUTH) into the SRB build environment and
  the SRB build environment modified to make it easier to configure and
  build with GSI.  Only GSI portion of this has been tested.  And this
  was with the current GSI version, 2.2.4.  The Kerberos and DCE code
  has been left here for now, but isn't being used.  We could convert
  this to use the globus_gss_assist API but that is only simplify it
  slightly.

  Wayne Schroeder
  3/2003
  ---------------

  LIBAID  Authentication and Integrity of Data interface

  This is an interface library to GSS-API security services, providing
  a simple API to calling applications.  It is to be used in the SDSC
  Storage Resource Broker (client/server) application in conjunction
  with the Globus GSS-API implementation on top of SSLeay (see
  www.globus.org).  X.509 Certificates are used for user and server
  authentication.  Data can be exchanged in a secure manner with data
  signing (not encryption).

  It also is used for Kerberos authentication/data integrity also via
  the GSS-API.  So that both Kerberos and SSL versions of GSS-API can
  be linked at the same time, the krb5_gss* routines (or
  generic_gss_release_buffer) are called for Kerberos instead of the
  gss_* routines.  The gss_* routines are the SSL GSS-API routines, the
  krb5_gss* routines are the Kerberos GSS-API routines.  Fortunately,
  in the Kerberos GSS-API package, each gss_* routine calls a krb5_gss*
  counterpart with the same arguments, making this kind of blending
  possible.

  Allocation of potentially large data buffers is left to the calling
  application rather than done in this library or below.  This is
  sometimes important in High Performance Computing as the arrays can
  get large and applications need to control the memory allocation.
  This is accomplished primarily by using gss_get_mic/gss_verify_mic
  instead of gss_wrap and gss_unwrap.  Some malloc's of small buffers
  are also avoided for efficiency and simplicity (matching the large
  buffers), although there is some risk that the scratch buffer may,
  someday, be too small.

  Two defines control whether this package makes GSI and/or Kerberos
  calls (GSI and Kerberos), so it can be built to link with either
  one or both.

  A third define (DCE) controls whether this builds for the DCE
  environment (and an earlier version of GSS-API).  We have not
  attempted to link DCE simultaneous with either Kerberos or GSI.

  The aid_setup_creds has a flag for type (AID_Kerberos, AID_GSI,
  AID_DCE) and so does each aid_establish_context.  For aid_read and
  aid_write this package knows which type of context has been
  established for the specified socket.

  The aid_read routine will malloc a (potentially large) buffer if the
  application's isn't big enough.  This allows aid_read to behave like
  the read system call and cache data if the app's buffer is too small.
  Currently it prints a message for each malloc so that we can tune
  applications (the SRB) to avoid a lot of malloc's.  I plan to make
  this (printing these messages) to be under the control of the
  application.

  Application callable routines:

    aid_setup_creds(service_name, client_flag, type_flag)
       reads user or server X.509 certificate/private key, or Kerberos
       credential locally; server/client flag indicates if this is a server
       or client; type_flag indicates Kerberos, GSI, or DCE.

       For Kerberos servers, environment variable KRB5_KTNAME is the
       Keytab file for the server (handled in Kerberos layers).

       For DCE servers, environment variable DCE_KTNAME is the
       Keytab file for the server (handled at this layer).

    aid_establish_context_serverside(s,clientName,max_len_clientName,type_flag)
       mutual secure authentication across a socket, called by a server;
       also prepares for possible use of aid_read/aid_write for data
       integrity checking

    aid_establish_context_clientside(s, service_name, deleg_flag, type_flag)
       mutual authentication across a socket, called by client; prepare for
       possible use of aid_read/aid_write for data integrity checking

    aid_read(fd,buffer,length)
       like read system call, across a socket, but confirms that data
       originated from the authenticated party on the other side and has
       not been altered in transit.

    aid_write(fd,buffer,length)
       like write system call, across a socket, adds MIC (Message Integrity
       Check, an MD5 hash of data and session key, etc) for use by aid_read.

    aid_close(fd)
       clear context information from memory.

    aid_debug(val)
       adjust verbose level for debug messages.

  All application callable routines are named aid_*.
  Internal routines are named aidi_*.

  In case of errors, messages are printed to stderr (both AID and GSS
  level) and negative values returned.


  Loosely based on GSS-API examples developed by Openvision distributed
  with Kerberos.

  With the addition of Kerberos, and then DCE, the number of ifdefs has
  gotten excessive in places and makes the code somewhat hard to read.
  But I believe it is best to leave it this way, since the calls and flow
  are quite similar across the three.