Security

Describes encryption, the essential methods for the CODE Travel Rule.

CODE performs HTTPS communication in the section between a VASP that sends a request and a VASP that responds to it for basic secure communication. However, important information such as transaction information and personal information is bundled with payload objects to be encrypted so that only VASPs can see it. (End-to-end encryption is applied by default even when interoperating with other solution.)

❗️

Warning

Basically, the payload object in a message is encrypted, but the payload is not encrypted for a virtual asset address search API which does not specify a beneficiary VASP that has to broadcast internally.

Encryption / Decryption algorithm library

For end-to-end encryption, the Networking and Cryptography library is used, with libsodium being the library of choice.

CODE Protocol uses the Public-key cryptography - Authenticated encryption method of libsodium. Using Public Key authenticated encryption, you can encrypt a message with the recipient's Public Key so that only they can decrypt it. Additionally, a Shared Secret Key can be generated using the recipient's Public Key along with the sender's Public Key and Private Key. The recipient can also generate the Shared Secret Key in the same manner, allowing them to verify that the message has not been tampered with before decryption.

The algorithms used are as follows:

In the CODE Protocol, key pairs are defined as follows:

  • Signing Key: A private key used for producing digital signatures using the Ed25519 algorithm. Within CODE protocol, this is referred to as the Private Key.
  • Verify Key: The public key counterpart to an Ed25519 Signing Key, used for producing digital signatures. Within CODE protocol, this is referred to as the Public Key.

Generating Key Pair

You can create key pairs in two ways:

  1. Create from the dashboard
    You can create keys by logging into the dashboard and going to Env Management.
  2. Use the provided sample code with Generator
    Run the sample code (generate_key.py) that was provided separately to generate a key pair whose roles are to create and verify a Signing Key and a Verify Key.

The sample code includes an example of generating an encryption key from the Signing Key and performing encryption.

In CODE protocol, encryption can be performed with the Signing Key, thus the Signing Key is used as the Private Key, and the Verify Key is used as the Public Key.

Please store the Private Key carefully to prevent loss and use it, and enter the Public Key in Env Management on the dashboard. If you lose the Private Key, you will need to regenerate the key pair.

Example for encryption

It is assumed that the following original message is encrypted.

{
  "currency": "XRP",
  "payload": {
    "ivms101": {
      "Beneficiary": {
        "accountNumber": ["rHcFoo6a9qT5NHiVn1THQRhsEGcxtYCV4d:memo or tag"]
      }
    }
  }
}

The target of encryption is the payload object, {"ivms101": ...} part is encrypted.

  1. VASP A on the sending side encrypts using the public key of VASP B on the receiving side and it's (VASP A) private key.
  2. The payload value is overwritten by encoding the encrypted result with base64.
  3. The payload type is changed from object to String.

After encryption, a message will be formatted in the following way:

If the type of the payload field is String, this is a result of base64-encoded encryption, and if the type is an object, this can be considered as the original text. Although the same method is used even when VASP B performs decoding, this is generated by entering the public key of VASP A and the private key of VASP B.

{
  "currency": "xrp",
  "payload": "base64 encoded string"
}

Example for signature creation

The CODE server uses the signed value of the data combined as per the specific rules in the header to check to check whether the VASP, which sent the message is correct or not.

Signature creates data that makes calling URL (empty string for response), Body string, X-Code-Req-Datetime, and X-Code-Req-Nonce data into one byte array by signing the data with Private Key (Signing Key) of the transmitting VASP A.

This signature is verified by the CODE server.

For the detailed signature algorithm please refer to Ed25529.

📘

Sample Code

For easier understanding, we provide sample codes written in Python, Java, and JavaScript. Please contact us through the support channel.