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 | |
---|---|---|
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
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
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 beused 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 wallethas a UTXO with nlocktime 6 months from now, the reset process will lock the wallet for18 months.Once confirmed a reset request can only be cancelled by a user with access to theoriginal 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_emailto complete the operation.Note that this does not enable email 2FA - it is possible to set an email address for thewallet 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: