net.sf.mmm.service.base.server

Interface CsrfTokenManager

All Superinterfaces:

Security

All Known Implementing Classes:

AbstractCsrfTokenManager, CsrfTokenManagerDefaultImpl

@ComponentSpecification
public interface CsrfTokenManager
extends Security

This is the interface for the manager of CsrfTokens.

Since:

1.0.0

Author:

Joerg Hohwiller (hohwille at users.sourceforge.net)

Method Summary

Modifier and Type	Method and Description
CsrfToken	generateInitialToken() This method generates a new CsrfToken for the initial "log-in" of a user.
CsrfToken	generateUpdateToken(CsrfToken currentToken) This method generates a new CsrfToken or updates an existing one-time CsrfToken.
boolean	isValidToken(CsrfToken token) Checks if the given CsrfToken that has been sent from the client is valid.
void	validateToken(CsrfToken token)

Method Detail

isValidToken

boolean isValidToken(CsrfToken token)

Checks if the given CsrfToken that has been sent from the client is valid. This method has to correspond to generateInitialToken() and generateUpdateToken(CsrfToken). In case a remote invocation is invoked that is secured (requires authentication and typically also authorization), the CsrfToken has to be checked. A value of null is never valid and will always fail. Only in case of a secured invocation and the presence of CsrfToken this method is invoked.

Parameters:

token - is the CsrfToken send from the client. Will not be null.

Returns:

true if the given token is valid, false otherwise (in case of an CSRF attack or some technical bug).

validateToken

void validateToken(CsrfToken token)
            throws SecurityException

Parameters:

token - is the token to validate.

Throws:

SecurityException - if the token is not valid.

See Also:

isValidToken(CsrfToken)

generateInitialToken

CsrfToken generateInitialToken()

This method generates a new CsrfToken for the initial "log-in" of a user. Here are some examples of possible implementation strategies:

• A token is generated that simply contains the session ID. If an attacker can force the browser to send a request to your service and after the user has already logged into your application the browser will send authentication data for the request (CSRF). However, the attacker can not easily access your session ID due to the SOP (Same Origin Policy).
• A token is generated with a unique ID that the client can not guess such as a UUID. The token is also stored in the server-side HTTP session so it can be compared for validation.
• A token is generated from a combination of different aspects (e.g. user login, user agent, server-secret, etc.) and digitally signed an encrypted. This approach can also be used in situations where no server-side HTTP session exists (e.g. with only HTTP Basic Authentication) as the validation can decrypt the token, split the aspects and verify them.

In case you create your own implementation be aware of the following things:

• The IP address of the user can legally change from one request to another, e.g. if the user enters or leaves a VPN. On the other hand attackers can easily fake IP addresses so relying on IP address often reduces user comfort without gaining a very much higher level of Security.
• Do not use Random to generate security tokens as this is too weak.

Returns:

the initial CsrfToken. Shall not be null.

generateUpdateToken

CsrfToken generateUpdateToken(CsrfToken currentToken)

This method generates a new CsrfToken or updates an existing one-time CsrfToken.

Parameters:

currentToken - is the current CsrfToken that has previously been generated and may be updated.

Returns:

the currentToken (same instance) to keep the token or a new instance of CsrfToken to replace the current token and expect the next request from the client to provide that new token (e.g. to implement one-time tokens for highest level of protection).

See Also:

generateInitialToken()