Engine (otr.Otr.Engine)

Message processing

Either when an OTR session should be established, or if a message containing OTR data is received, the corresponding function should be called to decrypt or encrypt the OTR data, or initiate a handshake.

val start_otr : State.session -> State.session * string

start_otr session is session', out, which initiates an OTR session. out should be sent to the communication partner, session' used in further API calls. The session is reset, and out contains an OTR query message (content depends on the configured State.version).

val send_otr : 
  State.session ->
  string ->
  State.session
  * string option
  * [ `Warning of string | `Sent of string | `Sent_encrypted of string ]

send_otr session message is session', out, user_data, where out should be sent to the communication partner and user_data be presented to the user. Depending on the current session state and configured State.policy, out can be encrypted, or the initiation of an OTR session, or the plain text. session' should be used in subsequent API calls. user_data contains more information on what happened with message (whether it was sent in plain, encrypted, or not at all).

val end_otr : State.session -> State.session * string option

end_otr session is session', out, which ends the OTR session. out should be sent to the communication partner, session' should be used in subsequent calls.

val handle : 
  State.session ->
  string ->
  State.session * string option * State.ret list

handle session data is session', out, ret, which handles received data. out should be sent to the communication partner (might contain data to complete a handshake), ret should be presented to the user. handle potentially decrypts the incoming message, or proceeds in the handshake setup. session' should be used in subsequent calls.

val start_smp : 
  State.session ->
  ?question:string ->
  string ->
  State.session * string option * State.ret list

start_smp session ~question shared_secret is session', out, ret, which starts the socialist millionairs problem if the session is already established, using potentially the question and shared_secret. out should be sent to the communication partner, and ret presented to the user. session' should be used in subsequent calls.

val abort_smp : State.session -> State.session * string option * State.ret list

abort_smp session is session', out, ret, which aborts an unfinished SMP. out should be sent to the communication patner, and ret presented to the user. session' should be used in subsequent calls.

val answer_smp : 
  State.session ->
  string ->
  State.session * string option * State.ret list

answer_smp session secret is session', out, ret, which answers the SMP. out should be sent to the communication partner, and ret presented to the user. The given secret is compared (in a zero-knowledge style) with the communication partners secret. session' should be used in subsequent calls.