public package Foswiki::Validation

See Published API for packages intended to be used by Plugin and Contrib authors, or browse all packages.
See also Developing plugins, Developer's Bible, Technical Overview

Perl Module:

Child packagesChild packages

public package Foswiki::Validation

"Validation" is the process of ensuring that an incoming request came from a page we generated. Validation keys are injected into all HTML pages generated by Foswiki, in Foswiki::writeCompletePage. When a request is received from the browser that requires validation, that request must be accompanied by the validation key. The functions in this package support the generation and checking of these validation keys.

Two key validation methods are supported by this module; simple token validation, and double-submission validation. Simple token validation stores a magic number in the session, and then adds that magic number to all forms in the output HTML. When a form is submitted, the magic number submitted with the form must match the number stored in the session. This is a relatively weak protection method, but requires some coding around so may discourage many hackers.

The second method supported is properly called double cookie submission, but referred to as "strikeone" in Foswiki. This again uses a token added to output forms, but this time it uses Javascript to combine that token with a secret stored in a cookie, to create a new token. This is more secure because the cookie containing the secret cannot be read outside the domain of the server, making it much harder for a page hosted on an evil site to forge a valid transaction.

When a request requiring validation comes in, Foswiki::UI::checkValidationKey is called. This compares the key in the request with the set of valid keys stored in the session. If the comparison fails, the browser is redirected to the login script (even if the user is currently logged in) with the action parameter set to validate. This generates a confirmation screen that the user must accept before the transaction can proceed. When the screen is confirmed, login is invoked again and the original transaction restored from passthrough.

In the function descriptions below, $cgis is a reference to a CGI::Session object.

StaticMethod addValidationKey( $cgis, $context, $strikeone ) → $form

Add a new validation key to a form. The key will time out after {Validation}{ValidForTime}.

• $cgis - a CGI::Session
• $context - the context for the key, usually the URL of the target page plus the time. This should be unique for each rendered page.
• $strikeone - if set, expect the nonce to be combined with the session secret before it is posted back.

The validation key will be added as a hidden parameter at the end of the form tag.

StaticMethod generateValidationKey( $cgis, $context, $strikeone ) → $nonce

Generate a new validation key. The key will time out after {Validation}{ValidForTime}.

• $cgis - a CGI::Session
• $context - the context for the key, usually the URL of the target page plus the time. This should be unique for each rendered page.
• $strikeone - if set, expect the nonce to be combined with the session secret before it is posted back.

The validation key can then be used in a HTML form, or headers for Rest Plugin API etc.

StaticMethod addOnSubmit( $form ) → $form

Add a double submission onsubmit handler to a form.

• $form - the opening tag of a form, ie. <form ...>=

The handler will be added to an existing on submit, or by adding a new onsubmit in the form tag.

StaticMethod getCookie( $cgis ) → $cookie

Get a double submission cookie

• $cgis - a CGI::Session

The cookie is a non-HttpOnly cookie that contains the current session ID and a secret. The secret is constant for a given session.

StaticMethod isValidNonce( $cgis, $key ) → $boolean

Check that the given validation key is valid for the session. Return false if not.

StaticMethod isValidNonceHash( $actions, $key ) → $boolean

Check that the given validation key is valid for the session. Return false if not.

StaticMethod expireValidationKeys($cgis[, $key])

Expire any timed-out validation keys for this session, and (optionally) force expiry of a specific key, even if it hasn't timed out.

StaticMethod validate($session)

Generate (or check) the "Suspicious request" verification screen for the given session. This screen is generated when a validation fails, as a response to a Validation Exception.