login module

The login module gives different ways of logging in to your GreenAddress wallet. This module allows the user to authenticate against the server.

Also, initial settings, like the nLocktime and Fiat price source, are provided within the login process.

com.greenaddress.login

com.greenaddress.login.ack_system_message(message_id, message_hash, message_sig)
Acknowledge a system message returned from login.get_system_message.

Once acknowledged, messages will not be returned in login data upon login.

The hash of the message must be the sha256d hash of the utf-8 encoded message text.
For example, given a message “test message” the hash can be calculated with the following
python code:
>>> import wallycore as wally
>>> messageHash = wally.sha256d(‘test message’.encode(‘utf-8’))
>>> wally.hex_from_bytes(messageHash) # Print the hash
‘251afd3f20ab4a307ecd50f3f84fd34097f2888505642dacce06c6ffa048ccf0’

The signature must be generated using a private key derived from the wallet extended
private key. The path of the signing key is:

[M/0x4741b11e/6/X]

M is the master key for the wallet and 0x4741b11e/6 indicates a message signing key. X
is derived by interpreting the last 4 bytes of the binary sha256d message hash as a 32 bit
big-endian unsigned integer with the highest bit cleared. For the message ‘test message’
above, this results in a path of [M/0x4741b11e/6/0xa048ccf0].

The signature must be generated using using the ‘Bitcoin Signed Message:’ convention
with the message set to the hex sha256d message hash.
Parameters:
  • message_id (Number) – Identifies the message being acknowledged
  • message_hash (String) – Hex encoded hash of message as described below
  • message_sig (String) – Hex encoded DER signature as described below
Return type:

Boolean

com.greenaddress.login.authenticate(signature_hex, logout[, path_hex][, device_id][, user_agent])
Authenticate the user by ensuring their signature of the login challenge is valid.
Check usage on Github: Python Example
Parameters:
  • signature_hex (Array) – DER encoded signature, hex-encoded
  • logout (Boolean) – whether to force log out existing session of the same user
  • path_hex (String) –

    32 bit path for deriving subkey which was used for login

    • ‘GA’ if using constant m/0x4741b11e (m/1195487518) path and deterministic signatures
    • 16 hex chars if using 4 path components (soon to be deprecated)
  • device_id (String) – unique device identifier. When doing forced logout, user is not warned about having “logged in elsewhere” if the same device forced the logout.
  • user_agent (String) – client name and version
Returns:

{‘appearance’: JSON, ‘currency’: String, ‘exchange’: String, ‘receiving_id’: String, ‘expired_deposits’: Array, ‘nlocktime_blocks’: Number, ‘csv_blocks’: Number, ‘cache_password’: String, ‘gait_path’: hex, ‘privacy’: {...}, ‘limits’: {‘is_fiat’: Boolean, ‘total’: satoshis, ‘per_tx’: satoshis}, ‘earliest_key_creation_time’: Number}

com.greenaddress.login.available_currencies()
Return a list of allowed currencies for all available pricing sources.
Returns:{“all”: [list of all currencies], “per_exchange”: {pricing_source_name: [list of supported currencies]}}
com.greenaddress.login.change_settings(key, value[, twofac_data])
Change user settings. Used for privacy settings and transaction limits.
Parameters:
  • key (String) – name of the value to change. Can be one of ‘tx_limits’, ‘privacy.send_me’, or ‘privacy.show_as_sender’.
  • value (String) –

    the new value to set.

    • For “tx_limits”: {total: amount, per_tx: amount_per_tx, is_fiat: Boolean} * Per transaction values are not currently supported. * Fiat values should be passed as the amount * 100, e.g.
      10.50 USD should be passed as 1050.
    • For “privacy.send_me”: one of:
      • 0 (PRIVATE)
      • 1 (ADDRBOOK)
      • 2 (PUBLIC)
    • For “privacy.show_as_sender”: one of:
      • 0 (PRIVATE)
      • 1 (MUTUAL_ADDRBOOK)
      • 2 (PUBLIC)
  • twofac_data – Two factor authentication data. Required to increase transaction limits. {method: ‘gauth’|’email’|’sms’|’phone’, code: String}
Returns:

success

Return type:

Boolean

com.greenaddress.login.create_session(token)
com.greenaddress.login.get_challenge(address)
Generate and return a challenge that must be signed for a successful authentication.
Parameters:address (String) – Base58 bitcoin address from the wallets master key
Returns:number to be signed from 0..2^256 range
Return type:Number
com.greenaddress.login.get_spending_limits()
Return the user’s current spending limits.
Returns:{‘total’: satoshis, ‘per_tx’: satoshis, ‘is_fiat’: Boolean}
com.greenaddress.login.get_system_message(message_id)
Get a system message and the id of the next message, if any.

The return value has the following fields:

message: utf-8 encoded message text, or blank if there are none remaining
message_id: Message id of the returned message, or 0 if there are none remaining
next_message_id: Message id of next message, or 0 if there are none remaining

Parameters:message_id (Number) – Identifies a message to get. This value comes from either the next_system_message_id field in the user’s login data, or from the next_message_id returned by a previous call to this API.
Returns:JSON
com.greenaddress.login.get_trezor_challenge(address[, hw_nlocktime_support])
Generate and return a Trezor challenge that must be signed for a successful authentication.
A string ‘greenaddress.it      login ABCDE‘ (‘greenaddress.it’ + 6 spaces + the returned random token) must be signed to proceed with authentication.
Check usage on Github: Python Example
Parameters:
  • address (String) – Base58 bitcoin address from the wallets master key
  • hw_nlocktime_support (Boolean) – whether the hw wallet supports nlocktime transactions
Returns:

random 5-character string to be signed

Return type:

String

com.greenaddress.login.register(pubkey_hex, chaincode_hex[, user_agent][, gait_path_hex])
Create a new GreenAddress account.

This call is used to register and create an account for a new user.
The caller should create a new BIP32 wallet and pass its master
pubkey and chaincode so that the service can generate and monitor
addresses for the wallet.

user_agent is free form ASCII text beginning with a capabilities
string surrounded by ‘[]’. As the value is logged by the service
it should not contain privacy sensitive or secret information.
Currently the caller must pass ‘[v2,sw]’ to indicate that they
are using the latest API version and support segwit addresses.

gait_path_hex is a 32 byte, hex encoded string which the service uses
when deriving server side keys for the user’s transactions. In order
to ensure that the path is unique, and to enable correct recovery of
funds, this data must be produced using the following algorithm:

1. Compute the master BIP 32 key from the user’s mnemonics (M)
2. Derive a child key from M using child number 0x80004741 (M’)
3. Note that the child derivation above is a BIP32 hardened deriviation
4. Create a binary buffer from hex ‘477265656e416464726573732e69742048442077616c6c65742070617468’ (S)
5. Append M’.chaincode and M’.pubkey into binary buffer (B)
6. Compute HMAC-SHA512(S, B)
7. The result of step 6 is the wallet path, gait_path_hex.
Check usage on Github: Python Example
Parameters:
  • pubkey_hex (String) – Master BIP32 public key in compressed sec format, hex-encoded
  • chaincode_hex (String) – Master BIP32 chaincode, hex-encoded
  • user_agent (String) – Client features, name and version
  • gait_path_hex (String) – Derived wallet path for the user, hex-encoded
Returns:

boolean

com.greenaddress.login.remove_account(twofac_data)
Remove the account
Parameters:twofac_data – Two factor authentication data. {method: ‘gauth’|’email’|’sms’|’phone’, code: String}
Returns:success
Return type:Boolean
com.greenaddress.login.set_appearance(appearance)
Update appearance settings.
Parameters:appearance (JSON) – {“sound”: Boolean, “altimeout”: Number, “pgp”: String, “unit”: String (‘BTC’, ‘mBTC’, ‘µBTC’, ‘bits’ }
Returns:success
Return type:Boolean
com.greenaddress.login.set_csvtime(csvtime[, twofac_data])
Set the number of blocks after which CSV transactions become
spendable without two factor authentication.
Parameters:
  • csvtime Number (Number) – Number of blocks
  • twofac_data (Array) – Two factor authentication data. {method: ‘gauth’|’email’|’sms’|’phone’, code: String}
Returns:

success

Return type:

Boolean

com.greenaddress.login.set_currency(currency)
Change the user’s pricing source currency.
Note that changing the currency resets the user’s spending limits if
any are set in fiat.
Parameters:String (currency) –
Returns:success
Return type:Boolean
Raises:#exchangecurrencynotsupported
com.greenaddress.login.set_exchange(exchange)
Change the user’s pricing source.
Note that changing the exchange resets the user’s spending limits if
any are set in fiat.
Parameters:String (currency) –
Returns:success
Return type:Boolean
Raises:#exchangecurrencynotsupported
com.greenaddress.login.set_gait_path(gait_path_hex)
com.greenaddress.login.set_nlocktime(nlocktime[, twofac_data])
Set the number of blocks after which nLockTime transactions become
spendable without two factor authentication. When this function
succeeds, if the user has an email address associated with the
wallet, an updated nlocktimes.zip file will be sent via email.
Parameters:
  • nlocktime Number (Number) – Number of blocks
  • twofac_data (Array) – Two factor authentication data. {method: ‘gauth’|’email’|’sms’|’phone’, code: String}
Returns:

success

Return type:

Boolean

com.greenaddress.login.set_pricing_source(currency, exchange)
Change the pricing source and currency.
Note that changing the pricing source resets the user’s spending limits if
any are set in fiat.
Parameters:
  • String (exchange) –
  • String – pricing source
Returns:

success

Return type:

Boolean

com.greenaddress.login.set_pricing_source_v2(currency, exchange)
com.greenaddress.login.watch_only(token_type, token, logout)
com.greenaddress.login.watch_only_v2(token_type, token, user_agent)
Log in to watch-only mode. It is limited to 100 watch only logins per day.
Check usage on Github: Python Example
Parameters:
  • String (token) – ‘custom’
  • String – login token value * for ‘custom’: {username: String, password: String}
  • user_agent (String) – client name and version