> ## Documentation Index
> Fetch the complete documentation index at: https://developer.gcashier.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Message Encryption and Signing in Gcashier Pay

> Gcashier Pay protects every message with AES+RSA hybrid encryption and SHA1withRSA digital signatures to ensure confidentiality and authenticity.

Every message exchanged with Gcashier Pay is both **encrypted** and **digitally signed**. Encryption guarantees that only the intended recipient can read the payload — even if it is intercepted in transit. Signing guarantees authenticity: the recipient can verify that the message genuinely came from the claimed sender and has not been tampered with. Both protections are mandatory on every request and response; neither is optional.

## Cryptographic Algorithms

| Purpose                      | Algorithm                                        |
| ---------------------------- | ------------------------------------------------ |
| Symmetric payload encryption | AES/ECB/PKCS7Padding                             |
| Session key encryption       | RSA/ECB/PKCS1Padding                             |
| Session key generation       | Java `KeyGenerator` (or equivalent)              |
| Digital signature            | SHA1withRSA                                      |
| Key encoding in envelope     | `keyEnc` → HEX; `jsonEnc` → Base64; `sign` → HEX |

## Key Exchange Overview

The security model depends on each party holding an RSA key pair:

* **You (merchant):** Generate your own RSA key pair. Keep your **private key** secret on your servers. Provide your **public key** to Gcashier Pay during onboarding.
* **Gcashier Pay:** Provides you with its **public key**. Gcashier Pay holds the corresponding private key internally.

When you send a request, you sign with your private key and encrypt the session key with Gcashier Pay's public key. When Gcashier Pay sends you a webhook, it signs with its private key and encrypts the session key with your public key.

## Outgoing Message: Encryption & Signing Flow

When you send a request to Gcashier Pay, follow these steps in order:

<Steps>
  <Step title="Compose the inner JSON plaintext">
    Build the complete inner JSON object (containing `head` and `body`) as a UTF-8 string. This is the plaintext you will sign and then encrypt.
  </Step>

  <Step title="Sign the plaintext">
    Sign the UTF-8 JSON string with your RSA private key using the **SHA1withRSA** algorithm. Encode the resulting signature bytes as a **HEX string** — this becomes the `sign` field.
  </Step>

  <Step title="Generate an AES session key">
    Use a cryptographically secure key generator (e.g., Java's `KeyGenerator` for AES) to produce a random AES session key for this request. Encode the raw key bytes as **Base64** — this is your intermediate `SK`.
  </Step>

  <Step title="Encrypt the JSON payload">
    Encrypt the UTF-8 JSON plaintext using `SK` with **AES/ECB/PKCS7Padding**. Encode the resulting ciphertext as **Base64** — this becomes the `jsonEnc` field.
  </Step>

  <Step title="Encrypt the session key">
    Encrypt `SK` (the Base64 string) using Gcashier Pay's RSA public key with **RSA/ECB/PKCS1Padding**. Encode the result as a **HEX string** — this becomes the `keyEnc` field.
  </Step>

  <Step title="Assemble and POST the envelope">
    Combine all four fields into the outer envelope and POST it as JSON:

    ```json theme={null}
    {
      "merchantNo": "your-merchant-number",
      "jsonEnc":    "<Base64-encoded AES ciphertext>",
      "keyEnc":     "<HEX-encoded RSA-encrypted session key>",
      "sign":       "<HEX-encoded SHA1withRSA signature>"
    }
    ```
  </Step>
</Steps>

## Incoming Message: Decryption & Verification Flow

When you receive a response from Gcashier Pay or a webhook callback, reverse the process:

<Steps>
  <Step title="Extract the envelope fields">
    Parse the incoming JSON body and retrieve `jsonEnc`, `keyEnc`, and `sign`.
  </Step>

  <Step title="Recover the AES session key">
    HEX-decode `keyEnc` to get the encrypted session key bytes. Decrypt those bytes using **your RSA private key** with **RSA/ECB/PKCS1Padding** to recover the Base64-encoded `SK`.
  </Step>

  <Step title="Decrypt the payload">
    Base64-decode both `jsonEnc` and `SK`. Use `SK` to AES-decrypt the ciphertext with **AES/ECB/PKCS7Padding** and UTF-8 decode the result to obtain the inner JSON plaintext.
  </Step>

  <Step title="Verify the signature">
    HEX-decode `sign` to get the signature bytes. Verify those bytes against the inner JSON plaintext string using **Gcashier Pay's RSA public key** and the **SHA1withRSA** algorithm. If verification fails, discard the message immediately.
  </Step>
</Steps>

<Warning>
  Always verify the signature **after** decryption, before acting on any field in the payload. Processing a message with an invalid signature could expose your system to forged callbacks or tampered responses.
</Warning>

## Generating Your RSA Key Pair

You need a 2048-bit RSA key pair. Generate one using either of the methods below.

### Windows

Download the Gcashier Pay RSA key-generation tool and follow the instructions bundled with it. The tool outputs a PKCS#8 private key file and a matching public key file.

### macOS / Linux (OpenSSL)

Run the following three commands in sequence. The intermediate file in `tmp/` is the raw RSA key; the final files are the formatted PKCS#8 private key and the X.509 public key you provide to Gcashier Pay.

```bash theme={null}
# Step 1 – Generate a 2048-bit RSA key (intermediate)
openssl genrsa -out tmp/tmp_rsa_private_key_2048.pem 2048

# Step 2 – Convert to PKCS#8 format (your actual private key — keep this secret)
openssl pkcs8 -topk8 \
  -in  tmp/tmp_rsa_private_key_2048.pem \
  -out rsa_private_key_2048.pem \
  -nocrypt

# Step 3 – Extract the public key (share this with Gcashier Pay)
openssl rsa \
  -in  tmp/tmp_rsa_private_key_2048.pem \
  -out rsa_public_key_2048.pem \
  -pubout
```

After running these commands:

* `rsa_private_key_2048.pem` — your PKCS#8 private key. **Never share or commit this file.**
* `rsa_public_key_2048.pem` — your public key. Submit this to Gcashier Pay during onboarding.

<Note>
  Gcashier Pay will send you its own public key (`gcashier_public_key.pem` or equivalent) after onboarding is complete. Store it securely; you need it to encrypt outgoing session keys and to verify incoming signatures.
</Note>

## Demo SDK

Gcashier Pay provides a reference implementation demonstrating the full encryption, signing, decryption, and verification flow. Download the demo SDK to explore working code examples:

**[Download java\_sdk.zip](https://developer.gcashier.com/files/java_sdk.zip)**

The demo includes sample key pairs, utility classes for each cryptographic step, and end-to-end integration tests you can run against the sandbox environment.