Security Requirements

SSL/HTTPS Transmission Channel

SSL/HTTPS is applied for data transmission between the partner's system and Gotadi. The purpose of using SSL/HTTPS is to ensure that the exchanged data is encrypted, making it difficult to be stolen or forged.

Security Headers and Traffic Monitoring

All requests from the partner system to Gotadi must include the following headers to support Gotadi's security operations and data analytics:

apikey: <api_key>
x-ibe-req-name: <access_code>

Note

The values of <api_key> and <access_code> are provided by Gotadi to the Partner.

Data Encryption and Digital Signature Authentication

The request/response between Gotadi and the Partner for certain critical APIs requires encryption using the asymmetric 3DES encryption algorithm and includes a digital signature for authentication. The encryption and decryption algorithms will be described in detail in this document.

Notes:

• APIs that require data encryption and digital signatures will be specified in the Security Requirements section.

Outgoing Data Encryption

• Input:

  • Original data

  • RSA Public Key of the recipient

  • RSA Private Key of the sender

• Output:

  • Encrypted Key

  • Encrypted Data

Step 1: Generate a Random Key

The 3DES Key Generate function is used to create a random key based on the DESedeKeySpec standard (Key length: 24 bytes). Each request/response will be assigned a unique random key to ensure security and prevent replay attacks..

Example:

    public static byte[] generateKey() throws Exception {
        KeyGenerator keyGenerator = KeyGenerator.getInstance("DESede");
        SecretKey secretKey = keyGenerator.generateKey();
        SecretKeyFactory secretKeyFactory = SecretKeyFactory.getInstance("DESede");
        DESedeKeySpec deSedeKeySpec = (DESedeKeySpec)   secretKeyFactory.getKeySpec(secretKey, DESedeKeySpec.class);
        byte[] randomKey = deSedeKeySpec.getKey();
        return randomKey;
    }

Step 2: Encrypted random key

The random key generated in Step 1 will be encrypted using the asymmetric encryption algorithm RSA with the receiver’s Public Key.

Example:

public static String encryptRSA(byte[] randomKey, String xmlPublicKey) throws Exception {
    Cipher cipher = createCipherEncrypt(xmlPublicKey);
    byte[] encryptedKey = cipher.doFinal(randomKey);
    return Base64.encodeBase64URLSafeString(encryptedKey);
}

Step 3: Signature

The sender applies the RSA-SHA256 algorithm combined with its own Private Key to generate the digital signature on the signature data.

Note: The schema for constructing the signature data will be specifically described for each API.

Example:

public static String signRSA(String signatureData, String xmlPrivateKey) throws Exception {
    PrivateKey privateKey = getPrivateKeyFromXML(xmlPrivateKey);
    Signature instance = Signature.getInstance("SHA256withRSA");
    instance.initSign(privateKey);
    instance.update(signatureData.getBytes("UTF-8"));
    byte[] signature = instance.sign();
    return Base64.encodeBase64String(signature);
}

Step 4: Encrypted data

The Original Data, which includes the signature, will be encrypted using the 3DES algorithm with the random key generated in the previous step.

Note: The schema for constructing the Original Data will be specifically described for each API.

Example:

public static String encryptTripleDes(String originalData, byte[] randomKey) throws Exception {
    Cipher cipher = Cipher.getInstance("DESede");
    SecretKeySpec secretKeySpec = new SecretKeySpec(randomKey, "DESede");
    cipher.init(Cipher.ENCRYPT_MODE, secretKeySpec);
    byte[] encryptedData = cipher.doFinal(originalData.getBytes("UTF-8"));
    return Base64.encodeBase64URLSafeString(encryptedData);
}

Decrypting Received Data and Verifying Digital Signature

Input:

• Encrypted Key

• Encrypted Data

• RSA Private Key (of the recipient)

• RSA Public Key (of the sender)

Output:

• Original Data

• Verification Result

Step 1: Decrypted random key

The recipient uses their own Private Key to decrypt the received Encrypted Key.

Example:

public static byte[] decryptRSAToByte(String encryptedKey, String xmlPrivateKey) throws Exception {
    Cipher cipher = createCipherDecrypt(xmlPrivateKey);
    byte[] bts = Base64.decodeBase64(encryptedKey);
    byte[] randomKey = cipher.doFinal(bts);
    return randomKey;
}

Step 2: Decrypted data

The recipient applies the 3DES algorithm using the random key obtained in the previous step to decrypt the Encrypted Data, retrieving the Original Data, which contains the signature.

Note: The schema for constructing the Original Data will be specifically described for each API.

Example:

public static String decryptTripleDes(String encryptedData, byte[] randomKey) throws Exception {
    Cipher cipher = Cipher.getInstance("DESede");
    SecretKeySpec secretKeySpec = new SecretKeySpec(randomKey, "DESede");
    cipher.init(Cipher.DECRYPT_MODE, secretKeySpec);
    byte[] originalData  = cipher.doFinal(Base64.decodeBase64(encryptedData));
    return new String(originalData, "UTF-8");
}

Step 3: Verify the electronic signature

The recipient applies the RSA-SHA256 algorithm along with the sender’s Public Key to verify the signature extracted from the Original Data.

Example:

public static boolean verifyRSA(String signedData, String signature, String xmlPublicKey) throws Exception {
    PublicKey publicKey = getPublicKeyFromXML(xmlPublicKey);
    Signature instance = Signature.getInstance("SHA256withRSA");
    instance.initVerify(publicKey);
    instance.update(signedData.getBytes("UTF-8"));
    return instance.verify(Base64.decodeBase64(signature));
}