diff --git a/agent-protocol.md b/agent-protocol.md index 0bb1c3b35..c9b8534d6 100644 --- a/agent-protocol.md +++ b/agent-protocol.md @@ -5,7 +5,7 @@ - [Abstract](#abstract) - [SMP agent](#smp-agent) - [SMP agent protocol components](#smp-agent-protocol-components) -- [Duplex connection](#duplex-connection) +- [Duplex connection procedure](#duplex-connection-procedure) - [Communication between SMP agents](#communication-between-smp-agents) - [Message syntax](#messages-between-smp-agents) - [SMP agent commands](#smp-agent-commands) @@ -46,11 +46,37 @@ SMP agent protocol has 3 main parts: - 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 +## Duplex connection procedure -**Creating duplex connection between Alice and Bob:** +![Duplex connection procedure](/diagrams/duplex-messaging/duplex-creating.svg) -![Creating duplex connection](/diagrams/duplex-messaging/duplex-creating.svg) +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 @@ -220,7 +246,7 @@ Connection invitation is a text with the following syntax: ``` qInfo = %s"smp::" smpServer "::" queueId "::" ephemeralPublicKey queueId = encoded -ephemeralPublicKey = encoded ; RSA key for sender to encrypt messages X509 base64 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 diff --git a/diagrams/duplex-messaging/duplex-creating.mmd b/diagrams/duplex-messaging/duplex-creating.mmd index f7b541a6a..d31a639e0 100644 --- a/diagrams/duplex-messaging/duplex-creating.mmd +++ b/diagrams/duplex-messaging/duplex-creating.mmd @@ -16,57 +16,56 @@ sequenceDiagram AS ->> AA: IDS: SMP queue IDs note over AA: status: NEW/NONE - A ->> AA: INVITE: invite
another party - AA ->> A: JOIN: invitation
to connect + AA ->> A: INV: invitation
to connect note over AA: status: PENDING/NONE note over A, B: 3. out-of-band invitation A ->> B: OOB: invitation to connect - B ->> BA: CONNECT:
via invitation info + + note over BA, B: 4. accept connection + B ->> BA: JOIN:
via invitation info note over BA: status: NONE/NEW - note over BA, AA: 4. establish Alice's SMP queue - BA ->> AS: SEND: KEY: sender's key and Bob's profile + 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 key
and Bob's profile + AS ->> AA: MSG: KEY: sender's server key note over AA: status: CONFIRMED/NONE - AA ->> A: Bob's profile
and party ID - A ->> AA: ACCEPT:
accept party ID AA ->> AS: KEY: secure queue note over AA: status: SECURED/NONE - BA ->> AS: SEND: HI: try sending until successful + BA ->> AS: SEND: HELLO: try sending until successful deactivate BA note over BA: status: NONE/ACTIVE - AS ->> AA: MSG: HI: Alice's agent
knows Bob can send + AS ->> AA: MSG: HELLO: Alice's agent
knows Bob can send note over AA: status: ACTIVE/NONE - note over BA, BS: 5. create Bob's SMP queue + 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: 6. establish Bob's SMP queue + 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
to connect note over AA: status: ACTIVE/NEW - AA ->> BS: SEND: KEY: sender's key and Alice's profile + AA ->> BS: SEND: KEY: sender's server key note over AA: status: ACTIVE/CONFIRMED activate AA - BS ->> BA: MSG: KEY: sender's key
and Alice's profile + 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: HI: try sending until successful + AA ->> BS: SEND: HELLO: try sending until successful deactivate AA note over AA: status: ACTIVE/ACTIVE - BS ->> BA: MSG: HI: Bob's agent
knows Alice can send + BS ->> BA: MSG: HELLO: Bob's agent
knows Alice can send note over BA: status: ACTIVE/ACTIVE - note over A, B: 7. notify users about connection success - AA ->> A: CONNECTED - BA ->> B: CONNECTED + note over A, B: 8. notify users about connection success + AA ->> A: CON: connected + BA ->> B: CON: connected diff --git a/diagrams/duplex-messaging/duplex-creating.svg b/diagrams/duplex-messaging/duplex-creating.svg index ede232e83..c92600134 100644 --- a/diagrams/duplex-messaging/duplex-creating.svg +++ b/diagrams/duplex-messaging/duplex-creating.svg @@ -1 +1 @@ -AliceAlice'sagentAlice'sserverBob'sserverBob'sagentBobstatus (receive/send): NONE/NONE1. request connection from agentNEW: createduplex connection2. create Alice's SMP queueNEW: create SMP queueIDS: SMP queue IDsstatus: NEW/NONEINVITE: inviteanother partyJOIN: invitationto connectstatus: PENDING/NONE3. out-of-band invitationOOB: invitation to connectCONNECT:via invitation infostatus: NONE/NEW4. establish Alice's SMP queueSEND: KEY: sender's key and Bob's profilestatus: NONE/CONFIRMEDMSG: KEY: sender's keyand Bob's profilestatus: CONFIRMED/NONEBob's profileand party IDACCEPT:accept party IDKEY: secure queuestatus: SECURED/NONESEND: HI: try sending until successfulstatus: NONE/ACTIVEMSG: HI: Alice's agentknows Bob can sendstatus: ACTIVE/NONE5. create Bob's SMP queueNEW: create SMP queueIDS: SMP queue IDsstatus: NEW/ACTIVE6. establish Bob's SMP queueSEND: REPLY: invitation to the connectstatus: PENDING/ACTIVEMSG: REPLY: invitationto connectstatus: ACTIVE/NEWSEND: KEY: sender's key and Alice's profilestatus: ACTIVE/CONFIRMEDMSG: KEY: sender's keyand Alice's profilestatus: CONFIRMED/ACTIVEKEY: secure queuestatus: SECURED/ACTIVESEND: HI: try sending until successfulstatus: ACTIVE/ACTIVEMSG: HI: Bob's agentknows Alice can sendstatus: ACTIVE/ACTIVE7. notify users about connection successCONNECTEDCONNECTEDAliceAlice'sagentAlice'sserverBob'sserverBob'sagentBob \ No newline at end of file +AliceAlice'sagentAlice'sserverBob'sserverBob'sagentBobstatus (receive/send): NONE/NONE1. request connection from agentNEW: createduplex connection2. create Alice's SMP queueNEW: create SMP queueIDS: SMP queue IDsstatus: NEW/NONEINV: invitationto connectstatus: PENDING/NONE3. out-of-band invitationOOB: invitation to connect4. accept connectionJOIN:via invitation infostatus: NONE/NEW5. establish Alice's SMP queueSEND: KEY: sender's server keystatus: NONE/CONFIRMEDMSG: KEY: sender's server keystatus: CONFIRMED/NONEKEY: secure queuestatus: SECURED/NONESEND: HELLO: try sending until successfulstatus: NONE/ACTIVEMSG: HELLO: Alice's agentknows Bob can sendstatus: ACTIVE/NONE6. create Bob's SMP queueNEW: create SMP queueIDS: SMP queue IDsstatus: NEW/ACTIVE7. establish Bob's SMP queueSEND: REPLY: invitation to the connectstatus: PENDING/ACTIVEMSG: REPLY: invitationto connectstatus: ACTIVE/NEWSEND: KEY: sender's server keystatus: ACTIVE/CONFIRMEDMSG: KEY: sender's server keystatus: CONFIRMED/ACTIVEKEY: secure queuestatus: SECURED/ACTIVESEND: HELLO: try sending until successfulstatus: ACTIVE/ACTIVEMSG: HELLO: Bob's agentknows Alice can sendstatus: ACTIVE/ACTIVE8. notify users about connection successCON: connectedCON: connectedAliceAlice'sagentAlice'sserverBob'sserverBob'sagentBob \ No newline at end of file