doc/developer/TokenArchitecture

Version 7 (modified by benoitg, 15 years ago)

--

Contributor(s): Benoit Grégoire, last modified: 2007-05-03

Token, General model

Currently, connection tokens are very weak entities, directly stored in the connection table. Many stakeholders would like to add features to connections (time limit, persistent token, etc.) to support the different WirelessCommunityModels. To do this without shooting ourselves in the foot, we need a data model that can solve the general problem of connection handling and re-use, not just a specific degenerate case of it (such as selling pre-paid time).

What follows is a first draft at doing so.

Data model

token_templates

  • token_network (Note: Server-wide tokens aren't supported, but the code will look up the tokens of networks you peer with)
  • token_max_incoming_data Ex: Allows capping bandwidth
  • token_max_outgoing_data Ex: Allows capping bandwidth
  • token_max_total_data Ex: Allows capping bandwidth
  • token_max_connection_duration: Ex: Allows limiting the length of a single connection
  • token_max_usage_duration: Ex: Allows selling access by the hour (counting only when in use)
  • token_max_wallclock_duration: Ex: Allows selling daily, weekly or monthly passes (starting the count as soon as the token is first used)
  • token_max_age: Ex: Allow setting a maximum time before epirint (starting the count as soon as the token is issued)
  • is_reusable: Is the connection reusable? (normally, yes)

tokens_template_valid_nodes (Unfortunately, for hotels selling 24h access to their clients, we have to consider that their network may consist of more than one node. If the token has no entry in this table, it's considered valid everywhere on the Network (and it's peers))

  • token_id
  • token_valid_at_node

token_lots

  • token_lot_id
  • comment: A freeform comment about the lot
  • creation_date

Lots are groups of tokens issued at the same time

tokens

  • token_id
  • token_status
  • token_lot_id: References token_lots
  • token_creation_date (not the same as connection start time)
  • token_issuer: A user in the system. User responsable for the creation of the token (not necessarily the same as the one using it)
  • token_owner: The user that can USE the token (anyone if empty?).

When a connection is established, the values in the tokens table are used, along with eventual network policies (maximum monthly data transfer, maximum connection time) or node policies (opening hours) to calculate max_data_transfer and expiration_date in the connection table. This calculation is expensive, but once done, all the auth server has to do is validate max_data_transfer and expiration_date which is practically free.

connection (new or redefined field in existing table)

  • connection_status (used to be token_status)
  • token_id Now references the tokens table
  • max_total_data (token_max_data_transfer - SUM(data transfer for all connections on this token))
  • max_incoming_data Similar to above
  • max_outgoing_data Similar to above
  • expiration_date (MIN(NOW+token_max_connection_duration, NOW+token_max_total_duration-SUM(data transfer for all connections on this token), token_expiration_date))
  • logout_reason Explains what caused the connection to be closed