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 # Create /home/user/hs20-server/terms-and-conditions file (HTML segment to be
  99 # inserted within the BODY section of the page).
 100 cat > /home/user/hs20-server/terms-and-conditions <<EOF
 101 <P>Terms and conditions..</P>
 102 EOF
 103
 104 # Build local keys and certs
 105 cd ca
 106 # Display help options.
 107 ./setup.sh -h
 108
 109 # Remove old keys, fill in appropriate values, and generate your keys.
 110 # For instance:
 111 ./clean.sh
 112 rm -fr rootCA"
 113 old_hostname=myserver.local
 114 ./setup.sh -C "Hotspot 2.0 Trust Root CA - CT" \
 115    -o $old_hostname-osu-client \
 116    -O $old_hostname-oscp -p lanforge -S $old_hostname \
 117    -V $old_hostname-osu-revoked \
 118    -m local -u http://$old_hostname:8888/
 119
 120 # Configure subscription policies
 121 mkdir -p /home/user/hs20-server/spp/policy
 122 cat > /home/user/hs20-server/spp/policy/default.xml <<EOF
 123 <Policy>
 124         <PolicyUpdate>
 125                 <UpdateInterval>30</UpdateInterval>
 126                 <UpdateMethod>ClientInitiated</UpdateMethod>
 127                 <Restriction>Unrestricted</Restriction>
 128                 <URI>https://policy-server.osu.example.com/hs20/spp.php</URI>
 129         </PolicyUpdate>
 130 </Policy>
 131 EOF
 132
 133
 134 # Install Hotspot 2.0 SPP and OMA DM XML schema/DTD files
 135
 136 # XML schema for SPP
 137 # Copy the latest XML schema into /home/user/hs20-server/spp/spp.xsd
 138
 139 # OMA DM Device Description Framework DTD
 140 # Copy into /home/user/hs20-server/spp/dm_ddf-v1_2.dtd
 141 # http://www.openmobilealliance.org/tech/DTD/dm_ddf-v1_2.dtd
 142
 143
 144 # Configure RADIUS authentication service
 145 # Note: Change the URL to match the setup
 146 # Note: Install AAA server key/certificate and root CA in Key directory
 147
 148 cat > /home/user/hs20-server/AS/as-sql.conf <<EOF
 149 driver=none
 150 radius_server_clients=as.radius_clients
 151 eap_server=1
 152 eap_user_file=sqlite:DB/eap_user.db
 153 ca_cert=Key/ca.pem
 154 server_cert=Key/server.pem
 155 private_key=Key/server.key
 156 private_key_passwd=passphrase
 157 eap_sim_db=unix:/tmp/hlr_auc_gw.sock db=eap_sim.db
 158 subscr_remediation_url=https://subscription-server.osu.example.com/hs20/spp.php
 159 EOF
 160
 161 # Set RADIUS passphrase for the APs
 162 # Note: Modify to match the setup
 163 cat > /home/user/hs20-server/AS/as.radius_clients <<EOF
 164 0.0.0.0/0       radius
 165 EOF
 166
 167
 168 Start RADIUS authentication server
 169 ----------------------------------
 170
 171 cd /home/user/hs20-server/AS
 172 ./hostapd -B as-sql.conf
 173
 174
 175 OSEN RADIUS server configuration notes
 176
 177 The OSEN RADIUS server config file should have the 'ocsp_stapling_response'
 178 configuration in it. For example:
 179
 180 # hostapd-radius config for the radius used by the OSEN AP
 181 interface=eth0#0
 182 driver=none
 183 logger_syslog=-1
 184 logger_syslog_level=2
 185 logger_stdout=-1
 186 logger_stdout_level=2
 187 ctrl_interface=/var/run/hostapd
 188 ctrl_interface_group=0
 189 eap_server=1
 190 eap_user_file=/home/user/hs20-server/AS/hostapd-osen.eap_user
 191 server_id=ben-ota-2-osen
 192 radius_server_auth_port=1811
 193 radius_server_clients=/home/user/hs20-server/AS/hostap.radius_clients
 194
 195 ca_cert=/home/user/hs20-server/ca/ca.pem
 196 server_cert=/home/user/hs20-server/ca/server.pem
 197 private_key=/home/user/hs20-server/ca/server.key
 198 private_key_passwd=whatever
 199
 200 ocsp_stapling_response=/home/user/hs20-server/ca/ocsp-server-cache.der
 201
 202 The /home/user/hs20-server/AS/hostapd-osen.eap_user file should look
 203 similar to this, and should coorelate with the osu_nai entry in
 204 the non-OSEN VAP config file.  For instance:
 205
 206 # cat hostapd-osen.eap_user
 207 # For OSEN authentication (Hotspot 2.0 Release 2)
 208 "osen@w1.fi"      WFA-UNAUTH-TLS
 209
 210
 211 # Run OCSP server:
 212 cd /home/user/hs20-server/ca
 213 ./ocsp-responder.sh&
 214
 215 # Update cache (This should be run periodically)
 216 ./ocsp-update-cache.sh
 217
 218
 219 Configure web server
 220 --------------------
 221
 222 Edit /etc/apache2/sites-available/default-ssl
 223
 224 Add following block just before "SSL Engine Switch" line":
 225
 226         Alias /hs20/ "/home/user/hs20-server/www/"
 227         <Directory "/home/user/hs20-server/www/">
 228                 Options Indexes MultiViews FollowSymLinks
 229                 AllowOverride None
 230                 Require all granted
 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