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
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: JS 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.
Check usage on Github: JS Example
Parameters:twofac_data – See Passing OTPs
Returns:success
Return type:Boolean
com.greenaddress.twofactor.disable_gauth(twofac_data)
Disable Google Authenticator
Check usage on Github: JS Example
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.
Check usage on Github: JS Example
Parameters:twofac_data – See Passing OTPs
Returns:success
Return type:Boolean
com.greenaddress.twofactor.disable_sms(twofac_data)
Disable SMS two factor authentication
Check usage on Github: JS Example
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.
Check usage on Github: JS Example
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
Check usage on Github: JS Example
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
Check usage on Github: JS Example
Parameters:code (String) – OTP
Returns:
com.greenaddress.twofactor.enable_sms(code)
Enable SMS two factor authentication
Check usage on Github: JS Example
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
Check usage on Github: JS Example
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
Check usage on Github: JS Example
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
Check usage on Github: JS Example
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.
Check usage on Github: JS Example
Parameters:
Returns:

None

com.greenaddress.twofactor.request_phone([action][, data])
Request an OTP via automated phone call, valid for the specified action.
Check usage on Github: JS Example
Parameters:
Returns:

None

com.greenaddress.twofactor.request_proxy(method, twofac_data)
Request a proxy OTP from an existing OTP. See Proxies.
Check usage on Github: JS Example
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.
Check usage on Github: JS Example
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.
Check usage on Github: JS Example
Parameters:
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: JS Example
Parameters:
  • email (string) – Email address
  • twofac_data – See Passing OTPs
Returns: