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