This is an overview of 's protocol for easier understanding the code, or so someone could implement another type of client.
Note: This protocol is highly likely to change in the future.
- All traffic over the network is formatted as JSON messages with the following properties:
serverCommand
: The command given to the serverclientCommand
: The command given to the destination clientsourceNick
: The nickname of the senderdestNick
: The nickname of the receiverpayload
: The content of the message. If an encrypted message, it is base64 encodedhmac
: The HMAC as calculated by the sender to be verified against by the receivererror
: The error code, if applicablenum
: The message number, starting from 0 and monotonically increasing with sequential numbers.
- All commands are case sensitive
- After the initial handshake is complete, the connection is kept alive indefinitely in a message loop until either the client or server sends the
END
command. - The client or server may send the
END
command at any time.
REG
: Register a nickname with the serverREL
: Relay a message to the client as specified in thedestClient
field
HELO
: The first command denotes the initation of a new connection with a clientREDY
: The client is ready to initiate a handshakeREJ
: If the client rejected a connection from another clientPUB_KEY [arg]
SMP1 [arg]
SMP2 [arg]
SMP3 [arg]
SMP4 [arg]
MSG [arg]
TYPING [arg]
END
ERR
A client may optional give the typing status of the user to the remote client by issuing the TYPING
command. The TYPING
command takes one of three possible arguments:
0
: The user is currently typing1
: The user has stopped typing and deleted all text from the buffer2
: The user has stopped typing, but left some text in the buffer
- 1568-bit secret is exchanged via Diffie-Hellman.
- The Socialist Millionaire protocol (as defined by Off-The-Record) is used to verify the Diffie-Hellman secret.
- An AES key is the first 32 bytes of the SHA512 digest of the Diffie-Hellman secret. The IV last 32 bytes of this hash.
- All AES operations are with a 256-bit key in CBC mode.
- HMAC's are the SHA256 digest of the AES key and the encrypted message payload. The receiver calculates and verifies the HMAC before attempting to decrypt the message payload.
The Socialist Millionaire Protocol (SMP) is a method for determining whether two clients share the same secret, but without exchanging the secret itself. In 's case, it is used to determine whether a MITM attack has occurred or is occurring and compromised the Diffie-Hellman key exchange protocol.
The SMP is relatively complex so it is best to defer to the documentation of it's implementation as defined in the Off-The-Record (OTR) protocol version 3.
The commands in the handshake must be performed in the following order:
Client A | direction | Client B |
---|---|---|
|
HELO | |
REDY |
|
|
|
PUB_KEY | |
PUB_KEY |
|
|
(switch t | o AES encr | yption) |
|
SMP1 | |
SMP2 |
|
|
|
SMP3 | |
SMP4 |
|
The client may reject a connection with the REJ
command instead of sending the REDY
command.
Clients may send messages any order including multiple messages in a row.
Client A | direction | Client B |
---|---|---|
MSG |
|
MSG |
TYPING |
|
TYPING |
END |
|
END |