README.certificate
README.gssapi
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
README.plainrsa
1HOW-TO use plainrsa auth, contributed by Simon Chang <simonychang@gmail.com>
2
3Before you begin, you should understand that the RSA authentication
4mechanism hinges upon the idea of a split cryptographic key: one used
5by the public, the other readable only to you. Any data that is
6encrypted by a public key can be decrypted only by the corresponding
7private key, so that the private key user can be assured that the
8content of the transmission has not been examined by unauthorized
9parties. Similarly, any data encrypted by the private key can be
10decrypted by the public key so that the public knows that this
11transmission came from this user and nobody else (this idea is called
12non-repudiation). Also, the longer the key length, the more difficult
13it would be for potential attacker to conduct brute-force discovery of
14the keys. So, what all this means for the security administrator is
15that the setup needs a pair of reasonably long keys for each host that
16wishes to authenticate in this manner.
17
18With this in mind, it should be relatively straightforward to set up
19RSA authentication. For the purpose of this document, we assume that
20we are setting up RSA authentication between two networked hosts
21called Boston and Chicago. Unless otherwise noted, all steps should
22be performed on both hosts with corresponding key names. Here are the
23steps:
24
251) Included in each default installation of ipsec-tools is a binary
26called plainrsa-gen. This executable is used to generate a pair of
27RSA keys for the host. There are only two parameters that you should
28be concerned about: -b, which sets the number of bits for the keys,
29and -f, which specifies the output file for plainrsa-gen to send the
30results. On an ordinary Pentium-II with 128 MB of RAM, it takes only
31seconds to generate keys that are 2048 bits long, and only slightly
32longer to generate 4096-bit keys. Either key length should be
33sufficient; any longer key length actually reduces performance and
34does not increase security significantly. You should therefore run it
35as:
36
37 plainrsa-gen -b 2048 -f /var/tmp/boston.keys
38
392) When the process completes, you should have a text file that
40includes both public and private keys. GUARD THIS FILE CAREFULLY,
41because once a private key is compromised it is no longer any good,
42and you must generate a new pair from scratch. Reading the file
43itself, you should see several very long lines of alphanumeric data.
44The only line you should be concerned with is the line towards the top
45of the output file that begins with "# pubkey=0sAQPAmBdT/" or
46something to that effect. This line is your public key, which should
47be made available to the other host that you are setting up. Copy
48this line to a separate file called "boston.pub" and change the
49beginning of the line so that it reads ": PUB 0sAQPAmBdT/".
50Alternatively, you can also grab the first line of the boston.keys
51file and uncomment the line so that it reads the same as above. Now
52rename the file you generated initially to "boston.priv".
53
543) You should now have two files, boston.priv and boston.pub
55(chicago.priv and chicago.pub on Chicago). The first file contains
56your private key and the second file your public key. Next you should
57find a way to get the public key over to the other host involved.
58Boston should have (1) its own key pair, and (2) Chicago's public key
59ONLY. Do not copy Chicago's private key over to Boston, because (a)
60it is not necessary, and (b) you would now have two potential places
61for losing control of your private key.
62
634) You should now configure the racoon.conf configuration file for
64each host to (a) turn on RSA authentication, and (b) designate each
65host's private key and the remote host(s)'s public key(s). Take all
66your keys and place it in one directory and use the global directive
67"path certificate" to specify the location of the keys. This step is
68especially important if you are running racoon with privilege
69separation, because if racoon cannot find the keys inside the
70directory you have just specified it will fail the authentication
71process. So, write the directive like the following:
72
73 path certificate "/etc/racoon";
74
75Next, you need to specify the host's own private key and the public
76keys of all the remote peers involved. For your local private key and
77remote public key(s), you should use the following directives:
78
79 certificate_type plain_rsa "/etc/racoon/boston.priv";
80 peers_certfile plain_rsa "/etc/racoon/chicago.pub";
81
82Notice the option "plain_rsa" for both directives.
83
84Finally, under the "proposal" statement section, you should specify
85the "rsasig" option for "authentication_method".
86
875) You have finished configuring the host for RSA authentication.
88Now use racoonctl to reload the configuration or simply restart the
89machine and you should be all set.
90
91TROUBLESHOOTING
92
93In the event that the hosts fail to communicate, first go back to the
94instructions above and make sure that:
95
961) You have placed all the keys in the directory that is specified by
97the "path certificate" directive. Keep in mind that privilege
98separation will force racoon to look into that directory and nowhere
99else.
1002) You have specified correctly the host's own private key and the
101remote peer's public key.
1023) You have specified the "rsasig" method for authentication in the
103proposal statement.
104
105If you run into any further problems, you should try to use "racoon
106-v" to debug the setup, and send a copy of the debug messages to the
107mailing list so that we can help you determine what the problem is.
108
109Last modified: $Date: 2006/12/10 05:51:14 $
110