pin module

Despite its simplicity, the pin module doesn’t sacrifice security. The module is built to make the user able to login against the GA API with a simple PIN code, the PIN is handled on GA servers, and every client should have a different PIN.

When the PIN + PIN ident + Device ID combination is correct, GA servers will send back a password, which is the same one used by the client to encrypt the seed and the mnemonic passphrase.

PIN module:

  • When a new PIN is set, a device ID must also specified previously (usually a string generated from some 256 bit random number). This ID is sent together with the PIN. This is specified during login.
  • The password should be used to encrypt the mnemonic passphrase as well as seed (for speed) on client side, the mnemonic passphrase or seed is never sent to GA servers.
  • When the combination of PIN, PIN ident and device ID match on GA servers, the password is returned, and can be used to decrypt the mnemonic passphrase locally.
  • After 3 wrong PIN attempts, the PIN, PIN ident and password are deleted on GA servers.

com.greenaddress.pin

com.greenaddress.pin.change_pin_login(pin, pin_ident)
Change the PIN for given pin_ident
Parameters:
  • pin (String) – string with a few characters (max 15 characters)
  • pin_ident (String) – uuid
Return bool status:
 

Always True if PIN is changed
com.greenaddress.pin.disable_pin_login(pin_ident)
com.greenaddress.pin.get_devices()
List all pin devices in this wallet sorted by device_name.
Returns:[["pin_ident", "device_name"], [...]]
Type:List
com.greenaddress.pin.get_password(pin, pin_ident)
Return the password associated with the given PIN and PIN identifier for
the user’s wallet.
If the passed PIN does not match the stored PIN, then after 3
incorrect calls the service will permanently delete the PIN password.
Parameters:
  • pin (string) – The previously set device PIN
  • pin_ident (string) – The PIN identifier
Returns:

password
Return type:

String
Raises:

#password if there is no such device or the number of attempts has been exceeded
com.greenaddress.pin.remove_all_pin_logins()
Remove all PIN logins previously set. After calling this method, user will not be able anymore to do PIN login from any device he previously paired.
Returns:success
Return type:Boolean
com.greenaddress.pin.remove_pin_login(pin_ident)
Remove the PIN login for given pin_ident
Parameters:pin_ident (String) – uuid
Returns:success
Return type:Boolean
com.greenaddress.pin.set_pin_login(pin, device_name[, return_password])
Generate a new PIN password and associate it with a new PIN identifier.
The returned PIN identifier is passed to pin.get_password along with the PIN
to retrieve the password and allow the client’s stored PIN to be decrypted.
Callers must not store the PIN password. Once used to decrypt any data it should
be securely erased and re-fetched from the server on demand.
Parameters:
  • pin (String) – The user’s chosen PIN (max 15 characters)
  • device_name (String) – A human readable string identifying the wallet device (max 100 characters)
  • return_password (Boolean) – Whether to append ‘;’ and the pin password to the returned pin_ident
Returns:

pin_ident - The pin identifier, optionally followed by ‘;’ and the PIN password
Return type:

String