| Up to higher level directory | |||
| Name | Date | Size | |
|---|---|---|---|
| FAQ | 15-Nov-2011 | 4.1K | |
| README.certificate | 15-Nov-2011 | 46 | |
| README.gssapi | 15-Nov-2011 | 5.4K | |
| README.plainrsa | 15-Nov-2011 | 5.4K | |
| README.privsep | 15-Nov-2011 | 5.9K | |
README.certificate
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 (a] 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 (a] wasabisystems.com> 106 107
README.plainrsa
1 HOW-TO use plainrsa auth, contributed by Simon Chang <simonychang (a] gmail.com> 2 3 Before you begin, you should understand that the RSA authentication 4 mechanism hinges upon the idea of a split cryptographic key: one used 5 by the public, the other readable only to you. Any data that is 6 encrypted by a public key can be decrypted only by the corresponding 7 private key, so that the private key user can be assured that the 8 content of the transmission has not been examined by unauthorized 9 parties. Similarly, any data encrypted by the private key can be 10 decrypted by the public key so that the public knows that this 11 transmission came from this user and nobody else (this idea is called 12 non-repudiation). Also, the longer the key length, the more difficult 13 it would be for potential attacker to conduct brute-force discovery of 14 the keys. So, what all this means for the security administrator is 15 that the setup needs a pair of reasonably long keys for each host that 16 wishes to authenticate in this manner. 17 18 With this in mind, it should be relatively straightforward to set up 19 RSA authentication. For the purpose of this document, we assume that 20 we are setting up RSA authentication between two networked hosts 21 called Boston and Chicago. Unless otherwise noted, all steps should 22 be performed on both hosts with corresponding key names. Here are the 23 steps: 24 25 1) Included in each default installation of ipsec-tools is a binary 26 called plainrsa-gen. This executable is used to generate a pair of 27 RSA keys for the host. There are only two parameters that you should 28 be concerned about: -b, which sets the number of bits for the keys, 29 and -f, which specifies the output file for plainrsa-gen to send the 30 results. On an ordinary Pentium-II with 128 MB of RAM, it takes only 31 seconds to generate keys that are 2048 bits long, and only slightly 32 longer to generate 4096-bit keys. Either key length should be 33 sufficient; any longer key length actually reduces performance and 34 does not increase security significantly. You should therefore run it 35 as: 36 37 plainrsa-gen -b 2048 -f /var/tmp/boston.keys 38 39 2) When the process completes, you should have a text file that 40 includes both public and private keys. GUARD THIS FILE CAREFULLY, 41 because once a private key is compromised it is no longer any good, 42 and you must generate a new pair from scratch. Reading the file 43 itself, you should see several very long lines of alphanumeric data. 44 The only line you should be concerned with is the line towards the top 45 of the output file that begins with "# pubkey=0sAQPAmBdT/" or 46 something to that effect. This line is your public key, which should 47 be made available to the other host that you are setting up. Copy 48 this line to a separate file called "boston.pub" and change the 49 beginning of the line so that it reads ": PUB 0sAQPAmBdT/". 50 Alternatively, you can also grab the first line of the boston.keys 51 file and uncomment the line so that it reads the same as above. Now 52 rename the file you generated initially to "boston.priv". 53 54 3) You should now have two files, boston.priv and boston.pub 55 (chicago.priv and chicago.pub on Chicago). The first file contains 56 your private key and the second file your public key. Next you should 57 find a way to get the public key over to the other host involved. 58 Boston should have (1) its own key pair, and (2) Chicago's public key 59 ONLY. Do not copy Chicago's private key over to Boston, because (a) 60 it is not necessary, and (b) you would now have two potential places 61 for losing control of your private key. 62 63 4) You should now configure the racoon.conf configuration file for 64 each host to (a) turn on RSA authentication, and (b) designate each 65 host's private key and the remote host(s)'s public key(s). Take all 66 your 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 68 especially important if you are running racoon with privilege 69 separation, because if racoon cannot find the keys inside the 70 directory you have just specified it will fail the authentication 71 process. So, write the directive like the following: 72 73 path certificate "/etc/racoon"; 74 75 Next, you need to specify the host's own private key and the public 76 keys of all the remote peers involved. For your local private key and 77 remote 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 82 Notice the option "plain_rsa" for both directives. 83 84 Finally, under the "proposal" statement section, you should specify 85 the "rsasig" option for "authentication_method". 86 87 5) You have finished configuring the host for RSA authentication. 88 Now use racoonctl to reload the configuration or simply restart the 89 machine and you should be all set. 90 91 TROUBLESHOOTING 92 93 In the event that the hosts fail to communicate, first go back to the 94 instructions above and make sure that: 95 96 1) You have placed all the keys in the directory that is specified by 97 the "path certificate" directive. Keep in mind that privilege 98 separation will force racoon to look into that directory and nowhere 99 else. 100 2) You have specified correctly the host's own private key and the 101 remote peer's public key. 102 3) You have specified the "rsasig" method for authentication in the 103 proposal statement. 104 105 If 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 107 mailing list so that we can help you determine what the problem is. 108 109 Last modified: $Date: 2006/12/10 05:51:14 $ 110
README.privsep
1 Using Racoon with Privilege Separation 2 Tue Mar 25 16:37:09 MDT 2008 3 4 5 Racoon can run in a chroot'd environment. When so instructed, it runs as two 6 processes, one of which handles a small number of simple requests and runs as 7 root in the full native filesystem, and another which runs as a less 8 privileged user in a chroot'd environment and which handles all the other and 9 very complex business of racoon. 10 11 Because racoon does many complex things there are many opportunities for 12 coding errors to lead to compromises and so this separation is important. If 13 someone breaks into your system using racoon and you have enabled privilege 14 separation, they will find themselves in a very limited environment and unable 15 to do much damage. They may be able to alter the host's security associations 16 or obtain the private keys stored on that system using file descriptors 17 available to the unprivileged instance of racoon, and from there they will be 18 able to alter security associations on other hosts in disruptive or dangerous 19 ways if you have generate_policy enabled on those hosts. But that's because 20 in its current form generate_policy is itself dangerous and requires that you 21 trust anyone with the credentials to use it. 22 23 They will also be able to execute any scripts you have placed in the scripts 24 directory, although racoon will prevent them from mis-using the traditional 25 environment variables PATH, LD_LIBRARY_PATH, and IFS. But if you have 26 introduced vulnerabilities into your scripts you may want to re-visit them. 27 The thing to watch for is blindly trusting the environment variables passed 28 in by racoon - assume they could be set to anything by a malicious entity and 29 check them for suitability before using them. 30 31 All these possibilities are present when privilege separation is not enabled, 32 and they are greatly reduced when it is enabled because the resources 33 available to the attacker are less. 34 35 ***** 36 37 The basic concept with racoon's privilege separation is that a minimal 38 environment containing all the files racoon needs to operate - with the 39 exception of private keys, scripts, and system-wide authentication services - 40 is placed in a stripped-down copy of the original environment. The private 41 keys and scripts are left in the original environment where only the 42 privileged instance of racoon will have access to them. 43 44 Here are basic instructions for setting up racoon to run with privilege 45 separation: 46 47 48 First, create a user/group for racoon to run under. For example, user:group 49 ike:ike. The account should not have a usable password or real home 50 directory, so copy the general format of another system-services type account 51 such as 'daemon'. 52 53 You already have files in, e.g. /usr/local/etc/racoon - perhaps racoon.conf, a 54 certs directory containing certificates, a scripts directory, and other 55 miscellaneous files such as welcome messages. Perform the following steps: 56 57 cd /usr/local/etc/racoon 58 mkdir root 59 mv certs root 60 mkdir certs 61 mv root/certs/*.key certs 62 63 If you want to be able to switch back and forth between using and not using 64 privsep, do this too: 65 66 cd /usr/local/etc/racoon/certs 67 for i in ../root/certs/* 68 do 69 ln -s $i . 70 done 71 72 Now root/certs contains certificates and certs contains the keys. The idea is 73 that the public certificates are in the chroot'd area 74 (/usr/local/etc/racoon/root) and the keys are available only to the privileged 75 instance of racoon. 76 77 Move any other racoon configuration data into /usr/local/etc/racoon/root, 78 with the exception of the scripts directory and racoon.conf. 79 80 All the files in /usr/local/etc/racoon/root should be owned by root and the 81 ike:ike user you created should not have write access to any directories or 82 files (unless you are using something like 'path backupsa', but you get the 83 idea). 84 85 Create the device nodes: 86 87 mkdir root/dev 88 89 Do whatever your OS requires to populate the new dev directory with a 90 minimal set of devices, e.g. mknod, MAKEDEV, or mount devfs... In freebsd 91 this is done by adding a line to /etc/fstab: 92 93 devfs /usr/local/etc/racoon/root/dev devfs rw 0 0 94 95 and then adding a line like this to /etc/rc.conf: 96 97 devfs_set_rulesets="/usr/local/etc/racoon/root/dev=devfsrules_basic" 98 99 and then adding the following lines to /etc/devfs.rules: 100 101 [devfsrules_basic=10] 102 add include $devfsrules_hide_all 103 add include $devfsrules_unhide_basic 104 105 and then either rebooting or entering "mount -a && /etc/rc.d/devfs start". 106 107 When done with that: 108 109 mkdir -p root/usr/local/etc 110 ln -s ../../../ root/usr/local/etc/racoon 111 112 This dummy hierarchy keeps the config file consistent between both copies of 113 racoon. Of course, you could actually put the certs directory and any other 114 configuration data down in the hierarchy but I prefer to leave it at the root 115 and link to it as shown. You may end up with something like this: 116 117 root# ls -FC /usr/local/etc/racoon/root 118 certs/ dev/ usr/ 119 120 root# ls -l /usr/local/etc/racoon/root/usr/local/etc 121 lrwxr-xr-x 1 root wheel 9 Mar 7 22:13 racoon -> ../../../ 122 123 root# ls -FC /usr/local/etc/racoon/root/usr/local/etc/racoon/ 124 certs/ dev/ usr/ 125 126 Presumably your racoon.conf already contains something like: 127 128 path certificate "/usr/local/etc/racoon/certs"; 129 path script "/usr/local/etc/racoon/scripts"; 130 131 If so, great. If not, add them. Then, finally, add the privsep section: 132 133 privsep { 134 user "ike"; 135 group "ike"; 136 chroot "/usr/local/etc/racoon/root"; 137 } 138 139 Apply the patches posted to the list and rebuild racoon (the patches will be 140 incorporated into the release subsequent to the date of this memo, so if you 141 use that or a later release you can skip this step). 142 143 Restart racoon and hopefully things will work. As of the date of this memo, 144 re-loading the configuration file with racoonctl will not work with privsep 145 enabled. However, the problem is not insurmountable and if you figure it out 146 let us know. 147 148 I have not tested privsep with many of racoon's features such as XAUTH or 149 scripts, so if you have trouble with them and work anything out please reply 150 to the list so that your discoveries may be incorporated into this document. 151 152 Last modified: $Date: 2008/03/28 04:18:52 $ 153
