Encryption in FIO Request and FIO Data
Overview
Certain sensitive data in /new_funds_request and /record_obt_data is encrypted using the Diffie-Hellman key exchange scheme. In a nutshell, to encrypt the data, the sender uses its private key and the public key of the receiver. To decrypt the data, the receiver uses its private key and the public key of the sender. This ensures that only the sender and receiver of the data can decrypt it.
The data is further serialized to reduce size. Currently there is no abi for that data, but you can find the relevant data elements inside /new_funds_request and /record_obt_data action spec.
For those unfamiliar with Diffie-Hellman encryption, methods in fiojs SDK make this easy.
Integration Considerations
Encryption/decryption inside the wallet
Because the encryption/decryption requires a private key of sender or receiver, it can only be done inside the wallet hosting the required private key.
Using correct Private Public Keys when decrypting data
It's important that the correct private/public keys are used to decrypt an existing FIO Data or FIO Request record, especially since those keys can change over time. For that purpose, the getters which return the encrypted blob (/get_pending_fio_requests, /get_sent_fio_requests, /get_received_fio_requests, /get_cancelled_fio_requests, /get_obt_data) also return payer_fio_public_key, payee_fio_public_key, which were used during the initial encryption.
When decrypting the content match the keys as follows:
Getter | Description | Private Key | Public Key |
---|---|---|---|
/get_pending_fio_requests /get_received_fio_requests | Typically used by the receiver of the FIO Request | Private key which hashes to payer_fio_public_key returned | payee_fio_public_key |
/get_sent_fio_requests /get_cancelled_fio_requests | Typically used by the sender of the FIO Request | Private key which hashes to payee_fio_public_key returned | payer_fio_public_key |
/get_obt_data | Typically used by the receiver of the FIO Data | Private key which hashes to payee_fio_public_key returned | payer_fio_public_key |
Validation
Data validation
The FIO Chain is not able to access the unencrypted data, so no validation is performed on the data in the content field. It is up to the wallet to ensure the data received is properly formatted and handle any exceptions.
As an example, it is recommended chain_code and token_code be converted to upper case to mitigate the risk that the sending entity used lower case.
Size limitations on encrypted data
Since the FIO Chain is not able to access the unencrypted content, it cannot enforce size limitations on the individual fields. Size limitation is therefore enforced on the content field containing the encrypted string.
Method | Minimum characters | Maximum characters |
---|---|---|
/new_funds_request | 64 | 296 |
/record_obt_data | 64 | 432 |
Once you factor encryption overhead the available characters for all parameters are:
Method | Maximum characters |
---|---|
/new_funds_request | 145 |
/record_obt_data | 260 |
Memo field size in FIO Request
Assuming typical FIO Request contains the following required parameters:
Parameter | Typical size |
---|---|
payee_public_address | 50 |
amount | 8 |
chain_code | 3 |
token_code | 3 |
This would allow for a memo field to be as long as 81 characters. However, some blockchains can have public addresses of over 100 characters, which can severely limit the characters available for memo.
It is recommended that the memo restrictions are computed dynamically based on public address and amount entered.
Updated 3 months ago