Shove all your authentication tasks to a central server
JavaScript Ruby
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
app
client
config
db
doc
lib/tasks
public
script
test
tmp
vendor
.gitignore
.gitmodules
Capfile
README.markdown
Rakefile

README.markdown

shove_auth

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