twofactor module

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

When 2FA is active (mandatory by default from our clients) for some funds/auth related operations on the GreenAddress API, the user is requested to verify themselves with a One Time Password.

OTP are handled by different methods, and whenever it is needed to set up a 2FA while another 2FA is active (i.e., setting a new SMS 2FA, confirming it with the email OTP) a proxy method is called.

proxies

In GreenAddress 2FA ‘proxies’ allow setting up a 2FA using another 2FA. A ‘proxy code’ is another kind of OTP, valid for 5 minutes, which is used for the sole purpose of enabling a new 2FA method. The ‘proxy codes’ are obtained by using some already set up 2FA method. It was implemented this way to allow the client to authenticate against some existing 2FA before providing the new 2FA data.

For example, on an account with previously enabled email 2FA, the steps to enable SMS 2FA are as follows:

  • Do a ‘request_email’, specify ‘enable_2fa’ as action and {method: ‘sms’} as data - this requests an email authorizing the new 2FA setup.
  • With the email OTP do a request_proxy, specifying ‘sms’ as the new ‘method’ and {code: “799154”, method: “email”} as twofac_data. We assume a proxy OTP ‘923039’ is returned. This ‘proxy code’ now allows initialising setting up of the new 2FA without providing any code than the ‘proxy code’ internally stored by the client.
  • Call the init_enable_sms method, with the full intl number as ‘number’ and {method: “proxy”, code: “923039”} as ‘twofac_data’.
  • Confirm the sms code, once received, with enable_sms method.

(To illustrate why proxies are useful: You should be also able to simply set up the new 2FA by providing the first email code as an argument to init_enable_sms, but then you need to know the phone number at the same time as the code, so you can’t validate the code provided by the user separately. This is especially important for user experience because you’d then have to ask for the second code directly after the ‘old method code’ and users could confuse the two codes - asking for ‘(1) email code, (2) phone number, (3) sms code’ is better in our opinion than asking for ‘(1) phone number, (2) email code, (3) sms code’ which would be the case without proxies - the order with asking for ‘phone number preceding the sms code’ seems more natural than ‘email code preceding sms code’.)

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 – {‘code’: String (OTP), method: ‘String’ (‘email’, ‘gauth’, ‘sms’, ‘phone’) }
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 robot phonecall two factor authentication.
Check usage on Github: JS Example
Parameters:twofac_data – {‘code’: String (OTP), method: ‘String’ (‘email’, ‘gauth’, ‘sms’, ‘phone’) }
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 – {‘code’: String (OTP), method: ‘String’ (‘email’, ‘gauth’, ‘sms’, ‘phone’) }
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
  • twofac_data – {‘method’: String, ‘code’: String}
Returns:

com.greenaddress.twofactor.enable_phone(code)
Enable robot 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
Returns:
com.greenaddress.twofactor.get_config()
Get two factor authentication configuration.
Check usage on Github: JS Example
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 – Data from already enabled 2fa. i.e. {code: “123456”, method: “sms”}
com.greenaddress.twofactor.init_enable_phone(number, twofac_data)
Initialize the procedure to enable a phone bot-call based two factor authentication.
Check usage on Github: JS Example
Parameters:
  • number (String) – Phone number for two factor authentication
  • twofac_data – Data from already enabled 2fa. i.e. {code: “123456”, method: “sms”}
com.greenaddress.twofactor.init_enable_sms(number, twofac_data)
Initialize the procedure to enable a SMS based two factor authentication
Check usage on Github: JS Example
Parameters:
  • number (String) – Phone number for two factor authentication
  • twofac_data – Data from already enabled 2fa. i.e. {code: “799154”, method: “email”}
com.greenaddress.twofactor.request_email([action][, data])
Request the OTP via email, valid for the specified action.
Check usage on Github: JS Example
Parameters:
  • action (String) – The action you’re going to execute and authorize with 2FA (i.e. ‘send_tx’)
  • data
Returns:

None

com.greenaddress.twofactor.request_phone([action][, data])
Request the OTP via robot phone call, valid for the specified action.
Check usage on Github: JS Example
Parameters:
  • action (String) – The action you’re going to execute and authorize with 2FA (i.e. ‘send_tx’)
  • data
Returns:

None

com.greenaddress.twofactor.request_proxy(method, twofac_data)
In GreenAddress two factor authentication, proxies are used to interact with a 2FA method from another.
Check usage on Github: JS Example
Parameters:
  • method (String) – Other 2FA method on which the proxy OTP will authorize.
  • twofac_data – Previously used 2fa method: i.e. {‘method’: ‘email’:, ‘code’: ‘123456’}
Returns:

com.greenaddress.twofactor.request_redeposit_proxy(twofac_data)

In GreenAddress, 2FA codes are not reusable, also if they have a limited validity time, like Google Authenticator. However, for nLocktime and multiple redeposits in a round, the need of a reusable 2FA code went up, but just for this operation. redeposit_proxies are, therefore, 2FA codes valid for any number N >= 1 of redeposits, for 300 seconds once the code is sent.

Check usage on Github: JS Example

Parameters:twofac_data – Data from already enabled 2FA. i.e. {code: “799154”, method: “email”}
Returns:
com.greenaddress.twofactor.request_sms([action][, data])
Request the OTP via SMS, valid for the specified action.
Check usage on Github: JS Example
Parameters:
  • action (String) – The action you’re going to execute and authorize with 2FA (i.e. ‘send_tx’)
  • data
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 – Two factor authorization with another method, if enabled.
Returns: