twofactor module¶

Two Factor Authentication (2FA) is an important piece of your GreenAddress wallet security.

When 2FA is enabled for a users wallet, operations that change security settings or move coins require 2FA authorization. This is done by requesting a One Time Password (OTP) for the required action from the service. After the service delivers the OTP to the user, the user passes it to to the API which allows the action to proceed.

One Time Passwords are valid only for a specific action and for a limited time.

Methods¶

The following two factor methods are available:

method	description
email	Sends the action details and OTP via email
gauth	Uses Google Authenticator to calculate OTPs
phone	Reads a short summary and the OTP via phone call
proxy	See Proxies
sms	Sends a short summary and the OTP via SMS

Note that SMS and phone authentication have recently been shown to be insecure and should not be used if possible. Users should always enable more than one two factor method and ensure they back up any two factor data in order to maintain full access to their wallet.

Action types¶

When calling the API calls request_<method> to request an OTP, you must pass an action string and associated data. The table below describes the available actions along with the corresponding expected data format.

action	data	Notes
activate_email	{}	No data
change_tx_limits	{ ‘is_fiat’: <bool>, ‘total’: <int>, ‘per_tx’: <bool>, }
enable_2fa	{ ‘method’: <string> }	2fa method to enable, one of: ‘email’ ‘sms’ ‘phone’ ‘gauth’
cancel_reset	{}	No data
remove_account	{}	No data
send_tx
set_nlocktime	{ ‘value’: <int>, }	nlocktime value
sign_alt_tx	{ ‘sha256d’: <hex>, ‘txtype’: <string> }	Double SHA256 of tx to sign Tx type to sign, one of: ‘bcash’, ‘forkid’

Passing OTPs¶

For calls that require a 2fa_data parameter, this takes the following format:

{'method': String, 'code': String }

Where method is a supported 2FA method (See Methods) and code is the OTP received using that method for the action to perform.

In cases where the user has no 2FA enabled, this parameter can be passed as null or an empty map.

Proxies¶

In GreenAddress 2FA proxies allow setting up 2FA using an existing 2FA method. The call request_proxy fetches an OTP for a new 2FA method given a valid OTP from an exiting method. This can be used to improve the user experience and reduce mistakes when interactively setting up two factor.

For example, assume a user that has email 2FA already enabled, and wishes to enable SMS. Using a proxy the application would do the following:

Request an OTP to enable the new SMS method from GreenAddress:

twofactor.request_email('enable_2fa', {'method': 'sms'})

Prompt the user to check their email and enter the OTP EMAIL_OTP received.

Request a proxy OTP PROXY_OTP for SMS using EMAIL_OTP from GreenAddress, then request enabling SMS 2FA using PROXY_OTP:

twofactor.request_proxy('sms', {'method': 'email', 'code': 'EMAIL_OTP'})

twofactor.init_enable_sms('<phone number>', {'method': 'proxy', 'code': 'PROXY_OTP'})

Prompt the user to check their SMS and enter the OTP SMS_OTP received.

Enable SMS 2FA using enable_sms:

twofactor.enable_sms('SMS_OTP')

Using a proxy in this case allows the order of operations presented to the user to be changed such that they are not prompted for the email and then SMS OTPs directly after each other.

For non interactive enablement, the proxy step can be skipped in this example by passing the orginal email code to twofactor.init_enable_sms instead.

API Calls¶

com.greenaddress.twofactor

com.greenaddress.twofactor.activate_email(code)¶

Activate the email address previously set by calling set_email.

Check usage on Github: Python Example

Parameters: code (String) –
OTP received via email after calling set_email

Returns: success

Return type: Boolean

com.greenaddress.twofactor.cancel_reset(twofac_data)¶

Cancel all outstanding two factor resets and unlock the wallet for normal operation.

Parameters: twofac_data – See Passing OTPs

Return type: { ‘reset_2fa_active’: False, ‘reset_2fa_days_remaining’: -1, ‘reset_2fa_disputed’: False }

com.greenaddress.twofactor.confirm_reset(email, is_dispute, twofac_data)¶

Confirm a twofactor reset request made by twofactor.request_reset.

Parameters:

email (String) – The email address originally passed to twofactor.request_reset

is_dispute (Boolean) – Pass true if the user is disputing an existing reset request

twofac_data – See Passing OTPs

Return type:
{ ‘reset_2fa_active’: Boolean, ‘reset_2fa_days_remaining’: Integer, ‘reset_2fa_disputed’: Boolean }

com.greenaddress.twofactor.disable_email(twofac_data)¶

Disable email two factor authentication.

Parameters: twofac_data – See Passing OTPs

Returns: success

Return type: Boolean

com.greenaddress.twofactor.disable_gauth(twofac_data)¶

Disable Google Authenticator

Parameters: twofac_data (String) – Gauth OTP

Returns: success

Return type: Boolean

com.greenaddress.twofactor.disable_phone(twofac_data)¶

Disable automated phone call two factor authentication.

Parameters: twofac_data – See Passing OTPs

Returns: success

Return type: Boolean

com.greenaddress.twofactor.disable_sms(twofac_data)¶

Disable SMS two factor authentication

Parameters: twofac_data – See Passing OTPs

Returns: success

Return type: Boolean

com.greenaddress.twofactor.enable_email(code[, reset_email])¶

Enable email two factor authentication on previously set email address.

Parameters: code – If you have another 2FA enabled, would be {‘code’: String (OTP), ‘method’: String}, else an empty String.

com.greenaddress.twofactor.enable_email_twofac(twofac_data)¶

com.greenaddress.twofactor.enable_gauth(code, twofac_data)¶

Enable Google Authenticator two factor authentication

Parameters:

code (Number) – OTP generated by Google Authenticator

twofac_data – See Passing OTPs

Return type:
Boolean

com.greenaddress.twofactor.enable_phone(code)¶

Enable automated phone call two factor authentication

Parameters: code (String) – OTP

Returns:

com.greenaddress.twofactor.enable_sms(code)¶

Enable SMS two factor authentication

Parameters: code (String) – OTP received via SMS

Returns:

com.greenaddress.twofactor.get_config()¶

Get two factor authentication configuration.

Returns: {‘any’: Boolean, ‘email’: Boolean, ‘email_addr’: String, ‘email_confirmed’: Boolean, ‘gauth’: Boolean, ‘gauth_url’: String, ‘phone’: Boolean, ‘sms’: Boolean}

com.greenaddress.twofactor.init_enable_email(email, twofac_data)¶

Initialize the procedure to enable an email based two factor authentication

Parameters:

email (String) – Email address for 2FA

twofac_data – See Passing OTPs

com.greenaddress.twofactor.init_enable_phone(number, twofac_data)¶

Initialize the procedure to enable automated phone call based two factor authentication.

Phone numbers must be given in E.164 format as defined in

http://www.itu.int/ITU-T/recommendations/rec.aspx?rec=E.164.

Parameters:

number (String) – Phone number for two factor authentication

twofac_data – See Passing OTPs

com.greenaddress.twofactor.init_enable_sms(number, twofac_data)¶

Initialize the procedure to enable SMS two factor authentication.

Phone numbers must be given in E.164 format as defined in

http://www.itu.int/ITU-T/recommendations/rec.aspx?rec=E.164.

Parameters:

number (String) – Phone number for two factor authentication

twofac_data – See Passing OTPs

com.greenaddress.twofactor.request_email([action][, data])¶

Request an OTP via email, valid for the specified action.

Parameters:

action (String) – The 2FA action. See Action types.

data (String) – Data specific to action. See Action types.

Returns:
None

com.greenaddress.twofactor.request_phone([action][, data])¶

Request an OTP via automated phone call, valid for the specified action.

Parameters:

action (String) – The 2FA action. See Action types.

data (String) – Data specific to action. See Action types.

Returns:
None

com.greenaddress.twofactor.request_proxy(method, twofac_data)¶

Request a proxy OTP from an existing OTP. See Proxies.

Parameters:

method (String) – Other 2FA method on which the proxy OTP will authorize.

twofac_data – See Passing OTPs

Returns:

com.greenaddress.twofactor.request_redeposit_proxy(twofac_data)¶

Request a redeposit proxy OTP from an existing OTP. See Proxies.

Redeposit proxies are valid for 5 minutes after being sent and can be

used for any number of redeposits until this time is up.

Parameters: twofac_data – See Passing OTPs

Returns:

com.greenaddress.twofactor.request_reset(email)¶

Request to begin the two factor authentication reset process.

Note that this locks the user’s wallet for a fixed period of time (currently 12 months)

plus the nlocktime of any outstanding balance in the wallet. For example, if the wallet

has a UTXO with nlocktime 6 months from now, the reset process will lock the wallet for

18 months.

Once confirmed a reset request can only be cancelled by a user with access to the

original two factor authentication (by calling twofactor.cancel_reset).

Parameters: email (String) – The new email address that the user will use for two factor once the reset period expires

Return type: { ‘reset_2fa_active’: Boolean, ‘reset_2fa_days_remaining’: -1, ‘reset_2fa_disputed’: Boolean }

com.greenaddress.twofactor.request_sms([action][, data])¶

Request an OTP via SMS, valid for the specified action.

Parameters:

action (String) – The 2FA action. See Action types.

data (String) – Data specific to action. See Action types.

Returns:
None

com.greenaddress.twofactor.set_email(email, twofac_data)¶

Set the email address associated with the wallet.

Sends an email with a confirmation code which should be passed to activate_email

to complete the operation.

Note that this does not enable email 2FA - it is possible to set an email address for the

wallet to receive notifications without enabling it as a 2FA method.

To enable email 2FA see init_enable_email and enable_email.

This method is not available if email 2FA is enabled.

Check usage on Github: Python Example

Parameters:

email (string) – Email address

twofac_data – See Passing OTPs

Returns: