Tokens

Tokens

Tokens allows us to easily proof properties for different objects. For instance, a token can be proof that the user may register account A on server Y within a certain time period, or that account A is allowed to register to server Y in organisation O.

Invitation tokens

Invitation tokens allow users to register accounts onto a BitMaelum.

A token is build up the following way:

 base64(
    address-hash
    ':'
    routingID
    ':'
    expiry timestamp
    ':'
    binary signature 
 )

The binary signature is build up the following way:

      sign(sha256(address-hash + routingID + expiry timestamp), pk)

where pk is the private key of the mail server.

To verify the token, we check:

• extract all the parts from the token
• generate hash
• fetch public key from the server pointed at routingID
• verify is the hash is signed correctly
• check if the expiry date hasn't been reached
• check if the routing ID matches the routing ID of the current mail server

if everything is ok, then this token is proof that user X may register the address on that mailserver.

Organisational tokens

An organisation token has the same format as a regular invitation token, except it is signed by the organisation's private key instead of the mailserver private key.

Organisational tokens are used in three ways:

• for registration of an account on a mailserver (much like an invitation token)
• for registration of an account on the key server system
• for validating validity when receiving messages

Registration on a mailserver

An invitation token allows us to register account A on mailserver X. But organisation accounts could have more restrictions: they may for instance not be allowed on 3rd party servers. So besides a regular invitation token, we also need to send an organisation token. A mail server can detect if the given account is for an organisation. We need to send the local part and the organisational part of an address to the mailserver during creation. With this, the mailserver can recreate the address-hash and see if it matches. If it does not match, the given address is not part of that organisation (or maybe it is, but the wrong name).

Once the mailserver knows the account is from an organisation, it can check the orgnaisation token to see if the account is allowed. If so, the account is created.

NOTE: we do not really need to check: a hostile mailserver could disable the check and register it anyway. In fact, ALL servers can register ALL accounts, including accounts already registered, or accounts from other people. They will, however, not be send any mail, as the key-server resolves to a different server.

Registration on the keyserver

We need this to make sure that the user is actually allowed by the organisation to register. If this fails, it doesn't matter if mail servers register the account, as no mail can be send or received.

Verification when receiving mail

When sending mail, we send the organisation token with it, so it can be verified that this email is actually send with permission of the organisation. When no organisation token is available, or incorrect, it can display a warning at the client. Note that this can only happen AFTER downloading the catalog, where this information is stored.