libeap/hs20/server/hs20-osu-server.txt

   1 Hotspot 2.0 OSU server
   2 ======================
   3
   4 The information in this document is based on the assumption that Ubuntu
   5 12.04 server (64-bit) distribution is used and the web server is
   6 Apache2. Neither of these are requirements for the installation, but if
   7 other combinations are used, the package names and configuration
   8 parameters may need to be adjusted.
   9
  10 NOTE: This implementation and the example configuration here is meant
  11 only for testing purposes in a lab environment. This design is not
  12 secure to be installed in a publicly available Internet server without
  13 considerable amount of modification and review for security issues.
  14
  15 NOTE: While this describes use on Ubuntu 12.04, the version of Apache2
  16 included in that distribution is not new enough to support all OSU
  17 server validation steps. In other words, it may be most adapt the steps
  18 described here to Ubuntu 13.10.
  19
  20
  21 Build dependencies
  22 ------------------
  23
  24 Ubuntu 12.04 server
  25 - default installation
  26 - upgraded to latest package versions
  27   sudo apt-get update
  28   sudo apt-get upgrade
  29
  30 Packages needed for running the service:
  31   sudo apt-get install sqlite3
  32   sudo apt-get install apache2
  33   sudo apt-get install php5-sqlite libapache2-mod-php5
  34
  35 Additional packages needed for building the components:
  36   sudo apt-get install build-essential
  37   sudo apt-get install libsqlite3-dev
  38   sudo apt-get install libssl-dev
  39   sudo apt-get install libxml2-dev
  40
  41
  42 Installation location
  43 ---------------------
  44
  45 Select a location for the installation root directory. The example here
  46 assumes /home/user/hs20-server to be used, but this can be changed by
  47 editing couple of files as indicated below.
  48
  49 sudo mkdir -p /home/user/hs20-server
  50 sudo chown $USER /home/user/hs20-server
  51 mkdir -p /home/user/hs20-server/spp
  52 mkdir -p /home/user/hs20-server/AS
  53
  54
  55 Build
  56 -----
  57
  58 # hostapd as RADIUS server
  59 cd hostapd
  60
  61 #example build configuration
  62 cat > .config <<EOF
  63 CONFIG_DRIVER_NONE=y
  64 CONFIG_PKCS12=y
  65 CONFIG_RADIUS_SERVER=y
  66 CONFIG_EAP=y
  67 CONFIG_EAP_TLS=y
  68 CONFIG_EAP_MSCHAPV2=y
  69 CONFIG_EAP_PEAP=y
  70 CONFIG_EAP_GTC=y
  71 CONFIG_EAP_TTLS=y
  72 CONFIG_EAP_SIM=y
  73 CONFIG_EAP_AKA=y
  74 CONFIG_EAP_AKA_PRIME=y
  75 CONFIG_SQLITE=y
  76 CONFIG_HS20=y
  77 EOF
  78
  79 make hostapd hlr_auc_gw
  80 cp hostapd hlr_auc_gw /home/user/hs20-server/AS
  81
  82 # build hs20_spp_server
  83 cd ../hs20/server
  84 make clean
  85 make
  86 cp hs20_spp_server /home/user/hs20-server/spp
  87 # prepare database (web server user/group needs to have write access)
  88 mkdir -p /home/user/hs20-server/AS/DB
  89 sudo chgrp www-data /home/user/hs20-server/AS/DB
  90 sudo chmod g+w /home/user/hs20-server/AS/DB
  91 sqlite3 /home/user/hs20-server/AS/DB/eap_user.db < sql.txt
  92 sudo chgrp www-data /home/user/hs20-server/AS/DB/eap_user.db
  93 sudo chmod g+w /home/user/hs20-server/AS/DB/eap_user.db
  94 # add example configuration (note: need to update URLs to match the system)
  95 sqlite3 /home/user/hs20-server/AS/DB/eap_user.db < sql-example.txt
  96
  97 # copy PHP scripts
  98 # Modify config.php if different installation directory is used.
  99 # Modify PHP scripts to get the desired behavior for user interaction (or use
 100 # the examples as-is for initial testing).
 101 cp -r www /home/user/hs20-server
 102
 103 # Build local keys and certs
 104 cd ca
 105 # Display help options.
 106 ./setup.sh -h
 107
 108 # Remove old keys, fill in appropriate values, and generate your keys.
 109 # For instance:
 110 ./clean.sh
 111 rm -fr rootCA"
 112 old_hostname=myserver.local
 113 ./setup.sh -C "Hotspot 2.0 Trust Root CA - CT" -d $old_hostname \
 114    -I "Hotspot 2.0 Intermediate CA - CT" -o $old_hostname-osu-client \
 115    -O $old_hostname-oscp -p lanforge -S $old_hostname \
 116    -V $old_hostname-osu-revoked \
 117    -m local -u http://$old_hostname:8888/
 118
 119 # Configure subscription policies
 120 mkdir -p /home/user/hs20-server/spp/policy
 121 cat > /home/user/hs20-server/spp/policy/default.xml <<EOF
 122 <Policy>
 123         <PolicyUpdate>
 124                 <UpdateInterval>30</UpdateInterval>
 125                 <UpdateMethod>ClientInitiated</UpdateMethod>
 126                 <Restriction>Unrestricted</Restriction>
 127                 <URI>https://policy-server.osu.example.com/hs20/spp.php</URI>
 128         </PolicyUpdate>
 129 </Policy>
 130 EOF
 131
 132
 133 # Install Hotspot 2.0 SPP and OMA DM XML schema/DTD files
 134
 135 # XML schema for SPP
 136 # Copy the latest XML schema into /home/user/hs20-server/spp/spp.xsd
 137
 138 # OMA DM Device Description Framework DTD
 139 # Copy into /home/user/hs20-server/spp/dm_ddf-v1_2.dtd
 140 # http://www.openmobilealliance.org/tech/DTD/dm_ddf-v1_2.dtd
 141
 142
 143 # Configure RADIUS authentication service
 144 # Note: Change the URL to match the setup
 145 # Note: Install AAA server key/certificate and root CA in Key directory
 146
 147 cat > /home/user/hs20-server/AS/as-sql.conf <<EOF
 148 driver=none
 149 radius_server_clients=as.radius_clients
 150 eap_server=1
 151 eap_user_file=sqlite:DB/eap_user.db
 152 ca_cert=Key/ca.pem
 153 server_cert=Key/server.pem
 154 private_key=Key/server.key
 155 private_key_passwd=passphrase
 156 eap_sim_db=unix:/tmp/hlr_auc_gw.sock db=eap_sim.db
 157 subscr_remediation_url=https://subscription-server.osu.example.com/hs20/spp.php
 158 EOF
 159
 160 # Set RADIUS passphrase for the APs
 161 # Note: Modify to match the setup
 162 cat > /home/user/hs20-server/AS/as.radius_clients <<EOF
 163 0.0.0.0/0       radius
 164 EOF
 165
 166
 167 Start RADIUS authentication server
 168 ----------------------------------
 169
 170 cd /home/user/hs20-server/AS
 171 ./hostapd -B as-sql.conf
 172
 173
 174 OSEN RADIUS server configuration notes
 175
 176 The OSEN RADIUS server config file should have the 'ocsp_stapling_response'
 177 configuration in it. For example:
 178
 179 # hostapd-radius config for the radius used by the OSEN AP
 180 interface=eth0#0
 181 driver=none
 182 logger_syslog=-1
 183 logger_syslog_level=2
 184 logger_stdout=-1
 185 logger_stdout_level=2
 186 ctrl_interface=/var/run/hostapd
 187 ctrl_interface_group=0
 188 eap_server=1
 189 eap_user_file=/home/user/hs20-server/AS/hostapd-osen.eap_user
 190 server_id=ben-ota-2-osen
 191 radius_server_auth_port=1811
 192 radius_server_clients=/home/user/hs20-server/AS/hostap.radius_clients
 193
 194 ca_cert=/home/user/hs20-server/ca/ca.pem
 195 server_cert=/home/user/hs20-server/ca/server.pem
 196 private_key=/home/user/hs20-server/ca/server.key
 197 private_key_passwd=whatever
 198
 199 ocsp_stapling_response=/home/user/hs20-server/ca/ocsp-server-cache.der
 200
 201 The /home/user/hs20-server/AS/hostapd-osen.eap_user file should look
 202 similar to this, and should coorelate with the osu_nai entry in
 203 the non-OSEN VAP config file.  For instance:
 204
 205 # cat hostapd-osen.eap_user
 206 # For OSEN authentication (Hotspot 2.0 Release 2)
 207 "osen@w1.fi"      WFA-UNAUTH-TLS
 208
 209
 210 # Run OCSP server:
 211 cd /home/user/hs20-server/ca
 212 ./ocsp-responder.sh&
 213
 214 # Update cache (This should be run periodically)
 215 ./ocsp-update-cache.sh
 216
 217
 218 Configure web server
 219 --------------------
 220
 221 Edit /etc/apache2/sites-available/default-ssl
 222
 223 Add following block just before "SSL Engine Switch" line":
 224
 225         Alias /hs20/ "/home/user/hs20-server/www/"
 226         <Directory "/home/user/hs20-server/www/">
 227                 Options Indexes MultiViews FollowSymLinks
 228                 AllowOverride None
 229                 Order allow,deny
 230                 Allow from all
 231         </Directory>
 232
 233 Update SSL configuration to use the OSU server certificate/key.
 234 They keys and certs are called 'server.key' and 'server.pem' from
 235 ca/setup.sh.
 236
 237 Enable default-ssl site and restart Apache2:
 238   sudo a2ensite default-ssl
 239   sudo a2enmod ssl
 240   sudo service apache2 restart
 241
 242
 243 Management UI
 244 -------------
 245
 246 The sample PHP scripts include a management UI for testing
 247 purposes. That is available at https://<server>/hs20/users.php
 248
 249
 250 AP configuration
 251 ----------------
 252
 253 APs can now be configured to use the OSU server as the RADIUS
 254 authentication server. In addition, the OSU Provider List ANQP element
 255 should be configured to use the SPP (SOAP+XML) option and with the
 256 following Server URL:
 257 https://<server>/hs20/spp.php/signup?realm=example.com