path: root/src/net/java/sip/communicator/plugin/otr/ScOtrEngine.java

/*
 * Jitsi, the OpenSource Java VoIP and Instant Messaging client.
 *
 * Copyright @ 2015 Atlassian Pty Ltd
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package net.java.sip.communicator.plugin.otr;

import java.security.*;
import java.util.*;

import net.java.otr4j.*;
import net.java.otr4j.session.*;
import net.java.sip.communicator.plugin.otr.OtrContactManager.OtrContact;
import net.java.sip.communicator.service.protocol.*;

/**
 * This interface must be implemented by classes that provide the Off-the-Record
 * functionality.
 *
 * @author George Politis
 */
public interface ScOtrEngine
{
    // Proxy methods OtrEngine.

    /**
     * Initializes Smp negotiation.
     * @See <a href="http://en.wikipedia.org/wiki/Socialist_Millionaire_Problem"
     * >http://en.wikipedia.org/wiki/Socialist_Millionaire_Problem</a>
     * 
     * @param contact The contact with whom we want to start the Smp negotiation
     * @param question The question that is asked during the Smp negotiation
     * @param secret The secret answer for the question.
     */
    public abstract void initSmp(
        OtrContact contact, String question, String secret);

    /**
     * Responds to a question that is asked during the Smp negotiation process.
     * @See <a href="http://en.wikipedia.org/wiki/Socialist_Millionaire_Problem"
     * >http://en.wikipedia.org/wiki/Socialist_Millionaire_Problem</a>
     * 
     * @param contact The contact for whom we want to respond to a question
     *                  during the Smp negotiation process.
     * @param receiverTag The instance tag of the intended receiver of the SMP
     *                  response
     * @param question The question that is asked during the Smp negotiation.
     * @param secret The secret answer for the question.
     */
    public abstract void respondSmp(OtrContact contact,
                                    InstanceTag receiverTag,
                                    String question,
                                    String secret);

    /**
     * Aborts the Smp negotiation process.
     * @See <a href="http://en.wikipedia.org/wiki/Socialist_Millionaire_Problem"
     * >http://en.wikipedia.org/wiki/Socialist_Millionaire_Problem</a>
     * 
     * @param contact The contact with whom we want to abort the
     * Smp negotiation process.
     */
    public abstract void abortSmp(OtrContact contact);

    /**
     * Transforms an outgoing message.
     *
     * @param contact the destination {@link OtrContact}.
     * @param content the original message content.
     * @return the transformed message content.
     */
    public abstract String[] transformSending(OtrContact contact, String content);

    /**
     * Transforms an incoming message.
     *
     * @param contact the source {@link OtrContact}.
     * @param content the original message content.
     * @return the transformed message content.
     */
    public abstract String transformReceiving(OtrContact contact, String content);

    /**
     * Starts the Off-the-Record session for the given {@link OtrContact}, if it's
     * not already started.
     *
     * @param contact the {@link OtrContact} with whom we want to start an OTR
     *            session.
     */
    public abstract void startSession(OtrContact contact);

    /**
     * Ends the Off-the-Record session for the given {@link OtrContact}, if it is
     * not already started.
     *
     * @param contact the {@link OtrContact} with whom we want to end the OTR
     *            session.
     */
    public abstract void endSession(OtrContact contact);

    /**
     * Refreshes the Off-the-Record session for the given {@link OtrContact}. If
     * the session does not exist, a new session is established.
     *
     * @param contact the {@link OtrContact} with whom we want to refresh the OTR
     *            session.
     */
    public abstract void refreshSession(OtrContact contact);

    /**
     * Get the outgoing OTRv3 <tt>Session</tt>. This could be the 'master'
     * session as well as a 'slave' session.
     * This method could also be safely used for OTRv2 sessions. In the case of
     * version 2 the master session itself will always be returned.
     *
     * @param contact the {@link OtrContact} for whom we want to get the
     * outgoing OTR session.
     *
     * @return the <tt>Session</tt> that is currently transforming outgoing all
     *            messages.
     */
    public abstract Session getOutgoingSession(OtrContact contact);

    /**
     * Some IM networks always relay all messages to all sessions of a client
     * who is logged in multiple times. OTR version 3 deals with this problem
     * with introducing instance tags.
     * <a href="https://otr.cypherpunks.ca/Protocol-v3-4.0.0.html">
     * https://otr.cypherpunks.ca/Protocol-v3-4.0.0.html</a>
     * <p>
     * Returns a list containing all instances of a session. The 'master'
     * session is always first in the list.
     * 
     * @param contact the {@link OtrContact} for whom we want to get the instances
     * 
     * @return A list of all instances of the session for the specified contact.
     */
    public abstract List<Session> getSessionInstances(OtrContact contact);

    /**
     * Some IM networks always relay all messages to all sessions of a client
     * who is logged in multiple times. OTR version 3 deals with this problem
     * with introducing instance tags.
     * <a href="https://otr.cypherpunks.ca/Protocol-v3-4.0.0.html">
     * https://otr.cypherpunks.ca/Protocol-v3-4.0.0.html</a>
     * <p>
     * When the client wishes to start sending OTRv3 encrypted messages to a
     * specific session of his buddy who is logged in multiple times, he can set
     * the outgoing instance of his buddy by specifying his <tt>InstanceTag</tt>.
     * 
     * @param contact the {@link OtrContact} to whom we want to set the outgoing
     *          instance tag.
     * @param tag the outgoing {@link InstanceTag}
     *
     * @return true if an outgoing session with such {@link InstanceTag} exists
     *          . Otherwise false
     */
    public abstract boolean setOutgoingSession(OtrContact contact, InstanceTag tag);

    /**
     * Gets the {@link ScSessionStatus} for the given {@link OtrContact}.
     *
     * @param contact the {@link OtrContact} whose {@link ScSessionStatus} we are
     *            interested in.
     * @return the {@link ScSessionStatus}.
     */
    public abstract ScSessionStatus getSessionStatus(OtrContact contact);

    // New Methods (Misc)

    /**
     * Gets weather the passed in messageUID is injected by the engine or not.
     * If it is injected, it shouldn't be re-transformed.
     *
     * @param messageUID the messageUID which is to be determined whether it is
     * injected by the engine or not
     * @return <tt>true</tt> if the passed in messageUID is injected by the
     * engine; <tt>false</tt>, otherwise
     */
    public abstract boolean isMessageUIDInjected(String messageUID);

    /**
     * Registers an {@link ScOtrEngineListener}.
     *
     * @param listener the {@link ScOtrEngineListener} to register.
     */
    public abstract void addListener(ScOtrEngineListener listener);

    /**
     * Unregisters an {@link ScOtrEngineListener}.
     *
     * @param listener the {@link ScOtrEngineListener} to unregister.
     */
    public abstract void removeListener(ScOtrEngineListener listener);

    public abstract PublicKey getRemotePublicKey(OtrContact otrContact);

    // New Methods (Policy management)
    /**
     * Gets the global {@link OtrPolicy}.
     *
     * @return the global {@link OtrPolicy}
     */
    public abstract OtrPolicy getGlobalPolicy();

    /**
     * Gets a {@link Contact} specific policy.
     *
     * @param contact the {@link Contact} whose policy we want.
     * @return The {@link Contact} specific OTR policy. If the specified
     *         {@link Contact} has no policy, the global policy is returned.
     */
    public abstract OtrPolicy getContactPolicy(Contact contact);

    /**
     * Sets the global policy.
     *
     * @param policy the global policy
     */
    public abstract void setGlobalPolicy(OtrPolicy policy);

    /**
     * Sets the contact specific policy
     *
     * @param contact the {@link Contact} whose policy we want to set
     * @param policy the {@link OtrPolicy}
     */
    public abstract void setContactPolicy(Contact contact, OtrPolicy policy);

    /**
     * Launches the help page.
     */
    public abstract void launchHelp();
}