The ZAZ Authentication Kit

Authentication Kit is a module which makes it easy to implement Security Through Obesity password storage and TOTP Two Factor Authentication.

Simply add an interface to an existing (or new) user storage system, add a few columns to the database if necessary, and start working. Authentication Kit can even added Two Factor Authentication to existing Security Through Obesity implementations.

Requirements

Authentication Kit requires the PBKDF2 hashing added to the new Xojo Framework in Xojo 2015 Release 2. All projects can compile and use the framework.

Installation

Download the Authentication Kit project, open the Authentication Kit.xojo_binary_project file, then copy the AuthenticationKit module into your project.

Getting Started

A class implementing the AuthenticationKit.User interface is required. The job of this interface is to provide user details immutable user details to the AuthenticationKit.Validator interface.

A second class interface, AuthenticationKit.MutableUser is used to describe a user class which can be modified.

The code below creates an MutableSampleUser object (example class in project) with user id 1, then sets the login key and password. An array of AuthenticationKit.Token objects is returned when setting the password. One random token in the array is the correct one, the rest are bogus filler noise. All must be saved to the validator.

Dim EditableUser As MutableSampleUser = New MutableSampleUser(1)
EditableUser.LoginKey = "JoeUser"
Dim Tokens() As AuthenticationKit.Token = EditableUser.SetPassword("ThisIsTheCorrectPassword", 1000, Xojo.Crypto.HashAlgorithms.SHA512)
If Not Validator.Save(EditableUser, Tokens) Then
  MsgBox("Unable to save user")
  Return
End If

Once a user has been saved, the password can be validated. The first step is to lookup the user. No password validation is done on lookup, which allows password resets to happen if necessary.

When validating the password, a reference to a AuthenticationKit.TwoFactorProfile must be provided ByRef. If the password matches, the ValidatePassword method returns true, and the Generator reference may be set to a value. If nil, the user has not enabled two factor authentication. If not nil, two factor authentication is enabled and the user should be required to provide a code to continue. This can also be determined using the AuthenticationKit.User.TwoFactorEnabled method.

// Lookup the user based on the username
Dim User As AuthenticationKit.User = Validator.LookupUser("JoeUser")
If User = Nil Then
  MsgBox("Unable to find user")
  Return
End If

// Validate the password, passing in the ByRef Generator. If a generator is
// returned, then two factor authentication is enabled.
Dim Generator As AuthenticationKit.TwoFactorProfile
If Not Validator.ValidatePassword(User, "ThisIsTheCorrectPassword", Generator) Then
  MsgBox("Incorrect password")
  Return
End If

If Generator <> Nil Then
  // Two factor authentication enabled
  Dim Code As Integer = SomeMethodToAskUserForCode()
  If Not Generator.Verify(Code) Then
    MsgBox("Code did not match")
    Return
  End If
End If

Next Steps

With the basic workflow understood, the next step is to implement the AuthenticationKit.Validator and AuthenticationKit.MutableUser interfaces.