API Payload Encryption
For additional security, you can encrypt the payload when calling the withdrawal API. The same endpoint as the existing withdrawal API is used. If the header contains Octet-Access-Key, the request is treated as using API payload encryption. Therefore, to use this feature, you must first issue an AccessKey. See the guide below for how to call the withdrawal API with an encrypted API payload.
TIP
This feature supports all key management types.
Both singlesig wallets and multisig wallets can withdraw with an encrypted API payload.
Supported APIs
- Withdrawal request
- NFT contract deployment request
- NFT item creation request
- NFT withdrawal request
- NFT contract method execution request
Encrypting the API payload
- Call the Create AES Key API to generate the key pair for two-way encryption.
SecretKey and hashKey can only be viewed at the time of issuance, while AccessKey can be viewed at any time. If you lose SecretKey and hashKey, you must reissue the keys.
- Build the Body for the API call.
When using payload encryption, you do not need to RSA-encrypt the user key before sending it. You can send it in plain text, or RSA-encrypt it as before. However, when sending it in plain text, you must send it asuserKey.
// Existing multisig wallet withdrawal request API Payload
{
...
"encryptedUserKey": "rsa encrypted userkey",
...
}
// Multisig wallet withdrawal request API Payload when encrypting
{
...
"userKey": "802...",
...
}
- Put the encrypted result into the Body as data.
// Body for the API call
{
"data": "Owl9/MDqndW0jNpz2waUSO3Ed50ZGwTNEAjXTkhlLYVPi9e05cMzKeugYFKywPDNx/FCeUQOKzHeyHKKsKFLVC+7Eo5mrefC30t8E4tfjDMY+PRQJPLl4LsQICCiTDUr6n/s/y/6hchNlea1beobmSHY9IFDc39aQJmr1T3gYh0fhQOTHCv9GvyAmRwv18L7wOLvTT/jYySLq2uYa24hR4IcCtUe4yYLUmPMYqPi4Rh4aXOkooOWKJP0ARdtk09WQwKNAh1NbHpWkIa3CRpHUg=="
}
- Put the AccessKey into the Header of the API call.
HEADER
Authorization: 'Bearer {apiToken}'
Octet-Access-Key: '{Access Key}'
BODY
{
"data": "Owl9/MDqndW0jNpz2waUSO3Ed50ZGwTNEAjXTkhlLYVPi9e05cMzKeugYFKywPDNx/FCeUQOKzHeyHKKsKFLVC+7Eo5mrefC30t8E4tfjDMY+PRQJPLl4LsQICCiTDUr6n/s/y/6hchNlea1beobmSHY9IFDc39aQJmr1T3gYh0fhQOTHCv9GvyAmRwv18L7wOLvTT/jYySLq2uYa24hR4IcCtUe4yYLUmPMYqPi4Rh4aXOkooOWKJP0ARdtk09WQwKNAh1NbHpWkIa3CRpHUg=="
}
- To verify the integrity of the Payload, an HMAC must be included in the header.
Hash the 'Body value before encrypting with the SecretKey' with SHA256 using the HashKey.
Send that value in the header.
// Body that is the HMAC target
{
"symbol": "ETH",
"requestId": "user1-amount0.001-symbolETH-202302281830",
"amount": "0.001",
"senderAddress": "0x55Bc4ba7A86A00C8A1A09C59DcC32eA2E7FAbCd4",
"receiverAddress": "0xee3c0f0AF227dA8DaccbF3Bc33bCf20f0a222aEF"
}
HEADER
Authorization: 'Bearer {apiToken}'
Octet-Access-Key: '{Access Key}'
Octet-Hmac: '5EJZMSFuZrtTle+O5FzuPvHZFnFWRFe5WZJ/VKWfaBY=' <-- HMAC-SHA256
BODY
{
"data": "Owl9/MDqndW0jNpz2waUSO3Ed50ZGwTNEAjXTkhlLYVPi9e05cMzKeugYFKywPDNx/FCeUQOKzHeyHKKsKFLVC+7Eo5mrefC30t8E4tfjDMY+PRQJPLl4LsQICCiTDUr6n/s/y/6hchNlea1beobmSHY9IFDc39aQJmr1T3gYh0fhQOTHCv9GvyAmRwv18L7wOLvTT/jYySLq2uYa24hR4IcCtUe4yYLUmPMYqPi4Rh4aXOkooOWKJP0ARdtk09WQwKNAh1NbHpWkIa3CRpHUg=="
}
Sample code
Sample code, by language, for the encryption that the client must perform.
Node.js
import { createHash, randomBytes, createCipheriv, createDecipheriv, generateKey, generateKeySync, createHmac } from 'crypto';
hashMAC(data: Record<string, any>, hashKey: string): string {
const message = JSON.stringify(data);
return createHmac('sha256', hashKey).update(message).digest('base64');
}
encryptMessage(data: Record<string, any>, secretKey: string): string {
const AES_ALGORITHM = 'aes-256-cbc';
const AES_IV_SIZE = 16;
const AES_OUTPUT_ENCODING = 'base64';
const message = JSON.stringify(data);
const keyHash = createHash('sha256').update(secretKey);
const iv = randomBytes(AES_IV_SIZE);
const cipher = createCipheriv(AES_ALGORITHM, keyHash.digest(), iv);
const cipherText = cipher.update(Buffer.from(message));
const cipherFinal = cipher.final();
const encrypted = Buffer.concat([iv, cipherText, cipherFinal]);
return encrypted.toString(AES_OUTPUT_ENCODING);
}
Java
// gson
class JsonUtil {
public static String stringify(Object obj) {
Gson gson = new Gson();
return gson.toJson(obj);
}
}
// jackson
class JsonUtil {
public static String stringify(Object obj) throws JsonProcessingException {
ObjectMapper objectMapper = new ObjectMapper();
return objectMapper.writeValueAsString(obj);
}
}
class AesEncryptionUtil {
private static final String AES_ALGORITHM = "AES/CBC/PKCS5Padding";
private static final int AES_IV_SIZE = 16;
public static String aesEncrypt(Object data, String password) throws Exception {
String message = JsonUtil.stringify(data);
MessageDigest md = MessageDigest.getInstance("SHA-256");
byte[] keyBytes = md.digest(password.getBytes(StandardCharsets.UTF_8));
SecretKeySpec secretKeySpec = new SecretKeySpec(keyBytes, "AES");
byte[] iv = new byte[AES_IV_SIZE];
SecureRandom random = new SecureRandom();
random.nextBytes(iv);
IvParameterSpec ivParams = new IvParameterSpec(iv);
Cipher cipher = Cipher.getInstance(AES_ALGORITHM);
cipher.init(Cipher.ENCRYPT_MODE, secretKeySpec, ivParams);
byte[] cipherText = cipher.update(message.getBytes(StandardCharsets.UTF_8));
byte[] cipherFinal = cipher.doFinal();
byte[] encryptedBytes = new byte[iv.length + cipherText.length + cipherFinal.length];
System.arraycopy(iv, 0, encryptedBytes, 0, iv.length);
System.arraycopy(cipherText, 0, encryptedBytes, iv.length, cipherText.length);
System.arraycopy(cipherFinal, 0, encryptedBytes, iv.length + cipherText.length, cipherFinal.length);
return Base64.getEncoder().encodeToString(encryptedBytes);
}
}
class HmacUtil {
public static String createHmac(Object data, String hashKey) throws Exception {
String message = JsonUtil.stringify(data);
Mac mac = Mac.getInstance("HmacSHA256");
SecretKeySpec keySpec = new SecretKeySpec(hashKey.getBytes(StandardCharsets.UTF_8), "HmacSHA256");
mac.init(keySpec);
byte[] hmacBytes = mac.doFinal(message.getBytes(StandardCharsets.UTF_8));
return Base64.getEncoder().encodeToString(hmacBytes);
}
}
// lombok
@Builder
@Getter
class Withdrawal {
private String symbol;
private String requestId;
private String amount;
private String senderAddress;
private String receiverAddress;
}
Using other languages
If you encrypt in a language other than those above, you can test with the values below.
1. Test data
secretKey : 5ba425e8473f74e246f393f1950f0509772c35d2cfc0c3dae8fdbe5db33daa51
hashKey : 218471b0f4b1e4f8a01a8bd783462ef7a988569ecb1518263b129a10a910945d
iv : HEXLANTOCTETV2.0
{
"symbol": "ETH",
"requestId": "1ETH_20230511_1738_USER_000",
"amount": "1",
"senderAddress": "0x0CDAf02E737bF187c40bdd44f6f5230a4007A4d6",
"receiverAddress": "0x1317e2E91eb1f3161fad47D5a70A3C52E8E84f4D",
"userKey": "rawUserKeyrawUserKeyrawUserKeyrawUserKeyrawUserKeyrawUserKeyrawUserKeyrawUserKeyrawUserKeyrawUserKeyrawUserKeyrawUserKeyrawUserKeyrawUserKey"
}
2. Verification
When the object above is encrypted, the output should be the following values.
HMAC : KQTd+eynbbyeDA1Hc+N75taYqCNc5Ln04HlXUOvg7qg=
Encrypted Body : SEVYTEFOVE9DVEVUVjIuMH4ftbMr9z+fYILoCWSOnUeRwPb2E8orqtKDEM3eSZ7WxrYIUH76Yp0FkA5i9sdBTUj48mdtlxQ1Hc2oPpQkAf5SZql3rdnaT5B4fC1csnkSopCg3cqFbknlVOThpUpF+d7Lrb708IEkWmmyOADAn67GSO9XP7lKkHBdzi4ueSAPg8JovNoVq27tjcINLhNMln+HS+gQp0t/HgfP5AC8sxgwMxuNoJ2i7qU3BFt8pPov8nBpY/4989kY1bE1r31GeEkHr30iiG5S3HsRoZRXeEMetVt7/4Vwk/FmoIBbO4tujIabsunNo5CRxMpoAHYFoGtGI+AqG2HdoZL70csNDdMAen0jjBaF4Q/W+PMgrPimmUjYTxpVDgVrKXFa1H5PeK1lncpE0CUnRA7v6kXptMyNVyaAR4xFYELRjSHt3aSFy4Do3Q8rERmEhfeAOJdIpD7iOC5wx3hr/XNEfn0mctw=
When the object above is serialized and printed as a string, the output should be the following value.
{"symbol":"ETH","requestId":"1ETH_20230511_1738_USER_000","amount":"1","senderAddress":"0x0CDAf02E737bF187c40bdd44f6f5230a4007A4d6","receiverAddress":"0x1317e2E91eb1f3161fad47D5a70A3C52E8E84f4D","userKey":"rawUserKeyrawUserKeyrawUserKeyrawUserKeyrawUserKeyrawUserKeyrawUserKeyrawUserKeyrawUserKeyrawUserKeyrawUserKeyrawUserKeyrawUserKeyrawUserKey"}