com.github.dbadia.sqrl.server

Interface SqrlPersistence

All Known Implementing Classes:

SqrlAutoCloseablePersistence, SqrlJpaPersistenceProvider

public interface SqrlPersistence

Bridge between the SQRL library and the persistence layer (database, etc)

Author:

Dave Badia

See Also:

SqrlJpaPersistenceProvider

Method Summary

Modifier and Type	Method and Description
void	cleanUpExpiredEntries() Delete any expired objects in the persistence store
void	closeCommit() Commit all updates since this persistence object was created
void	closeRollback() Ignore all updates since this persistence object was created
void	createAndEnableSqrlIdentity(String sqrlIdk, Map<String,String> identityDataTable) Create a new SqrlIdentity and enable SQRL authentication
SqrlCorrelator	createCorrelator(String correlatorString, Date expiryTime) Create a new correlator instance in the persistence
void	deleteSqrlCorrelator(SqrlCorrelator sqrlCorrelator)
void	deleteSqrlIdentity(String sqrlIdk) Invoked when the user chooses to remove SQRL authentication for this site
boolean	doesSqrlIdentityExistByIdk(String sqrlIdk) Check persistence to see if a user exists with the given sqrlIdk
SqrlCorrelator	fetchSqrlCorrelator(String correlator) Fetch the correlator object for the given string value
SqrlCorrelator	fetchSqrlCorrelatorRequired(String correlator) Fetch the correlator object for the given string value, or throw an exception if it does not exist
Map<String,SqrlCorrelator>	fetchSqrlCorrelatorsDetached(Set<String> correlatorStringSet)
Map<String,SqrlAuthenticationStatus>	fetchSqrlCorrelatorStatusUpdates(Map<String,SqrlAuthenticationStatus> correlatorToCurrentStatusTable) Checks for correlators who's status has changed or is SqrlAuthenticationStatus.AUTH_COMPLETE.
Boolean	fetchSqrlFlagForIdentity(String sqrlIdk, SqrlFlag flagToFetch) Invoked to determine if SQRL auth is enabled for a user
SqrlIdentity	fetchSqrlIdentityByUserXref(String appUserXref) Fetch the sqrl identity for the the given app user cross reference id
String	fetchSqrlIdentityDataItem(String sqrlIdk, String toFetch) Request to the data store to retrieve user specific SQRL data that was previously stored via #userAuthenticatedViaSqrl(String, String, Map)
String	fetchTransientAuthData(String correlator, String transientNameServerParrot) Fetch a short lived name/value for a given correlator and name
boolean	hasTokenBeenUsed(String nutTokenString) Check persistence to see if this token has already been used
boolean	isClosed()
void	markTokenAsUsed(String nutTokenString, Date expiryTime) Mark the given token as used in persistence.
void	setSqrlFlagForIdentity(String sqrlIdk, SqrlFlag flagToSet, boolean valueToSet) Invoked when the user chooses to temporarily disable SQRL authentication for this site
void	storeSqrlDataForSqrlIdentity(String sqrlIdk, Map<String,String> dataToStore) Indicates that we have received user specific data from the SQRL client that needs to be stored for the user; NOTE this is often the first call made for a new SQRL identity, so if the identity does not currently exist, it must be created
void	updateIdkForSqrlIdentity(String previousSqrlIdk, String newSqrlIdk) The user has updated their SQRL ID but this application is still using the old one.
void	updateNativeUserXref(long sqrlIdentityId, String nativeUserXref) Called to assign a native user cross reference to the given SQRL identity object so when SQRL authentication takes place, the application knows which user has authenticated
void	userAuthenticatedViaSqrl(String sqrlIdk, String correlator) Indicates that a user was authenticated successfully via SQRL.

Method Detail

createAndEnableSqrlIdentity

void createAndEnableSqrlIdentity(String sqrlIdk,
                                 Map<String,String> identityDataTable)

Create a new SqrlIdentity and enable SQRL authentication

Parameters:

sqrlIdk - the idk of the SQRL identity

identityDataTable - auth data for this SQRL identity

doesSqrlIdentityExistByIdk

boolean doesSqrlIdentityExistByIdk(String sqrlIdk)

Check persistence to see if a user exists with the given sqrlIdk

Parameters:

sqrlIdk - the SQRL ID to check for

Returns:

true if sqrlIdk exists, false otherwise

fetchSqrlIdentityByUserXref

SqrlIdentity fetchSqrlIdentityByUserXref(String appUserXref)

Fetch the sqrl identity for the the given app user cross reference id

Parameters:

appUserXref - the app user cross reference value to search by

Returns:

the SQRL identity for this app user

updateIdkForSqrlIdentity

void updateIdkForSqrlIdentity(String previousSqrlIdk,
                              String newSqrlIdk)

The user has updated their SQRL ID but this application is still using the old one. The application must lookup the user by previousSqrlIdk, and replace that SQRL ID with nnewSqrlIdk

Parameters:

previousSqrlIdk - the old SQRL ID, which is present in persistence

newSqrlIdk - the new SQRL ID, which should replace previousSqrlIdk in persistence

deleteSqrlIdentity

void deleteSqrlIdentity(String sqrlIdk)

Invoked when the user chooses to remove SQRL authentication for this site

Parameters:

sqrlIdk - the SQRL ID which represents the user.

Throws:

SqrlPersistenceException - if there was an error accessing the persistence store

updateNativeUserXref

void updateNativeUserXref(long sqrlIdentityId,
                          String nativeUserXref)

Called to assign a native user cross reference to the given SQRL identity object so when SQRL authentication takes place, the application knows which user has authenticated

Parameters:

sqrlIdentityId - the SQRL identity to update

nativeUserXref - the applications native user id for this user

userAuthenticatedViaSqrl

void userAuthenticatedViaSqrl(String sqrlIdk,
                              String correlator)

Indicates that a user was authenticated successfully via SQRL. The webapp must use the given parameters to:

• Find the users web session by using nutToken as a correlator
• Determine if the sqrlUserId is already associated with an account or not. If not, ask the user if the have an existing username/password. If not, enroll the user as new
• Follow the webapp flow as if the user logged in via username and password. That is, lookup customer data and display the relevant content

Parameters:

sqrlIdk - the SQRL ID which the user authenticated with.

correlator - The correlator ID that was generated when the login page was presented and embedded in the sqrl url

dataToStore - SQRL related data that must be persisted for this user and be retreivable via fetchSqrlIdentityDataItem(String, String)

fetchSqrlFlagForIdentity

Boolean fetchSqrlFlagForIdentity(String sqrlIdk,
                                 SqrlFlag flagToFetch)

Invoked to determine if SQRL auth is enabled for a user

Parameters:

sqrlIdk - the SQRL ID which represents the user.

Returns:

the auth state of the SQRL user or SqrlEaabledState#NOT_EXIST if there is none

Throws:

SqrlPersistenceException - if there was an error accessing the persistence store

setSqrlFlagForIdentity

void setSqrlFlagForIdentity(String sqrlIdk,
                            SqrlFlag flagToSet,
                            boolean valueToSet)

Invoked when the user chooses to temporarily disable SQRL authentication for this site

Parameters:

sqrlIdk - the SQRL ID which represents the user.

state - the auth state to set for this SQRL user

Throws:

SqrlPersistenceException - if there was an error accessing the persistence store

storeSqrlDataForSqrlIdentity

void storeSqrlDataForSqrlIdentity(String sqrlIdk,
                                  Map<String,String> dataToStore)

Indicates that we have received user specific data from the SQRL client that needs to be stored for the user; NOTE this is often the first call made for a new SQRL identity, so if the identity does not currently exist, it must be created

Parameters:

sqrlIdk - the SQRL ID which the user authenticated with.

dataToStore - SQRL related data that must be persisted for this user and be retreivable via fetchSqrlIdentityDataItem(String, String)

fetchSqrlIdentityDataItem

String fetchSqrlIdentityDataItem(String sqrlIdk,
                                 String toFetch)

Request to the data store to retrieve user specific SQRL data that was previously stored via #userAuthenticatedViaSqrl(String, String, Map)

Parameters:

sqrlIdk - the SQRL ID which the user authenticated with.

toFetch - The name of the SQRL data to be fetched. Was the key in the Map when

Returns:

the data or null if it does not exist

hasTokenBeenUsed

boolean hasTokenBeenUsed(String nutTokenString)

Check persistence to see if this token has already been used

Parameters:

nutTokenString - the SqrlNutToken token in sqbase64 format as received from the client the token sent by the SQRL client in the request

Returns:

true if the token was already used, false if not

markTokenAsUsed

void markTokenAsUsed(String nutTokenString,
                     Date expiryTime)

Mark the given token as used in persistence. After this call, any subsequent calls to #hasTokenBeenUsed(SqrlNutToken) must return true for this token until expiryTime. Once the expiryTime has been reached, persistence cleanup can occur and this token can be deleted from persistence

Parameters:

nutTokenString - the SqrlNutToken token in sqbase64 format as received from the client

expiryTime - the time at which this token can safely be deleted from persistence since it will fail timestamp validation

fetchTransientAuthData

String fetchTransientAuthData(String correlator,
                              String transientNameServerParrot)

Fetch a short lived name/value for a given correlator and name

Parameters:

correlator - correlator to which this data belongs

name - the name of the item to be fetched

Returns:

the value for the correlator and name or null if it does not exist

createCorrelator

SqrlCorrelator createCorrelator(String correlatorString,
                                Date expiryTime)

Create a new correlator instance in the persistence

Parameters:

correlatorString - the correlator value string

expiryTime - the time at which this correlator expires

Returns:

fetchSqrlCorrelatorRequired

SqrlCorrelator fetchSqrlCorrelatorRequired(String correlator)

Fetch the correlator object for the given string value, or throw an exception if it does not exist

Parameters:

correlator - the string value to search for

Returns:

the non-null correlator object

fetchSqrlCorrelator

SqrlCorrelator fetchSqrlCorrelator(String correlator)

Fetch the correlator object for the given string value

Parameters:

correlator - the string value to search for

Returns:

the correlator object or null if it does not exist

closeCommit

void closeCommit()

Commit all updates since this persistence object was created

closeRollback

void closeRollback()

Ignore all updates since this persistence object was created

isClosed

boolean isClosed()

Returns:

true if this persistence object has been closed

cleanUpExpiredEntries

void cleanUpExpiredEntries()

Delete any expired objects in the persistence store

fetchSqrlCorrelatorsDetached

Map<String,SqrlCorrelator> fetchSqrlCorrelatorsDetached(Set<String> correlatorStringSet)

fetchSqrlCorrelatorStatusUpdates

Map<String,SqrlAuthenticationStatus> fetchSqrlCorrelatorStatusUpdates(Map<String,SqrlAuthenticationStatus> correlatorToCurrentStatusTable)

Checks for correlators who's status has changed or is SqrlAuthenticationStatus.AUTH_COMPLETE. Complete state is always returned in case the client didn't get the update the first time it was sent

Parameters:

correlatorToCurrentStatusTable - table of string correlators and their current state as sent by the browser

Returns:

table of correlators and their updated (or complete) states

deleteSqrlCorrelator

void deleteSqrlCorrelator(SqrlCorrelator sqrlCorrelator)