Whitebeam Template Reference Documentation

Site Map
Application Guide
  XML Markup
  JavaScript Classes
  Dev Process
  External Links
  Example libraries
Contact Whitebeam
Whitebeam Users

Whitebeam Template Reference Documentation

System Template

session.setPublicKey() - Available since version 1.3.6

Store a public key against the current session.

See Also



void = rb.page.session.setPublicKey(publicKey)


The 'session.setPublicKey' method takes 1 parameter:

Name Type/Value Range/Length Description
publicKeynumbersigned 64 bit integer Optional.

A 64 bit integer to be used to reference this session from other sessions

To remove the currently assigned public key call setPublicKey with no parameters.


The 'session.setPublicKey' method returns no useful information.


Individual session access their private session data via their session ID. This is a long random number. In versions of Whitebeam prior to 1.3.5 the only way to access this data is by the session ID and only then by the current session. There was no mechanism by which an application running as part of another session could access of even determine which sessions exist.

While very secure and in keeping with the Whitebeam philosophy there are valid situations in which inter-session communication is required. Examples include:

  • An administrator wishes to change the access permissions of a user - and informm any sessions in use by that user to revalidate.
  • An application may wish to limit the number of concurrent logins available (eg to one per person). Without knowing which other sessions exist this is not possible.

Version 1.3.6 of Whitebeam introduces the concept of a 'public key' for sessions. This allows sessions to interract with each other without having to expose the private sessions IDs.

A 'public key' in this context is a 64 bit integer. It is anticipated that this would usually be set to the contact ID of the user currently logged in through a specific session.

Assigning a public key to a session is:

  1. entirely optional and at the discretion of the application
  2. can only be set by the application running within that session - eg you can only set your own public key
  3. allows signalling between session without allowing one session to access the private information of another session

Using an extension of the session API applications can write information to the session data structure via the public key. For example, suppose an application wishes to tell user X that they need to reauthenticate. The application running the administrators interface could 'write' a flag to all sessions with public key X.

1 There may be multiple sessions marked with the same public key. Addressing sessions by their public key will write to all sessions that share the same public key - i.e. in this example to all sessions where the user is logged in as user X.

2 Generally it is anticipated that when a site visitor logs in to an application the authentication code will write the contact ID of the authorised user as the 'public key' for that session. If/when the user explicitly logs out the public key should be removed by calling setPublicKey with no parameter.

Whitebeam release 1.3.36
(loadtime : 187ms)