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