info.guardianproject.netcipher.proxy

Class OrbotHelper

java.lang.Object

info.guardianproject.netcipher.proxy.OrbotHelper

All Implemented Interfaces:

ProxyHelper

public class OrbotHelper
extends java.lang.Object
implements ProxyHelper

Utility class to simplify setting up a proxy connection to Orbot.

If you are using classes in the info.guardianproject.netcipher.client package, call OrbotHelper.get(this).init(); from onCreate() of a custom Application subclass, or from some other guaranteed entry point to your app. At that point, the info.guardianproject.netcipher.client classes will be ready for use.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	OrbotHelper.InstallCallback Callback interface used for reporting the results of an attempt to install Orbot
static class	OrbotHelper.SimpleStatusCallback

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	ACTION_REQUEST_HS
static java.lang.String	ACTION_START A request to Orbot to transparently start Tor services
static java.lang.String	ACTION_START_TOR
static java.lang.String	ACTION_STATUS Intent send by Orbot with ON/OFF/STARTING/STOPPING status included as an EXTRA_STATUS String.
static java.lang.String	DEFAULT_PROXY_HOST
static int	DEFAULT_PROXY_HTTP_PORT
static int	DEFAULT_PROXY_SOCKS_PORT
static java.lang.String	EXTRA_PACKAGE_NAME A String packageName for Orbot to direct its status reply to, used in ACTION_START Intents sent to Orbot
static java.lang.String	EXTRA_PROXY_PORT_HTTP
static java.lang.String	EXTRA_PROXY_PORT_SOCKS
static java.lang.String	EXTRA_STATUS String that contains a status constant: STATUS_ON, STATUS_OFF, STATUS_STARTING, or STATUS_STOPPING
static int	HS_REQUEST_CODE
static java.lang.String	ORBOT_FDROID_URI
static java.lang.String	ORBOT_MARKET_URI
static java.lang.String	ORBOT_PACKAGE_NAME
static java.lang.String	ORBOT_PLAY_URI
static int	START_TOR_RESULT
static java.lang.String	STATUS_OFF All tor-related services and daemons are stopped
static java.lang.String	STATUS_ON All tor-related services and daemons have completed starting
static java.lang.String	STATUS_STARTING
static java.lang.String	STATUS_STARTS_DISABLED The user has disabled the ability for background starts triggered by apps.
static java.lang.String	STATUS_STOPPING

Fields inherited from interface info.guardianproject.netcipher.proxy.ProxyHelper

FDROID_PACKAGE_NAME, PLAY_PACKAGE_NAME

Method Summary

Modifier and Type	Method and Description
OrbotHelper	addInstallCallback(OrbotHelper.InstallCallback cb) Adds an InstallCallback to be called when we find out that Orbot is installed
OrbotHelper	addStatusCallback(StatusCallback cb) Adds a StatusCallback to be called when we find out that Orbot is ready.
static OrbotHelper	get(android.content.Context context) Retrieves the singleton, initializing if if needed
android.content.Intent	getInstallIntent(android.content.Context context)
java.lang.String	getName()
static android.content.Intent	getOrbotInstallIntent(android.content.Context context)
static android.content.Intent	getOrbotStartIntent() Deprecated.
static android.content.Intent	getOrbotStartIntent(android.content.Context context) Gets an Intent for starting Orbot.
static android.content.Intent	getShowOrbotStartIntent()
android.content.Intent	getStartIntent(android.content.Context context)
boolean	init() Initializes the connection to Orbot, revalidating that it is installed and requesting fresh status broadcasts.
void	installOrbot(android.app.Activity host) Given that init() returned false, calling installOrbot() will trigger an attempt to install Orbot from an available distribution channel (e.g., the Play Store).
OrbotHelper	installTimeout(long timeoutMs) Sets how long of a delay, in milliseconds, after trying to install Orbot do we assume that it's not happening.
boolean	isInstalled()
boolean	isInstalled(android.content.Context context)
static boolean	isOnionAddress(java.lang.String urlString) Test whether a URL String is a Tor Hidden Service host name, also known as an ".onion address".
static boolean	isOnionAddress(android.net.Uri uri) Test whether a Uri is a Tor Hidden Service host name, also known as an ".onion address".
static boolean	isOnionAddress(java.net.URL url) Test whether a URL is a Tor Hidden Service host name, also known as an ".onion address".
static boolean	isOrbotInstalled(android.content.Context context)
static boolean	isOrbotRunning(android.content.Context context) Deprecated.
OrbotHelper	removeInstallCallback(OrbotHelper.InstallCallback cb) Removes an existing registered InstallCallback.
OrbotHelper	removeStatusCallback(StatusCallback cb) Removes an existing registered StatusCallback.
static void	requestHiddenServiceOnPort(android.app.Activity activity, int port)
static boolean	requestShowOrbotStart(android.app.Activity activity) First, checks whether Orbot is installed, then checks whether Orbot is running.
boolean	requestStart(android.content.Context context)
static boolean	requestStartTor(android.content.Context context) First, checks whether Orbot is installed.
void	requestStatus(android.content.Context context)
OrbotHelper	skipOrbotValidation() By default, NetCipher ensures that the Orbot on the device is one of the official builds.
OrbotHelper	statusTimeout(long timeoutMs) Sets how long of a delay, in milliseconds, after trying to get a status from Orbot before we give up.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ORBOT_PACKAGE_NAME

public static final java.lang.String ORBOT_PACKAGE_NAME

See Also:

Constant Field Values

ORBOT_MARKET_URI

public static final java.lang.String ORBOT_MARKET_URI

See Also:

Constant Field Values

ORBOT_FDROID_URI

public static final java.lang.String ORBOT_FDROID_URI

See Also:

Constant Field Values

ORBOT_PLAY_URI

public static final java.lang.String ORBOT_PLAY_URI

See Also:

Constant Field Values

DEFAULT_PROXY_HOST

public static final java.lang.String DEFAULT_PROXY_HOST

See Also:

Constant Field Values

DEFAULT_PROXY_HTTP_PORT

public static final int DEFAULT_PROXY_HTTP_PORT

See Also:

Constant Field Values

DEFAULT_PROXY_SOCKS_PORT

public static final int DEFAULT_PROXY_SOCKS_PORT

See Also:

Constant Field Values

ACTION_START

public static final java.lang.String ACTION_START

A request to Orbot to transparently start Tor services

See Also:

Constant Field Values

ACTION_STATUS

public static final java.lang.String ACTION_STATUS

Intent send by Orbot with ON/OFF/STARTING/STOPPING status included as an EXTRA_STATUS String. Your app should always receive ACTION_STATUS Intents since any other app could start Orbot. Also, user-triggered starts and stops will also cause ACTION_STATUS Intents to be broadcast.

See Also:

Constant Field Values

EXTRA_STATUS

public static final java.lang.String EXTRA_STATUS

String that contains a status constant: STATUS_ON, STATUS_OFF, STATUS_STARTING, or STATUS_STOPPING

See Also:

Constant Field Values

EXTRA_PACKAGE_NAME

public static final java.lang.String EXTRA_PACKAGE_NAME

A String packageName for Orbot to direct its status reply to, used in ACTION_START Intents sent to Orbot

See Also:

Constant Field Values

EXTRA_PROXY_PORT_HTTP

public static final java.lang.String EXTRA_PROXY_PORT_HTTP

See Also:

Constant Field Values

EXTRA_PROXY_PORT_SOCKS

public static final java.lang.String EXTRA_PROXY_PORT_SOCKS

See Also:

Constant Field Values

STATUS_OFF

public static final java.lang.String STATUS_OFF

All tor-related services and daemons are stopped

See Also:

Constant Field Values

STATUS_ON

public static final java.lang.String STATUS_ON

All tor-related services and daemons have completed starting

See Also:

Constant Field Values

STATUS_STARTING

public static final java.lang.String STATUS_STARTING

See Also:

Constant Field Values

STATUS_STOPPING

public static final java.lang.String STATUS_STOPPING

See Also:

Constant Field Values

STATUS_STARTS_DISABLED

public static final java.lang.String STATUS_STARTS_DISABLED

The user has disabled the ability for background starts triggered by apps. Fallback to the old Intent that brings up Orbot.

See Also:

Constant Field Values

ACTION_START_TOR

public static final java.lang.String ACTION_START_TOR

See Also:

Constant Field Values

ACTION_REQUEST_HS

public static final java.lang.String ACTION_REQUEST_HS

See Also:

Constant Field Values

START_TOR_RESULT

public static final int START_TOR_RESULT

See Also:

Constant Field Values

HS_REQUEST_CODE

public static final int HS_REQUEST_CODE

See Also:

Constant Field Values

Method Detail

isOnionAddress

public static boolean isOnionAddress(java.net.URL url)

Test whether a URL is a Tor Hidden Service host name, also known as an ".onion address".

Returns:

whether the host name is a Tor .onion address

isOnionAddress

public static boolean isOnionAddress(java.lang.String urlString)

Test whether a URL String is a Tor Hidden Service host name, also known as an ".onion address".

Returns:

whether the host name is a Tor .onion address

isOnionAddress

public static boolean isOnionAddress(android.net.Uri uri)

Test whether a Uri is a Tor Hidden Service host name, also known as an ".onion address".

Returns:

whether the host name is a Tor .onion address

isOrbotRunning

@Deprecated
public static boolean isOrbotRunning(android.content.Context context)

Deprecated.

Check if the tor process is running. This method is very brittle, and is therefore deprecated in favor of using the ACTION_STATUS Intent along with the requestStartTor(Context) method.

isOrbotInstalled

public static boolean isOrbotInstalled(android.content.Context context)

requestHiddenServiceOnPort

public static void requestHiddenServiceOnPort(android.app.Activity activity,
                                              int port)

requestStartTor

public static boolean requestStartTor(android.content.Context context)

First, checks whether Orbot is installed. If Orbot is installed, then a broadcast Intent is sent to request Orbot to start transparently in the background. When Orbot receives this Intent, it will immediately reply to the app that called this method with an ACTION_STATUS Intent that is broadcast to the packageName of the provided Context (i.e. Context.getPackageName().

That reply ACTION_STATUS Intent could say that the user has disabled background starts with the status STATUS_STARTS_DISABLED. That means that Orbot ignored this request. To directly prompt the user to start Tor, use requestShowOrbotStart(Activity), which will bring up Orbot itself for the user to manually start Tor. Orbot always broadcasts it's status, so your app will receive those no matter how Tor gets started.

Parameters:

context - the app Context will receive the reply

Returns:

whether the start request was sent to Orbot

See Also:

requestShowOrbotStart(Activity activity)

getOrbotStartIntent

public static android.content.Intent getOrbotStartIntent(android.content.Context context)

Gets an Intent for starting Orbot. Orbot will reply with the current status to the packageName of the app in the provided Context (i.e. Context.getPackageName().

getOrbotStartIntent

@Deprecated
public static android.content.Intent getOrbotStartIntent()

Deprecated.

Gets a barebones Intent for starting Orbot. This is deprecated in favor of getOrbotStartIntent(Context).

requestShowOrbotStart

public static boolean requestShowOrbotStart(android.app.Activity activity)

First, checks whether Orbot is installed, then checks whether Orbot is running. If Orbot is installed and not running, then an Intent is sent to request the user to start Orbot, which will show the main Orbot screen. The result will be returned in Activity.onActivityResult(int requestCode, int resultCode, Intent data) with a requestCode of START_TOR_RESULT

Orbot will also always broadcast the status of starting Tor via the ACTION_STATUS Intent, no matter how it is started.

Parameters:

activity - the Activity that gets the result of the START_TOR_RESULT request

Returns:

whether the start request was sent to Orbot

See Also:

requestStartTor(Context context)

getShowOrbotStartIntent

public static android.content.Intent getShowOrbotStartIntent()

getOrbotInstallIntent

public static android.content.Intent getOrbotInstallIntent(android.content.Context context)

isInstalled

public boolean isInstalled(android.content.Context context)

Specified by:

isInstalled in interface ProxyHelper

requestStatus

public void requestStatus(android.content.Context context)

Specified by:

requestStatus in interface ProxyHelper

requestStart

public boolean requestStart(android.content.Context context)

Specified by:

requestStart in interface ProxyHelper

getInstallIntent

public android.content.Intent getInstallIntent(android.content.Context context)

Specified by:

getInstallIntent in interface ProxyHelper

getStartIntent

public android.content.Intent getStartIntent(android.content.Context context)

Specified by:

getStartIntent in interface ProxyHelper

getName

public java.lang.String getName()

Specified by:

getName in interface ProxyHelper

get

public static OrbotHelper get(android.content.Context context)

Retrieves the singleton, initializing if if needed

Parameters:

context - any Context will do, as we will hold onto the Application

Returns:

the singleton

addStatusCallback

public OrbotHelper addStatusCallback(StatusCallback cb)

Adds a StatusCallback to be called when we find out that Orbot is ready. If Orbot is ready for use, your callback will be called with onEnabled() immediately, before this method returns.

Parameters:

cb - a callback

Returns:

the singleton, for chaining

removeStatusCallback

public OrbotHelper removeStatusCallback(StatusCallback cb)

Removes an existing registered StatusCallback.

Parameters:

cb - the callback to remove

Returns:

the singleton, for chaining

addInstallCallback

public OrbotHelper addInstallCallback(OrbotHelper.InstallCallback cb)

Adds an InstallCallback to be called when we find out that Orbot is installed

Parameters:

cb - a callback

Returns:

the singleton, for chaining

removeInstallCallback

public OrbotHelper removeInstallCallback(OrbotHelper.InstallCallback cb)

Removes an existing registered InstallCallback.

Parameters:

cb - the callback to remove

Returns:

the singleton, for chaining

statusTimeout

public OrbotHelper statusTimeout(long timeoutMs)

Sets how long of a delay, in milliseconds, after trying to get a status from Orbot before we give up. Defaults to 30000ms = 30 seconds = 0.000347222 days

Parameters:

timeoutMs - delay period in milliseconds

Returns:

the singleton, for chaining

installTimeout

public OrbotHelper installTimeout(long timeoutMs)

Sets how long of a delay, in milliseconds, after trying to install Orbot do we assume that it's not happening. Defaults to 60000ms = 60 seconds = 1 minute = 1.90259e-6 years

Parameters:

timeoutMs - delay period in milliseconds

Returns:

the singleton, for chaining

skipOrbotValidation

public OrbotHelper skipOrbotValidation()

By default, NetCipher ensures that the Orbot on the device is one of the official builds. Call this method to skip that validation. Mostly, this is for developers who have their own custom Orbot builds (e.g., for dedicated hardware).

Returns:

the singleton, for chaining

isInstalled

public boolean isInstalled()

Returns:

true if Orbot is installed (the last time we checked), false otherwise

init

public boolean init()

Initializes the connection to Orbot, revalidating that it is installed and requesting fresh status broadcasts. This is best run in your app's Application subclass, in its Application.onCreate() method.

Returns:

true if initialization is proceeding, false if Orbot is not installed, or version of Orbot with a unofficial signing key is present.

installOrbot

public void installOrbot(android.app.Activity host)

Given that init() returned false, calling installOrbot() will trigger an attempt to install Orbot from an available distribution channel (e.g., the Play Store). Only call this if the user is expecting it, such as in response to tapping a dialog button or an action bar item.

Note that installation may take a long time, even if the user is proceeding with the installation, due to network speeds, waiting for user input, and so on. Either specify a long timeout, or consider the timeout to be merely advisory and use some other user input to cause you to try init() again after, presumably, Orbot has been installed and configured by the user.

If the user does install Orbot, we will attempt init() again automatically. Hence, you will probably need user input to tell you when the user has gotten Orbot up and going.

Parameters:

host - the Activity that is triggering this work