Home | History | Annotate | Download | only in server
      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 (a] 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
    258