Protocol¶
This is an overview of Cryptully’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.
Basic Properties¶
- 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.
List of All Commands¶
Server Commands¶
VERSION
: Tell the server what protocol version the client is usingREG
: Register a nickname with the serverREL
: Relay a message to the client as specified in thedestClient
field
Client Commands¶
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]
SMP0 [arg]
: The question the SMP initiator is askingSMP1 [arg]
SMP2 [arg]
SMP3 [arg]
SMP4 [arg]
MSG [arg]
: The user has sent a chat messageTYPING [arg]
: The user is currently typing or has stopped typingEND
ERR
Typing Status¶
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
Encryption Details¶
- 4096-bit prime is used to generate and exchange a shared secret via Diffie-Hellman.
- 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.
Handshake Details¶
The commands in the handshake must be performed in the following order:
Client A | direction | Client B |
---|---|---|
<- | HELO | |
REDY | -> | |
<- | PUB_KEY | |
PUB_KEY | -> | |
(switch to AES encryption) |
The client may reject a connection with the REJ
command instead of sending the REDY
command.
Message Loop Details¶
Clients may send messages any order including multiple messages in a row.
Client A | direction | Client B |
---|---|---|
MSG | <-> | MSG |
TYPING | <-> | TYPING |
END | <-> | END |
Socialist Millionaire Protocol¶
The Socialist Millionaire Protocol (SMP) is a method for determining whether two clients share the same secret, but without exchanging the secret itself. In Cryptully’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 innards of 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.
Cryptully’s implementation uses the following commands:
SMP0
contains the question the initiator is asking. The remaining commands may be sent at any time, as long as they are completed in order and another SMP request is not started before the previous one is completed.