OTP Helper

The OTP Helper provides handlers to generate and verify time-based one-time passwords conforming to RFC6238 TOTP standards. Additionally it includes a handler to draw QR codes based on the otpauth:// URI scheme. You can use this helper on its own but as the Authentication Library incorporates the OTP helper it makes more sense and it is easier to deal with the Authentication Library, it's OTP related handlers and the associated settings in application/config/authentication.lc.

Note: This helper requires LiveCode's QR Code Generator Library which needs to be stored in application/libraries. Rename the library to "QR.livecodescript". So, the path to the library is application/libraries/QR.livecodescript. Please read about how to create libraries in chapter "Creating Libraries".

Note: You don't need to load the QR library, this is done by the helper.

Preparation of the QR Code Generator Library

Find the library in the LiveCode application in Extensions/com.livecode.library.qr/qr.livecodescript.
Rename it to "QR.livecodescript".
Open the library in an editor and capitalize the name of the script in the first line.
Then add the following code to the library script:

global gRigA

local sStackInUse


on libraryStack
  if (gRigA is not an array) and (the environment is "server") then
    put "No direct script access allowed."
    exit to top
  end if

  if the short name of the target = the short name of me then
    if sStackInUse <> TRUE then
      put TRUE into sStackInUse

      # LOGGING
      if the environment is "server" then
        rigLogMessage "debug", "QR Library Loaded"
      end if

      # SET INITIAL VALUES OF THE LIBRARY VARIABLES
      _rigSetDefaultValues
      #
    end if -- if sStackInUse <> TRUE

  else
    pass libraryStack
  end if -- if the short name of the target = the short name of me
end libraryStack



# SET INITIAL VALUES
private command _rigSetDefaultValues
  __Initialize
end _rigSetDefaultValues



command rigRunInitialQRConfig
  --Run initial configuration procedures. Don't remove this handler, even if it does nothing.
end rigRunInitialQRConfig

Loading the OTP Helper

This helper is loaded using the following code:

rigLoadHelper "otp"

Note: You don't need to load the helper if you use the Authentication Library. Please read about OTP authentication in chapter "One-Time Password Authentication".

Handler Reference

rigOTPgenerate pSecret, pTokenLength, pCryptoType, pCryptoNumBits, pTimeStep, pType

Generate a one-time password.

Parameters

Alternatively provide all parameters as an array. Array key names are: secret, tokenLength, cryptoType, cryptoNumBits, timeStep and type.

This handler returns FALSE in the result in case an error occurred, otherwise the result contains the one-time password.

rigOTPcompareKeys pChallenge, pKey, pTokenLength, pCryptoType, pCryptoNumBits, pTimeStep, pTimeWindow

Compare user supplied OTP with generated OTP.

Parameters

Alternatively provide all parameters as an array. Array key names are: challenge, key, tokenLength, cryptoType, cryptoNumBits, timeStep and timeWindow.

This handler returns TRUE in the result if the two passwords match.

rigOTPgenerateUserKey pSecret

Generate a base32 encoded user key that conforms to the RFC6238 TOTP standards. Provide the secret as parameter.
Returns the base32 encoded shared secret in the result which can be displayed for the purpose of manually entering the secret in authenticator apps. The secret should always be transferred over a secure channel.

rigOTPqrCode(pKey, pAccount, pIssuer, pAlgo, pDigits, pPeriod, pECC, pSize, pMask)

Create QR code image data based on OTP URI data.

Parameters

Alternatively provide all parameters as an array. Array key names are: key, account, issuer, algo, digits, period, ECC, size and mask.

This function returns FALSE in the result in case an error occurred, otherwise the result contains the base64 encoded image data of the QR code. Here is an example:

rigOTPgenerateUserKey tSecret
put the result into tKey
put "user@example.com" into tAccount
put "Issuer Example" into tIssuer
put "SHA256" into tAlgo
put 8 into tDigits
put 60 into tPeriod
put "Q" into tECC
put 5 into tSize

put rigOTPqrCode(tKey, tAccount, tIssuer, tAlgo, tDigits, tPeriod, tECC, tSize) into tImgData

put "<img src='data:image/png;base64," & tImgData & "' />" into gData["qrCode"]