Menu ▾ ▴

Pame - Protocol Standard

Twisted Head

PAME (Protocolo Avanzado de Mensajería Electrónica or Advanced Protocol for Electronic Messaging)

Twisted Head

Somewhere over the rainbow

Introduction

==============

The objective of Protocolo Avanzado de Mensajería Electrónica (PAME) is to transfer electronic messages (Epost) in an efficient, effective, secure, fast and reliable way. The main objective of PAME is to provide with a system of electronic communications that is easy to implement and extend according to new technologies and user requirements. It is also not limited to a single network or domain, it may communicate with other networks that implement the same protocol. Built in encryption protocols is one of its core strengths.

It is designed to be extensible and easy to implement in any machine.

Standard Protocol

===================

Version: 0.2.1: wellcome_my_son_wellcome_to_machine

License

==========

This protocol is distributed under a 'Do no harm' license. You may use it in any way you want as long as you do no harm to any living creature.

If for some reason you can not comply with that you may use it under a GPl v2 license.

General information

======================

Any communication done by the system is made via a reserved user called "psychocat" in the form of "psychocat::mydomain.com". (See 'countersign' bellow for an explanation on '::')

Example:
If example.com needs to inform example2.com that mark::example2.com is suspected of spam it will send a message from psychocat::example.com

The default communications port is 80 in a subdomain Epost.example.com, this may be altered depending on specific requirements for example if you want a private network.

Messages ar always utf-8 encoded either via GET or POST in plain text. The contents may be encoded and this is actually encouraged.

All text strings must be JSON encoded in requests and all replies are JSON encoded.

Requests are done via POST or GET only. POST is recommended for sending messages since they may include a lot of text.

Privacy is paramount for Epost for which is it not allowed as part of the protocol to store sensitive information about a user except for the IP which is used in cases of abuse or spam. There is a section that deals with this better.

All times are UTC.

Definitions

===============

PAME Client: Software application used to send, recieve and manage PAME systems, it is intended for end users. Think of Thunderbird for emails.

PAME Server: Software application used to handle PAME communications in a central Hive. Think of qmail or sendmail in *nix systems.

PAME Hive: Usually a domain hosting a PAME server for communications. If your company installs a PAME Server that would be 'your' Hive.

Message: A message, usually an Epost, sent from one party to another.

Request: A request made from a Hive to another. Example: relay a message or get information about a contact.

Reply: Response given to a request.

Security, the Countersign

============================

One of the biggest innovations of PAME is the Countersign, this communications are done in two parts:

  • First part: contacting party sends a request.
  • Second part: recieving party finishes the request.

Example:

  • step 1: machine 1 sends a request from psychocat::example1.com to send a new Epost to psychocat::example2.com in (obviously) machine 2.

  • step 2: machine 2 accepts the request and then contacts back machine 1 to retrieve the message.

This way machine 1 can never fool machine 2 by sending a fake message from say machine 3. Also machine 2 is free from all the hasle of verifying the identity of machine 1 via reverse ip lookup which can be problematic and slow.

Simple communications use other mecanisms for example when user1 wants to alert user2 about a possible spammer user1 will use a secret code previously established between them.

Security is built in by default in Epost and the PAME protocol takes advantage of this. More security meassures will be discussed on a per case basis.

HTML is not accepted in the body of an Epost message, they can be either 'plain text' or 'rich text' via BBCode (this may change to Markdown in future implementations).

Javascript is not allowed, at the moment there is no option to provide with interactive content.

SSL

=======

All communications are encouraged to be done via https protocol, each Hive may reject communications recieved from non secure connections and may also reject communicating with other Hives that do not provide said secure connections.

Forbidden things

===================

This is a list of things that may never be implemented in an Epost server, doing so will (should) get you banned from the global network.

  • Providing api requests to get personal details about a user such as (and not limited to):

    • message numbers
    • chat subscriptions
    • contact lists
    • ip or location details

  • Storing location information. This does not apply to location sharing services that may be implemented in the future or sent via Epost.

This applies even to open information, for example:
User 'a' is registred in chat 'ab' and anyone can access said chat and view a list of its current members. That is fine, but the system should NOT provide automated ways of retrieving this type of information.

Only the approved api calls listed in this document are valid, any other option is a direct violation of the standard and you are most likely going to get banned in the network.

Clients requiring phone numbers or other directly personal information in order to register or get activated.

Anonymity versus Accountability

==================================

Epost aims at giving freedom and a great level of anonimity to its users in regards to tracking their movements or keeping personal records, but it is not the aim of creating a 100% anonymous system where a message may not tracked back to its source.

Each message contains a header with information about the sending party including their public IP (at the moment at least, this may change) which is important for many reasons.

This protocol does not require the clients to provide direct personal information such as phone numbers or even email accounts.

Todo

=======

This is a non-exaustive list of pending things comming to this standard:

  • Complete chats specifications (partially done)
  • Attachments (on the way)
  • Encryption (almost ready!)

Comunication requests

========================

All new communications start with a request that uses a specific identifier, for example a relayed message uses the code 'Epost_msg_relay'.

The main goal is to have clear requests instead of broad ones that may lead to errors or bugs.

There is a code to get old messages in a conversation and another one for new messages once the user is active in it.

Every request must include the following parts even if they are not required.

iam: username::example.com

The usermane and domain of the person sending the message. This can be psychocat::example.com for system cammunications or a user sending an Epost.

The domain part is optional, it may be omitted and it means that it is a user from the same domain where the server is running.

w: request_code

Each communication has a unique request code wich will tell the recieving end what you will be doing.

Other parts may be mandatory on a per case basis and they will be indicated.

Start-Limit

Some requests may use a start-limit indicator, such cases are for example when retrieving old messages in a conversation. The default values are start = 0 and limit = 0.

Requests that accept this indicators will mention it in the protocol.

Example:
start: 0
limit: 10

Reply codes

==============

Reply codes to requests follow the same principle but use numbers instead of words. This way it is easier to recognize if there was an error. All negative codes are erros, zero means 'no' or just nothing found and 1 means 'yes' or 'all good' (success).

Security:

In most cases the general -1 'unknown error' code is used in order to avoid providing much information to potential attackers.

The codes

=============

(This list is under construction and at the moment a little volatile until the protocol is stable)

All replies are JSON encoded in a variable named resp.

This is a general list, the use of each code will be explained on a per case basis further on.

  • 1: All good (always) or 'yes'
  • 0: No results found or 'no'
  • -1: Unknown Error
  • -1.1: Bad request
  • -1.301: Wrong log in information
  • -1.303: Access denied. Not logged in.
  • -1.304: User exists. When trying to register a new one for example.
  • -3.2: The conversation does not exist
  • -3.3: Not a valid contact (either it does not exist or maybe it was an invalid request)
  • -3.4: Contact not welcome (it was blocked by the recieving party)
  • -1.3: User not valid (Not logged in or blocked)

Example:

{"resp":1}

Sessions

==========

Client and Hive exchange messages and other communications inside of a 'session', each request will indicate the session key and the user for said session.

Sessions are handled via session keys that each Hive must maintain and validate. Cookies are not accepted as a means to handle sessions.

At the moment this is a simple sessionKey/ip implementation, the next revision of the protocol will include a much more secure system with a challeng based verification on each request. This is already designed but not yet fully implemented.

For security reasons some requests are based on a session, such requests will indicate this with Uses session.

Example:
Sending a message will always be on the name of the currently logged in user. There is no need to send userName/password, a session must be open before hand in order to send a message.

Another case is a user trying to get a list of their contacts, just indicate the session and the directory will be loaded based in this.

Messaging (Eposts)

====================

Epost are electronic messages between two or more parties, they are the basic foundation of the system. Other parts of it are sustained by them or use an implementation of them.