DOCS: Document cookie usage in Etherpad - Waiting on Final Edits

[tiblu]

Overview

It's important to the Users and the host of the Etherpad instance to know what cookies are used in Etherpad and what is their purpose.

List of known cookies issued by Ethepad

name	sample value	domain	path	expires/max-age	http	secure	usage
express_sid	s%3A7yCNjRmTW8ylGQ53I2IhOwYF9...	example.org	/	1969-12-31T23:59:59.000Z	true	true	Session ID of the Express web framework. When Etherpad is behind a reverse proxy, and an administrator wants to use session stickiness, he may use this cookie. If you are behind a reverse proxy, please remember to set trustProxy: true in settings.json
io	uUrtV8P-cJF0IVDOAAAV	example.org	/	1969-12-31T23:59:59.000Z	true	false	No longer used since Etherpad 1.8, see a51684b
language	en	example.org	/	1969-12-31T23:59:59.000Z	false	true	The language of the UI (e.g.: en-GB, it)
prefs	%7B%22epThemesExtTheme%22...	example.org	/p	3000-02-25T13:17:08.000Z	false	true	client-side preferences (e.g.: font family, chat always visible, show authorship colors, ...)
token	t.tFzkihhhBf4xKEpCK3PU	example.org	/	2019-04-26T13:17:07.000Z	false	true	A random token representing the author, of the form t.randomstring_of_lenght_20. The random string is generated by the client, at (pad.js#L55-L66). This cookie is always set by the client (at pad.js#L153-L158) without any solicitation from the server. It is used for all the pads accessed via the web UI (not used for the HTTP API). On the server side, its value is accessed at SecurityManager.js#L33.
sessionID	s.1c70968b333b25476a2c7bdd0e0bed17	example.org	/	2019-04-26T13:17:07.000Z	?	?	Sessions can be created between a group and an author. This allows an author to access more than one group. The sessionID will be set as a cookie to the client and is valid until a certain date. The session cookie can also contain multiple comma-separated sessionIDs, allowing a user to edit pads in different groups at the same time. More info - https://github.com/ether/etherpad-lite/blob/develop/doc/api/http_api.md#session

|

TODO

• Extend the cookie list above
• Add usage clarifications to every cookie

[muxator]

That's right.
A PR with the needed changes in the documentation would be promptly accepted.

BTW, this table is going to be updated as soon as #3561 is implemented: we will need to explain that the secure flag is dependent whether or not Etherpad is accessed via TLS.

[tiblu]

@muxator Thanks for the quick response.

I can PR the documentation change once the information has been collected but before that I would need the information to be correct.

Can you comment on any of the cookies mentioned above?

[HamzaKhait]

Hello,
Is there any way to completely disable these cookies ? I don't think they're useful

[muxator]

@tiblu, I finally had the time to work on #3561 and thus simplified & clarified the scope of the cookies.

The perfs cookie holds the client-side settings (e.g.: font family, chat always visible, show authorship colors, ...), but I did not have time to thoroughly assess the code like for the other ones.

[muxator]

Added another optional cookie, sessionID, that can be used with the HTTP API. Details are scattered throughout the http_api.md documentation and the source code, for example in src/node/padaccess.js and src/static/js/pad.js.

[muxator]

Postponing the release of this documentation to a point release after 1.8.0.

[tiblu]

@muxator Thanks for the input on this, from our POV we have all the info on all the cookies we're using in our Etherpad deployment.

One thought tho, as privacy is important and GDPR requires to have very granular cookie consents which describe to the User the use of cookies we should have a place in documentation that holds the up to date info about the cookies? I think this GH issue is a good start, but MAY be hard to find and get out of date.

Thanks again for all your work on Etherpad.

[tiblu]

Now that I think about it, the token is one which usage is actually not all that clear - how it actually is used, when is it actually needed. Even when public pads are disabled, it's still generated while the claim is "used for public pads".

[JohnMcLear]

TLDR; token is an abstraction of authorID so we don't have to always pass authorID? :)

grep -rni "token" .

Server side:

./hooks/express/importexport.js:79:      if (!req.cookies.token) {
./hooks/express/importexport.js:80:        console.warn(`Unable to import file into "${req.params.pad}". No token in the cookies`);
./hooks/express/importexport.js:84:      let author = await authorManager.getAuthor4Token(req.cookies.token);
./hooks/express/importexport.js:87:        console.warn(`Unable to import file into "${req.params.pad}". No Author found for token ${req.cookies.token}`);
./hooks/express/openapi.js:232:    checkToken: {
./hooks/express/openapi.js:233:      operationId: 'checkToken',
./hooks/express/openapi.js:234:      summary: 'returns ok when the current api token is valid',
./db/SecurityManager.js:33: * @param token the token of the author (randomly generated at client side, used for public pads)
./db/SecurityManager.js:37:exports.checkAccess = async function(padID, sessionCookie, token, password)
./db/SecurityManager.js:47:  var deniedByHook = hooks.callAll("onAccessCheck", {'padID': padID, 'password': password, 'token': token, 'sessionCookie': sessionCookie}).indexOf(false) > -1;
./db/SecurityManager.js:52:  // start to get author for this token
./db/SecurityManager.js:53:  let p_tokenAuthor = authorManager.getAuthor4Token(token);
./db/SecurityManager.js:70:      let authorID = await p_tokenAuthor;
./db/SecurityManager.js:85:      // grant access, with author of token
./db/SecurityManager.js:239:    let authorID = await p_tokenAuthor;
./db/SecurityManager.js:245:      // --> grant access, with author of token
./db/SecurityManager.js:252:      // --> grant access, with author of token
./db/AuthorManager.js:52: * Returns the AuthorID for a token.
./db/AuthorManager.js:53: * @param {String} token The token
./db/AuthorManager.js:55:exports.getAuthor4Token = async function(token)
./db/AuthorManager.js:57:  let author = await mapAuthorWithDBKey("token2author", token);
./db/AuthorManager.js:65: * @param {String} token The mapper
./db/AuthorManager.js:82: * so far this is token2author and mapper2author
./db/AuthorManager.js:95:    // create the token2author relation
./db/API.js:780:checkToken() returns ok when the current api token is valid
./db/API.js:787:exports.checkToken = async function()
./handler/PadMessageHandler.js:293:    let { accessStatus } = await securityManager.checkAccess(padId, auth.sessionID, auth.token, auth.password);
./handler/PadMessageHandler.js:859:    token : message.token,
./handler/PadMessageHandler.js:865: * Handles a CLIENT_READY. A CLIENT_READY is the first message from the client to the server. The Client sends his token
./handler/PadMessageHandler.js:873:  if (!message.token) {
./handler/PadMessageHandler.js:874:    messageLogger.warn("Dropped message, CLIENT_READY Message has no token!");
./handler/PadMessageHandler.js:905:  let statusObject = await securityManager.checkAccess(padIds.padId, message.sessionID, message.token, message.password);
./handler/SocketIORouter.js:93:        if (message.padId !== undefined && message.sessionID !== undefined && message.token !== undefined && message.password !== undefined) {
./handler/SocketIORouter.js:100:          let { accessStatus } = await securityManager.checkAccess(padId, message.sessionID, message.token, message.password);
./handler/APIHandler.js:89:  { "checkToken"                : []
./padaccess.js:6:    let accessObj = await securityManager.checkAccess(req.params.pad, req.cookies.sessionID, req.cookies.token, req.cookies.password);

./pad.js:153:  var token = readCookie("token");
./pad.js:154:  if (token == null)
./pad.js:156:    token = "t." + randomString();
./pad.js:157:    createCookie("token", token, 60);
./pad.js:169:    "token": token,
./timeslider.js:33:var token, padId, export_links;
./timeslider.js:48:    //ensure we have a token
./timeslider.js:49:    token = readCookie("token");
./timeslider.js:50:    if(token == null)
./timeslider.js:52:      token = "t." + randomString();
./timeslider.js:53:      createCookie("token", token, 60);
./timeslider.js:120:              "token": token,
./pad_impexp.js:139:  function importSuccessful(token)
./pad_impexp.js:146:        token: token,

Most notable:

/**
 * Returns the AuthorID for a token.
 * @param {String} token The token
 */
exports.getAuthor4Token = async function(token)
{
  let author = await mapAuthorWithDBKey("token2author", token);

  // return only the sub value authorID
  return author ? author.authorID : author;
}

and

/**
 * Returns the AuthorID for a mapper.
 * @param {String} token The mapper
 * @param {String} name The name of the author (optional)
 */
exports.createAuthorIfNotExistsFor = async function(authorMapper, name)
{
  let author = await mapAuthorWithDBKey("mapper2author", authorMapper);

  if (name) {
    // set the name of this author
    await exports.setAuthorName(author.authorID, name);
  }

  return author;
};

So token is a representation of an author.

My assumption would be.. session is dynamic, changes, doesn't matter. You need token to let Etherpad know you are who you say you are, type thing.. IE session isn't persistent between restarts, but token is.. It's not used for auth, it's used to say I am "John" who did these edits (but obv doesn't include the edits).

If token is leaked, it's nbd, it's not as if Etherpad would ever tell you what edits you did historically..