README.gssapi revision 1.1.1.1
1The gss-api authentication mechanism implementation for racoon was 2based on the ietf draft draft-ietf-ipsec-isakmp-gss-auth-06.txt. 3 4The implementation uses the Heimdal gss-api library, i.e. gss-api 5on top of Kerberos 5. The Heimdal gss-api library had to be modified 6to meet the requirements of using gss-api in a daemon. More specifically, 7the gss_acquire_cred() call did not work for other cases than 8GSS_C_NO_CREDENTIAL ("use default creds"). Daemons are often started 9as root, and have no Kerberos 5 credentials, so racoon explicitly 10needs to acquire its credentials. The usual method (already used 11by login authentication daemons) in these situations is to add 12a set of special credentials to be used. For example, authentication 13by daemons concerned with login credentials, uses 'host/fqdn' as 14its credential, where fqdn is the hostname on the interface that 15is being used. These special credentials need to be extracted into 16a local keytab from the kdc. The default value used in racoon 17is 'ike/fqdn', but it can be overridden in the racoon config file. 18 19The modification to the Heimdal gss-api library implements the 20mechanism above. If a credential other than GSS_C_NO_CREDENTIAL 21is specified to gss_acquire_cred(), it first looks in the default 22credential cache if it its principal matches the desired credential. 23If not, it extracts it from the default keytab file, and stores 24it in a memory-based credential cache, part of the gss credential 25structure. 26 27 28 29The 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 80This implementation tried to follow the specification in the ietf draft 81as close as possible. However, it has not been tested against other 82IKE daemon implementations. The only other one I know of is Windows 2000, 83and it has some caveats. I attempted to be Windows 2000 compatible. 84Should racoon be tried against Windows 2000, the gssapi_id option in 85the config file must be used, as Windows 2000 expects the GSS endpoint 86name to be sent at all times. I have my doubts as to the W2K compatibility, 87because the spec describes the GSS endpoint name sent by W2K as 88an unicode string 'xxx@domain', which doesn't seem to match the 89required standard for gss-api + kerberos 5 (i.e. I am fairly certain 90that such a string will be rejected by the Heimdal gss-api library, as it 91is not a valid Kerberos 5 principal). 92 93With the Heimdal gss-api implementation, the gssapi_krb authentication 94method will only work in main mode. Aggressive mode does not allow 95for the extra round-trips needed by gss_init_sec_context and 96gss_accept_sec_context when mutual authentication is requested. 97The draft specifies that the a fallback should be done to main mode, 98through the return of INVALID-EXCHANGE-TYPE if it turns out that 99the gss-api mechanisms needs more roundtrips. This is implemented. 100Unfortunately, racoon does not seem to properly fall back to 101its next mode, and this is not specific to the gssapi_krb method. 102So, to avoid problems, only specify main mode in the config file. 103 104 105 -- Frank van der Linden <fvdl@wasabisystems.com> 106 107