Package 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	Description
static class	CrumbIssuer.RestrictedApi

Nested classes/interfaces inherited from interface hudson.ExtensionPoint

ExtensionPoint.LegacyInstancesAreScopedToHudson

Field Summary

Fields

Modifier and Type	Field	Description
static final String	DEFAULT_CRUMB_NAME

Constructor Summary

Constructors

Constructor	Description
CrumbIssuer()

Method Summary

Modifier and Type	Method	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 Details

DEFAULT_CRUMB_NAME

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

See Also:

• Constant Field Values

Constructor Details

CrumbIssuer

public CrumbIssuer()

Method Details

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.

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.

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.

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.

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:

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.