XSRF, RPC & Server Security

The client-side types live in com.google.gwt.user.client.rpc and are identical in gwt-user and in both servlet jars. The server-side classes exist twice: com.google.gwt.user.server.rpc in gwt-servlet (javax.servlet) and com.google.gwt.user.server.rpc.jakarta in gwt-servlet-jakarta (jakarta.servlet, since GWT 2.11). The two annotations stay in the old package and are shared by both flavours.

Source: GWT 2.13.1 source — client.rpc package

The default implementation is stateless. XsrfTokenServiceServlet reads the value of the session cookie, computes its MD5 digest and returns the digest as an upper-case hexadecimal string of 32 characters (the sources use Md5Utils.getMd5Digest and StringUtils.toHexString). XsrfProtectedServiceServlet repeats the computation on each protected call and compares the result with the token that the client sent as the first object of the RPC payload. The check was confirmed by computing the MD5 digest of the JSESSIONID value of a test session with the operating system’s md5 and comparing it with the token that the servlet returned: they were equal, so the token is a function of the session id and nothing else.

This design has consequences that the Developer Guide leaves implicit and the source makes plain:

The diagram shows one page load. The names are the real ones of the Bookshelf: /bookshelf/xsrf is the XsrfTokenServiceServlet, /bookshelf/catalog is CatalogServiceImpl, and SessionFilter makes sure that a session cookie exists before the first token is requested.

The forged request in steps 10 and 11 carries the victim’s cookie, because the browser attaches it, but not the token, because the attacker’s page cannot read the cookie and cannot call the token servlet cross-origin and read the answer. Even if the attacker could send the right payload shape, the request has to be a Content-Type: text/x-gwt-rpc POST with an X-GWT-Permutation header, which a cross-site form cannot produce (see the replay discussion on the GWT-RPC page, GWT-RPC). The token is the real defence, the headers are a weak extra layer.

The scenario’s web.xml declares the cookie name once as a context parameter, so that the token servlet and every protected servlet read the same value, and maps the token servlet next to the catalog servlet:

Both the init parameter of one servlet and the context parameter work: XsrfProtectedServiceServlet.init and XsrfTokenServiceServlet.init read the servlet’s own ServletConfig first and the ServletContext second, and throw IllegalStateException with the text in the pitfalls table if neither is set. Both servlets also have a constructor that takes the cookie name, which is how a Spring Boot application registers them without a web.xml (see Server Integration & Deployment).

The filter is three lines, and the page of the scenario that uses it is the reason the first token request works:

The protected servlet is an ordinary servlet whose base class changed:

and the shared interface extends the protected marker:

The Async interface does not change. Because the token service is itself an RPC service, GWT.create(XsrfTokenService.class) also needs its URL set, and the shared module must be inherited by the client (the token types are in gwt-user, nothing extra to inherit).

Source: GWT — Security: GWT RPC XSRF protection

The client fetches one token at start-up and installs it on every protected proxy. Until the callback fires, no protected call can succeed, so the Bookshelf starts its history handling only afterwards:

The generated proxy writes the token as the first object of the payload when getRpcToken() is not null (RemoteServiceProxy.ServiceHelper.start), so the flag in the second position of the payload is 2 instead of 0. setRpcToken also checks the token’s type against the service’s: if the service interface has a single serialisable RpcToken implementation, the generated proxy refuses any other class with Invalid RpcToken type: expected ... but got ... (the generator’s checkRpcTokenType).

Source: GWT — Security: GWT RPC XSRF protection

A token goes stale when the session id changes, typically after login, after a session timeout and re-login, or after the server restarted and lost its sessions. The proxy reports it as an RpcTokenException, and RpcTokenExceptionHandler is the place to react centrally instead of in every callback:

This compiled against gwt-user 2.13.1 together with the other client snippets of this page. When a handler is set, the failing call’s own onFailure is not called for an RpcTokenException (RequestCallbackAdapter.onResponseReceived routes the exception to the handler only), so the handler must either retry the original call or tell the user; a silent handler makes the call vanish. The retry is the application’s business: remember the last request or ask the user to repeat the action, and retry at most once, or an expired session turns into a loop.

Source: GWT — Security: GWT RPC XSRF protection

AbstractXsrfProtectedServiceServlet.shouldValidateXsrfToken delegates to Util.isMethodXsrfProtected, whose rules the Javadoc lists in order:

The result is that extending XsrfProtectedService protects everything, which is the safe default, and that the exemption for a public read-only method such as a version check or a login ping must be explicit:

Note that annotating only the interface is enough for the check, because the rules inspect the method that the servlet is about to invoke and its declaring type; the servlet class does not have to repeat the annotation. A servlet class that extends RemoteServiceServlet (not XsrfProtectedServiceServlet) ignores all of this: the annotations are only evaluated by AbstractXsrfProtectedServiceServlet. That is the most common way to end up with a service that the team believes to be protected and that is not.

Source: GWT — Security: GWT RPC XSRF protection

Three extension points exist, all protected methods of AbstractXsrfProtectedServiceServlet:

A custom token type is a class that implements RpcToken (serialisable, public default constructor), annotated on the service interface with @RpcToken.RpcTokenImplementation("com.example.bookshelf.shared.SignedToken") so that the compiler generates a serialiser for that class only. The Developer Guide shows the same structure with a trivial example. Nothing else in this page depends on a custom token and the Bookshelf uses the shipped XsrfToken.

The calls below replay the three steps of the diagram with curl against the running Bookshelf. The permutation header and the policy hashes are placeholders; the session id and the token are placeholders for the real values, which are not printed.

A protected call without a token is refused with a serialised RpcTokenException, delivered with HTTP status 200 as every RPC answer is (the client library turns the //EX prefix into an exception):

The container log of that request held WARNING: catalogServlet: An RpcTokenException was thrown while processing this call. followed by the stack trace. That answer needs a JVM that can serialise exceptions, which on Java 17 and later means --add-opens java.base/java.lang=ALL-UNNAMED (the Jetty run above used it through MAVEN_OPTS; see the GWT-RPC page and GWT issue 9793). Without that option the same request answered:

so on Java 17 and later without the option the browser sees a generic 500 and the RpcTokenExceptionHandler is never called. The protection itself still works, because the exception is thrown before the method runs; only the explanatory answer is lost.

The token request, with the session cookie that the filter created, and the protected call that carries the token (the first object of the payload, type XsrfToken/4254043109, flag 2):

In the request the string table has seven entries, the token object is written as 3|4 (type, then the string <xsrf-token>) before the service name 5 and the method 6, and the flag 2 in the header says "an RPC token is included". Three more variations were sent with a valid session, to see each branch of validateXsrfToken:

The last row is the reason for the SessionFilter: the token servlet throws its RpcTokenException from a method whose signature does not declare it, so the RPC engine reports an unexpected exception and the client sees a 500, not a catchable token error.

Spring Security protects unsafe HTTP methods (POST, PUT, PATCH, DELETE) with the CsrfFilter by default. The browser-side pattern that suits a GWT client is the cookie variant, which the reference documentation describes: CookieCsrfTokenRepository writes a cookie named XSRF-TOKEN that JavaScript is allowed to read when it is created with withHttpOnlyFalse(), and the filter accepts the value back in the request header X-XSRF-TOKEN or the request parameter _csrf. The names were checked by asking the 7.1.1 classes directly:

The first line is CookieCsrfTokenRepository.withHttpOnlyFalse().generateToken(null), the second the default HttpSessionCsrfTokenRepository, which keeps the token in the session and expects the header X-CSRF-TOKEN. A configuration for the Bookshelf’s JSON and upload endpoints that leaves the GWT-RPC URLs to the GWT mechanism looks like this:

This configuration compiled against Spring Security 7.1.1 and Spring Framework 7.0.9. The request-handler line matters for a browser client. Since Spring Security 6 the default handler, XorCsrfTokenRequestAttributeHandler, masks the token on every response as a protection against the BREACH compression attack, while the cookie holds the plain value; the reference documentation’s section on single-page applications explains that JavaScript then only has the plain value and a handler that resolves it is needed. CsrfTokenRequestAttributeHandler is the plain handler, which accepts the cookie value as the header value; the documentation’s own SPA example delegates to the masking handler for rendered pages and to the plain one for headers, which keeps the BREACH protection for server-rendered tokens. Which of the two to pick depends on whether the same application renders pages with embedded tokens; read the reference page before copying either line.

The ignoringRequestMatchers line is a judgement call: it is correct only because the two GWT-RPC URLs enforce their own token, and it must be re-read whenever a service is added. The alternative, protecting RPC with Spring’s CSRF token as well, works by adding a custom RpcRequestBuilder that sets the header, but then two token systems run side by side, and the GWT one does not go away. Everything about the Spring Security filter chain, user stores and method security is on the backend side of this wiki: Spring Security; and the same CSRF tokens in server-rendered pages are covered in Thymeleaf with Spring Security.

The behaviour of the Spring filter was not run end to end in the scenario (no Spring Boot application was started for this page); the class names, header and parameter names and the default repository were verified as shown, and the filter’s contract is the documented one.

Source: Spring Security reference — Cross Site Request Forgery

RequestBuilder reads the cookie with Cookies.getCookie and sets the header; setIncludeCredentials(true) is needed only for cross-origin requests that must send cookies. A FormPanel cannot set headers, so the token travels in a Hidden field named _csrf:

Both methods compiled against gwt-user 2.13.1. Two details from the RequestBuilder, JSON & XML page apply: any setHeader call removes the default form content type of RequestBuilder, which is why the example sets Content-Type itself, and a FormPanel post is answered into a hidden frame, so the server’s 403 is visible only through the submit-complete event.

Source: GWT — Security for GWT applications

The mechanism of the cookie repository fits in a servlet filter. The one below is the lab version used for this page: it issues a random XSRF-TOKEN cookie that the page may read and requires the same value in the X-XSRF-TOKEN header on every method that is not GET, HEAD or OPTIONS. It exists to show the mechanism and to be run; in an application with Spring Security the framework’s filter replaces it.

It is mapped in web.xml to /api/* and /upload/*. The comparison uses MessageDigest.isEqual, which takes the same time whatever the position of the first differing byte; the token is a random 256-bit value encoded as URL-safe Base64, and the cookie is Secure whenever the request arrived over TLS. The answers observed with curl are in the table of the worked example further down (Worked example: a bounded upload and a fixed-upstream proxy).

A server that is also reachable cross-origin through CORS must not echo arbitrary origins together with credentials, or the same-origin guarantee that the token relies on is gone; see What is CORS? for the origin validation rules.

Source: OWASP — CSRF Prevention Cheat Sheet

CVE-2007-2378 ("JavaScript Hijacking"), published on 2007-04-30, is the National Vulnerability Database entry for the design weakness that GWT, like every toolkit of the time, exchanged JSON with no protection scheme against cross-site script inclusion; the NVD entry lists all versions of GWT of that date and no fixed version, because it describes a practice and not a bug. The attack needs three conditions: the server answers an authenticated GET (or a POST that a script tag can imitate) with a top-level JSON array or a JavaScript value that executes when evaluated; the answer depends on the user’s cookies; and the victim’s browser evaluates the response as a script. The attacker’s page includes <script src="https://bookshelf.example/api/loans">, the browser sends the victim’s cookies, evaluates the response as JavaScript, and, in the engines of the time, the attacker could observe the data by redefining the Array constructor or the property setters before the include. The same-origin policy does not intervene, because script inclusion across origins has always been allowed. The Developer Guide article "Security for GWT applications" describes the attack and the countermeasures in its "JSON and XSRF" and "JSON and GWT" sections. I did not test the constructor-redefinition trick, and the article itself is of 2007 vintage; current engines have closed most of it, but the cheap countermeasures below are still correct and cost nothing.

What the scenario shows, measured on the running server:

JSONP is the practice of working around the same-origin policy by inserting a script tag whose response is a call of a function that the page defines. GWT ships it as JsonpRequestBuilder (module com.google.gwt.jsonp.Jsonp, package com.google.gwt.jsonp.client), with requestObject, requestString and similar methods, and the Javadoc marks the URL parameter of send with @IsTrustedResourceUri. That annotation is the warning: JSONP runs the answer as code in your page, with all of your page’s privileges. Whoever controls the server or the URL controls your application, so a JSONP endpoint is a full cross-site scripting hole by design, and the article states that attacks against JSON and JSONP are fundamental, that "there’s nothing you can do to stop it" once the browser runs the code, and that the defence is not to send private data in that form. Rules that follow:

Source: GWT — Security for GWT applications

At compile time the GWT compiler computes, for each RemoteService, the set of types that may be sent and received, and writes it to <hash>.gwt.rpc next to the JavaScript (the Bookshelf’s has lines such as com.example.bookshelf.shared.Book, true, true, true, true, ...). At run time RemoteServiceServlet loads the policy that the request names (the strong name is the second token of the payload) and StandardSerializationPolicy.validateDeserialize refuses any class that is not on the list:

(The text is the message in StandardSerializationPolicy of the 2.13.1 source.) So a hostile client cannot make the server instantiate an arbitrary class by naming it in the payload: only types that the compiler found reachable from the service interface can be created, and a class that is on the class path of the server but not in the policy is refused. Two related checks are in the engine: a payload that names a service interface the servlet does not implement is refused with IncompatibleRemoteServiceException: Blocked attempt to access interface '...', which is not implemented by '...'; this is either misconfiguration or a hack attempt, and a value whose actual type does not fit the declared parameter type raises SerializedTypeViolationException (Attempt to deserialize an object of type X when an object of type Y is expected).

Consequences for hardening:

Until GWT 2.10.0 the policy could include "enhanced classes", persistence-framework classes that the container adds server-only fields to. To keep those fields across a client round trip, the server serialised them with Java object serialisation, put the bytes into the RPC payload as a Base64 string, and on the way back called ObjectInputStream.readObject on whatever the client had returned (visible in ServerSerializationStreamReader, in the branch that handles getClientFieldNamesForEnhancedClass). There was no signature, so a client could substitute any serialised object graph, which is the textbook insecure-deserialisation vulnerability, and it was reported as GWT issue 9709, "Java Deserialization vulnerability in GWT-RPC". The fix, in the release notes of 2.10.1 (backported) and 2.11.0, is to disable the enhanced-classes mechanism by default and log a warning when it is in use. In 2.13.1 the switch is the system property gwt.enhancedClasses.enabled, read once by SerializationPolicyLoader and effective only when its value is exactly true:

Do not set it. The reliable fix, independent of any version, is the one every other section of the web uses for JPA entities: a service interface exposes DTOs, plain shared classes that carry the fields the client needs, and the server maps entities to DTOs and back (the Bookshelf’s Book and BookPage are such classes). That also keeps lazy associations, internal ids, password hashes and audit columns out of the response, which is a leak, and not only a deserialisation, risk. The GWT-RPC page of this section covers the DTO shapes and the compiler messages in detail.

Source: GWT 2.13.1 source — StandardSerializationPolicy

The lab declared the librarian area in web.xml and ran Jetty with a one-user realm (alice: changeit-placeholder,librarian, a placeholder password in a throw-away file; production uses a real user store and TLS):

An unauthenticated request got 401 Unauthorized with WWW-Authenticate: Basic realm="Bookshelf" before any filter or servlet of the application ran. Basic authentication is shown only because it needs no extra page; use form login, OIDC or your framework’s mechanism with TLS in a real application. The rest of the checks stay in the servlet, as the example in the next section shows with a belt-and-braces role check.

An order detail that matters for the filters on this page: the container’s <security-constraint> is evaluated before the servlet filters. An unauthenticated POST therefore got the 401, not the 403 of the CSRF filter, and the CSRF filter ran only for authenticated requests; with Spring Security the order is explicit in the filter chain (CsrfFilter before the authorisation filter).

Source: Jakarta Servlet 6.0 specification

The rules it enforces are: the caller is authenticated and in the librarian role; the CSRF filter has already checked the header; the size is capped twice (by <multipart-config> in web.xml, enforced by the container before the application code reads the data, and by an explicit check); the type is decided from the content (the first bytes), not from the declared content type or the file name; and the file name is chosen by the server (a random UUID plus a fixed extension), so the client’s name is never used in a path.

with this declaration, whose limits are in bytes:

What a real deployment adds: antivirus or image re-encoding (decoding the image and writing it again strips payloads hidden in metadata and proves it is an image), storage outside the web root and outside the application’s code path, a quota per user, an Content-Disposition: attachment and nosniff when serving the file back, and the OWASP file-upload checklist (linked in the references). Magic bytes prove the first four bytes, not the whole file; a servlet that must trust nothing re-encodes.

Source: OWASP — File Upload Cheat Sheet

A page that needs data from another host should call a servlet of its own server, and that servlet must never turn into a way to reach internal hosts. The safe shape is a fixed upstream with parameters that are parsed, clamped and re-encoded, never a URL taken from the request:

The properties that make it safe: one upstream host written in the code or in configuration; only two integer parameters, clamped; connect and request timeouts; a response size limit; the caller is authenticated by the container; errors are mapped to status codes and logged, not swallowed. If the real design needs several upstreams, use a server-side allow-list of names mapped to fixed base URLs (?source=openlibrary), never a host from the request, and resolve the host names yourself and reject loopback, link-local and private addresses (the OWASP server-side request forgery cheat sheet in the references).

Source: OWASP — Server-Side Request Forgery Prevention Cheat Sheet

All the requests used curl; the cookie jar kept the XSRF-TOKEN cookie, the user was alice with the placeholder password, and <uuid> stands for the random name.

The two classes, the filter and the web.xml fragments were compiled with javac --release 17 against jakarta.servlet-api 6.0.0 and run on Jetty 12.1.10 with JDK 21. They are an illustration of the pattern, with no persistence, no quota and a single hard-coded role; they are not meant to be copied into production unchanged. The upload servlet of the deployment page (Server Integration & Deployment) shows the <multipart-config> plumbing for a Spring Boot jar; combine it with the checks above.