Home | History | Annotate | Download | only in libgss
      1  0  stevel 
      2  0  stevel  CDDL HEADER START
      3  0  stevel 
      4  0  stevel  The contents of this file are subject to the terms of the
      5  0  stevel  Common Development and Distribution License, Version 1.0 only
      6  0  stevel  (the "License").  You may not use this file except in compliance
      7  0  stevel  with the License.
      8  0  stevel 
      9  0  stevel  You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
     10  0  stevel  or http://www.opensolaris.org/os/licensing.
     11  0  stevel  See the License for the specific language governing permissions
     12  0  stevel  and limitations under the License.
     13  0  stevel 
     14  0  stevel  When distributing Covered Code, include this CDDL HEADER in each
     15  0  stevel  file and include the License file at usr/src/OPENSOLARIS.LICENSE.
     16  0  stevel  If applicable, add the following below this CDDL HEADER, with the
     17  0  stevel  fields enclosed by brackets "[]" replaced with your own identifying
     18  0  stevel  information: Portions Copyright [yyyy] [name of copyright owner]
     19  0  stevel 
     20  0  stevel  CDDL HEADER END
     21  0  stevel 
     22  0  stevel  Copyright 2005 Sun Microsystems, Inc.  All rights reserved.
     23  0  stevel  Use is subject to license terms.
     24  0  stevel 
     25  0  stevel #ident	"%Z%%M%	%I%	%E% SMI"
     26  0  stevel 
     27  0  stevel 
     28  0  stevel 	The Service Provider Interface for libgss and its Mechanisms
     29  0  stevel 	------------------------------------------------------------
     30  0  stevel 
     31  0  stevel /* CRYPT DELETE START */
     32  0  stevel 
     33  0  stevel 1.  The libgss SPI upto 11/2004
     34  0  stevel 
     35  0  stevel     Prior to PSARC 2004/810 the libgss SPI consisted of a function
     36  0  stevel     provided by each mechanism whose return value is a pointer to a
     37  0  stevel     structure full of references to the mechanism's entry points
     38  0  stevel     (hereinafter: methods).
     39  0  stevel 
     40  0  stevel     This structure does not include any hooks for versioning, which
     41  0  stevel     means that additions of any mechanism methods at micro/patch
     42  0  stevel     releases require patching libgss.so.1 and all the GSS mechanisms
     43  0  stevel     shipped with Solaris (Kerberos V, DH, SPNEGO).
     44  0  stevel 
     45  0  stevel 2.  The libgss SPI after PSARC 2004/810
     46  0  stevel 
     47  0  stevel     In order to avoid changing the gss_config struct and patching all
     48  0  stevel     three mechanisms (four, if the dummy mech counts) and libgss
     49  0  stevel     together and in anticipation of a cleaner SPI in the future (see
     50  0  stevel     next section) the SPI after PSARC 2004/810 will be as before but
     51  0  stevel     supplemented as follows:
     52  0  stevel 
     53  0  stevel      - any new SPI mechanism methods will NOT be placed in gss_config,
     54  0  stevel        instead there is a new gss_config_ext structure, which is to be
     55  0  stevel        used _only_ by libgss (to avoid struct versioning and/or patch
     56  0  stevel        issues), which should be extended to have a pointer to the new
     57  0  stevel        method;
     58  0  stevel 
     59  0  stevel      - there is a new libgss function, __gss_get_mechanism_ext(), which
     60  0  stevel        is used to get at the gss_config_ext for a mechanism;
     61  0  stevel 
     62  0  stevel      - __gss_get_mechanism_ext() uses dlsym() to build the
     63  0  stevel        gss_config_ext struct for the mech by individually loading each
     64  0  stevel        and every mechanism method that isn't part of the old gss_config
     65  0  stevel        struct -- this happens only once per-method, of course; the
     66  0  stevel        result is cached.
     67  0  stevel 
     68  0  stevel        The symbol names that are dlsym()ed are of the form gssspi_* and
     69  0  stevel        correspond to gss_*; e.g., gssspi_acquire_cred_with_password().
     70  0  stevel 
     71  0  stevel        New methods also have a corresponding typedef named
     72  0  stevel        <gss_func>_sfct -- the 's' in 'sfct' is for "SPI" and the 'fct'
     73  0  stevel        is for "function."  This is used to keep cast expressions short.
     74  0  stevel 
     75  0  stevel 3.  The Future libgss SPI
     76  0  stevel 
     77  0  stevel     Once the Solaris krb5 source is resync'ed with MIT krb5 1.4 there
     78  0  stevel     will be no further need for the 'void *context' argument to all the
     79  0  stevel     libgss mechanisms' methods.
     80  0  stevel 
     81  0  stevel     At that point it will be possible to remove this 'void *context'
     82  0  stevel     argument from all the libgss SPI function prototypes, the main
     83  0  stevel     result of which will be that the mechanisms' methods will then have
     84  0  stevel     the same function signature as the corresponding GSS-API functions.
     85  0  stevel 
     86  0  stevel     We can then rename all mechanisms' methods from <mech>_<gss-func> to
     87  0  stevel     <gss-func>.  The corresponding typedefs will be renamed to
     88  0  stevel     <gss-func>_fct.
     89  0  stevel 
     90  0  stevel     The SPI, then, will be almost exactly the same as the API.
     91  0  stevel 
     92  0  stevel     There will be some minor differences, primarily that some API
     93  0  stevel     functions won't have a corresponding SPI method, such as
     94  0  stevel     gss_release_buffer(3GSS), for example.
     95  0  stevel 
     96  0  stevel     Some time later we may open the SPI to third party implementors;
     97  0  stevel     this could be particularly useful as a way to get access to 3rd
     98  0  stevel     party implementations of SPKM and LIPKEY (assuming any ever exist --
     99  0  stevel     SPKM's is a very problematic specification).
    100  0  stevel 
    101  0  stevel     Third party mechanisms should just export all the symbols for the
    102  0  stevel     GSS-API functions, like MIT krb5 does, but functions which libgss
    103  0  stevel     won't call (e.g., gss_release_buffer(3GSS)) should either not be
    104  0  stevel     implemented or should be weak symbols.
    105  0  stevel 
    106  0  stevel     Solaris native mechanisms may still provide the mechanism method
    107  0  stevel     registration function as usual for optimization purposes -- to
    108  0  stevel     reduce the number of calls to dlsym().
    109  0  stevel 
    110  0  stevel     Mechanisms that do not provide the old method registration function
    111  0  stevel     will be loaded as follows:
    112  0  stevel 
    113  0  stevel      - libgss will look for and find the mechanism's
    114  0  stevel        GSS_Indicate_mechs() method and will call it to discover the
    115  0  stevel        mechanism provider's mechanism OIDs.
    116  0  stevel 
    117  0  stevel      - libgss will dlsym() each mechanism provider SPI method.
    118  0  stevel 
    119  0  stevel /* CRYPT DELETE END */
    120