1 Notes about generic-sessions Plugin
2 ===================================
4 @section gseb Enabling lwsgs for build
6 Enable at CMake with -DLWS_WITH_GENERIC_SESSIONS=1
8 This also needs sqlite3 (libsqlite3-dev or similar package)
11 @section gsi lwsgs Introduction
13 The generic-sessions protocol plugin provides cookie-based login
14 authentication for lws web and ws connections.
16 The plugin handles everything about generic account registration,
17 email verification, lost password, account deletion, and other generic account
20 Other code, in another eg, ws protocol handler, only needs very high-level
21 state information from generic-sessions, ie, which user the client is
22 authenticated as. Everything underneath is managed in generic-sessions.
25 - random 20-byte session id managed in a cookie
27 - all information related to the session held at the server, nothing managed clientside
29 - sqlite3 used at the server to manage active sessions and users
31 - defaults to creating anonymous sessions with no user associated
33 - admin account (with user-selectable username) is defined in config with a SHA-1 of the password; rest of the accounts are in sqlite3
35 - user account passwords stored as salted SHA-1 with additional confounder
36 only stored in the JSON config, not the database
38 - login, logout, register account + email verification built-in with examples
40 - in a mount, some file suffixes (ie, .js) can be associated with a protocol for the purposes of rewriting symbolnames. These are read-only copies of logged-in server state.
42 - When your page fetches .js or other rewritten files from that mount, "$lwsgs_user" and so on are rewritten on the fly using chunked transfer encoding
44 - Eliminates server-side scripting with a few rewritten symbols and
45 javascript on client side
47 - 32-bit bitfield for authentication sectoring, mounts can provide a mask on the loggin-in session's associated server-side bitfield that must be set for access.
49 - No code (just config) required for, eg, private URL namespace that requires login to access.
52 @section gsin Lwsgs Integration to HTML
54 Only three steps are needed to integrate lwsgs in your HTML.
56 1) lwsgs HTML UI is bundled with the javascript it uses in `lwsgs.js`, so
57 import that script file in your head section
59 2) define an empty div of id "lwsgs" somewhere
61 3) Call lwsgs_initial() in your page
63 That's it. An example is below
68 <script src="lwsgs.js"></script>
70 .body { font-size: 12 }
71 .gstitle { font-size: 18 }
74 <body style="background-image:url(seats.jpg)">
75 <table style="width:100%;transition: max-height 2s;">
77 <td style="vertical-align:top;text-align:left;width=200px">
78 <img src="lwsgs-logo.png">
80 <td style="vertical-align:top;float:right">
81 <div id=lwsgs style="text-align:right;background-color: rgba(255, 255, 255, 0.8);"></div>
87 <script>lwsgs_initial();</script>
93 @section gsof Lwsgs Overall Flow@
95 When the protocol is initialized, it gets per-vhost information from the config, such
96 as where the sqlite3 databases are to be stored. The admin username and sha-1 of the
97 admin password are also taken from here.
99 In the mounts using protocol-generic-sessions, a cookie is maintained against any requests; if no cookie was active on the initial request a new session is
100 created with no attached user.
102 So there should always be an active session after any transactions with the server.
104 In the example html going to the mount /lwsgs loads a login / register page as the default.
106 The <form> in the login page contains 'next url' hidden inputs that let the html 'program' where the form handler will go after a successful admin login, a successful user login and a failed login.
108 After a successful login, the sqlite record at the server for the current session is updated to have the logged-in username associated with it.
112 @section gsconf Lwsgs Configuration
114 "auth-mask" defines the authorization sector bits that must be enabled on the session to gain access.
116 "auth-mask" 0 is the default.
118 - b0 is set if you are logged in as a user at all.
119 - b1 is set if you are logged in with the user configured to be admin
120 - b2 is set if the account has been verified (the account configured for admin is always verified)
121 - b3 is set if your session just did the forgot password flow successfully
125 # things in here can always be served
126 "mountpoint": "/lwsgs",
127 "origin": "file:///usr/share/libwebsockets-test-server/generic-sessions",
128 "origin": "callback://protocol-lws-messageboard",
129 "default": "generic-sessions-login-example.html",
132 ".js": "protocol-lws-messageboard"
135 # things in here can only be served if logged in as a user
136 "mountpoint": "/lwsgs/needauth",
137 "origin": "file:///usr/share/libwebsockets-test-server/generic-sessions/needauth",
138 "origin": "callback://protocol-lws-messageboard",
139 "default": "generic-sessions-login-example.html",
140 "auth-mask": "5", # logged in as a verified user
142 ".js": "protocol-lws-messageboard"
145 # things in here can only be served if logged in as admin
146 "mountpoint": "/lwsgs/needadmin",
147 "origin": "file:///usr/share/libwebsockets-test-server/generic-sessions/needadmin",
148 "origin": "callback://protocol-lws-messageboard",
149 "default": "generic-sessions-login-example.html",
150 "auth-mask": "7", # b2 = verified (by email / or admin), b1 = admin, b0 = logged in with any user name
152 ".js": "protocol-lws-messageboard"
156 Note that the name of the real application protocol that uses generic-sessions
157 is used, not generic-sessions itself.
159 The vhost configures the storage dir, admin credentials and session cookie lifetimes:
163 "protocol-generic-sessions": {
165 "admin-user": "admin",
167 # create the pw hash like this (for the example pw, "jipdocesExunt" )
168 # $ echo -n "jipdocesExunt" | sha1sum
169 # 046ce9a9cca769e85798133be06ef30c9c0122c9 -
171 # Obviously ** change this password hash to a secret one before deploying **
173 "admin-password-sha1": "046ce9a9cca769e85798133be06ef30c9c0122c9",
174 "session-db": "/var/www/sessions/lws.sqlite3",
175 "timeout-idle-secs": "600",
176 "timeout-anon-idle-secs": "1200",
177 "timeout-absolute-secs": "6000",
178 # the confounder is part of the salted password hashes. If this config
179 # file is in a 0700 root:root dir, an attacker with apache credentials
180 # will have to get the confounder out of the process image to even try
181 # to guess the password hashes.
182 "confounder": "Change to <=31 chars of junk",
184 "email-from": "noreply@example.com",
185 "email-smtp-ip": "127.0.0.1",
186 "email-expire": "3600",
187 "email-helo": "myhost.com",
188 "email-contact-person": "Set Me <real-person@email.com>",
189 "email-confirm-url-base": "http://localhost:7681/lwsgs"
193 The email- related settings control generation of automatic emails for
194 registration and forgotten password.
196 - `email-from`: The email address automatic emails are sent from
198 - `email-smtp-ip`: Normally 127.0.0.1, if you have a suitable server on port
199 25 on your lan you can use this instead here.
201 - `email-expire`: Seconds that links sent in email will work before being
204 - `email-helo`: HELO to use when communicating with your SMTP server
206 - `email-contact-person`: mentioned in the automatic emails as a human who can
209 - `email-confirm-url-base`: the URL to start links with in the emails, so the
210 recipient can get back to the web server
212 The real protocol that makes use of generic-sessions must also be listed and
213 any configuration it needs given
216 "protocol-lws-messageboard": {
218 "message-db": "/var/www/sessions/messageboard.sqlite3"
222 Notice the real application uses his own sqlite db, no details about how
223 generic-sessions works or how it stores data are available to it.
226 @section gspwc Lwsgs Password Confounder
228 You can also define a per-vhost confounder shown in the example above, used
229 when aggregating the password with the salt when it is hashed. Any attacker
230 will also need to get the confounder along with the database, which you can
231 make harder by making the config dir only eneterable / readable by root.
234 @section gsprep Lwsgs Preparing the db directory
236 You will have to prepare the db directory so it's suitable for the lwsws user to use,
237 that usually means apache, eg
240 # mkdir -p /var/www/sessions
241 # chown root:apache /var/www/sessions
242 # chmod 770 /var/www/sessions
245 @section gsrmail Lwsgs Email configuration
247 lwsgs will can send emails by talking to an SMTP server on localhost:25. That
248 will usually be sendmail or postfix, you should confirm that works first by
249 itself using the `mail` application to send on it.
251 lwsgs has been tested on stock Fedora sendmail and postfix.
254 @section gsap Lwsgs Integration with another protocol
256 lwsgs is designed to provide sessions and accounts in a standalone and generic way.
258 But it's not useful by itself, there will always be the actual application who wants
259 to make use of generic-sessions features.
261 We provide the "messageboard" plugin as an example of how to integrate with
262 your actual application protocol.
264 The basic approach is the 'real' protocol handler (usually a plugin itself)
265 subclasses the generic-sessions plugin and calls through to it by default.
267 The "real" protocol handler entirely deals with ws-related stuff itself, since
268 generic-sessions does not use ws. But for
271 - LWS_CALLBACK_HTTP_BODY
272 - LWS_CALLBACK_HTTP_BODY_COMPLETION
273 - LWS_CALLBACK_HTTP_DROP_PROTOCOL
275 the "real" protocol handler checks if it recognizes the activity (eg, his own
276 POST form URL) and if not, passes stuff through to the generic-sessions protocol callback to handle it. To simplify matters the real protocol can just pass
277 through any unhandled messages to generic-sessions.
279 The "real" protocol can get a pointer to generic-sessions protocol on the
283 vhd->gsp = lws_vhost_name_to_protocol(vhd->vh, "protocol-generic-sessions");
286 The "real" protocol must also arrange generic-sessions per_session_data in his
287 own per-session allocation. To allow keeping generic-sessions opaque, the
288 real protocol must allocate that space at runtime, using the pss size
289 the generic-sessions protocol struct exposes
292 struct per_session_data__myapp {
296 pss->pss_gs = malloc(vhd->gsp->per_session_data_size);
299 The allocation reserved for generic-sessions is then used as user_space when
300 the real protocol calls through to the generic-sessions callback
303 vhd->gsp->callback(wsi, reason, &pss->pss_gs, in, len);
306 In that way the "real" protocol can subclass generic-sessions functionality.
309 To ease management of these secondary allocations, there are callbacks that
310 occur when a wsi binds to a protocol and when the binding is dropped. These
311 should be used to malloc and free and kind of per-connection
312 secondary allocations.
315 case LWS_CALLBACK_HTTP_BIND_PROTOCOL:
316 if (!pss || pss->pss_gs)
319 pss->pss_gs = malloc(vhd->gsp->per_session_data_size);
323 memset(pss->pss_gs, 0, vhd->gsp->per_session_data_size);
326 case LWS_CALLBACK_HTTP_DROP_PROTOCOL:
327 if (vhd->gsp->callback(wsi, reason, pss ? pss->pss_gs : NULL, in, len))
338 #section gsapsib Getting session-specific information from another protocol
340 At least at the time when someone tries to upgrade an http(s) connection to
341 ws(s) with your real protocol, it is necessary to confirm the cookie the http(s)
342 connection has with generic-sessions and find out his username and other info.
344 Generic sessions lets another protocol check it again by calling his callback,
345 and lws itself provides a generic session info struct to pass the related data
348 struct lws_session_info {
356 struct lws_session_info sinfo;
358 vhd->gsp->callback(wsi, LWS_CALLBACK_SESSION_INFO,
359 &pss->pss_gs, &sinfo, 0);
362 After the call to generic-sessions, the results can be
364 - all the strings will be zero-length and .mask zero, there is no usable cookie
366 - only .ip and .session are set: the cookie is OK but no user logged in
368 - all the strings contain information about the logged-in user
370 the real protocol can use this to reject attempts to open ws connections from
371 http connections that are not authenticated; afterwards there's no need to
372 check the ws connection auth status again.