Annotation of embedaddon/ipsec-tools/src/racoon/doc/README.gssapi, revision 1.1
1.1 ! misho 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:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>