de.ipcon.db.tools

Class AuthToken

java.lang.Object

de.ipcon.db.tools.AuthToken

All Implemented Interfaces:

java.io.Serializable

public class AuthToken
extends java.lang.Object
implements java.io.Serializable

This class provides a means to safely deposit a piece of information on the client or transfer it to another client, which can be resolved at a later point in time. This class provides a means to transfer an authorization claim between two parties (let's say two different services or two requests not sharing a common session) using an ExpiringTokenStorageProviderI (ETSPI), without having to compromise the secret within the authorization claim to the ETSPI instance. The reason for this is, that the ETSPI needs to do some short term persistance if the expiration time exceeds the JVM livetime - if it does that, the secret would be dumped somewhere, possibly compromising it.

See Also:

Serialized Form

Method Summary

Modifier and Type	Method and Description
static java.lang.String	canonicFromAddr(javax.servlet.http.HttpServletRequest request) Extract a textual description of the machine the request came from using the remoteAddr and X-Forwarded-For Header variables
static java.lang.String	canonicFromAddr(org.eclipse.jetty.websocket.servlet.ServletUpgradeRequest request)
static java.lang.String	createAndGetCredential(java.lang.String serviceName, Benutzer user, javax.servlet.http.HttpServletRequest request, int validitySeconds) Same as createAndGetCredential(String,Benutzer,String,int), but with an automatic handling of the from data of the given request.
static java.lang.String	createAndGetCredential(java.lang.String serviceName, Benutzer user, javax.servlet.http.HttpServletRequest request, java.lang.String document, int validitySeconds) Same as createAndGetCredential(String,Benutzer,String,String,byte[],int), but with an automatic handling of the from data of the given request, without auxData.
static java.lang.String	createAndGetCredential(java.lang.String serviceName, Benutzer user, java.lang.String machine, int validitySeconds) Same as createAndGetCredential(String,Benutzer,String,String,byte[],int) for minimum requirements such as automatic Website logon, without document and auxData.
static java.lang.String	createAndGetCredential(java.lang.String serviceName, Benutzer user, java.lang.String machine, java.lang.String document, byte[] auxData, int validitySeconds) Creates an AuthToken with given Benutzer object, a machine and document identifier, a not-to-encrypt auxiliary data and a validity in seconds, persisting it and returning a url encoded String to retrieve that information on a later occasion.
void	destroy(java.lang.String serviceName, BOLoaderI loader) Destroy this AuthToken immediately
byte[]	getAuxData() return the auxiliary data stored on the server not included in the credential
java.lang.String	getCredential() Return a url encoded (using only [a-zA-Z0-9_\-]) credential string having user, document and machine encoded with a random password, which can be used to retrieve that AuthToken from the ExpiringTokenStorageProviderI.
java.lang.String	getDocument() get the name of the document the access was granted to
static AuthToken	getInstance(java.lang.String serviceName, Benutzer user, java.lang.String machine, java.lang.String document, byte[] auxData, int validitySeconds) Creates an AuthToken with given Benutzer object, a machine and document identifier, a not-to-encrypt auxiliary data and a validity in seconds, persisting and returning it.
java.lang.String	getMachine() get a textual description of the machine the request came from
long	getUserId() get the userId associated
static AuthToken	parse(java.lang.String serviceName, java.lang.String cred, BOLoaderI loader) Recovers an AuthToken from the given credential
void	renew(java.lang.String serviceName, BOLoaderI loader, int validitySeconds) Renew this AuthToken, eventually with updated auxData
void	setAuxData(byte[] auxData) set the auxiliary data stored on the server not included in the credential
void	validate(BOLoaderI loader, javax.servlet.http.HttpServletRequest request) minimum version of the validate(BOLoaderI,String,String) call without a document, automatically handling a request as machine substitute.
void	validate(BOLoaderI loader, org.eclipse.jetty.websocket.servlet.ServletUpgradeRequest request)
void	validate(BOLoaderI loader, java.lang.String machine, java.lang.String document) check if the encoded user id is available and a valid user object, and, if given, check restrictions upon machine and document.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

createAndGetCredential

public static java.lang.String createAndGetCredential(java.lang.String serviceName,
                                                      Benutzer user,
                                                      java.lang.String machine,
                                                      java.lang.String document,
                                                      byte[] auxData,
                                                      int validitySeconds)

Creates an AuthToken with given Benutzer object, a machine and document identifier, a not-to-encrypt auxiliary data and a validity in seconds, persisting it and returning a url encoded String to retrieve that information on a later occasion. Please not that the loader of the Benutzer object will be used to access the ExpiringTokenStorageProviderI to persist the token.

Parameters:

serviceName - a name for the service provided (such as 'dav', 'u2f' or 'weblogon')

user - Benutzer which wants access to a resource, must be !=null

machine - a text describing the machine from which that access came from, ideally from request.remoteAddr or X-Forwarded-For header

document - a string describing the document the access was granted to

auxData - a payload which will be stored unencrypted on the server not to be encoded into the token (could be a remark in case of an error)

validitySeconds - the duration in seconds after which this AuthToken will expire

Returns:

a url encoded (using only [a-zA-Z0-9_\-]) string having user, document and machine encoded with a random password, which is stored in the ExpiringTokenStorageProviderI.

createAndGetCredential

public static java.lang.String createAndGetCredential(java.lang.String serviceName,
                                                      Benutzer user,
                                                      javax.servlet.http.HttpServletRequest request,
                                                      java.lang.String document,
                                                      int validitySeconds)

Same as createAndGetCredential(String,Benutzer,String,String,byte[],int), but with an automatic handling of the from data of the given request, without auxData.

Parameters:

String - serviceName a name for the service provided (such as 'dav', 'u2f' or 'weblogon')

user - Benutzer which wants access to a resource, must be !=null

request - an HttpServletRequest from the servlet; will be analyzed via remoteAddr and X-Forwarded-For headers to extract the machine the request came from

document - the name of the document we granted access to

validitySeconds - the duration in seconds after which this AuthToken will expire

Returns:

a url encoded (using only [a-zA-Z0-9_\-]) string having user, document and machine encoded with a random password, which is stored in the ExpiringTokenStorageProviderI.

createAndGetCredential

public static java.lang.String createAndGetCredential(java.lang.String serviceName,
                                                      Benutzer user,
                                                      java.lang.String machine,
                                                      int validitySeconds)

Same as createAndGetCredential(String,Benutzer,String,String,byte[],int) for minimum requirements such as automatic Website logon, without document and auxData.

createAndGetCredential

public static java.lang.String createAndGetCredential(java.lang.String serviceName,
                                                      Benutzer user,
                                                      javax.servlet.http.HttpServletRequest request,
                                                      int validitySeconds)

Same as createAndGetCredential(String,Benutzer,String,int), but with an automatic handling of the from data of the given request.

Parameters:

serviceName - a name for the service provided (such as 'dav', 'u2f' or 'weblogon')

user - Benutzer which wants access to a resource, must be !=null

request - an HttpServletRequest from the servlet; will be analyzed via remoteAddr and X-Forwarded-For headers to extract the machine the request came from

validitySeconds - the duration in seconds after which this AuthToken will expire

Returns:

a url encoded (using only [a-zA-Z0-9_\-]) string having user, document and machine encoded with a random password, which is stored in the ExpiringTokenStorageProviderI.

getInstance

public static AuthToken getInstance(java.lang.String serviceName,
                                    Benutzer user,
                                    java.lang.String machine,
                                    java.lang.String document,
                                    byte[] auxData,
                                    int validitySeconds)

Creates an AuthToken with given Benutzer object, a machine and document identifier, a not-to-encrypt auxiliary data and a validity in seconds, persisting and returning it. Please not that the loader of the Benutzer object will be used to access the ExpiringTokenStorageProviderI to persist the token.

Parameters:

serviceName - a name for the service provided (such as 'dav', 'u2f' or 'weblogon')

user - Benutzer which wants access to a resource, must be !=null

machine - a text describing the machine from which that access came from, ideally from request.remoteAddr or X-Forwarded-For header

document - the name of the document the access was granted to

auxData - a payload which will be stored unencrypted on the server not to be encoded into the token (could be a remark in case of an error)

validitySeconds - the duration in seconds after which this AuthToken will expire

Returns:

a url encoded (using only [a-zA-Z0-9_\-]) string having user, document and machine encoded with a random password, which is stored in the ExpiringTokenStorageProviderI.

getCredential

public java.lang.String getCredential()

Return a url encoded (using only [a-zA-Z0-9_\-]) credential string having user, document and machine encoded with a random password, which can be used to retrieve that AuthToken from the ExpiringTokenStorageProviderI.

renew

public void renew(java.lang.String serviceName,
                  BOLoaderI loader,
                  int validitySeconds)

Renew this AuthToken, eventually with updated auxData

Parameters:

loader - loader to use

validitySeconds - duration in seconds after which this AuthToken will expire

destroy

public void destroy(java.lang.String serviceName,
                    BOLoaderI loader)

Destroy this AuthToken immediately

Parameters:

loader - loader to use

parse

public static AuthToken parse(java.lang.String serviceName,
                              java.lang.String cred,
                              BOLoaderI loader)
                       throws AuthenticationException

Recovers an AuthToken from the given credential

Parameters:

serviceName - a name for the service provided (such as 'dav', 'u2f' or 'weblogon')

cred - the credential to recover

loader - the loader to use

Returns:

an AuthToken

Throws:

java.lang.IllegalArgumentException - if cred or loader is null or cred doesn't consist of two parts concatted with a dot.

AuthenticationException - in case the token is expired or we're unable to decrypt the credential

validate

public void validate(BOLoaderI loader,
                     java.lang.String machine,
                     java.lang.String document)
              throws AuthenticationException

check if the encoded user id is available and a valid user object, and, if given, check restrictions upon machine and document. If you leave machine or document null, it won't check for equality within the encoded payload.

Parameters:

loader - loader to fetch user and check

machine - a text describing the machine from which that access came from, ideally from request.remoteAddr or X-Forwarded-For header

document - string describing the document the request wants access to

Throws:

AuthenticationException - if the userId in the encoded payload is non-existent or invalid (read: no Benutzer object).

validate

public void validate(BOLoaderI loader,
                     javax.servlet.http.HttpServletRequest request)
              throws AuthenticationException

minimum version of the validate(BOLoaderI,String,String) call without a document, automatically handling a request as machine substitute.

Parameters:

loader - loader to fetch user and check

request - an HttpServletRequest from the servlet

Throws:

AuthenticationException

validate

public void validate(BOLoaderI loader,
                     org.eclipse.jetty.websocket.servlet.ServletUpgradeRequest request)
              throws AuthenticationException

Throws:

AuthenticationException

getUserId

public long getUserId()

get the userId associated

getMachine

public java.lang.String getMachine()

get a textual description of the machine the request came from

getDocument

public java.lang.String getDocument()

get the name of the document the access was granted to

getAuxData

public byte[] getAuxData()

return the auxiliary data stored on the server not included in the credential

setAuxData

public void setAuxData(byte[] auxData)

set the auxiliary data stored on the server not included in the credential

Parameters:

auxData - the data to be stored on the server aside the encryption password

canonicFromAddr

public static java.lang.String canonicFromAddr(javax.servlet.http.HttpServletRequest request)

Extract a textual description of the machine the request came from using the remoteAddr and X-Forwarded-For Header variables

Parameters:

request - the request from the http server, must be !=null

Returns:

a textual description of the machine the request came from, or the string "samesame" if it's the local machine itself.

canonicFromAddr

public static java.lang.String canonicFromAddr(org.eclipse.jetty.websocket.servlet.ServletUpgradeRequest request)