Skip to content

Latest commit

 

History

History
205 lines (182 loc) · 9.37 KB

fip-0039.md

File metadata and controls

205 lines (182 loc) · 9.37 KB
fip title status type author created updated
39
Support alternate FIO Public Key for encryption of New Funds Request/Record OBT content blob
Accepted
Functionality
Pawel Mastalerz <[email protected]>
2022-02-04
2022-02-23

Abstract

This FIP adds ability supply FIO Public Key, different from FIO Public Key for receiving tokens, to use for encryption of New Funds Request/Record OBT content blob.

New actions

Contract Action Endpoint Description
fio.address updcryptkey /update_encrypt_key Updates the FIO Public Key to use for encryption of New Funds Request/Record OBT content blob.

Modified actions

Contract Action Endpoint Description
fio.address regaddress /register_fio_address Create entry for encrypt_public_key equal to FIO Public Key which owns the new FIO Address.
fio.address xferaddress /transfer_fio_address Update entry for encrypt_public_key equal to FIO Public Key of the new FIO Address owner.
fio.address burnaddress /burn_fio_address Remove entry for encrypt_public_key for FIO Address being burned.

New getters

Endpoint Description
/get_encrypt_key Returns the FIO Public Key to use for encryption of New Funds Request/Record OBT content blob.

Motivation

Certain content on FIO Chain, e.g. FIO Request details, are encrypted using Diffie-Hellman encryption scheme. This scheme requires private key of one party and a public key of another. Today the key used for encryption is the same key which is used for sending and receiving tokens and is obtained using get_pub_address.

An improvement has been suggested to have a separate key for receiving tokens and for encryption. This would allow for a different security scheme to be applied to each key. In fact, the account owner may not even have access to a private key designated as the receiving key for tokens, e.g. it’s in cold storage, while they do need to have access to the private key in order to decrypt some FIO Chain data.

It is important to note, that the encryption key is only used by the client and has no use on-chain. Here's how is encryption key used:

Sender is encrypting data intended for receiver

Step Before FIP After FIP
Fetch receiver's FIO Public Key to use for encryption. get_pub_address for sender's fio_address, chain_code: FIO, token_code: FIO get_encrypt_key for sender's fio_address
Encrypt the data Client process No change
Send on-chain transaction newfundsreq or recordobt No change

Receiver is decrypting the data from Sender

Step Before FIP After FIP
Read FIO Public Key to use for decryption from the specific record get_received_fio_requests, _get_sent_fio_requests, get_pending_fio_requests, get_obt_data, get_cancelled_fio_requests No change
Decrypt the data Client process No change

Specification

New actions

Update encryption key

Updates the FIO Public Key to use for encryption of New Funds Request/Record OBT content blob.

Contract: fio.address

New action: updcryptkey

New end point: /update_encrypt_key

New fee: update_encrypt_key, bundle-eligible (1 bundled transaction) fee amount will be determined during development and updated here

RAM increase: To be determined during implementation

Request body

Parameter Required Format Definition
fio_address Yes String FIO Address to add encrypto key for.
encrypt_public_key Yes Valid FIO Public Key FIO Public key to use for encryption.
max_fee Yes Positive Int Maximum amount of SUFs the user is willing to pay for fee. Should be preceded by /get_fee for correct value.
actor Yes 12 character string Valid actor of signer
tpid Yes FIO Address FIO Address of the entity which generates this transaction. TPID rewards will be paid to this address. Set to empty if not known.
Example
{
  "fio_address": "purse@alice",
  "encrypt_public_key": "FIO5G2tfhPZtiaiBU6o9SpT2XKbb28gtKUeXXarvBjxuU29VYgYCs",
  "max_fee": 0,
  "actor": "aftyershcu22",
  "tpid": "rewards@wallet"
}

Processing

  • Request is validated per Exception handling.
    • Explicitly allowed
      • Setting of encrypt_public_key to empty string
  • Supplied encryption key is added to FIO Address.
  • RAM of actor calling action is increased.
  • Fee or bundled transaction is deducted.
  • Check for maximum FIO transaction size is applied.

Exception handling

Error condition Trigger Type fields:name fields:value Error message
Invalid FIO Address Format of FIO Address not valid or FIO Address does not exist. 400 "fio_address" Value sent in, i.e. "purse@alice" "FIO Address invalid or does not exist."
Invalid encrypt public key Specified public key is not valid FIO format. 400 "encrypt_public_key" Value sent in, e.g. "notakey" "Encrypt key not a valid FIO Public Key."
FIO Domain expired Domain of supplied FIO Address has expired more than 30 days ago 400 "fio_address" Value sent in, i.e. "purse@alice" "FIO Domain expired."
Invalid fee value max_fee format is not valid 400 "max_fee" Value sent in, e.g. "-100" "Invalid fee value"
Fee exceeds maximum Actual fee is greater than supplied max_fee 400 "max_fee" Value sent in, e.g. "1000000000" "Fee exceeds supplied maximum"
Insufficient balance Available (unlocked and unstaked) balance in account is less than chain fee 400 "max_fee" Value sent in, e.g. "100000000000" "Insufficient balance"
Invalid TPID tpid format is not valid 400 "tpid" Value sent in, e.g. "notvalidfioaddress" "TPID must be empty or valid FIO address"
Not owner of FIO Address The signer does not own the FIO Address 403 Type: invalid_signature
Signer not actor Signer not actor 403 Type: invalid_signature

Response body

Parameter Format Definition
status String OK if successful
fee_collected Int Amount of SUFs collected as fee
Example
{
  "status": "OK",
  "fee_collected": 0
}

Modified actions

Register Address

Create entry for encrypt_public_key equal to FIO Public Key which owns the new FIO Address.

Contract: fio.address

Action: regaddress

End point: /register_fio_address

Request body

No change

Processing

  • Create entry for encrypt_public_key equal to FIO Public Key which owns the new FIO Address.

Exception handling

No change

Response body

No change

Transfer FIO Address

Update entry for encrypt_public_key equal to FIO Public Key of the new FIO Address owner.

Contract: fio.address

Action: xferaddress

End point: /transfer_fio_address

Request body

No change

Processing

  • Update entry for encrypt_public_key equal to FIO Public Key of the new FIO Address owner.

Exception handling

No change

Response body

No change

Burn Address

Remove entry for encrypt_public_key for FIO Address being burned.

Contract: fio.address

Action: burnaddress

End point: /burn_fio_address

Request body

No change

Processing

Remove entry for encrypt_public_key for FIO Address being burned.

Exception handling

No change

Response body

No change

New getters

Get encryption key

Returns the FIO Public Key to use for encryption of New Funds Request/Record OBT content blob.

New end point: /get_encrypt_key

Request body

Parameter Required Format Definition
fio_address Yes FIO Public Key FIO Address to fetch encrypt key for.
Example
{
  "fio_address": "purse@alice"
}
Processing
  • Request is validated per Exception handling
  • Return encrypt_public_key set using updcryptkey. If not set return FIO Public Key mapped using add_pub_address for chain_code: FIO, token_code: FIO
Exception handling
Error condition Trigger Type fields:name fields:value Error message
Invalid FIO Address Format of FIO Address not valid or FIO Address does not exist. 400 "fio_address" Value sent in, i.e. "purse@alice" "FIO Address invalid or does not exist."

Response body

Parameter Format Definition
encrypt_public_key Int FIO Public key to use for encryption.
Example
{
  "encrypt_public_key": "FIO5G2tfhPZtiaiBU6o9SpT2XKbb28gtKUeXXarvBjxuU29VYgYCs"
}

Rationale

Storing the encryption key as a new token_code for chain_code:FIO using add_pub_address was considered. However, it would have been harder to support backwards compatibility in that an existing getter get_pub_address would have to be modified for a specific chain_code and token_code.

Implementation

TBD

Backwards Compatibility

It is recommended that /get_encrypt_key is rolled out ahead of updcryptkey and an advisory is issued to wallets and exchanges instructing them to start using the new getter. The current encryption key will be returned by /get_encrypt_key even if unique key is not specified using updcryptkey.

After 90 days updcryptkey should be enabled to allow for a new key to be added. This delay should decrese the chances that a wallet obtains invalid encryption key because it used /get_pub_address instead of /get_encrypt_key

Existing New Funds Request and OBT Data records are not affected, because public keys used for the encryption is stored as part of those records.

Future considerations

None

Discussion link

https://fioprotocol.atlassian.net/wiki/spaces/FC/pages/473104421/Enhanced+permissions