Efim Poberezkin
GitHub
parent
eb44fb24e8
commit
822c9bbd3a
@ -1,331 +0,0 @@
|
||||
# SMP agent protocol - duplex communication over SMP protocol
|
||||
|
||||
## Table of contents
|
||||
|
||||
- [Abstract](#abstract)
|
||||
- [SMP agent](#smp-agent)
|
||||
- [SMP agent protocol components](#smp-agent-protocol-components)
|
||||
- [Duplex connection procedure](#duplex-connection-procedure)
|
||||
- [Communication between SMP agents](#communication-between-smp-agents)
|
||||
- [Message syntax](#messages-between-smp-agents)
|
||||
- [HELLO message](#hello-message)
|
||||
- [REPLY message](#reply-message)
|
||||
- [MSG message](#msg-message)
|
||||
- [SMP agent commands](#smp-agent-commands)
|
||||
- [Client commands and server responses](#client-commands-and-server-responses)
|
||||
- [NEW command and INV response](#new-command-and-inv-response)
|
||||
- [JOIN command](#join-command)
|
||||
- [CON notification](#con-notification)
|
||||
- [SUB command](#sub-command)
|
||||
- [SEND command and SENT response](#send-command-and-sent-response)
|
||||
- [MSG notification](#msg-notification)
|
||||
- [END notification](#end-notification)
|
||||
- [OFF command](#off-command)
|
||||
- [DEL command](#del-command)
|
||||
- [Connection invitation](#connection-invitation)
|
||||
|
||||
## Abstract
|
||||
|
||||
The purpose of SMP agent protocol is to define the syntax and the semantics of communications between the client and the agent that connects to [SMP](./simplex-messaging.md) servers.
|
||||
|
||||
It provides:
|
||||
- convenient protocol to create and manage a bi-directional (duplex) connection to the users of SMP agents consisting of two separate unidirectional (simplex) SMP queues, abstracting away multiple steps required to establish bi-directional connections.
|
||||
- management of E2E encryption between SMP agents, generating ephemeral RSA keys for each connection.
|
||||
- SMP command authentication on SMP servers, generating ephemeral RSA keys for each SMP queue.
|
||||
- TCP transport handshake and encryption with SMP servers.
|
||||
- validation of message integrity.
|
||||
|
||||
SMP agent protocols provides no encryption or any security on the client side - it is assumed that the agent is executed in the trusted and secure environment.
|
||||
|
||||
The future versions of this protocol could provide:
|
||||
- managing redundant SMP queues with more than 1 queue in each direction.
|
||||
- managing simple symmetric groups as a foundation for chat groups and device synchronization.
|
||||
- agent cluster - synchronizing states of multiple agents.
|
||||
- secure "synchronous" streams with symmetric message encryption and connection-level authentication (requires extending [SMP protocol](./simplex-messaging.md)) - it can be used, e.g., for file transfers.
|
||||
|
||||
## SMP agent
|
||||
|
||||
SMP agent is a client-side process or library that communicates via SMP servers using [simplex messaging protocol (SMP)](./simplex-messaging.md) with other SMP agents according to the commands received from its users. This protocol is a middle layer in SMP protocols stack (above SMP protocol but below any application level protocol) - it is intended to be used by client-side applications that need secure asynchronous bi-directional communication channels ("connections").
|
||||
|
||||
The agent must have a persistent storage to manage the states of known connections and of the client-side information of two SMP queues that each connection consists of, and also the buffer of the most recent messages. The number of the messages that should be stored is implementation specific, depending on the error management approach that the agent implements; at the very least the agent must store the hash and id of the last received message.
|
||||
|
||||
## SMP agent protocol components
|
||||
|
||||
SMP agent protocol has 3 main parts:
|
||||
|
||||
- the syntax and semantics of messages that SMP agents exchange between each other in order to:
|
||||
- negotiate establishing unidirectional (simplex) encrypted queues on SMP server(s)
|
||||
- exchange client messages and delivery notifications, providing sequential message IDs and message integrity (by including the hash of the previous message).
|
||||
- the syntax and semantics of the commands (a higher level interface than SMP protocol) that are sent over TCP or other sequential protocol by agent clients to the agents. This protocol allows to create and manage multiple connections, each consisting of two simplex SMP queues.
|
||||
- the syntax and semantics of the message that the clients of SMP agents should send out-of-band (as pre-shared "invitation" including SMP server, queue ID and encryption key) to ensure [E2E encryption][1] the integrity of SMP queues and protection against active attacks ([MITM attacks][2]).
|
||||
|
||||
## Duplex connection procedure
|
||||
|
||||
|
||||
|
||||
The procedure of establishing a duplex connection is explained on the example of Alice and Bob creating a bi-directional connection comprised of two unidirectional (simplex) queues, using SMP agents (A and B) to facilitate it, and two different SMP servers (which could be the same server). It is shown on the diagram above and has these steps:
|
||||
|
||||
1. Alice requests the new connection from the SMP agent A using `NEW` command.
|
||||
2. Agent A creates an SMP queue on the server (using [SMP protocol](./simplex-messaging.md)) and responds to Alice with the invitation that contains queue information and the encryption key Bob's agent B should use. The invitation format is described in [Connection invitation](#connection-invitation).
|
||||
3. Alice sends the invitation to Bob via any secure channel they have (out-of-band message).
|
||||
4. Bob sends `JOIN` command with the invitation as a parameter to agent B to accept the connection.
|
||||
5. Establishing Alice's SMP queue (with SMP protocol commands):
|
||||
- Agent B sends unauthenticated message to SMP queue with ephemeral key that will be used to authenticate commands to the queue, as described in SMP protocol.
|
||||
- Agent A receives the KEY and secures the queue.
|
||||
- Agent B tries sending authenticated SMP SEND command with agent `HELLO` message until it succeeds. Once it succeeds, Bob's agent "knows" the queue is secured.
|
||||
6. Agent B creates a new SMP queue on the server.
|
||||
7. Establish Bob's SMP queue:
|
||||
- Agent B sends `REPLY` message with the invitation to this 2nd queue to Alice's agent (via the 1st queue).
|
||||
- Agent A having received this `REPLY` message sends unauthenticated message to SMP queue with Alice agent's ephemeral key that will be used to authenticate commands to the queue, as described in SMP protocol.
|
||||
- Bob's agent receives the key and secures the queue.
|
||||
- Alice's agent keeps sending `HELLO` message until it succeeds.
|
||||
8. Agents A and B notify Alice and Bob that connection is established.
|
||||
- Once sending `HELLO` succeeds, Alice's agent sends to Alice `CON` notification that confirms that now both parties can communicate.
|
||||
- Once Bob's agent receives `HELLO` from Alice's agent, it sends to Bob `CON` notification as well.
|
||||
|
||||
At this point the duplex connection between Alice and Bob is established, they can use `SEND` command to send messages. The diagram also shows how the connection status changes for both parties, where the first part is the status of the SMP queue to receive messages, and the second part - the status of the queue to send messages.
|
||||
|
||||
The most communication happens between the agents and servers, from the point of view of Alice and Bob they have only 3 steps to do:
|
||||
|
||||
1. Alice requests a new connection with `NEW` command and receives the invitation.
|
||||
2. Alice passes invitation out-of-band to Bob.
|
||||
3. Bob accepts the connection by sending `JOIN` command with the invitation to his agent.
|
||||
|
||||
## Communication between SMP agents
|
||||
|
||||
SMP agents communicate via SMP servers managing creation, deletion and operations of SMP queues.
|
||||
|
||||
Agents can use SMP message client body (the part of the SMP message after header - see [SMP protocol](./simplex-messaging.md)) to transmit agent client messages and exchange messages between each other.
|
||||
|
||||
Each SMP message client body, once decrypted, contains 3 parts (one of them may include binary message body), as defined by `decryptedSmpMessageBody` syntax:
|
||||
|
||||
- `agentMsgHeader` - agent message header that contains sequential agent message ID for a particular SMP queue, agent timestamp (ISO8601) and the hash of the previous message.
|
||||
- `agentMessage` - a command/message to the other SMP agent:
|
||||
- to establish the connection with two SMP queues (`helloMsg`, `replyQueueMsg`)
|
||||
- to send and to acknowledge user messages (`clientMsg`, `acknowledgeMsg`)
|
||||
- to notify another agent about queue deletion (`deleteQueueMsg`)
|
||||
- `msgPadding` - an optional message padding to make all SMP messages have consistent size as an additional privacy protection measure.
|
||||
|
||||
### Messages between SMP agents
|
||||
|
||||
Message syntax below uses [ABNF][3] with [case-sensitive strings extension][4].
|
||||
|
||||
```abnf
|
||||
decryptedSmpMessageBody = agentMsgHeader CRLF agentMessage CRLF msgPadding
|
||||
agentMsgHeader = agentMsgId SP agentTimestamp SP previousMsgHash
|
||||
agentMsgId = 1*DIGIT ; sequential agent message ID set by the sending agent
|
||||
|
||||
agentMessage = helloMsg / replyQueueMsg / deleteQueueMsg
|
||||
/ clientMsg / acknowledgeMsg
|
||||
|
||||
msgPadding = *OCTET ; optional random bytes to get messages to the same size (as defined in SMP message size)
|
||||
|
||||
helloMsg = %s"HELLO" SP signatureVerificationKey [SP %s"NO_ACK"]
|
||||
; NO_ACK means that acknowledgements to client messages will NOT be sent in this connection by the agent that sent `HELLO` message.
|
||||
signatureVerificationKey = encoded ; base64 encoded
|
||||
|
||||
replyQueueMsg = %s"REPLY" SP qInfo ; `qInfo` is the same as in out-of-band message
|
||||
; this message can only be sent by the second connection party
|
||||
|
||||
deleteQueueMsg = %s"DEL" ; notification that recipient queue will be deleted
|
||||
; no need to notify the other party about suspending queue separately, as suspended and deleted queues are the same to the sender
|
||||
; NOT SUPPORTED with the current implementation
|
||||
|
||||
clientMsg = %s"MSG" SP size CRLF clientMsgBody CRLF ; CRLF is in addition to CRLF in decryptedSmpMessageBody
|
||||
size = 1*DIGIT
|
||||
clientMsgBody = *OCTET
|
||||
|
||||
acknowledgeMsg = %s"ACK" SP agentMsgId SP ackStatus
|
||||
; NOT SUPPORTED with the current implementation
|
||||
|
||||
ackStatus = %s"OK" / ackError
|
||||
|
||||
ackError = %s"ERR" SP ackErrorType
|
||||
|
||||
ackErrorType = ackUnknownMsg / ackProhibitedMsg / ackSyntaxErr
|
||||
|
||||
ackUnknownMsg = %s"UNKNOWN"
|
||||
|
||||
ackProhibitedMsg = %"PROHIBITED" ; e.g. "HELLO" or "REPLY"
|
||||
|
||||
ackSyntaxErr = %"SYNTAX" SP syntaxErrCode
|
||||
syntaxErrCode = 1*DIGIT ; TODO
|
||||
```
|
||||
|
||||
#### HELLO message
|
||||
|
||||
This is the first message that both agents send after the respective SMP queue is secured by the receiving agent (see diagram). It contains the verification key that the sender will use to cryptographically sign the messages.
|
||||
|
||||
Sending agent might need to retry sending HELLO message, as it would not have any other confirmation that the queue is secured other than the success of sending this message with the signed SEND command of SMP protocol.
|
||||
|
||||
#### REPLY message
|
||||
|
||||
This is the message that is sent by the agent that received an out-of-band invitation to pass the invitation to the reply SMP queue to the agent that originated the connection (see diagram).
|
||||
|
||||
#### MSG message
|
||||
|
||||
This is the agent envelope used to send client messages once the connection is established. Do not confuse it with the MSG response from SMP server to the agent and MSG response from SMP agent to the client that are sent in different contexts.
|
||||
|
||||
## SMP agent commands
|
||||
|
||||
This part describes the transmissions between users and client-side SMP agents: commands that the users send to create and operate duplex connections and SMP agent responses and messages they deliver.
|
||||
|
||||
Commands syntax below is provided using [ABNF][3] with [case-sensitive strings extension][4].
|
||||
|
||||
Each transmission between the user and SMP agent must have this format/syntax:
|
||||
|
||||
```abnf
|
||||
agentTransmission = [corrId] CRLF [cAlias] CRLF agentCommand
|
||||
|
||||
corrId = 1*(%x21-7F) ; any characters other than control/whitespace
|
||||
|
||||
cAlias = cId / cName
|
||||
cId = encoded
|
||||
cName = 1*(ALPHA / DIGIT / "_" / "-")
|
||||
|
||||
agentCommand = (userCmd / agentMsg) CRLF
|
||||
userCmd = newCmd / joinCmd
|
||||
/ acceptCmd / subscribeCmd
|
||||
/ sendCmd / acknowledgeCmd
|
||||
/ suspendCmd / deleteCmd
|
||||
|
||||
agentMsg = invitation / confirmation
|
||||
/ connected / unsubscribed
|
||||
/ message / sent / received
|
||||
/ ok / error
|
||||
|
||||
newCmd = %s"NEW" SP smpServer [SP %s"NO_ACK"]
|
||||
; response is `invitation` or `error`
|
||||
smpServer = srvHost [":" port] ["#" keyFingerprint]
|
||||
srvHost = hostname ; RFC1123, RFC5891
|
||||
port = 1*DIGIT
|
||||
keyFingerprint = encoded
|
||||
|
||||
invitation = %s"INV" SP qInfo
|
||||
|
||||
connected = %s"CON"
|
||||
|
||||
subscribeCmd = %s"SUB" ; response is `ok` or `error`
|
||||
|
||||
unsubscribed = %s"END"
|
||||
; when another agent (or another client of the same agent)
|
||||
; subscribes to the same SMP queue on the server
|
||||
|
||||
joinCmd = %s"JOIN" SP qInfo
|
||||
[SP (smpServer / %s"NO_REPLY")] ; reply queue SMP server
|
||||
; server from qInfo is used by default
|
||||
[SP %s"NO_ACK"]
|
||||
; response is `connected` or `error`
|
||||
|
||||
confirmation = %s"CONF" SP partyId SP partyInfo
|
||||
; currently not implemented
|
||||
|
||||
acceptCmd = %s"LET" SP partyId ; response is `ok` or `error`
|
||||
; currently not implemented
|
||||
|
||||
suspendCmd = %s"OFF" ; can be sent by either party, response `ok` or `error`
|
||||
|
||||
deleteCmd = %s"DEL" ; can be sent by either party, response `ok` or `error`
|
||||
|
||||
sendCmd = %s"SEND" SP msgBody
|
||||
; send syntax is similar to that of SMP protocol, but it is wrapped in SMP message
|
||||
msgBody = stringMsg | binaryMsg
|
||||
stringMsg = ":" string ; until CRLF in the transmission
|
||||
string = *(%x01-09 / %x0B-0C / %x0E-FF %) ; any characters other than NUL, CR and LF
|
||||
binaryMsg = size CRLF msgBody CRLF ; the last CRLF is in addition to CRLF in the transmission
|
||||
size = 1*DIGIT ; size in bytes
|
||||
msgBody = *OCTET ; any content of specified size - safe for binary
|
||||
|
||||
sent = %s"SENT" SP agentMsgId
|
||||
|
||||
message = %s"MSG" SP msgIntegrity
|
||||
SP %s"R=" agentMsgId "," agentTimestamp ; receiving agent
|
||||
SP %s"B=" brokerMsgId "," srvTimestamp ; broker (server)
|
||||
SP %s"S=" agentMsgId "," agentTimestamp ; sending agent
|
||||
SP binaryMsg
|
||||
agentMsgId = 1*DIGIT
|
||||
srvTimestamp = date-time ; RFC3339
|
||||
agentTimestamp = date-time
|
||||
msgIntegrity = ok / messageError
|
||||
|
||||
messageError = %s"ERR" SP messageErrorType
|
||||
messageErrorType = skippedMsgErr / badMsgIdErr / badHashErr
|
||||
|
||||
skippedMsgErr = %"IDS" SP missingFromMsgId SP missingToMsgId
|
||||
badMsgIdErr = %"ID" SP previousMsgId ; ID is lower than the previous
|
||||
badHashErr = %"HASH"
|
||||
|
||||
acknowledge = %s"ACK" SP agentMsgId ; ID assigned by receiving agent (in MSG "R")
|
||||
; currently not implemented
|
||||
|
||||
received = %s"RCVD" SP agentMsgId ; ID assigned by sending agent (in SENT response)
|
||||
; currently not implemented
|
||||
|
||||
ok = %s"OK"
|
||||
|
||||
error = %s"ERR" SP errorType
|
||||
|
||||
encoded = base64
|
||||
```
|
||||
|
||||
### Client commands and server responses
|
||||
|
||||
#### NEW command and INV response
|
||||
|
||||
`NEW` command is used to create a connection and an invitation to be sent out-of-band to another protocol user. It should be used by the client of the agent that initiates creating a duplex connection.
|
||||
|
||||
`INV` response is sent by the agent to the client.
|
||||
|
||||
#### JOIN command
|
||||
|
||||
It is used to create a connection and accept the invitation received out-of-band. It should be used by the client of the agent that accepts the connection.
|
||||
|
||||
#### CON notification
|
||||
|
||||
It is sent by both agents managing duplex connection to their clients once the connection is established and ready to accept client messages.
|
||||
|
||||
#### SUB command
|
||||
|
||||
This command can be used by the client to resume receiving messages from the connection that was created in another TCP/client session. Agent response to this command can be `OK` or `ERR` in case connection does not exist (or can only be used to send connections - e.g. when the reply queue was not created).
|
||||
|
||||
#### SEND command and SENT response
|
||||
|
||||
`SEND` command is used to the client to send messages
|
||||
|
||||
`SENT` response is sent by the agent to confirm that the message was delivered to the SMP server. Message ID in this response is the sequential message number that includes both sent and received messages in the connection.
|
||||
|
||||
#### MSG notification
|
||||
|
||||
It is sent by the agent to the client when agent receives the message from the SMP server. It has message ID and timestamp from both the receiving and sending agents and from SMP server:
|
||||
- recipient agent ID is intended to be used to refer to the message in the future.
|
||||
- sender agent ID is intended to be used to identify any missed / skipped message(s)
|
||||
- broker ID should be used to detect duplicate deliveries (it would happen if TCP connection is lost before the message is acknowledged by the agent - see [SMP protocol](./simplex-messaging.md))
|
||||
|
||||
#### END notification
|
||||
|
||||
It is sent by the agent to the client when agent receives SMP protocol `END` notification from SMP server. It indicates that another agent has subscribed to the same SMP queue on the server and the server terminated the subscription of the current agent.
|
||||
|
||||
#### OFF command
|
||||
|
||||
It is used to suspend the receiving SMP queue - sender will no longer be able to send the messages to the connection, but the recipient can retrieve the remaining messages. Agent response to this command can be `OK` or `ERR`. This command is irreversible.
|
||||
|
||||
#### DEL command
|
||||
|
||||
It is used to delete the connection and all messages in it, as well as the receiving SMP queue and all messages in it that were remaining on the server. Agent response to this command can be `OK` or `ERR`. This command is irreversible.
|
||||
|
||||
## Connection invitation
|
||||
|
||||
Connection invitation `qInfo` is generated by SMP agent in response to `newCmd` command (`"NEW"`), used by another party user with `joinCmd` command (`"JOIN"`), and then another invitation is sent by the agent in `replyQueueMsg` and used by the first party agent to connect to the reply queue (the second part of the process is invisible to the users).
|
||||
|
||||
Connection invitation is a text with the following syntax:
|
||||
|
||||
```
|
||||
qInfo = %s"smp::" smpServer "::" queueId "::" ephemeralPublicKey
|
||||
queueId = encoded
|
||||
ephemeralPublicKey = %s"rsa:" encoded ; RSA key for sender to encrypt messages X509 base64 encoded
|
||||
```
|
||||
|
||||
[1]: https://en.wikipedia.org/wiki/End-to-end_encryption
|
||||
[2]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack
|
||||
[3]: https://tools.ietf.org/html/rfc5234
|
||||
[4]: https://tools.ietf.org/html/rfc7405
|
||||
@ -1,661 +0,0 @@
|
||||
GNU AFFERO GENERAL PUBLIC LICENSE
|
||||
Version 3, 19 November 2007
|
||||
|
||||
Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
|
||||
Everyone is permitted to copy and distribute verbatim copies
|
||||
of this license document, but changing it is not allowed.
|
||||
|
||||
Preamble
|
||||
|
||||
The GNU Affero General Public License is a free, copyleft license for
|
||||
software and other kinds of works, specifically designed to ensure
|
||||
cooperation with the community in the case of network server software.
|
||||
|
||||
The licenses for most software and other practical works are designed
|
||||
to take away your freedom to share and change the works. By contrast,
|
||||
our General Public Licenses are intended to guarantee your freedom to
|
||||
share and change all versions of a program--to make sure it remains free
|
||||
software for all its users.
|
||||
|
||||
When we speak of free software, we are referring to freedom, not
|
||||
price. Our General Public Licenses are designed to make sure that you
|
||||
have the freedom to distribute copies of free software (and charge for
|
||||
them if you wish), that you receive source code or can get it if you
|
||||
want it, that you can change the software or use pieces of it in new
|
||||
free programs, and that you know you can do these things.
|
||||
|
||||
Developers that use our General Public Licenses protect your rights
|
||||
with two steps: (1) assert copyright on the software, and (2) offer
|
||||
you this License which gives you legal permission to copy, distribute
|
||||
and/or modify the software.
|
||||
|
||||
A secondary benefit of defending all users' freedom is that
|
||||
improvements made in alternate versions of the program, if they
|
||||
receive widespread use, become available for other developers to
|
||||
incorporate. Many developers of free software are heartened and
|
||||
encouraged by the resulting cooperation. However, in the case of
|
||||
software used on network servers, this result may fail to come about.
|
||||
The GNU General Public License permits making a modified version and
|
||||
letting the public access it on a server without ever releasing its
|
||||
source code to the public.
|
||||
|
||||
The GNU Affero General Public License is designed specifically to
|
||||
ensure that, in such cases, the modified source code becomes available
|
||||
to the community. It requires the operator of a network server to
|
||||
provide the source code of the modified version running there to the
|
||||
users of that server. Therefore, public use of a modified version, on
|
||||
a publicly accessible server, gives the public access to the source
|
||||
code of the modified version.
|
||||
|
||||
An older license, called the Affero General Public License and
|
||||
published by Affero, was designed to accomplish similar goals. This is
|
||||
a different license, not a version of the Affero GPL, but Affero has
|
||||
released a new version of the Affero GPL which permits relicensing under
|
||||
this license.
|
||||
|
||||
The precise terms and conditions for copying, distribution and
|
||||
modification follow.
|
||||
|
||||
TERMS AND CONDITIONS
|
||||
|
||||
0. Definitions.
|
||||
|
||||
"This License" refers to version 3 of the GNU Affero General Public License.
|
||||
|
||||
"Copyright" also means copyright-like laws that apply to other kinds of
|
||||
works, such as semiconductor masks.
|
||||
|
||||
"The Program" refers to any copyrightable work licensed under this
|
||||
License. Each licensee is addressed as "you". "Licensees" and
|
||||
"recipients" may be individuals or organizations.
|
||||
|
||||
To "modify" a work means to copy from or adapt all or part of the work
|
||||
in a fashion requiring copyright permission, other than the making of an
|
||||
exact copy. The resulting work is called a "modified version" of the
|
||||
earlier work or a work "based on" the earlier work.
|
||||
|
||||
A "covered work" means either the unmodified Program or a work based
|
||||
on the Program.
|
||||
|
||||
To "propagate" a work means to do anything with it that, without
|
||||
permission, would make you directly or secondarily liable for
|
||||
infringement under applicable copyright law, except executing it on a
|
||||
computer or modifying a private copy. Propagation includes copying,
|
||||
distribution (with or without modification), making available to the
|
||||
public, and in some countries other activities as well.
|
||||
|
||||
To "convey" a work means any kind of propagation that enables other
|
||||
parties to make or receive copies. Mere interaction with a user through
|
||||
a computer network, with no transfer of a copy, is not conveying.
|
||||
|
||||
An interactive user interface displays "Appropriate Legal Notices"
|
||||
to the extent that it includes a convenient and prominently visible
|
||||
feature that (1) displays an appropriate copyright notice, and (2)
|
||||
tells the user that there is no warranty for the work (except to the
|
||||
extent that warranties are provided), that licensees may convey the
|
||||
work under this License, and how to view a copy of this License. If
|
||||
the interface presents a list of user commands or options, such as a
|
||||
menu, a prominent item in the list meets this criterion.
|
||||
|
||||
1. Source Code.
|
||||
|
||||
The "source code" for a work means the preferred form of the work
|
||||
for making modifications to it. "Object code" means any non-source
|
||||
form of a work.
|
||||
|
||||
A "Standard Interface" means an interface that either is an official
|
||||
standard defined by a recognized standards body, or, in the case of
|
||||
interfaces specified for a particular programming language, one that
|
||||
is widely used among developers working in that language.
|
||||
|
||||
The "System Libraries" of an executable work include anything, other
|
||||
than the work as a whole, that (a) is included in the normal form of
|
||||
packaging a Major Component, but which is not part of that Major
|
||||
Component, and (b) serves only to enable use of the work with that
|
||||
Major Component, or to implement a Standard Interface for which an
|
||||
implementation is available to the public in source code form. A
|
||||
"Major Component", in this context, means a major essential component
|
||||
(kernel, window system, and so on) of the specific operating system
|
||||
(if any) on which the executable work runs, or a compiler used to
|
||||
produce the work, or an object code interpreter used to run it.
|
||||
|
||||
The "Corresponding Source" for a work in object code form means all
|
||||
the source code needed to generate, install, and (for an executable
|
||||
work) run the object code and to modify the work, including scripts to
|
||||
control those activities. However, it does not include the work's
|
||||
System Libraries, or general-purpose tools or generally available free
|
||||
programs which are used unmodified in performing those activities but
|
||||
which are not part of the work. For example, Corresponding Source
|
||||
includes interface definition files associated with source files for
|
||||
the work, and the source code for shared libraries and dynamically
|
||||
linked subprograms that the work is specifically designed to require,
|
||||
such as by intimate data communication or control flow between those
|
||||
subprograms and other parts of the work.
|
||||
|
||||
The Corresponding Source need not include anything that users
|
||||
can regenerate automatically from other parts of the Corresponding
|
||||
Source.
|
||||
|
||||
The Corresponding Source for a work in source code form is that
|
||||
same work.
|
||||
|
||||
2. Basic Permissions.
|
||||
|
||||
All rights granted under this License are granted for the term of
|
||||
copyright on the Program, and are irrevocable provided the stated
|
||||
conditions are met. This License explicitly affirms your unlimited
|
||||
permission to run the unmodified Program. The output from running a
|
||||
covered work is covered by this License only if the output, given its
|
||||
content, constitutes a covered work. This License acknowledges your
|
||||
rights of fair use or other equivalent, as provided by copyright law.
|
||||
|
||||
You may make, run and propagate covered works that you do not
|
||||
convey, without conditions so long as your license otherwise remains
|
||||
in force. You may convey covered works to others for the sole purpose
|
||||
of having them make modifications exclusively for you, or provide you
|
||||
with facilities for running those works, provided that you comply with
|
||||
the terms of this License in conveying all material for which you do
|
||||
not control copyright. Those thus making or running the covered works
|
||||
for you must do so exclusively on your behalf, under your direction
|
||||
and control, on terms that prohibit them from making any copies of
|
||||
your copyrighted material outside their relationship with you.
|
||||
|
||||
Conveying under any other circumstances is permitted solely under
|
||||
the conditions stated below. Sublicensing is not allowed; section 10
|
||||
makes it unnecessary.
|
||||
|
||||
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
|
||||
|
||||
No covered work shall be deemed part of an effective technological
|
||||
measure under any applicable law fulfilling obligations under article
|
||||
11 of the WIPO copyright treaty adopted on 20 December 1996, or
|
||||
similar laws prohibiting or restricting circumvention of such
|
||||
measures.
|
||||
|
||||
When you convey a covered work, you waive any legal power to forbid
|
||||
circumvention of technological measures to the extent such circumvention
|
||||
is effected by exercising rights under this License with respect to
|
||||
the covered work, and you disclaim any intention to limit operation or
|
||||
modification of the work as a means of enforcing, against the work's
|
||||
users, your or third parties' legal rights to forbid circumvention of
|
||||
technological measures.
|
||||
|
||||
4. Conveying Verbatim Copies.
|
||||
|
||||
You may convey verbatim copies of the Program's source code as you
|
||||
receive it, in any medium, provided that you conspicuously and
|
||||
appropriately publish on each copy an appropriate copyright notice;
|
||||
keep intact all notices stating that this License and any
|
||||
non-permissive terms added in accord with section 7 apply to the code;
|
||||
keep intact all notices of the absence of any warranty; and give all
|
||||
recipients a copy of this License along with the Program.
|
||||
|
||||
You may charge any price or no price for each copy that you convey,
|
||||
and you may offer support or warranty protection for a fee.
|
||||
|
||||
5. Conveying Modified Source Versions.
|
||||
|
||||
You may convey a work based on the Program, or the modifications to
|
||||
produce it from the Program, in the form of source code under the
|
||||
terms of section 4, provided that you also meet all of these conditions:
|
||||
|
||||
a) The work must carry prominent notices stating that you modified
|
||||
it, and giving a relevant date.
|
||||
|
||||
b) The work must carry prominent notices stating that it is
|
||||
released under this License and any conditions added under section
|
||||
7. This requirement modifies the requirement in section 4 to
|
||||
"keep intact all notices".
|
||||
|
||||
c) You must license the entire work, as a whole, under this
|
||||
License to anyone who comes into possession of a copy. This
|
||||
License will therefore apply, along with any applicable section 7
|
||||
additional terms, to the whole of the work, and all its parts,
|
||||
regardless of how they are packaged. This License gives no
|
||||
permission to license the work in any other way, but it does not
|
||||
invalidate such permission if you have separately received it.
|
||||
|
||||
d) If the work has interactive user interfaces, each must display
|
||||
Appropriate Legal Notices; however, if the Program has interactive
|
||||
interfaces that do not display Appropriate Legal Notices, your
|
||||
work need not make them do so.
|
||||
|
||||
A compilation of a covered work with other separate and independent
|
||||
works, which are not by their nature extensions of the covered work,
|
||||
and which are not combined with it such as to form a larger program,
|
||||
in or on a volume of a storage or distribution medium, is called an
|
||||
"aggregate" if the compilation and its resulting copyright are not
|
||||
used to limit the access or legal rights of the compilation's users
|
||||
beyond what the individual works permit. Inclusion of a covered work
|
||||
in an aggregate does not cause this License to apply to the other
|
||||
parts of the aggregate.
|
||||
|
||||
6. Conveying Non-Source Forms.
|
||||
|
||||
You may convey a covered work in object code form under the terms
|
||||
of sections 4 and 5, provided that you also convey the
|
||||
machine-readable Corresponding Source under the terms of this License,
|
||||
in one of these ways:
|
||||
|
||||
a) Convey the object code in, or embodied in, a physical product
|
||||
(including a physical distribution medium), accompanied by the
|
||||
Corresponding Source fixed on a durable physical medium
|
||||
customarily used for software interchange.
|
||||
|
||||
b) Convey the object code in, or embodied in, a physical product
|
||||
(including a physical distribution medium), accompanied by a
|
||||
written offer, valid for at least three years and valid for as
|
||||
long as you offer spare parts or customer support for that product
|
||||
model, to give anyone who possesses the object code either (1) a
|
||||
copy of the Corresponding Source for all the software in the
|
||||
product that is covered by this License, on a durable physical
|
||||
medium customarily used for software interchange, for a price no
|
||||
more than your reasonable cost of physically performing this
|
||||
conveying of source, or (2) access to copy the
|
||||
Corresponding Source from a network server at no charge.
|
||||
|
||||
c) Convey individual copies of the object code with a copy of the
|
||||
written offer to provide the Corresponding Source. This
|
||||
alternative is allowed only occasionally and noncommercially, and
|
||||
only if you received the object code with such an offer, in accord
|
||||
with subsection 6b.
|
||||
|
||||
d) Convey the object code by offering access from a designated
|
||||
place (gratis or for a charge), and offer equivalent access to the
|
||||
Corresponding Source in the same way through the same place at no
|
||||
further charge. You need not require recipients to copy the
|
||||
Corresponding Source along with the object code. If the place to
|
||||
copy the object code is a network server, the Corresponding Source
|
||||
may be on a different server (operated by you or a third party)
|
||||
that supports equivalent copying facilities, provided you maintain
|
||||
clear directions next to the object code saying where to find the
|
||||
Corresponding Source. Regardless of what server hosts the
|
||||
Corresponding Source, you remain obligated to ensure that it is
|
||||
available for as long as needed to satisfy these requirements.
|
||||
|
||||
e) Convey the object code using peer-to-peer transmission, provided
|
||||
you inform other peers where the object code and Corresponding
|
||||
Source of the work are being offered to the general public at no
|
||||
charge under subsection 6d.
|
||||
|
||||
A separable portion of the object code, whose source code is excluded
|
||||
from the Corresponding Source as a System Library, need not be
|
||||
included in conveying the object code work.
|
||||
|
||||
A "User Product" is either (1) a "consumer product", which means any
|
||||
tangible personal property which is normally used for personal, family,
|
||||
or household purposes, or (2) anything designed or sold for incorporation
|
||||
into a dwelling. In determining whether a product is a consumer product,
|
||||
doubtful cases shall be resolved in favor of coverage. For a particular
|
||||
product received by a particular user, "normally used" refers to a
|
||||
typical or common use of that class of product, regardless of the status
|
||||
of the particular user or of the way in which the particular user
|
||||
actually uses, or expects or is expected to use, the product. A product
|
||||
is a consumer product regardless of whether the product has substantial
|
||||
commercial, industrial or non-consumer uses, unless such uses represent
|
||||
the only significant mode of use of the product.
|
||||
|
||||
"Installation Information" for a User Product means any methods,
|
||||
procedures, authorization keys, or other information required to install
|
||||
and execute modified versions of a covered work in that User Product from
|
||||
a modified version of its Corresponding Source. The information must
|
||||
suffice to ensure that the continued functioning of the modified object
|
||||
code is in no case prevented or interfered with solely because
|
||||
modification has been made.
|
||||
|
||||
If you convey an object code work under this section in, or with, or
|
||||
specifically for use in, a User Product, and the conveying occurs as
|
||||
part of a transaction in which the right of possession and use of the
|
||||
User Product is transferred to the recipient in perpetuity or for a
|
||||
fixed term (regardless of how the transaction is characterized), the
|
||||
Corresponding Source conveyed under this section must be accompanied
|
||||
by the Installation Information. But this requirement does not apply
|
||||
if neither you nor any third party retains the ability to install
|
||||
modified object code on the User Product (for example, the work has
|
||||
been installed in ROM).
|
||||
|
||||
The requirement to provide Installation Information does not include a
|
||||
requirement to continue to provide support service, warranty, or updates
|
||||
for a work that has been modified or installed by the recipient, or for
|
||||
the User Product in which it has been modified or installed. Access to a
|
||||
network may be denied when the modification itself materially and
|
||||
adversely affects the operation of the network or violates the rules and
|
||||
protocols for communication across the network.
|
||||
|
||||
Corresponding Source conveyed, and Installation Information provided,
|
||||
in accord with this section must be in a format that is publicly
|
||||
documented (and with an implementation available to the public in
|
||||
source code form), and must require no special password or key for
|
||||
unpacking, reading or copying.
|
||||
|
||||
7. Additional Terms.
|
||||
|
||||
"Additional permissions" are terms that supplement the terms of this
|
||||
License by making exceptions from one or more of its conditions.
|
||||
Additional permissions that are applicable to the entire Program shall
|
||||
be treated as though they were included in this License, to the extent
|
||||
that they are valid under applicable law. If additional permissions
|
||||
apply only to part of the Program, that part may be used separately
|
||||
under those permissions, but the entire Program remains governed by
|
||||
this License without regard to the additional permissions.
|
||||
|
||||
When you convey a copy of a covered work, you may at your option
|
||||
remove any additional permissions from that copy, or from any part of
|
||||
it. (Additional permissions may be written to require their own
|
||||
removal in certain cases when you modify the work.) You may place
|
||||
additional permissions on material, added by you to a covered work,
|
||||
for which you have or can give appropriate copyright permission.
|
||||
|
||||
Notwithstanding any other provision of this License, for material you
|
||||
add to a covered work, you may (if authorized by the copyright holders of
|
||||
that material) supplement the terms of this License with terms:
|
||||
|
||||
a) Disclaiming warranty or limiting liability differently from the
|
||||
terms of sections 15 and 16 of this License; or
|
||||
|
||||
b) Requiring preservation of specified reasonable legal notices or
|
||||
author attributions in that material or in the Appropriate Legal
|
||||
Notices displayed by works containing it; or
|
||||
|
||||
c) Prohibiting misrepresentation of the origin of that material, or
|
||||
requiring that modified versions of such material be marked in
|
||||
reasonable ways as different from the original version; or
|
||||
|
||||
d) Limiting the use for publicity purposes of names of licensors or
|
||||
authors of the material; or
|
||||
|
||||
e) Declining to grant rights under trademark law for use of some
|
||||
trade names, trademarks, or service marks; or
|
||||
|
||||
f) Requiring indemnification of licensors and authors of that
|
||||
material by anyone who conveys the material (or modified versions of
|
||||
it) with contractual assumptions of liability to the recipient, for
|
||||
any liability that these contractual assumptions directly impose on
|
||||
those licensors and authors.
|
||||
|
||||
All other non-permissive additional terms are considered "further
|
||||
restrictions" within the meaning of section 10. If the Program as you
|
||||
received it, or any part of it, contains a notice stating that it is
|
||||
governed by this License along with a term that is a further
|
||||
restriction, you may remove that term. If a license document contains
|
||||
a further restriction but permits relicensing or conveying under this
|
||||
License, you may add to a covered work material governed by the terms
|
||||
of that license document, provided that the further restriction does
|
||||
not survive such relicensing or conveying.
|
||||
|
||||
If you add terms to a covered work in accord with this section, you
|
||||
must place, in the relevant source files, a statement of the
|
||||
additional terms that apply to those files, or a notice indicating
|
||||
where to find the applicable terms.
|
||||
|
||||
Additional terms, permissive or non-permissive, may be stated in the
|
||||
form of a separately written license, or stated as exceptions;
|
||||
the above requirements apply either way.
|
||||
|
||||
8. Termination.
|
||||
|
||||
You may not propagate or modify a covered work except as expressly
|
||||
provided under this License. Any attempt otherwise to propagate or
|
||||
modify it is void, and will automatically terminate your rights under
|
||||
this License (including any patent licenses granted under the third
|
||||
paragraph of section 11).
|
||||
|
||||
However, if you cease all violation of this License, then your
|
||||
license from a particular copyright holder is reinstated (a)
|
||||
provisionally, unless and until the copyright holder explicitly and
|
||||
finally terminates your license, and (b) permanently, if the copyright
|
||||
holder fails to notify you of the violation by some reasonable means
|
||||
prior to 60 days after the cessation.
|
||||
|
||||
Moreover, your license from a particular copyright holder is
|
||||
reinstated permanently if the copyright holder notifies you of the
|
||||
violation by some reasonable means, this is the first time you have
|
||||
received notice of violation of this License (for any work) from that
|
||||
copyright holder, and you cure the violation prior to 30 days after
|
||||
your receipt of the notice.
|
||||
|
||||
Termination of your rights under this section does not terminate the
|
||||
licenses of parties who have received copies or rights from you under
|
||||
this License. If your rights have been terminated and not permanently
|
||||
reinstated, you do not qualify to receive new licenses for the same
|
||||
material under section 10.
|
||||
|
||||
9. Acceptance Not Required for Having Copies.
|
||||
|
||||
You are not required to accept this License in order to receive or
|
||||
run a copy of the Program. Ancillary propagation of a covered work
|
||||
occurring solely as a consequence of using peer-to-peer transmission
|
||||
to receive a copy likewise does not require acceptance. However,
|
||||
nothing other than this License grants you permission to propagate or
|
||||
modify any covered work. These actions infringe copyright if you do
|
||||
not accept this License. Therefore, by modifying or propagating a
|
||||
covered work, you indicate your acceptance of this License to do so.
|
||||
|
||||
10. Automatic Licensing of Downstream Recipients.
|
||||
|
||||
Each time you convey a covered work, the recipient automatically
|
||||
receives a license from the original licensors, to run, modify and
|
||||
propagate that work, subject to this License. You are not responsible
|
||||
for enforcing compliance by third parties with this License.
|
||||
|
||||
An "entity transaction" is a transaction transferring control of an
|
||||
organization, or substantially all assets of one, or subdividing an
|
||||
organization, or merging organizations. If propagation of a covered
|
||||
work results from an entity transaction, each party to that
|
||||
transaction who receives a copy of the work also receives whatever
|
||||
licenses to the work the party's predecessor in interest had or could
|
||||
give under the previous paragraph, plus a right to possession of the
|
||||
Corresponding Source of the work from the predecessor in interest, if
|
||||
the predecessor has it or can get it with reasonable efforts.
|
||||
|
||||
You may not impose any further restrictions on the exercise of the
|
||||
rights granted or affirmed under this License. For example, you may
|
||||
not impose a license fee, royalty, or other charge for exercise of
|
||||
rights granted under this License, and you may not initiate litigation
|
||||
(including a cross-claim or counterclaim in a lawsuit) alleging that
|
||||
any patent claim is infringed by making, using, selling, offering for
|
||||
sale, or importing the Program or any portion of it.
|
||||
|
||||
11. Patents.
|
||||
|
||||
A "contributor" is a copyright holder who authorizes use under this
|
||||
License of the Program or a work on which the Program is based. The
|
||||
work thus licensed is called the contributor's "contributor version".
|
||||
|
||||
A contributor's "essential patent claims" are all patent claims
|
||||
owned or controlled by the contributor, whether already acquired or
|
||||
hereafter acquired, that would be infringed by some manner, permitted
|
||||
by this License, of making, using, or selling its contributor version,
|
||||
but do not include claims that would be infringed only as a
|
||||
consequence of further modification of the contributor version. For
|
||||
purposes of this definition, "control" includes the right to grant
|
||||
patent sublicenses in a manner consistent with the requirements of
|
||||
this License.
|
||||
|
||||
Each contributor grants you a non-exclusive, worldwide, royalty-free
|
||||
patent license under the contributor's essential patent claims, to
|
||||
make, use, sell, offer for sale, import and otherwise run, modify and
|
||||
propagate the contents of its contributor version.
|
||||
|
||||
In the following three paragraphs, a "patent license" is any express
|
||||
agreement or commitment, however denominated, not to enforce a patent
|
||||
(such as an express permission to practice a patent or covenant not to
|
||||
sue for patent infringement). To "grant" such a patent license to a
|
||||
party means to make such an agreement or commitment not to enforce a
|
||||
patent against the party.
|
||||
|
||||
If you convey a covered work, knowingly relying on a patent license,
|
||||
and the Corresponding Source of the work is not available for anyone
|
||||
to copy, free of charge and under the terms of this License, through a
|
||||
publicly available network server or other readily accessible means,
|
||||
then you must either (1) cause the Corresponding Source to be so
|
||||
available, or (2) arrange to deprive yourself of the benefit of the
|
||||
patent license for this particular work, or (3) arrange, in a manner
|
||||
consistent with the requirements of this License, to extend the patent
|
||||
license to downstream recipients. "Knowingly relying" means you have
|
||||
actual knowledge that, but for the patent license, your conveying the
|
||||
covered work in a country, or your recipient's use of the covered work
|
||||
in a country, would infringe one or more identifiable patents in that
|
||||
country that you have reason to believe are valid.
|
||||
|
||||
If, pursuant to or in connection with a single transaction or
|
||||
arrangement, you convey, or propagate by procuring conveyance of, a
|
||||
covered work, and grant a patent license to some of the parties
|
||||
receiving the covered work authorizing them to use, propagate, modify
|
||||
or convey a specific copy of the covered work, then the patent license
|
||||
you grant is automatically extended to all recipients of the covered
|
||||
work and works based on it.
|
||||
|
||||
A patent license is "discriminatory" if it does not include within
|
||||
the scope of its coverage, prohibits the exercise of, or is
|
||||
conditioned on the non-exercise of one or more of the rights that are
|
||||
specifically granted under this License. You may not convey a covered
|
||||
work if you are a party to an arrangement with a third party that is
|
||||
in the business of distributing software, under which you make payment
|
||||
to the third party based on the extent of your activity of conveying
|
||||
the work, and under which the third party grants, to any of the
|
||||
parties who would receive the covered work from you, a discriminatory
|
||||
patent license (a) in connection with copies of the covered work
|
||||
conveyed by you (or copies made from those copies), or (b) primarily
|
||||
for and in connection with specific products or compilations that
|
||||
contain the covered work, unless you entered into that arrangement,
|
||||
or that patent license was granted, prior to 28 March 2007.
|
||||
|
||||
Nothing in this License shall be construed as excluding or limiting
|
||||
any implied license or other defenses to infringement that may
|
||||
otherwise be available to you under applicable patent law.
|
||||
|
||||
12. No Surrender of Others' Freedom.
|
||||
|
||||
If conditions are imposed on you (whether by court order, agreement or
|
||||
otherwise) that contradict the conditions of this License, they do not
|
||||
excuse you from the conditions of this License. If you cannot convey a
|
||||
covered work so as to satisfy simultaneously your obligations under this
|
||||
License and any other pertinent obligations, then as a consequence you may
|
||||
not convey it at all. For example, if you agree to terms that obligate you
|
||||
to collect a royalty for further conveying from those to whom you convey
|
||||
the Program, the only way you could satisfy both those terms and this
|
||||
License would be to refrain entirely from conveying the Program.
|
||||
|
||||
13. Remote Network Interaction; Use with the GNU General Public License.
|
||||
|
||||
Notwithstanding any other provision of this License, if you modify the
|
||||
Program, your modified version must prominently offer all users
|
||||
interacting with it remotely through a computer network (if your version
|
||||
supports such interaction) an opportunity to receive the Corresponding
|
||||
Source of your version by providing access to the Corresponding Source
|
||||
from a network server at no charge, through some standard or customary
|
||||
means of facilitating copying of software. This Corresponding Source
|
||||
shall include the Corresponding Source for any work covered by version 3
|
||||
of the GNU General Public License that is incorporated pursuant to the
|
||||
following paragraph.
|
||||
|
||||
Notwithstanding any other provision of this License, you have
|
||||
permission to link or combine any covered work with a work licensed
|
||||
under version 3 of the GNU General Public License into a single
|
||||
combined work, and to convey the resulting work. The terms of this
|
||||
License will continue to apply to the part which is the covered work,
|
||||
but the work with which it is combined will remain governed by version
|
||||
3 of the GNU General Public License.
|
||||
|
||||
14. Revised Versions of this License.
|
||||
|
||||
The Free Software Foundation may publish revised and/or new versions of
|
||||
the GNU Affero General Public License from time to time. Such new versions
|
||||
will be similar in spirit to the present version, but may differ in detail to
|
||||
address new problems or concerns.
|
||||
|
||||
Each version is given a distinguishing version number. If the
|
||||
Program specifies that a certain numbered version of the GNU Affero General
|
||||
Public License "or any later version" applies to it, you have the
|
||||
option of following the terms and conditions either of that numbered
|
||||
version or of any later version published by the Free Software
|
||||
Foundation. If the Program does not specify a version number of the
|
||||
GNU Affero General Public License, you may choose any version ever published
|
||||
by the Free Software Foundation.
|
||||
|
||||
If the Program specifies that a proxy can decide which future
|
||||
versions of the GNU Affero General Public License can be used, that proxy's
|
||||
public statement of acceptance of a version permanently authorizes you
|
||||
to choose that version for the Program.
|
||||
|
||||
Later license versions may give you additional or different
|
||||
permissions. However, no additional obligations are imposed on any
|
||||
author or copyright holder as a result of your choosing to follow a
|
||||
later version.
|
||||
|
||||
15. Disclaimer of Warranty.
|
||||
|
||||
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
|
||||
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
|
||||
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
|
||||
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
|
||||
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
|
||||
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
|
||||
IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
|
||||
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
|
||||
|
||||
16. Limitation of Liability.
|
||||
|
||||
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
|
||||
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
|
||||
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
|
||||
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
|
||||
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
|
||||
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
|
||||
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
|
||||
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
|
||||
SUCH DAMAGES.
|
||||
|
||||
17. Interpretation of Sections 15 and 16.
|
||||
|
||||
If the disclaimer of warranty and limitation of liability provided
|
||||
above cannot be given local legal effect according to their terms,
|
||||
reviewing courts shall apply local law that most closely approximates
|
||||
an absolute waiver of all civil liability in connection with the
|
||||
Program, unless a warranty or assumption of liability accompanies a
|
||||
copy of the Program in return for a fee.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
|
||||
How to Apply These Terms to Your New Programs
|
||||
|
||||
If you develop a new program, and you want it to be of the greatest
|
||||
possible use to the public, the best way to achieve this is to make it
|
||||
free software which everyone can redistribute and change under these terms.
|
||||
|
||||
To do so, attach the following notices to the program. It is safest
|
||||
to attach them to the start of each source file to most effectively
|
||||
state the exclusion of warranty; and each file should have at least
|
||||
the "copyright" line and a pointer to where the full notice is found.
|
||||
|
||||
<one line to give the program's name and a brief idea of what it does.>
|
||||
Copyright (C) <year> <name of author>
|
||||
|
||||
This program is free software: you can redistribute it and/or modify
|
||||
it under the terms of the GNU Affero General Public License as published
|
||||
by the Free Software Foundation, either version 3 of the License, or
|
||||
(at your option) any later version.
|
||||
|
||||
This program is distributed in the hope that it will be useful,
|
||||
but WITHOUT ANY WARRANTY; without even the implied warranty of
|
||||
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
||||
GNU Affero General Public License for more details.
|
||||
|
||||
You should have received a copy of the GNU Affero General Public License
|
||||
along with this program. If not, see <https://www.gnu.org/licenses/>.
|
||||
|
||||
Also add information on how to contact you by electronic and paper mail.
|
||||
|
||||
If your software can interact with users remotely through a computer
|
||||
network, you should also make sure that it provides a way for users to
|
||||
get its source. For example, if your program is a web application, its
|
||||
interface could display a "Source" link that leads users to an archive
|
||||
of the code. There are many ways you could offer source, and different
|
||||
solutions will be better for different programs; see section 13 for the
|
||||
specific requirements.
|
||||
|
||||
You should also get your employer (if you work as a programmer) or school,
|
||||
if any, to sign a "copyright disclaimer" for the program, if necessary.
|
||||
For more information on this, and how to apply and follow the GNU AGPL, see
|
||||
<https://www.gnu.org/licenses/>.
|
||||
@ -1,2 +0,0 @@
|
||||
import Distribution.Simple
|
||||
main = defaultMain
|
||||
@ -1,16 +0,0 @@
|
||||
module Main where
|
||||
|
||||
import Simplex.Messaging.ServerAPI
|
||||
|
||||
import Servant
|
||||
import Servant.Docs
|
||||
|
||||
apiDocs :: API
|
||||
apiDocs = docsWith
|
||||
defaultDocOptions
|
||||
[serverApiIntro]
|
||||
serverApiExtra
|
||||
(Proxy :: Proxy ServerAPI)
|
||||
|
||||
main :: IO ()
|
||||
main = writeFile "../simplex-messaging-api.md" $ markdown apiDocs
|
||||
@ -1,7 +0,0 @@
|
||||
module Main where
|
||||
|
||||
import Simplex.Messaging.PrintScenario
|
||||
import Simplex.Messaging.Scenarios
|
||||
|
||||
main :: IO ()
|
||||
main = printScenario establishConnection
|
||||
@ -1,62 +0,0 @@
|
||||
name: simplex-definitions
|
||||
version: 0.1.0.0
|
||||
#synopsis:
|
||||
#description:
|
||||
homepage: https://github.com/simplex-chat/protocol/blob/master/definitions/readme.md
|
||||
license: AGPL-3
|
||||
author: Evgeny Poberezkin
|
||||
copyright: 2020 Evgeny Poberezkin
|
||||
category: Web
|
||||
extra-source-files:
|
||||
- readme.md
|
||||
|
||||
ghc-options:
|
||||
# - -fplugin=Polysemy.Plugin
|
||||
- -O2
|
||||
- -Wall
|
||||
- -Wcompat
|
||||
- -Werror=incomplete-patterns
|
||||
- -Wredundant-constraints
|
||||
- -Wincomplete-record-updates
|
||||
- -Wincomplete-uni-patterns
|
||||
- -Wunused-type-patterns
|
||||
|
||||
dependencies:
|
||||
- aeson
|
||||
- base >= 4.7 && < 5
|
||||
- freer-indexed
|
||||
- polysemy
|
||||
# - polysemy-plugin
|
||||
- lens
|
||||
- mtl
|
||||
- protocol
|
||||
- singletons
|
||||
- servant-docs
|
||||
- servant-server
|
||||
- text
|
||||
- transformers
|
||||
|
||||
library:
|
||||
source-dirs: src
|
||||
|
||||
executables:
|
||||
api-docs:
|
||||
source-dirs: app/api-docs
|
||||
main: Main.hs
|
||||
ghc-options: -threaded
|
||||
dependencies: simplex-definitions
|
||||
|
||||
print-scenarios:
|
||||
source-dirs: app/print-scenarios
|
||||
main: Main.hs
|
||||
ghc-options: -threaded
|
||||
dependencies: simplex-definitions
|
||||
|
||||
tests:
|
||||
simplex-definitions-doctests:
|
||||
source-dirs: tests
|
||||
main: doctest-driver.hs
|
||||
ghc-options: -threaded
|
||||
dependencies:
|
||||
- doctest
|
||||
- doctest-driver-gen
|
||||
@ -1,3 +0,0 @@
|
||||
# simplex-messaging-api
|
||||
|
||||
This package contains [Servant](https://hackage.haskell.org/package/servant-server) API types and is used to generate [API documenation](../simplex-messaging-api.md)
|
||||
@ -1,53 +0,0 @@
|
||||
{-# LANGUAGE DataKinds #-}
|
||||
{-# LANGUAGE FlexibleContexts #-}
|
||||
{-# LANGUAGE FlexibleInstances #-}
|
||||
{-# LANGUAGE GADTs #-}
|
||||
{-# LANGUAGE InstanceSigs #-}
|
||||
{-# LANGUAGE MultiParamTypeClasses #-}
|
||||
{-# LANGUAGE PolyKinds #-}
|
||||
{-# OPTIONS_GHC -fno-warn-orphans #-}
|
||||
{-# OPTIONS_GHC -fno-warn-unticked-promoted-constructors #-}
|
||||
|
||||
module Simplex.Messaging.Broker where
|
||||
|
||||
import Control.Monad.Trans.Except
|
||||
import Polysemy.Internal
|
||||
import Simplex.Messaging.Protocol
|
||||
|
||||
instance Monad m => PartyProtocol m Broker where
|
||||
api ::
|
||||
SimplexCommand from '(Broker, s, s') a ->
|
||||
Connection Broker s ->
|
||||
ExceptT String m (a, Connection Broker s')
|
||||
api (CreateConn _) = apiStub
|
||||
api (Subscribe _) = apiStub
|
||||
api (Unsubscribe _) = apiStub
|
||||
api (ConfirmConn _ _) = apiStub
|
||||
api (SecureConn _ _) = apiStub
|
||||
api (SendMsg _ _) = apiStub
|
||||
api (DeleteMsg _ _) = apiStub
|
||||
|
||||
action ::
|
||||
SimplexCommand '(Broker, s, s') to a ->
|
||||
Connection Broker s ->
|
||||
ExceptT String m a ->
|
||||
ExceptT String m (Connection Broker s')
|
||||
action (PushConfirm _ _) = actionStub
|
||||
action (PushMsg _ _) = actionStub
|
||||
|
||||
type SimplexBroker = SimplexParty Broker
|
||||
|
||||
api' ::
|
||||
Member SimplexBroker r =>
|
||||
SimplexCommand from '(Broker, s, s') a ->
|
||||
Connection Broker s ->
|
||||
Sem r (Either String (a, Connection Broker s'))
|
||||
api' cmd conn = send $ Api cmd conn
|
||||
|
||||
action' ::
|
||||
Member SimplexBroker r =>
|
||||
SimplexCommand '(Broker, s, s') to a ->
|
||||
Connection Broker s ->
|
||||
Either String a ->
|
||||
Sem r (Either String (Connection Broker s'))
|
||||
action' cmd conn res = send $ Action cmd conn res
|
||||
@ -1,84 +0,0 @@
|
||||
{-# LANGUAGE DataKinds #-}
|
||||
{-# LANGUAGE FlexibleContexts #-}
|
||||
{-# LANGUAGE FlexibleInstances #-}
|
||||
{-# LANGUAGE GADTs #-}
|
||||
{-# LANGUAGE InstanceSigs #-}
|
||||
{-# LANGUAGE MultiParamTypeClasses #-}
|
||||
{-# LANGUAGE PolyKinds #-}
|
||||
{-# OPTIONS_GHC -fno-warn-orphans #-}
|
||||
{-# OPTIONS_GHC -fno-warn-unticked-promoted-constructors #-}
|
||||
|
||||
module Simplex.Messaging.Client where
|
||||
|
||||
import Control.Monad.Trans.Except
|
||||
import Polysemy.Internal
|
||||
import Simplex.Messaging.Protocol
|
||||
|
||||
instance Monad m => PartyProtocol m Recipient where
|
||||
api ::
|
||||
SimplexCommand from '(Recipient, s, s') a ->
|
||||
Connection Recipient s ->
|
||||
ExceptT String m (a, Connection Recipient s')
|
||||
api (PushConfirm _ _) = apiStub
|
||||
api (PushMsg _ _) = apiStub
|
||||
|
||||
action ::
|
||||
SimplexCommand '(Recipient, s, s') to a ->
|
||||
Connection Recipient s ->
|
||||
ExceptT String m a ->
|
||||
ExceptT String m (Connection Recipient s')
|
||||
action (CreateConn _) = actionStub
|
||||
action (Subscribe _) = actionStub
|
||||
action (Unsubscribe _) = actionStub
|
||||
action (SendInvite _) = actionStub
|
||||
action (SecureConn _ _) = actionStub
|
||||
action (DeleteMsg _ _) = actionStub
|
||||
|
||||
instance Monad m => PartyProtocol m Sender where
|
||||
api ::
|
||||
SimplexCommand from '(Sender, s, s') a ->
|
||||
Connection Sender s ->
|
||||
ExceptT String m (a, Connection Sender s')
|
||||
api (SendInvite _) = apiStub
|
||||
|
||||
action ::
|
||||
SimplexCommand '(Sender, s, s') to a ->
|
||||
Connection Sender s ->
|
||||
ExceptT String m a ->
|
||||
ExceptT String m (Connection Sender s')
|
||||
action (ConfirmConn _ _) = actionStub
|
||||
action (SendMsg _ _) = actionStub
|
||||
|
||||
type SimplexRecipient = SimplexParty Recipient
|
||||
|
||||
type SimplexSender = SimplexParty Sender
|
||||
|
||||
rApi ::
|
||||
Member SimplexRecipient r =>
|
||||
SimplexCommand from '(Recipient, s, s') a ->
|
||||
Connection Recipient s ->
|
||||
Sem r (Either String (a, Connection Recipient s'))
|
||||
rApi cmd conn = send $ Api cmd conn
|
||||
|
||||
rAction ::
|
||||
Member SimplexRecipient r =>
|
||||
SimplexCommand '(Recipient, s, s') to a ->
|
||||
Connection Recipient s ->
|
||||
Either String a ->
|
||||
Sem r (Either String (Connection Recipient s'))
|
||||
rAction cmd conn res = send $ Action cmd conn res
|
||||
|
||||
sApi ::
|
||||
Member SimplexSender r =>
|
||||
SimplexCommand from '(Sender, s, s') a ->
|
||||
Connection Sender s ->
|
||||
Sem r (Either String (a, Connection Sender s'))
|
||||
sApi cmd conn = send $ Api cmd conn
|
||||
|
||||
sAction ::
|
||||
Member SimplexSender r =>
|
||||
SimplexCommand '(Sender, s, s') to a ->
|
||||
Connection Sender s ->
|
||||
Either String a ->
|
||||
Sem r (Either String (Connection Sender s'))
|
||||
sAction cmd conn res = send $ Action cmd conn res
|
||||
@ -1,70 +0,0 @@
|
||||
{-# LANGUAGE DataKinds #-}
|
||||
{-# LANGUAGE DuplicateRecordFields #-}
|
||||
{-# LANGUAGE GADTs #-}
|
||||
{-# LANGUAGE TypeFamilies #-}
|
||||
{-# LANGUAGE TypeOperators #-}
|
||||
{-# OPTIONS_GHC -fno-warn-unticked-promoted-constructors #-}
|
||||
|
||||
module Simplex.Messaging.Connection where
|
||||
|
||||
import Data.Kind
|
||||
import Data.Text
|
||||
import Data.Type.Bool (type (||))
|
||||
import Data.Type.Equality (type (==))
|
||||
import Simplex.Messaging.Core
|
||||
import Simplex.Messaging.Types hiding (Invitation)
|
||||
|
||||
-- | 'Connection' for all participants
|
||||
data Connection (p :: Party) (s :: ConnState) :: Type where
|
||||
-- | no connection with this ID, used by all parties
|
||||
NoConnection ::
|
||||
ConnId ->
|
||||
Connection p None
|
||||
-- | connection created by the broker
|
||||
ConnRcpNew ::
|
||||
(s == New || s == Pending) ~ True =>
|
||||
ClientConn ->
|
||||
SenderConnId ->
|
||||
PrivateKey -> -- key to decrypt messages from sender
|
||||
PublicKey -> -- key for sender to encrypt messages to recipient
|
||||
Connection Recipient s
|
||||
-- | After sender confirmed connection:
|
||||
-- * added sender's key for the broker (inside Conn)
|
||||
-- * removed PublicKey previously sent to sender
|
||||
ConnRcpConfirmed ::
|
||||
ClientConn ->
|
||||
Conn -> -- sender's connection info
|
||||
PrivateKey -> -- key to decrypt messages from the sender
|
||||
Connection Recipient Confirmed
|
||||
-- | Connection is secured and can be used by the sender or it is disabled.
|
||||
-- All sender connection information is removed now.
|
||||
ConnRcp ::
|
||||
(s == Secured || s == Disabled) ~ True =>
|
||||
ClientConn ->
|
||||
PrivateKey -> -- to decrypt messages from sender
|
||||
Connection Recipient s
|
||||
ConnSnd ::
|
||||
(HasState Sender s, (s == None) ~ False) =>
|
||||
ClientConn ->
|
||||
PublicKey -> -- to encrypt messages to recipient
|
||||
Connection Sender s
|
||||
ConnBrkNew ::
|
||||
Conn ->
|
||||
SenderConnId ->
|
||||
Connection Broker New
|
||||
ConnBrk ::
|
||||
(s == Secured || s == Disabled) ~ True =>
|
||||
{recipient :: Conn, sender :: Conn} ->
|
||||
Connection Broker s
|
||||
|
||||
data Conn = Conn
|
||||
{ connId :: ConnId,
|
||||
brokerVerifyKey :: PublicKey
|
||||
}
|
||||
|
||||
data ClientConn = ClientConn
|
||||
{ connId :: ConnId,
|
||||
brokerVerifyKey :: PublicKey,
|
||||
brokerKey :: PrivateKey,
|
||||
brokerUri :: Text
|
||||
}
|
||||
@ -1,49 +0,0 @@
|
||||
{-# LANGUAGE DataKinds #-}
|
||||
{-# LANGUAGE EmptyCase #-}
|
||||
{-# LANGUAGE GADTs #-}
|
||||
{-# LANGUAGE InstanceSigs #-}
|
||||
{-# LANGUAGE PolyKinds #-}
|
||||
{-# LANGUAGE ScopedTypeVariables #-}
|
||||
{-# LANGUAGE TemplateHaskell #-}
|
||||
{-# LANGUAGE TypeApplications #-}
|
||||
{-# LANGUAGE TypeFamilies #-}
|
||||
{-# LANGUAGE UndecidableInstances #-}
|
||||
{-# OPTIONS_GHC -fno-warn-unticked-promoted-constructors #-}
|
||||
|
||||
module Simplex.Messaging.Core where
|
||||
|
||||
import Data.Kind
|
||||
import Data.Singletons.TH
|
||||
|
||||
$( singletons
|
||||
[d|
|
||||
data Party = Recipient | Broker | Sender
|
||||
deriving (Show, Eq)
|
||||
|
||||
data ConnState
|
||||
= None -- (all) not available or removed from the broker
|
||||
| New -- (all) connection created (or, for sender, received from recipient)
|
||||
| Pending -- (recipient) sent to sender out-of-band
|
||||
| Confirmed -- (recipient, sender) confirmed by sender with the broker
|
||||
| Secured -- (all) secured with the broker
|
||||
| Disabled -- (broker, recipient) disabled with the broker by recipient
|
||||
deriving (Show, Eq)
|
||||
|]
|
||||
)
|
||||
|
||||
type family HasState (p :: Party) (s :: ConnState) :: Constraint where
|
||||
HasState Recipient _ = ()
|
||||
HasState Broker None = ()
|
||||
HasState Broker New = ()
|
||||
HasState Broker Secured = ()
|
||||
HasState Broker Disabled = ()
|
||||
HasState Sender None = ()
|
||||
HasState Sender New = ()
|
||||
HasState Sender Confirmed = ()
|
||||
HasState Sender Secured = ()
|
||||
|
||||
type family Enabled (rs :: ConnState) (bs :: ConnState) :: Constraint where
|
||||
Enabled New New = ()
|
||||
Enabled Pending New = ()
|
||||
Enabled Confirmed New = ()
|
||||
Enabled Secured Secured = ()
|
||||
@ -1,70 +0,0 @@
|
||||
{-# LANGUAGE AllowAmbiguousTypes #-}
|
||||
{-# LANGUAGE DataKinds #-}
|
||||
{-# LANGUAGE FlexibleContexts #-}
|
||||
{-# LANGUAGE FlexibleInstances #-}
|
||||
{-# LANGUAGE GADTs #-}
|
||||
{-# LANGUAGE KindSignatures #-}
|
||||
{-# LANGUAGE LambdaCase #-}
|
||||
{-# OPTIONS_GHC -fno-warn-unticked-promoted-constructors #-}
|
||||
|
||||
module Simplex.Messaging.PrintScenario where
|
||||
|
||||
import Control.Monad.Writer
|
||||
import Control.Protocol (runProtocol)
|
||||
import Data.Singletons
|
||||
import Simplex.Messaging.Protocol
|
||||
import Simplex.Messaging.Types
|
||||
|
||||
printScenario :: SimplexProtocol s s' a -> IO ()
|
||||
printScenario scn = ps 1 "" $ execWriter $ logScenario scn
|
||||
where
|
||||
ps :: Int -> String -> [(String, String)] -> IO ()
|
||||
ps _ _ [] = return ()
|
||||
ps i p ((p', l) : ls)
|
||||
| p' /= p = part (i + 1) $ show i <> ". " <> p' <> ":\n" <> prefix l
|
||||
| otherwise = part i $ prefix l
|
||||
where
|
||||
part i' s = putStrLn s >> ps i' p' ls
|
||||
prefix s = " - " <> s
|
||||
|
||||
logScenario :: MonadWriter [(String, String)] m => SimplexProtocol s s' a -> m a
|
||||
logScenario = runProtocol $ \from to cmd -> do
|
||||
tell [(party from, commandStr cmd <> " " <> party to)]
|
||||
mockCommand cmd
|
||||
|
||||
commandStr :: SimplexCommand from to a -> String
|
||||
commandStr = \case
|
||||
CreateConn _ -> "creates connection in"
|
||||
Subscribe cid -> "subscribes to connection " <> show cid <> " in"
|
||||
Unsubscribe cid -> "unsubscribes from connection " <> show cid <> " in"
|
||||
SendInvite _ -> "sends out-of band invitation to "
|
||||
ConfirmConn cid _ -> "confirms connection " <> show cid <> " in"
|
||||
PushConfirm cid _ -> "pushes confirmation for " <> show cid <> " to"
|
||||
SecureConn cid _ -> "secures connection " <> show cid <> " in"
|
||||
SendMsg cid _ -> "sends message to connection " <> show cid <> " in"
|
||||
PushMsg cid _ -> "pushes message from connection " <> show cid <> " to"
|
||||
DeleteMsg cid _ -> "deletes message from connection " <> show cid <> " in"
|
||||
|
||||
mockCommand :: Monad m => SimplexCommand from to a -> m a
|
||||
mockCommand = \case
|
||||
(CreateConn _) ->
|
||||
return
|
||||
CreateConnResponse
|
||||
{ recipientId = "Qxz93A",
|
||||
senderId = "N9pA3g"
|
||||
}
|
||||
Subscribe _ -> return ()
|
||||
Unsubscribe _ -> return ()
|
||||
SendInvite _ -> return ()
|
||||
ConfirmConn _ _ -> return ()
|
||||
PushConfirm _ _ -> return ()
|
||||
SecureConn _ _ -> return ()
|
||||
SendMsg _ _ -> return ()
|
||||
PushMsg _ _ -> return ()
|
||||
DeleteMsg _ _ -> return ()
|
||||
|
||||
party :: Sing (p :: Party) -> String
|
||||
party = \case
|
||||
SRecipient -> "Alice (recipient)"
|
||||
SBroker -> "Alice's server (broker)"
|
||||
SSender -> "Bob (sender)"
|
||||
@ -1,133 +0,0 @@
|
||||
{-# LANGUAGE ConstraintKinds #-}
|
||||
{-# LANGUAGE DataKinds #-}
|
||||
{-# LANGUAGE GADTs #-}
|
||||
{-# LANGUAGE MultiParamTypeClasses #-}
|
||||
{-# LANGUAGE OverloadedStrings #-}
|
||||
{-# LANGUAGE PolyKinds #-}
|
||||
{-# LANGUAGE TypeFamilies #-}
|
||||
{-# LANGUAGE TypeOperators #-}
|
||||
{-# LANGUAGE UndecidableInstances #-}
|
||||
{-# OPTIONS_GHC -fno-warn-unticked-promoted-constructors #-}
|
||||
|
||||
module Simplex.Messaging.Protocol
|
||||
( module Simplex.Messaging.Core,
|
||||
module Simplex.Messaging.Protocol,
|
||||
)
|
||||
where
|
||||
|
||||
import Control.Monad.Trans.Except
|
||||
import Control.Protocol
|
||||
import Data.Kind
|
||||
import Data.Type.Bool (type (||))
|
||||
import Data.Type.Equality (type (==))
|
||||
import Simplex.Messaging.Core
|
||||
import Simplex.Messaging.Types
|
||||
|
||||
type SimplexProtocol = Protocol SimplexCommand '[Recipient, Broker, Sender]
|
||||
|
||||
data SimplexCommand :: Command Party ConnState where
|
||||
CreateConn ::
|
||||
PublicKey ->
|
||||
SimplexCommand
|
||||
'(Recipient, None, New)
|
||||
'(Broker, None, New)
|
||||
CreateConnResponse
|
||||
Subscribe ::
|
||||
Enabled rs bs =>
|
||||
ConnId ->
|
||||
SimplexCommand
|
||||
'(Recipient, rs, rs)
|
||||
'(Broker, bs, bs)
|
||||
()
|
||||
Unsubscribe ::
|
||||
Enabled rs bs =>
|
||||
ConnId ->
|
||||
SimplexCommand
|
||||
'(Recipient, rs, rs)
|
||||
'(Broker, bs, bs)
|
||||
()
|
||||
SendInvite ::
|
||||
Invitation ->
|
||||
SimplexCommand
|
||||
'(Recipient, New, Pending)
|
||||
'(Sender, None, New)
|
||||
()
|
||||
ConfirmConn ::
|
||||
SenderConnId ->
|
||||
Encrypted ->
|
||||
SimplexCommand
|
||||
'(Sender, New, Confirmed)
|
||||
'(Broker, New, New)
|
||||
()
|
||||
PushConfirm ::
|
||||
ConnId ->
|
||||
Message ->
|
||||
SimplexCommand
|
||||
'(Broker, New, New)
|
||||
'(Recipient, Pending, Confirmed)
|
||||
()
|
||||
SecureConn ::
|
||||
ConnId ->
|
||||
PublicKey ->
|
||||
SimplexCommand
|
||||
'(Recipient, Confirmed, Secured)
|
||||
'(Broker, New, Secured)
|
||||
()
|
||||
SendMsg ::
|
||||
(ss == Confirmed || ss == Secured) ~ True =>
|
||||
SenderConnId ->
|
||||
Encrypted ->
|
||||
SimplexCommand
|
||||
'(Sender, ss, Secured)
|
||||
'(Broker, Secured, Secured)
|
||||
()
|
||||
PushMsg ::
|
||||
ConnId ->
|
||||
Message ->
|
||||
SimplexCommand
|
||||
'(Broker, Secured, Secured)
|
||||
'(Recipient, Secured, Secured)
|
||||
()
|
||||
DeleteMsg ::
|
||||
ConnId ->
|
||||
MessageId ->
|
||||
SimplexCommand
|
||||
'(Recipient, Secured, Secured)
|
||||
'(Broker, Secured, Secured)
|
||||
()
|
||||
|
||||
-- connection type stub for all participants, TODO move from idris
|
||||
data
|
||||
Connection
|
||||
(p :: Party)
|
||||
(s :: ConnState) :: Type
|
||||
where
|
||||
Connection :: String -> Connection p s -- TODO replace with real type definition
|
||||
|
||||
class Monad m => PartyProtocol m (p :: Party) where
|
||||
api ::
|
||||
SimplexCommand from '(p, s, s') a ->
|
||||
Connection p s ->
|
||||
ExceptT String m (a, Connection p s')
|
||||
action ::
|
||||
SimplexCommand '(p, s, s') to a ->
|
||||
Connection p s ->
|
||||
ExceptT String m a ->
|
||||
ExceptT String m (Connection p s')
|
||||
|
||||
apiStub :: Monad m => Connection p s -> ExceptT String m (a, Connection p s')
|
||||
apiStub _ = throwE "api not implemented"
|
||||
|
||||
actionStub :: Monad m => Connection p s -> ExceptT String m a -> ExceptT String m (Connection p s')
|
||||
actionStub _ _ = throwE "action not implemented"
|
||||
|
||||
data SimplexParty (p :: Party) m a where
|
||||
Api ::
|
||||
SimplexCommand from '(p, s, s') x ->
|
||||
Connection p s ->
|
||||
SimplexParty p m (Either String (x, Connection p s'))
|
||||
Action ::
|
||||
SimplexCommand '(p, s, s') to x ->
|
||||
Connection p s ->
|
||||
Either String x ->
|
||||
SimplexParty p m (Either String (Connection p s'))
|
||||
@ -1,45 +0,0 @@
|
||||
{-# LANGUAGE DataKinds #-}
|
||||
{-# LANGUAGE DuplicateRecordFields #-}
|
||||
{-# LANGUAGE OverloadedStrings #-}
|
||||
{-# LANGUAGE RebindableSyntax #-}
|
||||
{-# OPTIONS_GHC -fno-warn-missing-fields #-}
|
||||
{-# OPTIONS_GHC -fno-warn-unticked-promoted-constructors #-}
|
||||
{-# OPTIONS_GHC -fno-warn-unused-do-bind #-}
|
||||
|
||||
module Simplex.Messaging.Scenarios where
|
||||
|
||||
import Control.Protocol
|
||||
import Control.XMonad.Do
|
||||
import Data.Singletons
|
||||
import Data.String
|
||||
import Simplex.Messaging.Protocol
|
||||
import Simplex.Messaging.Types
|
||||
import Prelude hiding ((>>), (>>=))
|
||||
|
||||
r :: Sing Recipient
|
||||
r = SRecipient
|
||||
|
||||
b :: Sing Broker
|
||||
b = SBroker
|
||||
|
||||
s :: Sing Sender
|
||||
s = SSender
|
||||
|
||||
-- Establish simplex messaging connection and send first message
|
||||
establishConnection :: SimplexProtocol '[None, None, None] '[Secured, Secured, Secured] ()
|
||||
establishConnection = do
|
||||
r ->: b $ CreateConn "BODbZxmtKUUF1l8pj4nVjQ"
|
||||
r ->: b $ Subscribe "RU"
|
||||
r ->: s $ SendInvite Invitation {connId = "SU"}
|
||||
s ->: b $ ConfirmConn "SU" "encrypted"
|
||||
b ->: r $ PushConfirm "RU" Message {msgId = "abc", msg = "XPaVEVNunkYKqqK0dnAT5Q"}
|
||||
r ->: b $ SecureConn "RU" "XPaVEVNunkYKqqK0dnAT5Q"
|
||||
r ->: b $ DeleteMsg "RU" "abc"
|
||||
s ->: b $ SendMsg "SU" "welcome" -- welcome message
|
||||
b ->: r $ PushMsg "RU" Message {msgId = "def", msg = "welcome"}
|
||||
r ->: b $ DeleteMsg "RU" "def"
|
||||
-- The connection is established ("Secured"), sending the message
|
||||
s ->: b $ SendMsg "SU" "hello there"
|
||||
b ->: r $ PushMsg "RU" Message {msgId = "ghi", msg = "hello there"}
|
||||
r ->: b $ DeleteMsg "RU" "ghi"
|
||||
r ->: b $ Unsubscribe "RU"
|
||||
@ -1,155 +0,0 @@
|
||||
{-# LANGUAGE DataKinds #-}
|
||||
{-# LANGUAGE DuplicateRecordFields #-}
|
||||
{-# LANGUAGE FlexibleInstances #-}
|
||||
{-# LANGUAGE OverloadedStrings #-}
|
||||
{-# LANGUAGE TypeOperators #-}
|
||||
{-# OPTIONS_GHC -fno-warn-orphans #-}
|
||||
|
||||
module Simplex.Messaging.ServerAPI
|
||||
( ServerAPI,
|
||||
serverApiIntro,
|
||||
serverApiExtra,
|
||||
)
|
||||
where
|
||||
|
||||
import Control.Lens
|
||||
import Data.Function ()
|
||||
import Servant
|
||||
import Servant.Docs
|
||||
import Simplex.Messaging.Types
|
||||
|
||||
type ServerAPI =
|
||||
CreateConnection
|
||||
:<|> SecureConnection
|
||||
:<|> DeleteConnection
|
||||
:<|> GetMessages
|
||||
:<|> DeleteMessage
|
||||
:<|> SendMessage
|
||||
|
||||
type CreateConnection =
|
||||
"connection" :> ReqBody '[JSON] CreateConnRequest
|
||||
:> PostCreated '[JSON] CreateConnResponse
|
||||
|
||||
type SecureConnection =
|
||||
"connection" :> Capture "connectionId" Base64EncodedString
|
||||
:> ReqBody '[JSON] SecureConnRequest
|
||||
:> Put '[JSON] NoContent
|
||||
|
||||
type DeleteConnection =
|
||||
"connection" :> Capture "connectionId" Base64EncodedString
|
||||
:> Delete '[JSON] NoContent
|
||||
|
||||
type GetMessages =
|
||||
"connection" :> Capture "connectionId" Base64EncodedString
|
||||
:> "messages"
|
||||
:> QueryParam "fromMessageId" (Maybe Base64EncodedString)
|
||||
:> Get '[JSON] MessagesResponse
|
||||
|
||||
type DeleteMessage =
|
||||
"connection" :> Capture "connectionId" Base64EncodedString
|
||||
:> "messages"
|
||||
:> Capture "messageId" Base64EncodedString
|
||||
:> Delete '[JSON] NoContent
|
||||
|
||||
type SendMessage =
|
||||
"connection" :> Capture "senderConnectionId" Base64EncodedString
|
||||
:> "messages"
|
||||
:> ReqBody '[JSON] SendMessageRequest
|
||||
:> PostCreated '[JSON] NoContent
|
||||
|
||||
-- API docs
|
||||
serverApiIntro :: DocIntro
|
||||
serverApiIntro =
|
||||
DocIntro
|
||||
"Simplex messaging protocol REST API"
|
||||
[ "This document lists all required REST endpoints of simplex messaging API.",
|
||||
"Also see [Simplex messaging protocol implementation](simplex-messaging-implementation.md) for more details."
|
||||
]
|
||||
|
||||
serverApiExtra :: ExtraInfo ServerAPI
|
||||
serverApiExtra =
|
||||
info
|
||||
(Proxy :: Proxy CreateConnection)
|
||||
"Create connection"
|
||||
[]
|
||||
<> info
|
||||
(Proxy :: Proxy SecureConnection)
|
||||
"Secure connection"
|
||||
[]
|
||||
<> info
|
||||
(Proxy :: Proxy DeleteConnection)
|
||||
"Delete connection"
|
||||
[]
|
||||
<> info
|
||||
(Proxy :: Proxy GetMessages)
|
||||
"Get messages"
|
||||
[]
|
||||
<> info
|
||||
(Proxy :: Proxy DeleteMessage)
|
||||
"Delete message"
|
||||
[]
|
||||
<> info
|
||||
(Proxy :: Proxy SendMessage)
|
||||
"Send message"
|
||||
[]
|
||||
where
|
||||
info p title comments =
|
||||
extraInfo p $ defAction & notes <>~ [DocNote title comments]
|
||||
|
||||
instance ToCapture (Capture "connectionId" String) where
|
||||
toCapture _ =
|
||||
DocCapture
|
||||
"connectionId"
|
||||
"Recipient connection ID - unique connection ID to be used by connection recipient"
|
||||
|
||||
instance ToCapture (Capture "senderConnectionId" String) where
|
||||
toCapture _ =
|
||||
DocCapture
|
||||
"senderConnectionId"
|
||||
"Sender connection ID - unique connection ID to be used by connection sender"
|
||||
|
||||
instance ToCapture (Capture "messageId" String) where
|
||||
toCapture _ =
|
||||
DocCapture
|
||||
"messageId"
|
||||
"Message ID - unique message ID to be used by connection recipient"
|
||||
|
||||
instance ToParam (QueryParam "fromMessageId" (Maybe Base64EncodedString)) where
|
||||
toParam _ =
|
||||
DocQueryParam
|
||||
"fromMessageId"
|
||||
["message ID, e.g., `p8PCiGPZ`"]
|
||||
"if set, the server will respond with the messages received starting from the message with server message ID (unique per server) passed in this parameter."
|
||||
Normal
|
||||
|
||||
instance ToSample CreateConnRequest where
|
||||
toSamples _ = singleSample $ CreateConnRequest "BODbZxmtKUUF1l8pj4nVjQ"
|
||||
|
||||
instance ToSample CreateConnResponse where
|
||||
toSamples _ = singleSample $ CreateConnResponse "Qxz93A" "N9pA3g"
|
||||
|
||||
instance ToSample SecureConnRequest where
|
||||
toSamples _ = singleSample $ SecureConnRequest "XPaVEVNunkYKqqK0dnAT5Q"
|
||||
|
||||
dummyMessage :: Message
|
||||
dummyMessage =
|
||||
Message
|
||||
{ msgId = "p8PCiGPZ",
|
||||
ts = "2020-03-15T19:58:33.695Z",
|
||||
msg = "OQLMXoEA4iv-aR46puPJuY1Rdoc1KY0gfq8oElJwtAs"
|
||||
}
|
||||
|
||||
instance ToSample MessagesResponse where
|
||||
toSamples _ =
|
||||
singleSample $
|
||||
MessagesResponse
|
||||
{ messages = [dummyMessage],
|
||||
nextMessageId = Nothing
|
||||
}
|
||||
|
||||
instance ToSample SendMessageRequest where
|
||||
toSamples _ =
|
||||
singleSample $
|
||||
SendMessageRequest
|
||||
{ msg = "OQLMXoEA4iv-aR46puPJuY1Rdoc1KY0gfq8oElJwtAs"
|
||||
}
|
||||
@ -1,77 +0,0 @@
|
||||
{-# LANGUAGE DeriveAnyClass #-}
|
||||
{-# LANGUAGE DeriveGeneric #-}
|
||||
{-# LANGUAGE DuplicateRecordFields #-}
|
||||
|
||||
module Simplex.Messaging.Types where
|
||||
|
||||
import Data.Aeson
|
||||
import Data.String
|
||||
import Data.Text
|
||||
import GHC.Generics
|
||||
|
||||
newtype CreateConnRequest = CreateConnRequest
|
||||
{ recipientKey :: Key
|
||||
}
|
||||
deriving (Eq, Show, Generic, ToJSON, FromJSON)
|
||||
|
||||
instance IsString CreateConnRequest where
|
||||
fromString = CreateConnRequest
|
||||
|
||||
data CreateConnResponse = CreateConnResponse
|
||||
{ recipientId :: String,
|
||||
senderId :: String
|
||||
}
|
||||
deriving (Show, Generic, ToJSON, FromJSON)
|
||||
|
||||
newtype SecureConnRequest = SecureConnRequest
|
||||
{ senderKey :: Key
|
||||
}
|
||||
deriving (Show, Generic, ToJSON, FromJSON)
|
||||
|
||||
instance IsString SecureConnRequest where
|
||||
fromString = SecureConnRequest
|
||||
|
||||
data Message = Message
|
||||
{ msgId :: MessageId,
|
||||
ts :: TimeStamp,
|
||||
msg :: Encrypted -- TODO make it Text
|
||||
}
|
||||
deriving (Show, Generic, ToJSON, FromJSON)
|
||||
|
||||
data MessagesResponse = MessagesResponse
|
||||
{ messages :: [Message],
|
||||
nextMessageId :: Maybe Base64EncodedString
|
||||
}
|
||||
deriving (Show, Generic, ToJSON, FromJSON)
|
||||
|
||||
newtype SendMessageRequest = SendMessageRequest
|
||||
{ msg :: Base64EncodedString
|
||||
}
|
||||
deriving (Show, Generic, ToJSON, FromJSON)
|
||||
|
||||
instance IsString SendMessageRequest where
|
||||
fromString = SendMessageRequest
|
||||
|
||||
data Invitation = Invitation
|
||||
{ connId :: ConnId,
|
||||
brokerUri :: Text,
|
||||
encryptKey :: PublicKey
|
||||
}
|
||||
|
||||
type Key = Base64EncodedString -- deprecated, not to be used
|
||||
|
||||
type PublicKey = Base64EncodedString
|
||||
|
||||
type PrivateKey = Base64EncodedString
|
||||
|
||||
type ConnId = Base64EncodedString
|
||||
|
||||
type SenderConnId = Base64EncodedString
|
||||
|
||||
type MessageId = Base64EncodedString
|
||||
|
||||
type Encrypted = Base64EncodedString
|
||||
|
||||
type Base64EncodedString = String
|
||||
|
||||
type TimeStamp = String
|
||||
@ -1,67 +0,0 @@
|
||||
# This file was automatically generated by 'stack init'
|
||||
#
|
||||
# Some commonly used options have been documented as comments in this file.
|
||||
# For advanced use and comprehensive documentation of the format, please see:
|
||||
# https://docs.haskellstack.org/en/stable/yaml_configuration/
|
||||
|
||||
# Resolver to choose a 'specific' stackage snapshot or a compiler version.
|
||||
# A snapshot resolver dictates the compiler version and the set of packages
|
||||
# to be used for project dependencies. For example:
|
||||
#
|
||||
# resolver: lts-3.5
|
||||
# resolver: nightly-2015-09-21
|
||||
# resolver: ghc-7.10.2
|
||||
#
|
||||
# The location of a snapshot can be provided as a file or url. Stack assumes
|
||||
# a snapshot provided as a file might change, whereas a url resource does not.
|
||||
#
|
||||
# resolver: ./custom-snapshot.yaml
|
||||
# resolver: https://example.com/snapshots/2018-01-01.yaml
|
||||
resolver: lts-15.11
|
||||
|
||||
# User packages to be built.
|
||||
# Various formats can be used as shown in the example below.
|
||||
#
|
||||
# packages:
|
||||
# - some-directory
|
||||
# - https://example.com/foo/bar/baz-0.0.2.tar.gz
|
||||
# subdirs:
|
||||
# - auto-update
|
||||
# - wai
|
||||
packages:
|
||||
- .
|
||||
# Dependency packages to be pulled from upstream that are not in the resolver.
|
||||
# These entries can reference officially published versions as well as
|
||||
# forks / in-progress versions pinned to a git hash. For example:
|
||||
#
|
||||
# extra-deps:
|
||||
# - acme-missiles-0.3
|
||||
# - git: https://github.com/commercialhaskell/stack.git
|
||||
# commit: e7b331f14bcffb8367cd58fbfc8b40ec7642100a
|
||||
#
|
||||
extra-deps:
|
||||
- freer-indexed-0.1.0.0@sha256:b247be91b8ad2154fe1a514dec7c6a2553281d89325f0bc213d1d832d4c1a0e9,3007
|
||||
- protocol-0.1.0.1@sha256:1e95952ba8fc17bbd6c1e4cf1e2993590a90ab938c30c6e530ad0f3ba4ec1a8c,1598
|
||||
# Override default flag values for local packages and extra-deps
|
||||
# flags: {}
|
||||
|
||||
# Extra package databases containing global packages
|
||||
# extra-package-dbs: []
|
||||
|
||||
# Control whether we use the GHC we find on the path
|
||||
# system-ghc: true
|
||||
#
|
||||
# Require a specific version of stack, using version ranges
|
||||
# require-stack-version: -any # Default
|
||||
# require-stack-version: ">=2.1"
|
||||
#
|
||||
# Override the architecture used by stack, especially useful on Windows
|
||||
# arch: i386
|
||||
# arch: x86_64
|
||||
#
|
||||
# Extra directories used by stack for building
|
||||
# extra-include-dirs: [/path/to/dir]
|
||||
# extra-lib-dirs: [/path/to/dir]
|
||||
#
|
||||
# Allow a newer minor version of GHC than the snapshot specifies
|
||||
# compiler-check: newer-minor
|
||||
@ -1 +0,0 @@
|
||||
{-# OPTIONS_GHC -F -pgmF doctest-driver-gen -optF src -optF -XBlockArguments -optF -XDuplicateRecordFields -optF -XLambdaCase -optF -XNamedFieldPuns -optF -XOverloadedStrings -optF -XRecordWildCards -optF -XAllowAmbiguousTypes -optF -XConstraintKinds -optF -XDeriveAnyClass -optF -XEmptyCase -optF -XFlexibleContexts -optF -XFlexibleInstances -optF -XGADTs -optF -XInstanceSigs -optF -XMultiParamTypeClasses -optF -XNoStarIsType -optF -XScopedTypeVariables -optF -XStandaloneDeriving -optF -XTemplateHaskell -optF -XTypeApplications -optF -XTypeFamilies -optF -XTypeInType -optF -XTypeOperators -optF -XUndecidableInstances #-}
|
||||
@ -1,71 +0,0 @@
|
||||
sequenceDiagram
|
||||
participant A as Alice
|
||||
participant AA as Alice's<br>agent
|
||||
participant AS as Alice's<br>server
|
||||
participant BS as Bob's<br>server
|
||||
participant BA as Bob's<br>agent
|
||||
participant B as Bob
|
||||
|
||||
note over AA, BA: status (receive/send): NONE/NONE
|
||||
|
||||
note over A, AA: 1. request connection from agent
|
||||
A ->> AA: NEW: create<br>duplex connection
|
||||
|
||||
note over AA, AS: 2. create Alice's SMP queue
|
||||
AA ->> AS: NEW: create SMP queue
|
||||
AS ->> AA: IDS: SMP queue IDs
|
||||
note over AA: status: NEW/NONE
|
||||
|
||||
AA ->> A: INV: invitation<br>to connect
|
||||
note over AA: status: PENDING/NONE
|
||||
|
||||
note over A, B: 3. out-of-band invitation
|
||||
A ->> B: OOB: invitation to connect
|
||||
|
||||
note over BA, B: 4. accept connection
|
||||
B ->> BA: JOIN:<br>via invitation info
|
||||
note over BA: status: NONE/NEW
|
||||
|
||||
note over BA, AA: 5. establish Alice's SMP queue
|
||||
BA ->> AS: SEND: KEY: sender's server key
|
||||
note over BA: status: NONE/CONFIRMED
|
||||
activate BA
|
||||
AS ->> AA: MSG: KEY: sender's server key
|
||||
note over AA: status: CONFIRMED/NONE
|
||||
AA ->> AS: KEY: secure queue
|
||||
note over AA: status: SECURED/NONE
|
||||
|
||||
BA ->> AS: SEND: HELLO: try sending until successful
|
||||
deactivate BA
|
||||
note over BA: status: NONE/ACTIVE
|
||||
AS ->> AA: MSG: HELLO: Alice's agent<br>knows Bob can send
|
||||
note over AA: status: ACTIVE/NONE
|
||||
|
||||
note over BA, BS: 6. create Bob's SMP queue
|
||||
BA ->> BS: NEW: create SMP queue
|
||||
BS ->> BA: IDS: SMP queue IDs
|
||||
note over BA: status: NEW/ACTIVE
|
||||
|
||||
note over AA, BA: 7. establish Bob's SMP queue
|
||||
BA ->> AS: SEND: REPLY: invitation to the connect
|
||||
note over BA: status: PENDING/ACTIVE
|
||||
AS ->> AA: MSG: REPLY: invitation<br>to connect
|
||||
note over AA: status: ACTIVE/NEW
|
||||
|
||||
AA ->> BS: SEND: KEY: sender's server key
|
||||
note over AA: status: ACTIVE/CONFIRMED
|
||||
activate AA
|
||||
BS ->> BA: MSG: KEY: sender's server key
|
||||
note over BA: status: CONFIRMED/ACTIVE
|
||||
BA ->> BS: KEY: secure queue
|
||||
note over BA: status: SECURED/ACTIVE
|
||||
|
||||
AA ->> BS: SEND: HELLO: try sending until successful
|
||||
deactivate AA
|
||||
note over AA: status: ACTIVE/ACTIVE
|
||||
BS ->> BA: MSG: HELLO: Bob's agent<br>knows Alice can send
|
||||
note over BA: status: ACTIVE/ACTIVE
|
||||
|
||||
note over A, B: 8. notify users about connection success
|
||||
AA ->> A: CON: connected
|
||||
BA ->> B: CON: connected
|
||||
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 31 KiB |
@ -1,40 +0,0 @@
|
||||
sequenceDiagram
|
||||
participant A as Alice's app
|
||||
participant SA as Alice's servers <br> (connections CAi)
|
||||
participant SB as Bob's servers <br> (connections CBi)
|
||||
participant B as Bob's app
|
||||
|
||||
note over A, SA: 1. initiate duplex connection
|
||||
A ->> SA: create n connections CAi (send RKAi)
|
||||
SA ->> A: receive connections URIs (RUAi and SUAi)
|
||||
A ->> SA: subscribe to messages from CAi
|
||||
|
||||
A -->> B: 2. send secure message with connections "public" keys (EKAi) and URIs (SUAi)
|
||||
|
||||
note over B: 3. accept Alice's <br> duplex connection
|
||||
B ->> SB: create n connections CBi (send RKBi)
|
||||
SB ->> B: receive connections URIs (RUBi and SUBi)
|
||||
B ->> SB: subscribe to messages from CBi
|
||||
note over B: prepare msgs with: <br> - sender key SKAi <br> - Bob's profile <br> - EKBi and SUBi
|
||||
B ->> SA: accept CAi (send EKAi-encrypted messages to CAi)
|
||||
|
||||
note over A: 4. Add Bob's duplex <br> connection
|
||||
SA ->> A: receive Bob's app messages
|
||||
note over A: identify Bob and <br> confirm connection
|
||||
A ->> SA: secure connections CAi with Bob's SKAi
|
||||
note over A: prepare msgs with: <br> - sender key SKBi <br> - Alice's profile <br> - CAi confirmation
|
||||
A ->> SB: accept CBi (send EKBi-encrypted messages to CBi)
|
||||
note over A: Bob's duplex conn. <br> "pending"
|
||||
|
||||
note over B: 5. Add Alice's duplex <br> connection
|
||||
SB ->> B: receive Alice's app messages
|
||||
B ->> SB: secure connections CBi with Alice's SKBi
|
||||
B ->> SA: send "welcome" message to duplex connection (via all CAi)
|
||||
note over B: Alice's duplex conn. <br> "pending"
|
||||
|
||||
SA ->> A: 6. receive Bob's "welcome" message
|
||||
note over A: Bob's duplex conn. <br> "established"
|
||||
A ->> SB: send "welcome" message to duplex connection (via all CBi)
|
||||
|
||||
SB ->> B: 7. receive Alice's "welcome" message
|
||||
note over B: Alice's duplex conn. <br> "established"
|
||||
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 24 KiB |
@ -1,21 +0,0 @@
|
||||
sequenceDiagram
|
||||
participant A as Alice's app
|
||||
participant SA as Alice's servers <br> (connections CAi)
|
||||
participant SB as Bob's servers <br> (connections CBi)
|
||||
participant B as Bob's app
|
||||
|
||||
note over A: 1. Alice writes msg <br> to Bob in the app: <br> - message ID <br> - timestamp <br> - message body
|
||||
note over A: sign and encrypt <br> message version <br> for each conn. CBi
|
||||
A ->> SB: send message versions to connections CBi on Bob's servers
|
||||
|
||||
SB ->> B: 2. retrive message versions from CBi
|
||||
note over B: decrypt and verify <br> message versions
|
||||
note over B: discard duplicates <br> and show in chat <br> with Alice
|
||||
|
||||
note over B: 3. prepare msg <br> "message received": <br> - new message ID <br> - msg correlation ID <br> - receipt timestamp
|
||||
note over B: sign and encrypt <br> message version <br> for each conn. CAi
|
||||
B ->> SA: send message versions to connections CAi on Alice's servers
|
||||
|
||||
SA ->> A: 4. retrive message versions from CAi
|
||||
note over A: decrypt and verify <br> message versions
|
||||
note over A: discard duplicates <br> and show sent msg <br> as delivered <br> in chat with Bob
|
||||
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 20 KiB |
@ -1,20 +0,0 @@
|
||||
sequenceDiagram
|
||||
participant B as Bob (sender)
|
||||
participant S as server (queue RID)
|
||||
participant A as Alice (recipient)
|
||||
|
||||
note over A: creating queue<br>("public" key RK<br>for msg retrieval)
|
||||
A ->> S: 1. create queue ("NEW")
|
||||
S ->> A: respond with queue RID and SID ("IDS")
|
||||
|
||||
note over A: out-of-band msg<br>(sender's queue SID<br>and "public" key EK<br>to encrypt msgs)
|
||||
A -->> B: 2. send out-of-band message
|
||||
|
||||
note over B: confirm queue<br>("public" key SK for<br>sending messages<br>and any optional<br>info encrypted with<br>"public" key EK)
|
||||
B ->> S: 3. confirm queue ("SEND" command not signed)
|
||||
|
||||
S ->> A: 4. deliver Bob's message
|
||||
note over A: decrypt message<br>("private" key EK)
|
||||
A ->> S: 5. secure queue ("KEY", RK-signed)
|
||||
|
||||
note over S: 6. simplex<br>queue RID<br>is ready to use!
|
||||
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 13 KiB |
@ -1,26 +0,0 @@
|
||||
sequenceDiagram
|
||||
participant S as sender (client)
|
||||
participant A as transport
|
||||
participant Q as pubsub
|
||||
participant P as transport
|
||||
participant R as receiver (client)
|
||||
note over R: sign subscription (1)
|
||||
R ->> P: subscribe to messages
|
||||
note over P: verify subscriber (1)
|
||||
alt subscriber verified?
|
||||
P -->> Q: subscribe
|
||||
else
|
||||
P ->> R: reject subscription
|
||||
end
|
||||
note over S: sign message (2)
|
||||
S ->> A: send message
|
||||
note over A: verify sender (2)
|
||||
alt sender verified?
|
||||
A -->> Q: queue message
|
||||
activate Q
|
||||
else
|
||||
A ->> S: reject message
|
||||
end
|
||||
Q -->> P: take message
|
||||
deactivate Q
|
||||
P ->> R: deliver message
|
||||
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 13 KiB |
@ -1,10 +0,0 @@
|
||||
sequenceDiagram
|
||||
participant B as Bob (sender)
|
||||
participant S as server (queue RID)
|
||||
participant A as Alice (recipient)
|
||||
|
||||
note over B: encrypt message<br>("public" key EK)
|
||||
B ->> S: 1. send message to SID (SK-signed command)
|
||||
|
||||
S ->> A: 2. receive messages from RID (RK-signed subscription)
|
||||
note over A: decrypt message<br>("private" key EK)
|
||||
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 7.7 KiB |
@ -1,11 +0,0 @@
|
||||
graph LR
|
||||
VS{{"verify sender (SK)"}}
|
||||
VR{{"verify recipient (RK)"}}
|
||||
|
||||
S(sender) -->|msg| VS
|
||||
subgraph "server (queue RID, SID)"
|
||||
VS --> DB[("storage")]
|
||||
DB --> VR
|
||||
end
|
||||
R(recipient) -->|"1) sub"| VR
|
||||
VR -->|"2) msg"| R
|
||||
File diff suppressed because one or more lines are too long
|
Before Width: | Height: | Size: 12 KiB |
214
graph-chat.md
214
graph-chat.md
@ -1,214 +0,0 @@
|
||||
# Graph-chat protocol
|
||||
|
||||
A generic chat protocol for client applications that communicate via simplex messaging protocol
|
||||
|
||||
|
||||
## Problems of the existing chat platforms and protocols
|
||||
|
||||
- Dependency on a single company/server to access and use chat. That creates implications for chat privacy, user profile resilience and data ownership.
|
||||
- Visiblity of user profile information to chat system and other chat users. Chat users have limited control as to who can see and find their profile.
|
||||
- Visibility of user contacts graph to chat server.
|
||||
- [E2EE][1] can be compromised by [MITM][2] attack (see [simplex messaging protocol][3]).
|
||||
- Identity related problems (also see [simplex messaging protocol][3]).
|
||||
|
||||
|
||||
## Graph-chat protocol abstract
|
||||
|
||||
TODO
|
||||
|
||||
|
||||
## Duplex connection
|
||||
|
||||
Majority of chat scenarios requires duplex (bi-directional) connections between participants. Graph-chat protocol uses multiple simplex (unidirectional) connections created on multiple simplex messaging servers to implement duplex connections.
|
||||
|
||||
Each duplex connection consists of one or multiple, for redundancy, pairs of simplex connections to connect chat participants or devices of the same participant - it is used for "contacts", "devices", "group participants", etc. For practical purposes of redundancy, chat clients can use 2-4 pairs of simplex connections.
|
||||
|
||||
The process described below establishes a duplex connection between Alice and Bob that has `n` simplex connections `CAi` (where `1 <= i <= n`) from Bob to Alice (created by Alice on her servers) and `n` simplex connections `CBi` (where `1 <= i <= n`) from Alice to Bob (created by Bob on his servers).
|
||||
|
||||
The following symbols are used below:
|
||||
- simplex connections:
|
||||
- `CAi` - Alice's simplex connection number `i` (out of `n`) allowing Bob to send messages to Alice.
|
||||
- `CBi` - Bob's simplex connection number `i` (out of `n`) allowing Alice to send messages to Bob.
|
||||
- keys created for Alice's connections:
|
||||
- `RUAi` - server-generated recipient connection URI of `CAi` (to be used by Alice to retrieve messages).
|
||||
- `EKAi` - Alice's assymetric key pair used:
|
||||
- by Bob to encrypt and by Alice to decrypt messages from Bob sent via `CAi`.
|
||||
- by Alice to sign and Bob to verify messages from Alice sent via `CBi`.
|
||||
- `SUAi` - server-generated sender connection URI of `CAi` (to be used by Bob to send messages).
|
||||
- `RKAi` - Alice's recipient key of `CAi`.
|
||||
- `SKAi` - Bob's sender key of `CAi`.
|
||||
- keys created for Bob's connections
|
||||
- `RUBi` - server-generated recipient connection URI of `CBi` (to be used by Bob to retrive messages).
|
||||
- `EKBi` - Bob's assymetric key pair used for:
|
||||
- Alice to encrypt and Bob to decrypt messages from Alice sent via `CBi`.
|
||||
- Bob to sign and Alice to verify messages from Bob sent via `CAi`.
|
||||
- `SUBi` - server-generated sender connection URI of `CBi` (to be used by Alice to send messages).
|
||||
- `RKBi` - Bob's recipient key of `CBi`.
|
||||
- `SKBi` - Alice's sender key of `CBi`.
|
||||
|
||||
|
||||
### Creating duplex connection
|
||||
|
||||
To create a duplex connection initiated by Alice, Alice's and Bob's apps follow these steps:
|
||||
|
||||
1. Alice's app initiates duplex connection:
|
||||
1. it creates `n` simplex connections `CAi` (step 1 in [simplex messaging][3]) that are defined by recipient URIs `RUAi` and have:
|
||||
- client-generated:
|
||||
- Alice's asymmetric key pairs `EKAi` to encrypt messages.
|
||||
- recipient keys `RKAi`.
|
||||
- server-generated:
|
||||
- sender URIs `SUAi`.
|
||||
2. optionally, Alice's app subsribes to receive messages from these new connections `CAi` ([simplex messaging protocol implementation][4] defines protocol to be used for subscriptions).
|
||||
2. Alice's app sends a secure message to Bob's app (step 2 in [simplex messaging][3]):
|
||||
1. it prepares the message with the information needed to establish all connections `CAi`, including all encryption keys `EKAi` and sender connection URIs (`SUAi`).
|
||||
2. depending on the communication scenario, Alice's app sends this message to Bob's app in one of available secure ways (either out-of-band or via available secure duplex connection(s) - see [Duplex connection security level](#TODO)), depending on communication scenario:
|
||||
- if Bob is a new contact, the information is presented as a visual code (e.g. QR code(s)) to Bob's app - as out-of-band message needed to establish connections `CAi` (see [simplex messaging protocol][3] and [Adding direct contact](#adding-direct-contact)).
|
||||
- if Bob is added to group chat with Alice by some contact of Alice or Bob, this information can be passed through all possible chains of contacts between Alice and Bob in the group (to minimise the risk of MITM attack) (see [Group chat](#TODO)).
|
||||
- if Alice adds Bob as a contact via Bob's trusted contact John, who also has Alice as a trusted contact, this information will be passed via John (who has secure duplex connections with both Alice and Bob), in the same way as with Group chat (see [Trusted contacts](#TODO)).
|
||||
- if Alice already has Bob as a contact, and she wants to create a separate off-the-record chat with him, this information will be passed via their existing connection (see [Off-the-record chat](#TODO)).
|
||||
- etc. In all cases, the protocol defines the most secure possible way to pass the out-of-band (from the point of view of the new connections) message required by [simplex messaging protocol][3] to create simplex connections.
|
||||
3. Bob's app accepts duplex connection with Alice:
|
||||
1. it receives the message from Alice's app, in a way defined by a specific chat scenario.
|
||||
2. it interprets the received information as simplex messaging protocol out-of-band messages to accept all simplex connections `CAi`.
|
||||
3. it creates `n` new simplex connections `CBi` on Bob's servers defined by recipient URIs `RUBi` and have:
|
||||
- client-generated:
|
||||
- Bob's asymmetric key pairs `EKBi` to encrypt messages.
|
||||
- recipient keys `RKBi`.
|
||||
- server-generated:
|
||||
- sender URIs `SUBi`.
|
||||
4. optionally, Bob's app subsribes to receive messages from these new connection `CBi` (see [simplex messaging protocol implementation][4]).
|
||||
5. it proceeds with accepting Alice's app connections `CAi` (step 3 in [simplex messaging protocol][3]).
|
||||
6. in response to each connection `CAi`, as optional information, Bob's app includes:
|
||||
- Bob's user profile (that is only stored in graph-chat client and not visible to any server)
|
||||
- information to establish connection `CBi`:
|
||||
- encryption key `EKBi`.
|
||||
- sender connection URIs (`SUBi`).
|
||||
7. his app now sends the unsigned requests to Alice's connections `CAi` (step 3.4 in [simplex messaging protocol][3]), to both confirm the connections `CAi` and to propose the new connections `CBi`. As each message is encrypted by the key `EKAi` of the connection `CAi` that only Alice can decrypt, it is safe to send it - from simplex messaging server point of view it is an out-of-band message.
|
||||
4. Alice's app adds Bob's duplex connection:
|
||||
1. it receives the messages from Bob via connections `CAi` (step 4 in [simplex messaging protocol][3]).
|
||||
2. depending on chat scenario, Bob is identified and confirmed:
|
||||
- for new contact, Alice may visually identify Bob's user profile and accepts Bob as a contact.
|
||||
- for group participant, Alice's app will match known Bob's user profile ID with received user profile ID (that is only visible to the clients apps that have this profile).
|
||||
3. it secures the connections `CAi` with keys `SKAi` received from Bob - the connections are now established (step 5 in [simplex messaging protocol][3]).
|
||||
4. it accepts the connections `CBi`, including in the response to Bob's server Alice's user profile and (as the additional information) the confirmation that the connections `CAi` are secured and can be used (step 3 in [simplex messaging protocol][3]).
|
||||
5. it sends the unsigned messages via connections `CBi`.
|
||||
6. it adds Bob's duplex connection to the list of available duplex connections as "pending" (Alice cannot yet send messages to Bob, but Bob already can send messages to Alice). Possibly, the status of duplex connection can indicate that Bob already can send messages to Alice.
|
||||
5. Bob's app adds duplex connection with Alice:
|
||||
1. it receives the initial messages via connections `CBi`.
|
||||
2. it secures the connections `CBi` - they are now established as well (step 5 in [simplex messaging protocol][3]).
|
||||
3. it adds duplex connection with Alice in the list of available duplex connections as "pending" (to indicate that Alice cannot yet send messages). Possibly, the status of duplex connection can indicate that Bob already can send messages to Alice.
|
||||
4. it sends a special message (message type "welcome") to Alice's app via duplex connection (i.e., via all connections `CAi`) to confirm that adding Alice's contact is completed (see [Sending messages via duplex connection](#TODO)).
|
||||
6. Alice's app finalises adding duplex connection with Bob:
|
||||
1. it receives "welcome" message from Bob's app via duplex connection.
|
||||
2. it changes Bob's duplex connection status to "established".
|
||||
3. it sends a special "welcome" message to Bob's app via duplex connection.
|
||||
7. Bob's app finalises adding duplex connection with Alice:
|
||||
1. it receives "welcome" message from Alice's app via duplex connection.
|
||||
2. it changes Alice's duplex connection status "established".
|
||||
|
||||
**Creating duplex connection between Alice and Bob:**
|
||||
|
||||
|
||||
|
||||
|
||||
### Sending message via duplex connection
|
||||
|
||||
When Alice sends the message to Bob via the duplex connection, they follow these steps:
|
||||
|
||||
1. Alice sends the message to Bob in the app:
|
||||
1. her app prepares the message, including:
|
||||
- client-generated message ID (unique per duplex connection).
|
||||
- client timestamp.
|
||||
- message body.
|
||||
2. her app prepares a separate version of the message for each connection `CBi`, by signing each version of the message with the corresponding key `EKAi` and encrypting it with `EKBi`.
|
||||
3. her app sends all copies of the message to corresponding connections `CBi`.
|
||||
2. Bob's app receives the message from Alice:
|
||||
1. it retrieves all versions of the message via all connections `CBi` (they can arrive at different time and possibly out of order with other messages).
|
||||
2. it decrypts each version with `EKBi` and verifies the signature with `EKAi`.
|
||||
3. the first successfully decrypted message version is added to the Bob's chat with Alice and notification can be shown to Bob; if message verification failed it is marked as "unverified" in the chat.
|
||||
4. all subsequently decrypted and verified copies are discarded.
|
||||
- if some of the decryptions or verifications fail, the corresponding connection is marked as "possibly compromised" and has to be replaced by the app with another connection.
|
||||
- if decryption or verification fails for all connections `CBi`, Alice's contact is marked as "compromised".
|
||||
3. Bob's app sends "message received" to Alice's app:
|
||||
1. it prepares a special "message received" message, including:
|
||||
- client-generated message ID (unique per duplex connection).
|
||||
- correlation ID of the message received from Alice.
|
||||
- client timestamp of the message reception.
|
||||
2. it prepares a separate version of the message for each connection `CAi`, by signing each version of the message with the corresponding key `EKBi` and encrypting it with `EKAi`.
|
||||
3. it sends all copies of the message to corresponding connections `CAi`.
|
||||
4. Alice's app receives "message received" from Bob's app:
|
||||
1. it retrieves all versions of the "message received" message via all connections `CAi` (they can arrive at different time and possibly out of order with other messages).
|
||||
2. it decrypts each version with `EKAi` and verifies the signature with `EKBi`.
|
||||
3. once the first version is successfully decrypted and verified, the previosly sent message in the Alice's chat with Bob is marked as delivered.
|
||||
4. all subsequently decrypted and verified copies are discarded.
|
||||
- if some of the decryptions or verifications fail, the corresponding connection is marked as "possibly compromised" and has to be replaced by the app with another connection.
|
||||
- if decryption or verification fails for all connections `CAi`, Bob's contact is marked as "compromised".
|
||||
|
||||
**Sending message from Alice to Bob via duplex connection:**
|
||||
|
||||
|
||||
|
||||
|
||||
## Adding direct contact
|
||||
|
||||
"Direct contact" is a term used for a duplex connection with another chat user established directly, not via another user. Establishing contact requires sending an out-of-band message - "visual code" (e.g. QR code(s)) is used for this purpose.
|
||||
|
||||
For example, Alice and Bob want to have a conversation in chat app, exchanging messages with each other. They both have graph-chat client and access to several simplex messaging servers (see [simplex messaging protocol][3]) that they can use to receive messages, and their graph-chat clients are configured to use these servers.
|
||||
|
||||
To chat in the app Alice needs to add Bob as "direct contact" to her contacts in the app.
|
||||
|
||||
1. Alice initiates adding "direct contact" in her graph-chat client app.
|
||||
2. Alice shares "visual code" (e.g. QR code(s)) with Bob:
|
||||
1. her app prepares secure message to establish duplex connection with Bob's app (step 1 in [Creating duplex connection](#creating-duplex-connection)).
|
||||
2. her app prepares and displays a visual code with this message (step 2 in [Creating duplex connection](#creating-duplex-connection)).
|
||||
3. Alice now can share this visual code with Bob, either in person or via a video call (see [simplex messaging protocol][3]).
|
||||
3. Bob reads "visual code" that Alice prepared via his app:
|
||||
1. he initiates adding "direct contact" via visual code in his graph-chat client app.
|
||||
2. his app interprets this visual code as secure message required to accept duplex connection with Alice and proceeds with creating duplex connection (step 3 in [Creating duplex connection](#creating-duplex-connection)).
|
||||
4. Alice's app adds Bob as "direct contact":
|
||||
1. it proceeds with creating duplex connection.
|
||||
2. once "pending" duplex connection with Bob's app is created in Alice's app, Bob is added as "direct contact" with the status "pending" in Alice's app (step 4 in [Creating duplex connection](#creating-duplex-connection)).
|
||||
5. Bob's app adds Alice as "direct contact":
|
||||
1. it proceeds with creating duplex connection.
|
||||
2. once "pending" duplex connection with Alice's app is created in Bob's app, Alice is added as "direct contact" with the status "pending" in Bob's app (step 5 in [Creating duplex connection](#creating-duplex-connection)).
|
||||
6. Alice's app finalises adding Bob as "direct contact":
|
||||
1. it finalises adding duplex connection with Bob's app (step 6 in [Creating duplex connection](#creating-duplex-connection)).
|
||||
2. it changes Bob's "direct contact" status to "established".
|
||||
7. Bob's app finalises adding Alice as "direct contact":
|
||||
1. it finalises adding duplex connection with Alice's app (step 7 in [Creating duplex connection](#creating-duplex-connection)).
|
||||
2. it changes Alice's "direct contact" status to "established".
|
||||
|
||||
|
||||
## Connection and message types used in graph-chat protocol
|
||||
|
||||
##### Duplex connections
|
||||
|
||||
TODO
|
||||
|
||||
- "contact" - can be of type "person", "bot", "device", "organisation".
|
||||
- "group-participant" - connection to another group participant that was established via the chain of other contacts in the group.
|
||||
- "broadcast" - duplex connection from broadcast subscriber to publisher; client apps should only allow to receive messages and send back control messages, but not the content messages. Profile of the subscriber is not shared with the publisher.
|
||||
- "broadcast-subscriber" - duplex connection from broadcast publisher to subscriber.
|
||||
|
||||
|
||||
##### Messages
|
||||
|
||||
Control messages:
|
||||
|
||||
- "welcome" - sent and recieved by both participants when duplex connection is being established.
|
||||
- "receipt" - acknowledging message receipt.
|
||||
- "contact: update" - changing "contact" profile .
|
||||
- "profile" - changing "contact
|
||||
- "gm: add" - sent to add simplex connection to graph-chat duplex connection.
|
||||
- "gm: remove" - sent to remove simplex connection from graph-chat duplex connection.
|
||||
|
||||
Content messages:
|
||||
|
||||
- "text"
|
||||
- "image"
|
||||
|
||||
|
||||
[1]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack
|
||||
[2]: https://en.wikipedia.org/wiki/End-to-end_encryption
|
||||
[3]: simplex-messaging.md
|
||||
[4]: simplex-messaging-implementation.md
|
||||
@ -1,624 +0,0 @@
|
||||
# Simplex Messaging Protocol (SMP)
|
||||
|
||||
## Table of contents
|
||||
|
||||
- [Abstract](#abstract)
|
||||
- [Introduction](#introduction)
|
||||
- [SMP Model](#smp-model)
|
||||
- [Out-of-band messages](#out-of-band-messages)
|
||||
- [Simplex queue](#simplex-queue)
|
||||
- [SMP procedure](#smp-procedure)
|
||||
- [SMP qualities and features](#smp-qualities-and-features)
|
||||
- [Cryptographic algorithms](#cryptographic-algorithms)
|
||||
- [Simplex queue IDs](#simplex-queue-ids)
|
||||
- [Server privacy requirements](#server-privacy-requirements)
|
||||
- [SMP commands](#smp-commands)
|
||||
- [Correlating responses with commands](#correlating-responses-with-commands)
|
||||
- [Command authentication](#command-authentication)
|
||||
- [Keep-alive command](#keep-alive-command)
|
||||
- [Recipient commands](#recipient-commands)
|
||||
- [Create queue command](#create-queue-command)
|
||||
- [Subscribe to queue](#subscribe-to-queue)
|
||||
- [Secure queue command](#secure-queue-command)
|
||||
- [Acknowledge message delivery](#acknowledge-message-delivery)
|
||||
- [Suspend queue](#suspend-queue)
|
||||
- [Delete queue](#delete-queue)
|
||||
- [Sender commands](#sender-commands)
|
||||
- [Send message](#send-message)
|
||||
- [Server messages](#server-messages)
|
||||
- [Queue IDs response](#queue-ids-response)
|
||||
- [Deliver queue message](#deliver-queue-message)
|
||||
- [Subscription END notification](#subscription-end-notification)
|
||||
- [Error responses](#error-responses)
|
||||
- [OK response](#ok-response)
|
||||
- [Appendices](#appendices)
|
||||
- [Appendix A. Transport connection with the SMP server](#appendix-a)
|
||||
|
||||
## Abstract
|
||||
|
||||
Simplex Messaging Protocol is a transport agnostic client-server protocol for asynchronous distributed secure unidirectional message transmission via persistent simplex message queues.
|
||||
|
||||
It's designed with the focus on communication security and integrity, under the assumption that any part of the message transmission network can be compromised.
|
||||
|
||||
It is designed as a low level protocol for other application protocols to solve the problem of secure and private message transmission, making [MITM attack][1] very difficult at any part of the message transmission system.
|
||||
|
||||
## Introduction
|
||||
|
||||
The objective of Simplex Messaging Protocol (SMP) is to facilitate the secure and private unidirectional transfer of messages from senders to recipients via persistent simplex queues managed by the message broker (server).
|
||||
|
||||
SMP is independent of any particular transmission system and requires only a reliable ordered data stream channel. While this document describes transport over TCP, other transports are also possible.
|
||||
|
||||
The protocol describes the set of commands that recipients and senders can exchange with SMP servers to create and to operate unidirectional "queues" (a data abstraction identifying one of many communication channels managed by the server) and to send messages from the sender to the recipient via the SMP server.
|
||||
|
||||
More complex communication scenarios can be designed using multiple queues - for example, a duplex communication channel can be made of 2 simplex queues.
|
||||
|
||||
The protocol is designed with the focus on privacy and security, to some extent deprioritizing reliability by requiring that SMP servers only store messages until they are acknowledged by the recipients and, in any case, for a limited period of time. For communication scenarios requiring more reliable transmission the users should use several SMP servers to pass each message and implement some additional protocol to ensure that messages are not removed, inserted or changed - this is out of scope of this document.
|
||||
|
||||
SMP does not use any form of participants' identities and provides [E2EE][2] without the possibility of [MITM attack][1] relying on two pre-requisites:
|
||||
|
||||
- the users can establish a secure encrypted transport connection with the SMP server. [Appendix A](#appendix-a) describes SMP transport protocol of such connection over TCP, but any other transport connection protocol can be used.
|
||||
|
||||
- the recipient can pass a single message to the sender via a pre-existing secure and private communication channel (out-of-band message) - the information in this message is used to encrypt messages and to establish connection with SMP server.
|
||||
|
||||
## SMP Model
|
||||
|
||||
The SMP model has three communication participants: the recipient, the message broker (SMP server) that is chosen and, possibly, controlled by the recipient, and the sender.
|
||||
|
||||
SMP server manages multiple "simplex queues" - data records on the server that identify communication channels from the senders to the recipients. The same communicating party that is the sender in one queue, can be the recipient in another - without exposing this fact to the server.
|
||||
|
||||
The queue record consists of 2 unique random IDs generated by the server, one for the recipient and another for the sender, and 2 keys to authenticate the recipient and the sender respectively, provided by the client. The users of SMP protocol must use a unique key for each queue, to avoid the possibility of aggregating and analysing their queues in case SMP server is compromised.
|
||||
|
||||
Creating and using the queue requires sending commands to the SMP server from the recipient and the sender - they are described in detail in [SMP commands](#smp-commands) section.
|
||||
|
||||
## Out-of-band messages
|
||||
|
||||
The out-of-band message with the queue information is sent via some trusted alternative channel from the recipient to the sender. This message is used to share the encryption (a.k.a. "public") key that the sender will use to encrypt the messages (to be decrypted by the recipient), sender queue ID, server hostname and any other information necessary to establish secure encrypted connection with SMP server (see [Appendix A](#appendix-a) for SMP transport protocol).
|
||||
|
||||
The [ABNF][8] syntax of the message is:
|
||||
|
||||
```abnf
|
||||
outOfBandMsg = "smp::" server "::" queueId "::" encryptionKey
|
||||
server = <hostname> [":" port] ["#" serverKeyHash]
|
||||
port = 1*DIGIT
|
||||
serverKeyHash = encoded
|
||||
queueId = encoded
|
||||
encryptionKey = %s"rsa:" x509encoded ; the recipient's RSA public key for sender to encrypt messages
|
||||
x509encoded = <base64 X509 key encoding>
|
||||
encoded = <base64 encoded binary>
|
||||
```
|
||||
|
||||
`hostname` can be IP address or domain name, as defined in RFC 1123, section 2.1.
|
||||
|
||||
`port` is optional, the default TCP port for SMP protocol is 5223.
|
||||
|
||||
`serverKeyHash` is an optional hash of the server transport key used during transport handshake (see [Appendix A](#appendix-a)).
|
||||
|
||||
Encryption keys are encoded using [X509][11] specification.
|
||||
|
||||
Defining the approach to out-of-band message passing is out of scope of this protocol.
|
||||
|
||||
## Simplex queue
|
||||
|
||||
The simplex queue is the main unit of SMP protocol. It is used by:
|
||||
|
||||
- Sender of the queue (who received out-of-band message) to send messages to the server using sender's queue ID, signed by sender's key.
|
||||
|
||||
- Recipient of the queue (who created the queue and sent out-of-band message) will use it to retrieve messages from the server, signing the commands by the recipient key.
|
||||
|
||||
- Participant identities are not shared with the server - new unique keys and queue IDs are used for each queue.
|
||||
|
||||
This simplex queue can serve as a building block for more complex communication network. For example, two (or more, for redundancy) simplex queues can be used to create a duplex communication channel. Higher level primitives that are only known to system participants in their client applications can be created as well - e.g., contacts, conversations, groups and broadcasts. Simplex messaging servers only have the information about the low-level simplex queues. In this way a high level of privacy and security of the communication is provided. Application level primitives are not in scope of this protocol.
|
||||
|
||||
This approach is based on the concept of [unidirectional networks][4] that are used for applications with high level of information security.
|
||||
|
||||
Access to each queue is controlled with unique (not shared with other queues) asymmetric key pairs, separate for the sender and the recipient. The sender and the receiver have private keys, and the server has associated public keys to authenticate participants' commands by verifying cryptographic signatures.
|
||||
|
||||
The messages sent over the queue are encrypted and decrypted using another key pair that was shared via out-of-band message - the recipient has the private key and the sender has the associated public key.
|
||||
|
||||
**Simplex queue diagram:**
|
||||
|
||||
|
||||
|
||||
Queue is defined by recipient ID `RID` and sender ID `SID`, unique for the server. Sender key (`SK`) is used by the server to verify sender's commands (identified by `SID`) to send messages. Recipient key (`RK`) is used by the server to verify recipient's commands (identified by `RID`) to retrieve messages.
|
||||
|
||||
The protocol uses different IDs for sender and recipient in order to provide an additional privacy by preventing the correlation of senders and recipients commands sent over the network - in case the encrypted transport is compromised, it would still be difficult to correlate senders and recipients without access to the queue records on the server.
|
||||
|
||||
## SMP procedure
|
||||
|
||||
The SMP procedure of creating a simplex queue on SMP server is explained using participants Alice (the recipient) who wants to receive messages from Bob (the sender).
|
||||
|
||||
To create and start using a simplex queue Alice and Bob follow these steps:
|
||||
|
||||
1. Alice creates a simplex queue on the server:
|
||||
|
||||
1. Decides which SMP server to use (can be the same or different server that Alice uses for other queues) and opens secure encrypted transport connection to the chosen SMP server (see [Appendix A](#appendix-a)).
|
||||
|
||||
2. Generates a new random public/private key pair (encryption key - `EK`) that she did not use before for Bob to encrypt the messages.
|
||||
|
||||
3. Generates another new random public/private key pair (recipient key - `RK`) that she did not use before for her to sign commands and to decrypt the transmissions received from the server.
|
||||
|
||||
4. Sends `"NEW"` command to the server to create a simplex queue (see `create` in [Create queue command](#create-queue-command)). This command contains previously generated unique "public" key `RK` that will be used to sign the following commands related to the same queue, for example to subscribe to the messages received to this queue or to update the queue, e.g. by setting the key required to send the messages (initially Alice creates the queue that accepts unsigned messages, so anybody could send the message via this queue if they knew the queue sender's ID and server address).
|
||||
|
||||
5. The server sends `"IDS"` response with queue IDs (`queueIds`):
|
||||
|
||||
- Recipient ID `RID` for Alice to manage the queue and to receive the messages.
|
||||
|
||||
- Sender ID `SID` for Bob to send messages to the queue.
|
||||
|
||||
2. Alice sends an out-of-band message to Bob via the alternative channel that both Alice and Bob trust (see [protocol abstract](#simplex-messaging-protocol-abstract)). The message must include:
|
||||
|
||||
- Unique "public" key (`EK`) that Bob must use to encrypt messages.
|
||||
|
||||
- SMP server hostname and information to open secure encrypted transport connection (see [Appendix A](#appendix-a)).
|
||||
|
||||
- Sender queue ID `SID` for Bob to use.
|
||||
|
||||
3. Bob, having received the out-of-band message from Alice, connects to the queue:
|
||||
|
||||
1. Generates a new random public/private key pair (sender key - `SK`) that he did not use before for him to sign messages sent to Alice's server.
|
||||
|
||||
2. Prepares the confirmation message for Alice to secure the queue. This message includes:
|
||||
|
||||
- Previously generated "public" key `SK` that will be used by Alice's server to authenticate Bob's messages, once the queue is secured.
|
||||
|
||||
- Optionally, any additional information (application specific, e.g. Bob's profile name and details).
|
||||
|
||||
3. Encrypts the confirmation body with the "public" key `EK` (that Alice provided via the out-of-band message).
|
||||
|
||||
4. Sends the encrypted message to the server with queue ID `SID` (see `send` in [Send message](#send-message)). This initial message to the queue must not be signed - signed messages will be rejected until Alice secures the queue (below).
|
||||
|
||||
4. Alice receives Bob's message from the server using recipient queue ID `RID` (possibly, via the same transport connection she already has opened - see `message` in [Deliver queue message](#deliver-queue-message)):
|
||||
|
||||
1. She decrypts received message with "private" key `EK`.
|
||||
|
||||
2. Even though anybody could have sent the message to the queue with ID `SID` before it is secured (e.g. if communication is compromised), Alice would ignore all messages until the decryption succeeds (i.e. the result contains the expected message format). Optionally, in the client application, she also may identify Bob using the information provided, but it is out of scope of SMP protocol.
|
||||
|
||||
5. Alice secures the queue `RID` with `"KEY"` command so only Bob can send messages to it (see [Secure queue command](#secure-queue-command)):
|
||||
|
||||
1. She sends the `KEY` command with `RID` signed with "private" key `RK` to update the queue to only accept requests signed by "private" key `SK` provided by Bob.
|
||||
|
||||
2. From this moment the server will accept only signed commands to `SID`, so only Bob will be able to send messages to the queue `SID` (corresponding to `RID` that Alice has).
|
||||
|
||||
3. Once queue is secured, Alice deletes `SID` and `SK` - even if Alice's client is compromised in the future, the attacker would not be able to send messages pretending to be Bob.
|
||||
|
||||
6. The simplex queue `RID` is now ready to be used.
|
||||
|
||||
This flow is shown on the sequence diagram below.
|
||||
|
||||
**Creating simplex queue from Bob to Alice:**
|
||||
|
||||
|
||||
|
||||
Bob now can securely send messages to Alice:
|
||||
|
||||
1. Bob sends the message:
|
||||
|
||||
1. He encrypts the message to Alice with "public" key `EK` (provided by Alice, only known to Bob, used only for one simplex queue).
|
||||
|
||||
2. He signs `"SEND"` command to the server queue `SID` using the "private" key `SK` (that only he knows, used only for this queue).
|
||||
|
||||
3. He sends the command to the server (see `send` in [Send message](#send-message)), that the server will authenticate using the "public" key `SK` (that Alice earlier provided to the server).
|
||||
|
||||
2. Alice receives the message(s):
|
||||
|
||||
1. She signs `"SUB"` command to the server to subscribe to the queue `RID` with the "private" key `RK` (see `subscribe` in [Subscribe to queue](#subscribe-to-queue)).
|
||||
|
||||
2. The server, having authenticated Alice's command with the "public" key `RK` that she provided, delivers Bob's message(s) (see `message` in [Deliver queue message](#deliver-queue-message)).
|
||||
|
||||
3. She decrypts Bob's message(s) with the "private" key `EK` (that only she has).
|
||||
|
||||
4. She acknowledges the message reception to the server with `"ACK"` so that the server can delete the message and deliver the next messages.
|
||||
|
||||
This flow is show on sequence diagram below.
|
||||
|
||||
**Sending messages from Bob to Alice via simplex queue:**
|
||||
|
||||
|
||||
|
||||
**Simplex queue operation:**
|
||||
|
||||
|
||||
|
||||
Sequence diagram does not show E2E encryption - server knows nothing about encryption between the sender and the receiver.
|
||||
|
||||
A higher level protocol application protocol should define the semantics that allow to use two simplex queues (or two sets of queues for redundancy) for the bi-directional or any other communication scenarios.
|
||||
|
||||
The SMP is intentionally unidirectional - it provides no answer to how Bob will know that the transmission succeeded, and whether Alice received any messages. There may be a scenario when Alice wants to securely receive the messages from Bob, but she does not want Bob to have any proof that she received any messages - this low-level protocol can be used in this scenario, as all Bob knows as a fact is that he was able to send one unsigned message to the server that Alice provided, and now he can only send messages signed with the key `SK` that he sent to the server - it does not prove that any message was received by Alice.
|
||||
|
||||
For practical purposes of bi-directional conversation, now that Bob can securely send encrypted messages to Alice, Bob can create the second simplex queue that will allow Alice to send messages to Bob in the same way, sending the second queue details via the first queue. If both Alice and Bob have their respective unique "public" keys (Alice's and Bob's `EK`s of two separate queues), or pass additional keys to sign the messages, the conversation can be both encrypted and signed.
|
||||
|
||||
The established queues can also be used to change the encryption keys providing [forward secrecy][5], or to negotiate using other SMP queue(s).
|
||||
|
||||
This protocol also can be used for off-the-record messaging, as Alice and Bob can use multiple queues between them and only information they pass to each other allows proving their identity, so if they want to share anything off-the-record they can initiate a new queue without linking it to any other information they exchanged. As a result, this protocol provides better anonymity and better protection from [MITM][1] than [OTR][6] protocol.
|
||||
|
||||
## SMP qualities and features
|
||||
|
||||
Simplex Messaging Protocol:
|
||||
|
||||
- Defines only message-passing protocol:
|
||||
|
||||
- Transport agnostic - the protocol does not define how clients connect to the servers. It can be implemented over any ordered data stream channel: TCP connection, HTTP with long polling, websockets, etc.
|
||||
|
||||
- Not semantic - the protocol does not assign any meaning to queues and messages. While on the application level the queues and messages can have different meaning (e.g., for messages: text or image chat message, message acknowledgement, participant profile information, status updates, changing "public" key to encrypt messages, changing servers, etc.), on SMP protocol level all the messages are binary and their meaning can only be interpreted by client applications and not by the servers - this interpretation is out of scope of this protocol.
|
||||
|
||||
- Client-server architecture:
|
||||
|
||||
- Multiple servers, that can be deployed by the system users, can be used to send and retrieve messages.
|
||||
|
||||
- Servers do not communicate with each other and do not "know" about other servers.
|
||||
|
||||
- Clients only communicate with servers (excluding the initial out-of-band message), so the message passing is asynchronous.
|
||||
|
||||
- For each queue, the message recipient defines the server through which the sender should send messages.
|
||||
|
||||
- While multiple servers and multiple queues can be used to pass each message, it is in scope of application level protocol(s), and out of scope of this protocol.
|
||||
|
||||
- Servers store messages only until they are retrieved by the recipients, and in any case, for a limited time.
|
||||
|
||||
- Servers are required to NOT store any message history or delivery log, but even if the server is compromised, it does not allow to decrypt the messages or to determine the list of queues established by any participant - this information is only stored on client devices.
|
||||
|
||||
- The only element provided by SMP servers is simplex queues:
|
||||
|
||||
- Each queue is created and managed by the queue recipient.
|
||||
|
||||
- Asymmetric encryption is used to sign and verify the requests to send and receive the messages.
|
||||
|
||||
- One unique "public" key is used by the servers to authenticate requests to send the messages into the queue, and another unique "public" key - to retrieve the messages from the queue. "Unique" here means that each "public" key is used only for one queue and is not used for any other context - effectively, this key is not public and does not represent any participant identity.
|
||||
|
||||
- Both "public" keys are provided to the server by the queue recipient when the queue is created.
|
||||
|
||||
- The "public" keys known to the server and used to authenticate commands from the participants are unrelated to the keys used to encrypt and decrypt the messages - the latter keys are also unique per each queue but they are only known to participants, not to the servers.
|
||||
|
||||
- Messaging graph can be asymmetric: Bob's ability to send messages to Alice does not automatically lead to the Alice's ability to send messages to Bob.
|
||||
|
||||
## Cryptographic algorithms
|
||||
|
||||
Simplex messaging clients need to cryptographically sign commands for the following operations:
|
||||
|
||||
- With the recipient's key `RK` (server to verify):
|
||||
- create the queue (`NEW`)
|
||||
- subscribe to queue (`SUB`)
|
||||
- secure the queue (`KEY`)
|
||||
- acknowledge received messages (`ACK`)
|
||||
- suspend the queue (`OFF`)
|
||||
- delete the queue (`DEL`)
|
||||
- With the sender's key `SK` (server to verify):
|
||||
- send messages (`SEND`)
|
||||
|
||||
To sign and verify commands, clients and servers MUST use RSA-PSS algorithm defined in [RFC3447][2].
|
||||
|
||||
To optionally sign and verify messages, clients SHOULD use RSA-PSS algorithm.
|
||||
|
||||
To encrypt and decrypt messages, clients and servers SHOULD use RSA-OAEP algorithm defined in [RFC3447][2].
|
||||
|
||||
The reasons to use these algorithms:
|
||||
|
||||
- They are supported by WebCrypto API.
|
||||
- They are more widely supported than ECC algorithms.
|
||||
- They are newer versions than RSA-PKCS1-v1_5 encryption and signature schemes.
|
||||
|
||||
Future versions of the protocol may allow different cryptographic algorithms.
|
||||
|
||||
## Simplex queue IDs
|
||||
|
||||
Simplex messaging servers MUST generate 2 different IDs for each new queue - for the recipient (that created the queue) and for the sender. It is REQUIRED that:
|
||||
|
||||
- These IDs are different and unique within the server.
|
||||
- Based on random bytes generated with cryptographically strong pseudo-random number generator.
|
||||
|
||||
## Server security requirements
|
||||
|
||||
Simplex messaging server implementations MUST NOT create, store or send to any other servers:
|
||||
|
||||
- Logs of the client commands and transport connections in the production environment.
|
||||
|
||||
- History of deleted queues, retrieved or acknowledged messages (deleted queues MAY be stored temporarily as part of the queue persistence implementation).
|
||||
|
||||
- Snapshots of the database they use to store queues and messages (instead simplex messaging clients must manage redundancy by using more than one simplex messaging server). In-memory persistence is recommended.
|
||||
|
||||
- Any other information that may compromise privacy or [forward secrecy][4] of communication between clients using simplex messaging servers.
|
||||
|
||||
## SMP commands
|
||||
|
||||
Commands syntax below is provided using [ABNF][8] with [case-sensitive strings extension][8a].
|
||||
|
||||
Each transmission between the client and the server must have this format/syntax (after the decryption):
|
||||
|
||||
```abnf
|
||||
transmission = [signature] SP signed SP pad ; pad to the fixed block size
|
||||
signed = [corrId] SP [queueId] SP cmd
|
||||
cmd = ping / recipientCmd / send / serverMsg
|
||||
recipientCmd = create / subscribe / secure / acknowledge / suspend / delete
|
||||
serverMsg = pong / queueIds / message / unsubscribed / ok / error
|
||||
corrId = 1*(%x21-7F) ; any characters other than control/whitespace
|
||||
queueId = encoded ; empty queue ID is used with "create" command
|
||||
signature = encoded
|
||||
; empty signature can be used with "create", "send" and "ping" commands and server messages
|
||||
encoded = <base64 encoded binary>
|
||||
```
|
||||
|
||||
`base64` encoding should be used with padding, as defined in section 4 of [RFC 4648][9]
|
||||
|
||||
The syntax of specific commands and responses is defined below.
|
||||
|
||||
### Correlating responses with commands
|
||||
|
||||
The server should send `queueIds`, `error` and `ok` responses in the same order within each queue ID as the commands received in the transport connection, so that they can be correlated by the clients. To simplify correlation of commands and responses, the server should use the same `corrId` in the response as in the command sent by the client.
|
||||
|
||||
If the transport connection is closed before some responses are sent, these responses should be discarded.
|
||||
|
||||
### Command authentication
|
||||
|
||||
SMP servers must authenticate all transmissions (excluding `ping` and `send` commands) by verifying the provided signatures. Command signature should be generated by applying RSA-PSS algorithm to the `signed` block of the transmission using the key associated with the queue ID (sender's or recipient's, depending on which queue ID is used).
|
||||
|
||||
### Keep-alive command
|
||||
|
||||
To keep the transport connection alive and to generate noise traffic the clients should use `ping` command to which the server responds with `pong` response. This command should be sent unsigned and without queue ID.
|
||||
|
||||
```abnf
|
||||
ping = %s"PING"
|
||||
pong = %s"PONG"
|
||||
```
|
||||
|
||||
### Recipient commands
|
||||
|
||||
Sending any of the commands in this section (other than `create`, that is sent without queue ID) is only allowed with recipient's ID (`RID`). If sender's ID is used the server must respond with `"ERR AUTH"` response (see [Error responses](#error-responses)).
|
||||
|
||||
#### Create queue command
|
||||
|
||||
This command is sent by the recipient to the SMP server to create a new queue. The syntax is:
|
||||
|
||||
```abnf
|
||||
create = %s"NEW" SP recipientKey
|
||||
recipientKey = %s"rsa:" x509encoded ; the recipient's RSA public key for this queue
|
||||
x509encoded = <base64 X509 key encoding>
|
||||
```
|
||||
|
||||
If the queue is created successfully, the server must send `queueIds` response with the recipient's and sender's queue IDs:
|
||||
|
||||
```abnf
|
||||
queueIds = %s"IDS" SP recipientId SP senderId
|
||||
recipientId = encoded
|
||||
senderId = encoded
|
||||
```
|
||||
|
||||
This response should be sent with empty queue ID (the second part of the transmission).
|
||||
|
||||
Once the queue is created, the recipient gets automatically subscribed to receive the messages from that queue, until the transport connection is closed. The `subscribe` command is needed only to start receiving the messages from the existing queue when the new transport connection is opened.
|
||||
|
||||
NEW `transmission` must be signed using the `recipientKey` that was passed in the transmission.
|
||||
|
||||
#### Subscribe to queue
|
||||
|
||||
When the simplex queue was not created in the current transport connection, the recipient must use this command to start receiving messages from it:
|
||||
|
||||
```abnf
|
||||
subscribe = %s"SUB"
|
||||
```
|
||||
|
||||
If subscription is successful the server must respond with the first available message or with `ok` response if no messages are available. The recipient will continue receiving the messages from this queue until the transport connection is closed or until another transport connection subscribes to the same simplex queue - in this case the first subscription should be cancelled and [subscription END notification](#subscription-end-notification) delivered.
|
||||
|
||||
The first message will be delivered either immediately or as soon as it is available; to receive the following message the recipient must acknowledge the reception of the message (see [Acknowledge message delivery](#acknowledge-message-delivery)).
|
||||
|
||||
#### Secure queue command
|
||||
|
||||
This command is sent by the recipient to the server to add sender's key to the queue:
|
||||
|
||||
```
|
||||
secure = %s"KEY" SP senderKey
|
||||
senderKey = %s"rsa:" x509encoded ; the sender's RSA public key for this queue
|
||||
```
|
||||
|
||||
`senderKey` is received from the sender as part of the first message - see [Send Message Command](#send-message-command).
|
||||
|
||||
Once the queue is secured only signed messages can be sent to it.
|
||||
|
||||
#### Acknowledge message delivery
|
||||
|
||||
The recipient should send the acknowledgement of message delivery once the message was stored in the client, to notify the server that the message should be deleted:
|
||||
|
||||
```abnf
|
||||
acknowledge = %s"ACK"
|
||||
```
|
||||
|
||||
Even if acknowledgement is not sent by the recipient, the server should limit the time of message storage, whether it was delivered to the recipient or not.
|
||||
|
||||
Having received the acknowledgement, SMP server should immediately delete the message and then send the next available message or respond with `ok` if there are no more messages available in this simplex queue.
|
||||
|
||||
#### Suspend queue
|
||||
|
||||
The recipient can suspend a queue prior to deleting it to make sure that no messages are lost:
|
||||
|
||||
```abnf
|
||||
suspend = %s"OFF"
|
||||
```
|
||||
|
||||
The server must respond with `"ERR AUTH"` to any messages sent after the queue was suspended (see [Error responses](#error-responses)).
|
||||
|
||||
The server must respond `ok` to this command if it was successful.
|
||||
|
||||
This command can be sent multiple times (in case transport connection was interrupted and the response was not delivered), the server should still respond `ok` even if the queue is already suspended.
|
||||
|
||||
There is no command to resume the queue. Servers must delete suspended queues that were not deleted after some period of time.
|
||||
|
||||
#### Delete queue
|
||||
|
||||
The recipient can delete the queue, whether it was suspended or not.
|
||||
|
||||
All undelivered messages must be deleted as soon as this command is received, before the response is sent.
|
||||
|
||||
```abnf
|
||||
delete = %s"DEL"
|
||||
```
|
||||
|
||||
### Sender commands
|
||||
|
||||
Currently SMP defines only one command that can be used by senders - `send` message. This command must be used with sender's ID, if recipient's ID is used the server must respond with `"ERR AUTH"` response (see [Error responses](#error-responses)).
|
||||
|
||||
#### Send message
|
||||
|
||||
This command is sent to the server by the sender both to confirm the queue after the sender received out-of-band message from the recipient and to send messages after the queue is secured:
|
||||
|
||||
```abnf
|
||||
send = %s"SEND" SP size SP msgBody SP
|
||||
; the last SP is in addition to SP in the transmission
|
||||
size = 1*DIGIT ; size in bytes
|
||||
msgBody = *OCTET ; any binary content of specified size
|
||||
```
|
||||
|
||||
The first message is sent to confirm the queue - it should contain sender's server key (see decrypted message syntax below) - this first message must be sent without signature.
|
||||
|
||||
Once the queue is secured (see [Secure queue command](#secure-queue-command)), the following send commands must be sent with the signature.
|
||||
|
||||
The server must respond with `"ERR AUTH"` response in the following cases:
|
||||
|
||||
- the queue does not exist or is suspended
|
||||
- the queue is secured but the transmission does NOT have a signature
|
||||
- the queue is NOT secured but the transmission has a signature
|
||||
|
||||
Until the queue is secured, the server should accept any number of unsigned messages - it both enables the legitimate sender to resend the confirmation in case of failure and also allows the simplex messaging client to ignore any confirmation messages that may be sent by the attackers (assuming they could have intercepted the queue ID in the server response, but do not have a correct encryption key passed to sender in out-of-band message).
|
||||
|
||||
The body should be encrypted with the recipient's "public" key (`EK`); once decrypted it must have this format:
|
||||
|
||||
```abnf
|
||||
decryptedBody = [clientHeader] CRLF clientBody CRLF
|
||||
clientHeader = senderKeyMsg
|
||||
senderKeyMsg = %s"KEY" SP senderKey
|
||||
senderKey = %s"rsa:" x509encoded ; the sender's RSA public key for this queue
|
||||
clientBody = *OCTET
|
||||
```
|
||||
|
||||
`clientHeader` in the initial unsigned message is used to transmit sender's server key and can be used in the future revisions of SMP protocol for other purposes.
|
||||
|
||||
### Server messages
|
||||
|
||||
#### Queue IDs response
|
||||
|
||||
Server must respond with this message when the new queue is created.
|
||||
|
||||
See its syntax in [Create queue command](#create-queue-command)
|
||||
|
||||
#### Deliver queue message
|
||||
|
||||
The server must deliver messages to all subscribed simplex queues on the currently open transport connection. The syntax for the message delivery is:
|
||||
|
||||
```abnf
|
||||
message = %s"MSG" SP msgId SP timestamp SP size SP msgBody SP
|
||||
msgId = encoded
|
||||
timestamp = <date-time defined in RFC3339>
|
||||
```
|
||||
|
||||
`msgId` - unique message ID generated by the server based on cryptographically strong random bytes. It should be used by the clients to detect messages that were delivered more than once (in case the transport connection was interrupted and the server did not receive the message delivery acknowledgement).
|
||||
|
||||
`timestamp` - the UTC time when the server received the message from the sender, must be in date-time format defined by [RFC 3339][10]
|
||||
|
||||
`binaryMsg` - see syntax in [Send message](#send-message)
|
||||
|
||||
#### Subscription END notification
|
||||
|
||||
When another transport connection is subscribed to the same simplex queue, the server should unsubscribe and to send the notification to the previously subscribed transport connection:
|
||||
|
||||
```abnf
|
||||
unsubscribed = %s"END"
|
||||
```
|
||||
|
||||
No further messages should be delivered to unsubscribed transport connection.
|
||||
|
||||
#### Error responses
|
||||
|
||||
- incorrect block format, encoding or signature size (`BLOCK`).
|
||||
- command errors (`CMD`):
|
||||
- error parsing command (`SYNTAX`)
|
||||
- prohibited command (`PROHIBITED`) - any server response sent from client or `ACK` sent without active subscription or without message delivery.
|
||||
- incorrect RSA key size in `NEW` or `KEY` commands - only 1024, 2048 and 4096-bit keys are allowed (`KEY_SIZE`).
|
||||
- transmission has no required signature or queue ID (`NO_AUTH`)
|
||||
- transmission has unexpected credentials (`HAS_AUTH`)
|
||||
- transmission has no required queue ID (`NO_QUEUE`)
|
||||
- authentication error (`AUTH`) - incorrect signature, unknown (or suspended) queue, sender's ID is used in place of recipient's and vice versa, and some other cases (see [Send message command](#send-message-command)).
|
||||
- incorrect message body size (`SIZE`).
|
||||
- internal server error (`INTERNAL`).
|
||||
|
||||
The syntax for error responses:
|
||||
|
||||
```abnf
|
||||
error = %s"ERR" SP errorType
|
||||
errorType = %s"BLOCK" / %s"CMD" SP cmdError / %s"AUTH" / %s"SIZE" /%s"INTERNAL"
|
||||
cmdError = %s"SYNTAX" / %s"PROHIBITED" / %s"KEY_SIZE" / %s"NO_AUTH" / %s"HAS_AUTH" / %s"NO_QUEUE"
|
||||
```
|
||||
|
||||
Server implementations must aim to respond within the same time for each command in all cases when `"ERR AUTH"` response is required to prevent timing attacks (e.g., the server should perform signature verification even when the queue does not exist on the server or the signature of different size is sent, using any RSA key with the same size as the signature size).
|
||||
|
||||
### OK response
|
||||
|
||||
When the command is successfully executed by the server, it should respond with OK response:
|
||||
|
||||
```abnf
|
||||
ok = %s"OK"
|
||||
```
|
||||
|
||||
## Appendices
|
||||
|
||||
### Appendix A.
|
||||
|
||||
**SMP transport protocol.**
|
||||
|
||||
Both the recipient and the sender can use TCP or some other, possibly higher level, transport protocol to communicate with the server. The default TCP port for SMP server is 5223.
|
||||
|
||||
By default, the client and server should use the protocol presented below, that does not depend on a centralized certificate authority.
|
||||
|
||||
Transport is encrypted with [AEAD-GCM][12] protocol with two random symmetric AES 256-bit keys and two random base IVs that will be agreed during the handshake. Both client and the server should maintain two 32-bit word counters, one for the sent and one for the received messages. The IV for each message should be computed by xor-ing the sequential message counter, starting from 0, with the first 32 bits of agreed base IV (the number is encoded in network byte order).
|
||||
|
||||
To establish the session keys and base IVs, the server should have an asymmetric key pair generated during server deployment and unknown to the clients. The users should know the key hash (256 bits) in advance in order to be able to validate the server public key during transport connection handshake.
|
||||
|
||||
The handshake sequence is the following:
|
||||
|
||||
1. Once the connection is established, the server sends the `server_header` followed by its public RSA key encoded in X509 binary (not base-64 encoded) format to the client.
|
||||
2. The client compares the SHA256 hash of the received key with the hash it already has (e.g. received as part of connection invitation or as SMP server configuration). If the hash does not match, the client must terminate the connection.
|
||||
3. If the hash is the same, the client should generate two random symmetric 256-bit AES keys and two base IVs that will be used as session keys/IVs by the client and the server.
|
||||
4. The client then should create the `client_handshake` block and send it to the server, encrypted using [RSA-OAEP][2] scheme with the server public key: `rsa-encrypt(client_handshake)`. `snd_aes_key` and `snd_base_iv` will be used by the client to encrypt **sent** messages and by the server to decrypt them, `rcv_aes_key` and `rcv_base_iv` will be used by the client to decrypt **received** messages and by the server to encrypt them. `client_handshake` also contains `block_size` and reserved `protocol` blocks (see syntax).
|
||||
5. The server should decrypt the received AES keys and base IVs with its private RSA key.
|
||||
6. In case of successful decryption, the server should send encrypted welcome block (`encrypted_welcome_block`) that contains SMP protocol version supported by the server.
|
||||
|
||||
All the subsequent data, both from the client and from the server, should be sent padded to the fixed agreed block size, encrypted with symmetric AES keys and base IVs (incremented by counters on both sides), that were sent by the client during the handshake. If the application needs to transmit a larger message, it should be broken down into fragments.
|
||||
|
||||
Handshake blocks sent by the client and the server have this syntax:
|
||||
|
||||
```abnf
|
||||
server_header = block_size protocol key_size
|
||||
block_size = 4*4(OCTET) ; 4-byte block size sent by the server
|
||||
protocol = 2*2(%x00) ; 0, reserved
|
||||
key_size = 2*2(OCTET) ; the size of the encoded key in bytes (binary encoded in X509 standard)
|
||||
|
||||
client_handshake = client_block_size protocol snd_aes_key snd_base_iv rcv_aes_key rcv_base_iv
|
||||
client_block_size = 4*4(OCTET) ; 4-byte block size sent by the client,
|
||||
; to confirm or override the block size sent by the server
|
||||
client_protocol = 2*2(%x00) ; 0, reserved
|
||||
snd_aes_key = 32*32(OCTET)
|
||||
snd_base_iv = 16*16(OCTET)
|
||||
rcv_aes_key = 32*32(OCTET)
|
||||
rcv_base_iv = 16*16(OCTET)
|
||||
|
||||
transport_block = aes_body_auth_tag aes_encrypted_body
|
||||
; size is sent by server during handshake, usually 4096 bytes
|
||||
aes_body_auth_tag = 16*16(OCTET)
|
||||
aes_encrypted_body = 1*OCTET
|
||||
|
||||
encrypted_welcome_block = transport_block
|
||||
welcome_block = smp_version SP pad ; decrypt(encrypted_welcome_block)
|
||||
smp_version = %s"v" 1*DIGIT "." 1*DIGIT "." 1*DIGIT ["-" 1*ALPHA "." 1*DIGIT] ; in semver format
|
||||
; for example: v123.456.789-alpha.7
|
||||
pad = 1*OCTET
|
||||
```
|
||||
|
||||
[1]: https://en.wikipedia.org/wiki/Man-in-the-middle_attack
|
||||
[2]: https://en.wikipedia.org/wiki/End-to-end_encryption
|
||||
[3]: https://en.wikipedia.org/wiki/QR_code
|
||||
[4]: https://en.wikipedia.org/wiki/Unidirectional_network
|
||||
[5]: https://en.wikipedia.org/wiki/Forward_secrecy
|
||||
[6]: https://en.wikipedia.org/wiki/Off-the-Record_Messaging
|
||||
[8]: https://tools.ietf.org/html/rfc5234
|
||||
[8a]: https://tools.ietf.org/html/rfc7405
|
||||
[9]: https://tools.ietf.org/html/rfc4648#section-4
|
||||
[10]: https://tools.ietf.org/html/rfc3339
|
||||
[11]: https://tools.ietf.org/html/rfc5280
|
||||
[12]: https://tools.ietf.org/html/rfc7714
|
||||
Loading…
Reference in New Issue
Block a user