| 1 | INSTALLATION INSTRUCTIONS for SECNET |
| 2 | |
| 3 | USE AT YOUR OWN RISK. THIS IS ALPHA TEST SOFTWARE. I DO NOT |
| 4 | GUARANTEE THAT THERE WILL BE PROTOCOL COMPATIBILITY BETWEEN DIFFERENT |
| 5 | VERSIONS. |
| 6 | |
| 7 | PROTOCOL COMPATIBILITY WAS BROKEN BETWEEN secnet-0.06, secnet-0.07 AND |
| 8 | secnet-0.08 FOR ENDIANNESS FIXES. |
| 9 | |
| 10 | THERE WILL BE ANOTHER CHANGE IN PROTOCOL IN THE secnet-0.1.x SERIES |
| 11 | |
| 12 | * Preparation |
| 13 | |
| 14 | ** System software support |
| 15 | |
| 16 | Ensure that you have libgmp2-dev and adns installed (and bison and |
| 17 | flex, and for that matter gcc...). |
| 18 | |
| 19 | [On BSD install /usr/ports/devel/bison and /usr/ports/devel/libgnugetopt] |
| 20 | |
| 21 | If you intend to configure secnet to obtain packets from the kernel |
| 22 | through userv-ipif, install and configure userv-ipif. It is part of |
| 23 | userv-utils, available from ftp.chiark.greenend.org.uk in |
| 24 | /users/ian/userv |
| 25 | |
| 26 | If you intend to configure secnet to obtain packets from the kernel |
| 27 | using the universal TUN/TAP driver, make sure it's configured in your |
| 28 | kernel (it's under "network device support" in Linux-2.4) and that |
| 29 | you've created the appropriate device files; see |
| 30 | linux/Documentation/networking/tuntap.txt |
| 31 | |
| 32 | If you're using TUN/TAP on a platform other than Linux-2.4, see |
| 33 | http://vtun.sourceforge.net/tun/ |
| 34 | |
| 35 | Note than TUN comes in two flavours, one (called 'tun' in the secnet |
| 36 | config file) which has only one device file (usually /dev/net/tun) and |
| 37 | the other (called 'tun-old') which has many device files (/dev/tun*). |
| 38 | Linux-2.4 has new-style TUN, Linux-2.2, BSD and Solaris have old-style |
| 39 | TUN. |
| 40 | |
| 41 | ** System and network configuration |
| 42 | |
| 43 | If you intend to start secnet as root, I suggest you create a userid |
| 44 | for it to run as once it's ready to drop its privileges. Example (on |
| 45 | Debian): |
| 46 | # adduser --system --no-create-home secnet |
| 47 | |
| 48 | You will need to allocate two IP addresses for use by secnet. One |
| 49 | will be for the tunnel interface on your tunnel endpoint machine (i.e. |
| 50 | the address you see in 'ifconfig' when you look at the tunnel |
| 51 | interface). The other will be for secnet itself. These addresses |
| 52 | could possibly be allocated from the range used by your internal |
| 53 | network: if you do this, you should think about providing appropriate |
| 54 | proxy-ARP on the internal network interface of the machine running |
| 55 | secnet (eg. add an entry net/ipv4/conf/eth_whatever/proxy_arp = 1 to |
| 56 | /etc/sysctl.conf on Debian systems and run sysctl -p). Alternatively |
| 57 | the addresses could be from some other range - this works well if the |
| 58 | machine running secnet is the default route out of your network. |
| 59 | |
| 60 | http://www.ucam.org/cam-grin/ may be useful. |
| 61 | |
| 62 | * Installation |
| 63 | |
| 64 | If you installed the Debian package of secnet, skip to "If installing |
| 65 | for the first time", below, and note that example.conf can be found in |
| 66 | /usr/share/doc/secnet/examples. |
| 67 | |
| 68 | To install secnet do |
| 69 | |
| 70 | $ ./configure |
| 71 | $ make |
| 72 | # make install |
| 73 | # mkdir /etc/secnet |
| 74 | |
| 75 | (Note: you may see the following warning while compiling |
| 76 | conffile.tab.c; I believe this is a bison bug: |
| 77 | /usr/share/bison/bison.simple: In function `yyparse': |
| 78 | /usr/share/bison/bison.simple:285: warning: `yyval' might be used |
| 79 | uninitialized in this function |
| 80 | ) |
| 81 | |
| 82 | Any other warnings or errors should be reported to |
| 83 | steve@greenend.org.uk. |
| 84 | |
| 85 | If installing for the first time, do |
| 86 | |
| 87 | # cp example.conf /etc/secnet/secnet.conf |
| 88 | # cd /etc/secnet |
| 89 | # ssh-keygen -f key -N "" |
| 90 | |
| 91 | [On BSD use |
| 92 | $ LDFLAGS="-L/usr/local/lib" ./configure |
| 93 | $ gmake CFLAGS="-I/usr/local/include" LDFLAGS="-L/usr/local/lib" |
| 94 | XXX this should eventually be worked out automatically by 'configure'.] |
| 95 | |
| 96 | Generate a site file fragment for your site (see below), and submit it |
| 97 | for inclusion in your VPN's 'sites' file. Download the vpn-sites file |
| 98 | to /etc/secnet/sites - MAKE SURE YOU GET AN AUTHENTIC COPY because the |
| 99 | sites file contains public keys for all the sites in the VPN. |
| 100 | |
| 101 | * Configuration |
| 102 | |
| 103 | Should be reasonably obvious - edit /etc/secnet/secnet.conf as |
| 104 | prompted by the comments. XXX Fuller documentation of the |
| 105 | configuration file format should be forthcoming in time. Its syntax |
| 106 | is described in the README file at the moment. |
| 107 | |
| 108 | * Constructing your site file fragment |
| 109 | |
| 110 | You need the following information: |
| 111 | |
| 112 | 1. a short name for your site, eg. "greenend". This is used to |
| 113 | identify your site in the vpn-sites file. |
| 114 | |
| 115 | 2. the name your site will use in the key setup protocol, |
| 116 | eg. "greenend" (these two will usually be similar or the same). |
| 117 | |
| 118 | 3. the DNS name of the machine that will be the "front-end" for your |
| 119 | secnet installation. This will typically be the name of the gateway |
| 120 | machine for your network, eg. sinister.dynamic.greenend.org.uk |
| 121 | |
| 122 | secnet does not actually have to run on this machine, as long as the |
| 123 | machine can be configured to forward UDP packets to the machine that |
| 124 | is running secnet. |
| 125 | |
| 126 | 4. the port number used to contact secnet at your site. This is the |
| 127 | port number on the front-end machine, and does not necessarily have to |
| 128 | match the port number on the machine running secnet. |
| 129 | |
| 130 | 5. the list of networks accessible at your site over the VPN. |
| 131 | |
| 132 | 6. the public part of the RSA key you generated during installation |
| 133 | (in /etc/secnet/key.pub if you followed the installation |
| 134 | instructions). This file contains three numbers and a comment on one |
| 135 | line. The first number is the key length in bits, and should be |
| 136 | ignored. The second number (typically small) is the encryption key |
| 137 | 'e', and the third number (large) is the modulus 'n'. |
| 138 | |
| 139 | If you are running secnet on a particularly slow machine, you may like |
| 140 | to specify a larger value for the key setup retry timeout than the |
| 141 | default, to prevent unnecessary retransmissions of key setup packets. |
| 142 | See the notes in the example configuration file for more on this. |
| 143 | |
| 144 | The site file fragment should look something like this: |
| 145 | |
| 146 | shortname { |
| 147 | name "sitename"; |
| 148 | address "your.public.address.org.uk"; |
| 149 | port 5678; |
| 150 | networks "172.18.45.0/24"; |
| 151 | key rsa-public("35","153279875126380522437827076871354104097683702803616313419670959273217685015951590424876274370401136371563604396779864283483623325238228723798087715987495590765759771552692972297669972616769731553560605291312242789575053620182470998166393580503400960149506261455420521811814445675652857085993458063584337404329"); |
| 152 | }; |
| 153 | |
| 154 | See 'example-sites-file' for more examples. |