userapps/opensource/ipsec-tools/src/racoon/doc/README.gssapi

   1 The gss-api authentication mechanism implementation for racoon was
   2 based on the ietf draft draft-ietf-ipsec-isakmp-gss-auth-06.txt.
   3
   4 The implementation uses the Heimdal gss-api library, i.e. gss-api
   5 on top of Kerberos 5. The Heimdal gss-api library had to be modified
   6 to meet the requirements of using gss-api in a daemon. More specifically,
   7 the gss_acquire_cred() call did not work for other cases than
   8 GSS_C_NO_CREDENTIAL ("use default creds"). Daemons are often started
   9 as root, and have no Kerberos 5 credentials, so racoon explicitly
  10 needs to acquire its credentials. The usual method (already used
  11 by login authentication daemons) in these situations is to add
  12 a set of special credentials to be used. For example, authentication
  13 by daemons concerned with login credentials, uses 'host/fqdn' as
  14 its credential, where fqdn is the hostname on the interface that
  15 is being used. These special credentials need to be extracted into
  16 a local keytab from the kdc. The default value used in racoon
  17 is 'ike/fqdn', but it can be overridden in the racoon config file.
  18
  19 The modification to the Heimdal gss-api library implements the
  20 mechanism above. If a credential other than GSS_C_NO_CREDENTIAL
  21 is specified to gss_acquire_cred(), it first looks in the default
  22 credential cache if it its principal matches the desired credential.
  23 If not, it extracts it from the default keytab file, and stores
  24 it in a memory-based credential cache, part of the gss credential
  25 structure.
  26
  27
  28
  29 The modifcations to racoon itself are as follows:
  30
  31         * The racoon.conf config file accepts a new keyword, "gssapi_id",
  32           to be used inside a proposal specification. It specifies
  33           a string (a Kerberos 5 principal in this case), specifying the
  34           credential that racoon will try to acquire. The default value
  35           is 'ike/fqdn', where fqdn is the hostname for the interface
  36           being used for the exchange. If the id is not specified, no
  37           GSS endpoint attribute will be specified in the first SA sent.
  38           However, if the initiator does specify a GSS endpoint attribute,
  39           racoon will always respond with its own GSS endpoint name
  40           in the SA (the default one if not specified by this option).
  41
  42         * The racoon.conf file accepts "gssapi_krb" as authentication
  43           method inside a proposal specification. The number used
  44           for this method is 65001, which is a temporary number as
  45           specified in the draft.
  46
  47         * The cftoken.l and cfparse.y source files were modified to
  48           pick up the configuration options. The original sources
  49           stored algorithms in bitmask, which unfortunately meant
  50           that the maximum value was 32, clearly not enough for 65001.
  51           After consulting with the author (sakane@kame.net), it turned
  52           out that method was a leftover, and no longer needed. I replaced
  53           it with plain integers.
  54
  55         * The gss-api specific code was concentrated as much as possible
  56           in gssapi.c and gssapi.h. The code to call functions defined
  57           in these files is conditional on HAVE_GSSAPI, except for the
  58           config scan code. Specifying this flag on the compiler commandline
  59           is conditional on the --enable-gssapi option to the configure
  60           script.
  61
  62         * Racoon seems to want to send accepted SA proposals back to
  63           the initiator in a verbatim fashion, leaving no room to
  64           insert the (variable-length) GSS endpoint name attribute.
  65           I worked around this by re-assembling the extracted SA
  66           into a new SA if the gssapi_krb method is used, and the
  67           initiator sent the name attribute. This scheme should
  68           possibly be re-examined by the racoon maintainers, storing
  69           the SAs (the transformations, to be more precise) in a different
  70           fashion to allow for variable-length attributes to be
  71           re-inserted would be a good change, but I considered it to be
  72           beyond the scope of this project.
  73
  74         * The various state functions for aggressive and main mode
  75           (in isakmp_agg.c and isakmp_ident.c respectively) were
  76           changed to conditionally change their behavior if the
  77           gssapi_krb method is specified.
  78
  79
  80 This implementation tried to follow the specification in the ietf draft
  81 as close as possible. However, it has not been tested against other
  82 IKE daemon implementations. The only other one I know of is Windows 2000,
  83 and it has some caveats. I attempted to be Windows 2000 compatible.
  84 Should racoon be tried against Windows 2000, the gssapi_id option in
  85 the config file must be used, as Windows 2000 expects the GSS endpoint
  86 name to be sent at all times. I have my doubts as to the W2K compatibility,
  87 because the spec describes the GSS endpoint name sent by W2K as
  88 an unicode string 'xxx@domain', which doesn't seem to match the
  89 required standard for gss-api + kerberos 5 (i.e. I am fairly certain
  90 that such a string will be rejected by the Heimdal gss-api library, as it
  91 is not a valid Kerberos 5 principal).
  92
  93 With the Heimdal gss-api implementation, the gssapi_krb authentication
  94 method will only work in main mode. Aggressive mode does not allow
  95 for the extra round-trips needed by gss_init_sec_context and
  96 gss_accept_sec_context when mutual authentication is requested.
  97 The draft specifies that the a fallback should be done to main mode,
  98 through the return of INVALID-EXCHANGE-TYPE if it turns out that
  99 the gss-api mechanisms needs more roundtrips. This is implemented.
 100 Unfortunately, racoon does not seem to properly fall back to
 101 its next mode, and this is not specific to the gssapi_krb method.
 102 So, to avoid problems, only specify main mode in the config file.
 103
 104
 105         -- Frank van der Linden <fvdl@wasabisystems.com>
 106