Module: FFI::OTR::Callbacks

Included in:
UserState
Defined in:
lib/ffi/otr/callbacks.rb

Overview

These are called from libotr, to be implemented by the application. There is already a basic implementation for #create_privkey and #write_fingerprints, so for minimal operation only #inject_message and #display_otr_message are required. To receive messages about missing callbacks, set the :debug option in your UserState.

Instance Method Summary collapse

Instance Method Details

#account_name(opdata, account, protocol) ⇒ Object

Return a newly allocated string containing a human-friendly representation for the given account.


115
116
117
# File 'lib/ffi/otr/callbacks.rb', line 115

def (opdata, , protocol)
  "#{protocol}://#{}"
end

#account_name_free(opdata, account) ⇒ Object

Deallocate a string returned by #account_name.


120
121
122
# File 'lib/ffi/otr/callbacks.rb', line 120

def (opdata, )
  not_implemented
end

#create_instag(opdata, account, protocol) ⇒ Object

Create a instance tag for the given accountname/protocol if desired.


244
245
246
247
248
249
250
251
# File 'lib/ffi/otr/callbacks.rb', line 244

def create_instag(opdata, , protocol)
  if @opts[:instags]
    debug "Creating new instance tag for #{},#{protocol}"
    otrl_instag_generate(@userstate, @opts[:instags], , protocol)
  else
    not_implemented
  end
end

#create_privkey(opdata, account, protocol) ⇒ Object

Create a private key for the given accountname/protocol if desired.


15
16
17
18
19
20
21
22
23
# File 'lib/ffi/otr/callbacks.rb', line 15

def create_privkey(opdata, , protocol)
  if @opts[:privkey]
    debug "Generating private key for #{} (#{protocol}). This may take a while."
    privkey_generate(@opts[:privkey], @account, @protocol)
    debug "Private key generated. Fingerprint is #{fingerprint}."
  else
    not_implemented
  end
end

#display_otr_message(opdata, account, protocol, user, msg) ⇒ Object

OTR control message for a particular accountname / protocol / username conversation. Return 0 if you are able to successfully display it. If you return non-0 (or if this function is NULL), the control message will be displayed inline, as a received message, or else by using the above notify() callback.


51
52
53
54
# File 'lib/ffi/otr/callbacks.rb', line 51

def display_otr_message(opdata, , protocol, user, msg)
  not_implemented
  0
end

#gone_insecure(opdata, context) ⇒ Object

A ConnContext has left a secure state.


93
94
95
# File 'lib/ffi/otr/callbacks.rb', line 93

def gone_insecure(opdata, context)
  not_implemented
end

#gone_secure(opdata, context) ⇒ Object

A ConnContext has entered a secure state


88
89
90
# File 'lib/ffi/otr/callbacks.rb', line 88

def gone_secure(opdata, context)
  not_implemented
end

#handle_msg_event(opdata, msg_event, context, message, err) ⇒ Object

Handle and send the appropriate message(s) to the sender/recipient depending on the message events. All the events only require an opdata, the event, and the context. The message and err will be NULL except for some events (see below). The possible events are:

Parameters:

  • OTRL_MSGEVENT_ENCRYPTION_REQUIRED

    Our policy requires encryption but we are trying to send an unencrypted message out.

  • OTRL_MSGEVENT_ENCRYPTION_ERROR

    An error occured while encrypting a message and the message was not sent.

  • OTRL_MSGEVENT_CONNECTION_ENDED

    Message has not been sent because our buddy has ended the private conversation. We should either close the connection, or refresh it.

  • OTRL_MSGEVENT_SETUP_ERROR

    A private conversation could not be set up. A gcry_error_t will be passed.

  • OTRL_MSGEVENT_MSG_REFLECTED

    Received our own OTR messages.

  • OTRL_MSGEVENT_MSG_RESENT

    The previous message was resent.

  • OTRL_MSGEVENT_RCVDMSG_NOT_IN_PRIVATE

    Received an encrypted message but cannot read it because no private connection is established yet.

  • OTRL_MSGEVENT_RCVDMSG_UNREADABLE

    Cannot read the received message.

  • OTRL_MSGEVENT_RCVDMSG_MALFORMED

    The message received contains malformed data.

  • OTRL_MSGEVENT_LOG_HEARTBEAT_RCVD

    Received a heartbeat.

  • OTRL_MSGEVENT_LOG_HEARTBEAT_SENT

    Sent a heartbeat.

  • OTRL_MSGEVENT_RCVDMSG_GENERAL_ERR

    Received a general OTR error. The argument 'message' will also be passed and it will contain the OTR error message.

  • OTRL_MSGEVENT_RCVDMSG_UNENCRYPTED

    Received an unencrypted message. The argument 'smessage' will also be passed and it will contain the plaintext message.

  • OTRL_MSGEVENT_RCVDMSG_UNRECOGNIZED

    Cannot recognize the type of OTR message received.


239
240
241
# File 'lib/ffi/otr/callbacks.rb', line 239

def handle_msg_event(opdata, msg_event, context, message, err)
  not_implemented
end

#handle_smp_event(opdata, smp_event, context, progress_percent, question) ⇒ Object

Update the authentication UI with respect to SMP events These are the possible events:

Parameters:

  • OTRL_SMPEVENT_ASK_FOR_SECRET

    prompt the user to enter a shared secret. The sender application should call otrl_message_initiate_smp, passing NULL as the question. When the receiver application resumes the SM protocol by calling otrl_message_respond_smp with the secret answer.

  • OTRL_SMPEVENT_ASK_FOR_ANSWER (same as OTRL_SMPEVENT_ASK_FOR_SECRET but sender calls otrl_message_initiate_smp_q instead)
  • OTRL_SMPEVENT_CHEATED

    abort the current auth and update the auth progress dialog with progress_percent. otrl_message_abort_smp should be called to stop the SM protocol.

  • OTRL_SMPEVENT_INPROGRESS

    and OTRL_SMPEVENT_SUCCESS and OTRL_SMPEVENT_FAILURE and OTRL_SMPEVENT_ABORT update the auth progress dialog with progress_percent

  • OTRL_SMPEVENT_ERROR (same as OTRL_SMPEVENT_CHEATED)

194
195
196
# File 'lib/ffi/otr/callbacks.rb', line 194

def handle_smp_event(opdata, smp_event, context, progress_percent, question)
  not_implemented
end

#inject_message(opdata, account, protocol, recipient, message) ⇒ Object

Send the given IM to the given recipient from the given account/protocol.


35
36
37
# File 'lib/ffi/otr/callbacks.rb', line 35

def inject_message(opdata, , protocol, recipient, message)
  not_implemented
end

#is_logged_in(opdata, account, protocol, recipient) ⇒ Object

Report whether you think the given user is online. Return 1 if you think he is, 0 if you think he isn't, -1 if you're not sure. If you return 1, messages such as heartbeats or other notifications may be sent to the user, which could result in "not logged in" errors if you're wrong.


30
31
32
# File 'lib/ffi/otr/callbacks.rb', line 30

def is_logged_in(opdata, , protocol, recipient)
  not_implemented
end

#log_message(opdata, message) ⇒ Object

Log a message. The passed message will end in "\n".


104
105
106
# File 'lib/ffi/otr/callbacks.rb', line 104

def log_message(opdata, message)
  debug message[0...-1]
end

#max_message_size(opdata, context) ⇒ Object

Find the maximum message size supported by this protocol.


109
110
111
# File 'lib/ffi/otr/callbacks.rb', line 109

def max_message_size(opdata, context)
  @opts[:max_message_size]
end

#new_fingerprint(opdata, userstate, account, protocol, from, fingerprint) ⇒ Object

A new fingerprint for the given user has been received.


74
75
76
# File 'lib/ffi/otr/callbacks.rb', line 74

def new_fingerprint(opdata, userstate, , protocol, from, fingerprint)
  not_implemented
end

#notify(opdata, level, account, protocol, user, title, primary, secondary) ⇒ Object

Display a notification message for a particular accountname / protocol / username conversation.


41
42
43
# File 'lib/ffi/otr/callbacks.rb', line 41

def notify(opdata, level, , protocol, user, title, primary, secondary)
  not_implemented
end

#otr_error_message(opdata, context, err_code) ⇒ Object

Return a string according to the error event. This string will then be concatenated to an OTR header to produce an OTR protocol error message. The following are the possible error events:

Parameters:

  • OTRL_ERRCODE_ENCRYPTION_ERROR

    occured while encrypting a message

  • OTRL_ERRCODE_MSG_NOT_IN_PRIVATE

    sent encrypted message to somebody who is not in a mutual OTR session

  • OTRL_ERRCODE_MSG_UNREADABLE

    sent an unreadable encrypted message

  • OTRL_ERRCODE_MSG_MALFORMED

    message sent is malformed


149
150
151
# File 'lib/ffi/otr/callbacks.rb', line 149

def otr_error_message(opdata, context, err_code)
  not_implemented
end

#otr_error_message_free(opdata, message) ⇒ Object

Deallocate a string returned by otr_error_message


154
155
156
# File 'lib/ffi/otr/callbacks.rb', line 154

def otr_error_message_free(opdata, message)
  not_implemented
end

#policy(opdata, context) ⇒ Object

Return the OTR policy for the given context.


10
11
12
# File 'lib/ffi/otr/callbacks.rb', line 10

def policy(opdata, context)
  @opts[:policy]
end

#protocol_name(opdata, protocol) ⇒ Object

Return a newly allocated string containing a human-friendly name for the given protocol id


64
65
66
# File 'lib/ffi/otr/callbacks.rb', line 64

def protocol_name(opdata, protocol)
  not_implemented
end

#protocol_name_free(opdata, protocol_name) ⇒ Object

Deallocate a string allocated by protocol_name


69
70
71
# File 'lib/ffi/otr/callbacks.rb', line 69

def protocol_name_free(opdata, protocol_name)
  not_implemented
end

#received_symkey(opdata, context, use, usedata, usedatalen, symkey) ⇒ Object

We received a request from the buddy to use the current "extra" symmetric key. The key will be passed in symkey, of length OTRL_EXTRAKEY_BYTES. The requested use, as well as use-specific data will be passed so that the applications can communicate other information (some id for the data transfer, for example).

This is called when a remote buddy has specified a use for the current symmetric key. If your application does not use the extra symmetric key it does not need to provide an implementation for this operation.


133
134
135
# File 'lib/ffi/otr/callbacks.rb', line 133

def received_symkey(opdata, context, use, usedata, usedatalen, symkey)
  not_implemented
end

#resent_msg_prefix(opdata, context) ⇒ Object

Return a string that will be prefixed to any resent message. If this function is not provided by the application then the default prefix, "[resent]", will be used.

These operations give the option of chosing an alternative to the English string "[resent]", when a message is resent.


164
165
166
# File 'lib/ffi/otr/callbacks.rb', line 164

def resent_msg_prefix(opdata, context)
  not_implemented
end

#resent_msg_prefix_free(opdata, prefix) ⇒ Object

Deallocate a string returned by resent_msg_prefix


169
170
171
# File 'lib/ffi/otr/callbacks.rb', line 169

def resent_msg_prefix_free(opdata, prefix)
  not_implemented
end

#still_secure(opdata, context, is_reply, _) ⇒ Object

We have completed an authentication, using the D-H keys we already knew. is_reply indicates whether we initiated the AKE.


99
100
101
# File 'lib/ffi/otr/callbacks.rb', line 99

def still_secure(opdata, context, is_reply, _)
  not_implemented
end

#update_context_list(opdata) ⇒ Object

When the list of ConnContexts changes (including a change in state), this is called so the UI can be updated


58
59
60
# File 'lib/ffi/otr/callbacks.rb', line 58

def update_context_list(opdata)
  not_implemented
end

#write_fingerprints(opdata) ⇒ Object

The list of known fingerprints has changed. Write them to disk.


79
80
81
82
83
84
85
# File 'lib/ffi/otr/callbacks.rb', line 79

def write_fingerprints(opdata)
  if @opts[:fingerprints]
    privkey_write_fingerprints(@opts[:fingerprints])
  else
    not_implemented
  end
end