PrivMX Architecture – client-server communication

PrivMX addresses

The PrivMX architecture assumes that the servers are identified through the hostname (domain name) and the users of the individual servers – through the address of the form of user#hostname.

Service Discovery procedure

Calling the API methods of the PrivMX Server is possible after obtaining the exact address for sending requests (API endpoint) for a given hostname. This is done by the Service Discovery (SD) Procedure which attempts to establish connection with the target server and asks it for configuration for the selected transport protocol. For example, the host "" for the "http" protocol can report the configuration:

defaultEndpoint =

Such a configuration, in addition to defaultEndpoint, may also contain other fields, i.e. TTL (time-to-live that is the maximum storage time of the endpoint address in cache), or Redirect (order to search for an endpoint address on another server).

The SD procedure while looking for a configuration, checks fixed locations on the target server – asks for specific URL addresses (e.g. http://hostname/privmx/privmx-configuration.json) and checks the TXT records in the DNS entry for the hostname domain. An example entry in DNS might have the form:


After performing the SD procedure and obtaining the address "defaultEndpoint", the client module is ready to establish a connection with the server by means of the PrivMX TLS protocol.

PrivMX TLS protocol

API calls are implemented using the secure PrivMX TLS communications protocol being a modified and simplified variant of the TLS 1.2 protocol.

PrivMX TLS inherits from TLS the overall manner of the protocol implementation including among others the standard division into the frames (CHANGE_CIPHER_SPEC, ALERT, HANDSHAKE, APPLICATION_DATA) and handshake procedures.

The PrivMX TLS protocol, in addition to creating and maintaining connection sessions, and encrypting of data sent to both sides, also provides a mechanism for users’ logging in and controlling the sessions for logged users. The characteristic features of PrivMX TLS are:

  • operation on any transport (also non-duplex), in the request-response schema.
  • Sessions control and their resuming based on the utilization of tickets lists used as a nonce – this means the lack of sending the fixed session ID and preventing observers from grouping frames. This is a different use of tickets than it is described in RFC 5077.
  • Simplified handshake procedures, which, among others, do not negotiate encryption algorithms.
  • Two levels of connection security:
    • standard – available to all clients. Connection security is achieved by using a common secret received from a handshake procedure utilizing ECDHE (or ECDH when the client has an authorized public key of the server).
    • logged in – the level available to the account holders on a given server. Logging into PrivMX is a procedure in which a client after the initial establishing of a "standard connection" asks the server for additional handshake procedure based on SRP-protocol. The PrivMX TLS module here, has access to the data stored on the server in the course of creating a user account.
  • Once a connection has been established, each party may at any time force a change of the connection encryption keys.

PrivMX provides clients with different sets of API methods depending on the PrivMX TLS connection level used. This topic is often referred to in the following chapters, when describing API methods.

PrivMX Proxy

PrivMX provides the API.proxy method, which allows the client programs to use "their own" server module as an intermediary in connections with other PrivMX servers. The operation of this service can be configured as needed. In particular, it depends on the manner of implementation of the client’s application whether and how it uses such a possibility.

Establishing PrivMX TLS connections with a "foreign" server via PrivMX Proxy service does not interfere with the security of connections. Encryption keys are set (handshake) with the target server in such a way that the proxy server does not have access to them.

Next: PrivMX server – ECC keys as identifiers and access rights, data blocks, descriptors, mailboxes, messages, public and private users’ data.
TOC: PrivMX Architecture
PDF version: PrivMX Architecture – whitepaper (pdf)