hudson.security.csrf

Class CrumbIssuer

java.lang.Object

hudson.security.csrf.CrumbIssuer

All Implemented Interfaces:

ExtensionPoint, Describable<CrumbIssuer>

Direct Known Subclasses:

DefaultCrumbIssuer

@ExportedBean
 @StaplerAccessibleType
public abstract class CrumbIssuer
extends Object
implements Describable<CrumbIssuer>, ExtensionPoint

A CrumbIssuer represents an algorithm to generate a nonce value, known as a crumb, to counter cross site request forgery exploits. Crumbs are typically hashes incorporating information that uniquely identifies an agent that sends a request, along with a guarded secret so that the crumb value cannot be forged by a third party.

Author:

dty

See Also:

Wikipedia: Cross site request forgery

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CrumbIssuer.RestrictedApi

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_CRUMB_NAME

Constructor Summary

Constructors

Constructor and Description
CrumbIssuer()

Method Summary

Modifier and Type	Method and Description
static DescriptorExtensionList<CrumbIssuer,Descriptor<CrumbIssuer>>	all() Returns all the registered CrumbIssuer descriptors.
Api	getApi()
String	getCrumb() Get a crumb value based on user specific information in the current request.
String	getCrumb(javax.servlet.ServletRequest request) Get a crumb value based on user specific information in the request.
String	getCrumbRequestField() Get the name of the request parameter the crumb will be stored in.
CrumbIssuerDescriptor<CrumbIssuer>	getDescriptor() Access global configuration for the crumb issuer.
static void	initStaplerCrumbIssuer() Sets up Stapler to use our crumb issuer.
protected abstract String	issueCrumb(javax.servlet.ServletRequest request, String salt) Create a crumb value based on user specific information in the request.
boolean	validateCrumb(javax.servlet.ServletRequest request) Get a crumb from a request parameter and validate it against other data in the current request.
boolean	validateCrumb(javax.servlet.ServletRequest request, MultipartFormDataParser parser) Get a crumb from multipart form data and validate it against other data in the current request.
abstract boolean	validateCrumb(javax.servlet.ServletRequest request, String salt, String crumb) Validate a previously created crumb against information in the current request.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_CRUMB_NAME

@Restricted(value=org.kohsuke.accmod.restrictions.NoExternalUse.class)
public static final String DEFAULT_CRUMB_NAME

See Also:

Constant Field Values

Constructor Detail

CrumbIssuer

public CrumbIssuer()

Method Detail

getCrumbRequestField

@Exported
public String getCrumbRequestField()

Get the name of the request parameter the crumb will be stored in. Exposed here for the remote API.

getCrumb

@Exported
public String getCrumb()

Get a crumb value based on user specific information in the current request. Intended for use only by the remote API.

getCrumb

public String getCrumb(javax.servlet.ServletRequest request)

Get a crumb value based on user specific information in the request.

Parameters:

request -

issueCrumb

protected abstract String issueCrumb(javax.servlet.ServletRequest request,
                                     String salt)

Create a crumb value based on user specific information in the request. The crumb should be generated by building a cryptographic hash of:

• relevant information in the request that can uniquely identify the client
• the salt value
• an implementation specific guarded secret.

Parameters:

request -

salt -

validateCrumb

public boolean validateCrumb(javax.servlet.ServletRequest request)

Get a crumb from a request parameter and validate it against other data in the current request. The salt and request parameter that is used is defined by the current configuration.

Parameters:

request -

validateCrumb

public boolean validateCrumb(javax.servlet.ServletRequest request,
                             MultipartFormDataParser parser)

Get a crumb from multipart form data and validate it against other data in the current request. The salt and request parameter that is used is defined by the current configuration.

Parameters:

request -

parser -

validateCrumb

public abstract boolean validateCrumb(javax.servlet.ServletRequest request,
                                      String salt,
                                      String crumb)

Validate a previously created crumb against information in the current request.

Parameters:

request -

salt -

crumb - The previously generated crumb to validate against information in the current request

getDescriptor

public CrumbIssuerDescriptor<CrumbIssuer> getDescriptor()

Access global configuration for the crumb issuer.

Specified by:

getDescriptor in interface Describable<CrumbIssuer>

all

public static DescriptorExtensionList<CrumbIssuer,Descriptor<CrumbIssuer>> all()

Returns all the registered CrumbIssuer descriptors.

getApi

public Api getApi()

initStaplerCrumbIssuer

@Initializer
public static void initStaplerCrumbIssuer()

Sets up Stapler to use our crumb issuer.