Created: 2008-07-09 15:23
Updated: 2016-05-08 10:33



shove_auth is a centralized authentication repository for webapps, using the HMAC protocol to verify passwords without any plaintext passwords at rest or in transit.

Concepts and variables

  • server - the system running shove_auth
  • client - an application acting on behalf of a user; in our case, the push2 webapp
  • auth_secret - sha1(username+pass) expressed in base64
  • session_secret - unique per session, keyed to particular client
  • sid - session_id, probably a big base64-encoded string (base64 looks cool)
  • signed request - requests relying on authentication should include a signature consisting of:
    • the action (for example, GET /user/username)
    • the current sid (even if this is already included in the action URL)
    • any arguments (such as the password for update user)
    • the output of the hmac function is passed as the hmac request parameter
  • legacy object - client-side object for the benefit of push2. If you don't know what that is, ignore it. Legacy features will be removed in the future.

REST protocol

  • Session management:
    • Create session: POST /session/create - returns the nonce and sid
    • Update session: PUT /session/sid username, hmac(auth_secret, PUT /session/sid nonce) * 200 OK - successful authentication, includes session_secret * 400 Bad Request - failed authentication or malformed request
    • Show session: GET /session/sid hmac(session_secret, GET /session/sid sid) * 404 Not Found - no session with this sid * 403 Forbidden - session not authenticated * 200 OK - return session secret
      • Destroy session: DELETE /session/sid hmac(session_secret, DELETE /session/sid)
        • 403 Forbidden - delete failed for permissions or something
        • 204 No Content - deletion happened
  • User management, returns 403 when provided session doesn't have permissions
    • Show user: GET /user/username sid, hmac(session_secret, GET /user/username sid) - show username, time and client of last login(s)
    • Update user: PUT /user/username sid, password, hmac(session_secret, PUT /user/username sid password) - set password
    • Destroy user: DELETE /user/username sid, hmac(session_secret, DELETE /user/username sid) - delete said user
    • Create user: POST /user/username sid, hmac(session_secret, POST /user/username sid) - create user with specified name
  • ACL checking, no hmac needed
    • Check access: GET /access/ sid, resource_selector - 200 when allowed, 403 when not

Protocol security

The session_secret is used instead of the auth_secret for maintenance of the session, since it must have a short lifetime, preferably 24 idle hours or less. If the client stores the session_secret in a cookie store over plaintext HTTP (i.e. Rails cookie sessions), the server must validate that data is coming from a valid client, either by whitelisting IP addresses or use of client SSL certs.

SSL/TLS should be used to protect the client-shove_auth session from replay attacks, allow secure transfer of the session_secret, password changes, and SSL certificate authentication of clients.

Logging in

  • Create a new session
  • Obtain username and password from user
  • Update the session with username and hmac from hashed password and nonce
    • On a 400 or 403, discard the session and nonce, and let the user know they suck
  • Allow the user to perform their normal tasks
Cookies help us deliver our services. By using our services, you agree to our use of cookies Learn more