README
¶
csrf
Generate CSRF (cross-site request forgery) tokens and validate them.
Concept
Unlike most CSRF implementations, this package does not rely on remembering previously handed out tokens. Instead, it uses TOTP (time-based one-time password) to generate an almost limitless number of CSRF tokens, and can validate them without needing to store a collection of active tokens.
This results in fewer false failures. For example, if a user keeps a form page open for a long time before submitting it, or performs other actions in another tab before submitting, the form submission will still succeed and still be protected against CSRF attacks. These patterns of behavior would cause other CSRF implementations to forget about the token, resulting in an unnecessary failure.
There are two downsides to this approach. The tokens must be twice as long to provide the same protection against brute-force attacks, because so many more of the randomly generated tokens are valid. Also, tokens cannot be revoked after being used once.
Usage
When you generate a token, you pass the current time (from time.Now()) and a byte slice that uniquely identifies the user. This can be as simple as []byte(username) or if you have a session token you can use that. Include this token in your HTML page as a hidden form field.
When you validate a token, it will validate if and only if the session matches and the token lifetime has not expired. This ensures the request being made is from the HTML page you generated earlier, and not from a malicious script or link on the user's device.
The tokens generated by this package are strings using alphanumeric characters, plus dot, dash, underscore, and tilde. These characters are safe to use in URL query strings, HTML attributes, and cookies.
License
This package is released under the GPL, version 2. If you require a different license, please contact me for permission.
Documentation
¶
Overview ¶
Generate CSRF (cross-site request forgery) tokens and validate them.
Unlike most CSRF implementations, this package does not rely on remembering previously handed out tokens. Instead, it uses TOTP (time-based one-time password) to generate an almost limitless number of CSRF tokens, and can validate them without needing to store a collection of active tokens.
This results in fewer false failures. For example, if a user keeps a form page open for a long time before submitting it, or performs other actions in another tab before submitting, the form submission will still succeed and still be protected against CSRF attacks. These patterns of behavior would cause other CSRF implementations to forget about the token, resulting in an unnecessary failure.
There are two downsides to this approach. The tokens must be twice as long to provide the same protection against brute-force attacks, because so many more of the randomly generated tokens are valid. Also, tokens cannot be revoked after being used once.
When you generate a token, you pass the current time (from time.Now()) and a byte slice that uniquely identifies the user. This can be as simple as []byte(username) or if you have a session token you can use that. Include this token in your HTML page as a hidden form field.
When you validate a token, it will validate if and only if the session matches and the token lifetime has not expired. This ensures the request being made is from the HTML page you generated earlier, and not from a malicious script or link on the user's device.
The tokens generated by this package are strings using alphanumeric characters, plus dot, dash, underscore, and tilde. These characters are safe to use in URL query strings, HTML attributes, and cookies.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Authenticator ¶
type Authenticator struct {
// Key should be approximately 64 bytes of unguessable data
Key []byte
// Each character of a token supplies 3.02 bits of security.
// Recommended values are 12 - 40. The maximum effective length
// is 168. Higher values work correctly but do not provide any
// additional security.
TokenLength int
// Tokens remain valid for at least Lifetime, and no more
// than twice Lifetime. Lower values provide better security,
// higher values provide better user experience.
Lifetime time.Duration
}
Create an Authenticator with site-specific values
func (*Authenticator) GenerateToken ¶
func (a *Authenticator) GenerateToken(date time.Time, session []byte) string
GenerateToken() creates a new token in the given session. Date should be the current time and session should uniquely identify the user, such as []byte(username) or a session token.
func (*Authenticator) ValidateToken ¶
ValidateToken() returns true if the token is valid for given time and session. Date should be the current time. Session must be the same identifier used when generating the token.
Source Files