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:

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.

Once you factor encryption overhead the available characters for all parameters are:

Memo field size in FIO Request

Assuming typical FIO Request contains the following required parameters:

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.