libwebsockets/READMEs/README.jwt.md

JWT support in lws

lws supports the common usage scenarios of JWS (signed) JWT generation, parsing and transferring in and out as http cookies. Care is taken to provide helpers that implement the current security best practices for cookie handling and JWT validation. All of the common algorithms like ES512 are supported along with JWK generation and handling apis.

The build options needed are -DLWS_WITH_JOSE=1 -DLWS_WITH_GENCRYPTO=1.

Underlying JOSE primitives are exposed as apis, some JWT specific primitives and finally a JWT-via http cookie level creation apis each building on top of what was underneath.

The higher level APIs are provided additionally because they have the most opportunity for implementation pitfalls like not validating alg carefully, or not using the latest cookie security options; the provided APIs handle that centrally for you. If your needs vary from what the higher level apis are doing, you can cut-and-paste out those implementations and create your own using the public lower level apis.

LWS JWT fields

Lws JWT uses mainly well-known fields

Field	Std	Meaning
iss	yes	Issuer, typically the domain like "warmcat.com"
aud	yes	Audience, typically a url path like "https://warmcat.com/sai"
iat	yes	Unix-time "Issued At"
nbf	yes	Unix-time "Not Before"
exp	yes	Unix-time "Expired"
sub	yes	Subject, eg, a username or user email
csrf	no	A random 16-char hex token generated with the JWT for use in links specific to the JWT bearer
ext	no	Application-specific JSON sub-object with whatever fields you need, eg, "authorization": 1

Approach for JWT as session token

Once JWTs are produced, they are autonomous bearer tokens, if they are not kept secret between the browser and the site, they will be accepted as evidence for having rights to the session from anyone.

Requiring https, and various other cookie hardening techniques make it more difficult for them to leak, but it is still necessary to strictly constrain the token's validity time, usually to a few tens of minutes or how long it takes a user to login and get stuff done on the site in one session.

CSRF mitigation

Cross Site Request Forgery (CSRF) is a hacking scenario where an authorized user with a valid token is tricked into clicking on an external link that performs some action with side-effects on the site he has active auth on. For example, he has a cookie that's logged into his bank, and the link posts a form to the bank site transferring money to the attacker.

Lws JWT mitigates this possibility by putting a random secret in the generated JWT; when the authorized user presents his JWT to generate the page, generated links that require auth to perform their actions include the CSRF string from that user's current JWT.

When the user clicks those links intentionally, the CSRF string in the link matches the CSRF string in the currently valid JWT that was also provided to the server along with the click, and all is well.

An attacker does not know the random, ephemeral JWT CSRF secret to include in forged links, so the attacker-controlled action gets rejected at the server as having used an invalid link.

The checking and link manipulation need to be implemented in user code / JS... lws JWT provides the random CSRF secret in the JWT and makes it visible to the server when the incoming JWT is processed.

Need for client tracking of short JWT validity times

Many links or references on pages do not require CSRF strings, only those that perform actions with side-effects like deletion or money transfer should need protecting this way.

Due to CSRF mitigation, generated pages containing the protected links effectively have an expiry time linked to that of the JWT, since only the bearer of the JWT used to generate the links on the page can use them; once that expires actually nobody can use them and the page contents, which may anyway be showing content that only authenticated users can see must be invalidated and re-fetched. Even if the contents are visible without authentication, additional UI elements like delete buttons that should only be shown when authenticated will wrongly still be shown

For that reason, the client should be informed by the server along with the authentication status, the expiry time of it. The client should then by itself make arrangements to refresh the page when this time is passed, either showing an unauthenticated version of the same page if it exists, or by redirecting to the site homepage if showing any of the contents required authentication. The user can then log back in using his credientials typically stored in the browser's password store and receive a new short-term JWT with a new random csrf token along with a new page using the new csrf token in its links.

Considerations for long-lived connections

Once established as authorized, websocket links may be very long-lived and hold their authorization state at the server. Although the browser monitoring the JWT reloading the page on auth expiry should mitigate this, an attacker can choose to just not do that and have an immortally useful websocket link.

At least for actions on the long-lived connection, it should not only confirm the JWT authorized it but that the current time is still before the "exp" time in the JWT, this is made available as expiry_unix_time in the args struct after successful validation.

Ideally the server should close long-lived connections according to their auth expiry time.

JWT lower level APIs

The related apis are in ./include/libwebsockets/lws-jws.h

Validation of JWT

int
lws_jwt_signed_validate(struct lws_context *ctx, struct lws_jwk *jwk,
			const char *alg_list, const char *com, size_t len,
			char *temp, int tl, char *out, size_t *out_len);

Composing and signing JWT

int
lws_jwt_sign_compact(struct lws_context *ctx, struct lws_jwk *jwk,
		     const char *alg, char *out, size_t *out_len, char *temp,
		     int tl, const char *format, ...);

JWT creation and cookie get / set API

Both the validation and signing apis use the same struct to contain their aguments.

struct lws_jwt_sign_set_cookie {
	struct lws_jwk			*jwk;
	/**< entry: required signing key */
	const char			*alg;
	/**< entry: required signing alg, eg, "ES512" */
	const char 			*iss;
	/**< entry: issuer name to use */
	const char			*aud;
	/**< entry: audience */
	const char			*cookie_name;
	/**< entry: the name of the cookie */
	char				sub[33];
	/**< sign-entry, validate-exit: subject */
	const char			*extra_json;
	/**< sign-entry, validate-exit:
	 * optional "ext" JSON object contents for the JWT */
	size_t				extra_json_len;
	/**< validate-exit:
	 * length of optional "ext" JSON object contents for the JWT */
	const char			*csrf_in;
	/**< validate-entry:
	 * NULL, or an external CSRF token to check against what is in the JWT */
	unsigned long			expiry_unix_time;
	/**< sign-entry: seconds the JWT and cookie may live,
	 * validate-exit: expiry unix time */
};

int
lws_jwt_sign_token_set_http_cookie(struct lws *wsi,
				   const struct lws_jwt_sign_set_cookie *i,
				   uint8_t **p, uint8_t *end);
int
lws_jwt_get_http_cookie_validate_jwt(struct lws *wsi,
				     struct lws_jwt_sign_set_cookie *i,
				     char *out, size_t *out_len);