# 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

<details>

<summary>Step 1: Generate a Random Key</summary>

![](https://3127657987-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fka3LMTlXv2Ay7BbFZMOc%2Fuploads%2FWEQ4EdiuUC733f6YD56a%2FScreenshot%202023-06-01%20at%2010.36.30.png?alt=media\&token=a71853a4-fe83-47d0-a4d0-1ea4ad9eb7a6)

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:

```javascript
    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;
    }
```

</details>

<details>

<summary>Step 2: Encrypted random key</summary>

![](https://3127657987-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fka3LMTlXv2Ay7BbFZMOc%2Fuploads%2FQ6RJFSab1qsmugeuemVy%2FScreenshot%202023-06-01%20at%2010.37.22.png?alt=media\&token=4fd522b6-3772-40e7-86f1-8e6e997ef64d)

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

#### Example:

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

</details>

<details>

<summary>Step 3: Signature</summary>

![](https://3127657987-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fka3LMTlXv2Ay7BbFZMOc%2Fuploads%2FBuNudRgyItys0LdOZEpc%2FScreenshot%202023-06-01%20at%2010.38.45.png?alt=media\&token=5beab99c-f4c7-416c-9ff8-ae0726017cc2)

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:

```java
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);
}
```

</details>

<details>

<summary>Step 4: Encrypted data</summary>

![](https://3127657987-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fka3LMTlXv2Ay7BbFZMOc%2Fuploads%2F2KfvCCCna2kf1hyj3JJ1%2FScreenshot%202023-06-01%20at%2010.39.47.png?alt=media\&token=04885eca-fee2-4b11-91df-f1317d532f1a)

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:

```javascript
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);
}
```

</details>

#### **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**

<details>

<summary>Step 1: Decrypted random key</summary>

![](https://3127657987-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fka3LMTlXv2Ay7BbFZMOc%2Fuploads%2F7mUENQUXQvuwj4NlH6hP%2FScreenshot%202023-06-01%20at%2010.40.11.png?alt=media\&token=d85840f9-c698-4fe8-9048-c66de121d9ac)

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

#### Example:

```java
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;
}
```

</details>

<details>

<summary>Step 2: Decrypted data</summary>

![](https://3127657987-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fka3LMTlXv2Ay7BbFZMOc%2Fuploads%2FtT8SrV6hUFBFy1SnsNkh%2FScreenshot%202023-06-01%20at%2010.40.32.png?alt=media\&token=ddddf553-0d45-4cc6-9c4d-6398315bf5ba)

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:

```java
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");
}
```

</details>

<details>

<summary>Step 3: Verify the electronic signature</summary>

![](https://3127657987-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2Fka3LMTlXv2Ay7BbFZMOc%2Fuploads%2FTnlPIVK5IbuOzWSSG72n%2FScreenshot%202023-06-01%20at%2010.40.47.png?alt=media\&token=a05efd6b-2910-4c76-852e-62d0e131e760)

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

#### Example:

```java
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));
}
```

</details>

<br>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://developer.gotadi.com/english/b2b2c-partner/webview-method/security-requirements.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.