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’

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 email 2FA
Check usage on Github: JS Example
Parameters:code (String) – OTP received via email
Returns:success
Return type: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
Returns:

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_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 email address for two factor authentication. Method not available if email 2FA is enabled.
Check usage on Github: JS Example
Parameters:
  • email (string) – Email address
  • twofac_data – See Passing OTPs
Returns: