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

# PCI Token Export

> How to request an export of PCI tokens.

You can request an export of PCI tokens that are stored on our systems. Requests are performed **only after review and approval**. Once approved, the resulting dataset is delivered as a **PKI-encrypted `.tgz` archive** via a **time-limited download link** to the requesting party.

***

## Prerequisites

### Certificate Requirements

For encryption, you must provide an **X.509 certificate (PEM)** containing the recipient's public key. We accept recipient certificates only if all of the following criteria are met:

| Requirement                            | Details                                                                              |
| -------------------------------------- | ------------------------------------------------------------------------------------ |
| <strong>Certificate type</strong>      | X.509 with <strong>OV</strong> or higher validation                                  |
| <strong>Organization identity</strong> | Subject includes at least <code>O</code> (Organization) and <code>C</code> (Country) |
| <strong>Trust anchor</strong>          | Issued by an approved public CA or an agreed private PKI                             |
| <strong>Validity</strong>              | Certificate is within its validity period                                            |
| <strong>Revocation status</strong>     | Not revoked (CRL / OCSP or equivalent checks)                                        |
| <strong>Key usage</strong>             | Suitable for encryption                                                              |

<Info>
  Use a dedicated certificate and key pair specifically for token export decryption, separate from TLS or general-purpose certificates.
</Info>

***

## Step-by-Step Process

<Steps>
  <Step title="Step 1 – Submit an export request">
    Submit an export request via your designated contact channel including:

    <ul>
      <li><strong>Legal organization name</strong></li>
      <li><strong>Cluster ID</strong></li>
      <li><strong>Intended use case</strong> of the exported data</li>
      <li><strong>Attestation of PCI compliance</strong></li>
      <li><strong>Scope</strong> (time range, system/batch, filters)</li>
      <li><strong>Recipient</strong> (team/service and responsible contact)</li>
      <li><strong>Point of contact</strong> for follow-up questions</li>
    </ul>

    <Info>
      Use a dedicated certificate and key pair specifically for token export decryption,
      separate from TLS or general-purpose certificates.
    </Info>
  </Step>

  <Step title="Step 2 – Provide the recipient OV certificate">
    Provide your recipient certificate in PEM format (Base64, including header and footer).
    The certificate must contain the public key used for encryption.

    <Warning>
      Never send private keys, passphrases, or HSM access details.
    </Warning>
  </Step>

  <Step title="Step 3 – Review and approval">
    We perform two independent checks:

    <ul>
      <li>
        <strong>Certificate validation</strong>: trust chain, validity period, revocation status,
        key usage / extended key usage, and organizational identity
      </li>

      <li>
        <strong>Authorization review</strong>: intended use, contractual scope,
        and applicable compliance requirements
      </li>
    </ul>

    <Info>
      Once all checks are successfully completed, the export is approved and scheduled.
      If any issues are identified, we will contact you with specific remediation steps.
    </Info>
  </Step>

  <Step title="Step 4 – Export and PKI encryption">
    After approval, the dataset is exported from the relevant system and packaged as a <strong>compressed <code>.tgz</code> archive</strong>.
    The archive is then <strong>encrypted using your provided OV certificate</strong>.

    <Warning>
      Only the holder of the corresponding private key can decrypt the exported archive.
    </Warning>
  </Step>

  <Step title="Step 5 – Delivery via download link">
    The encrypted <code>.tgz</code> archive is made available via a download link sent to the requester
    (or the designated contact specified in the request).

    The download link is:

    <ul>
      <li><strong>Time-limited</strong> (expiration communicated separately)</li>
      <li><strong>Auditable</strong> (request ID, timestamp, delivery record)</li>
    </ul>
  </Step>

  <Step title="Step 6 – Download, decryption, and internal handling">
    Download the encrypted archive and perform decryption and extraction using your internal tooling and security controls.

    <Info>
      Decryption, validation, and secure processing of the exported data are the responsibility
      of the receiving organization.
    </Info>

    <Check>
      Confirm that decryption succeeds, that the dataset matches the requested scope,
      and that internal controls for handling the data are in place before wider distribution.
    </Check>
  </Step>

  <Step title="Step 7 – Storage and retention">
    Store and process the decrypted dataset in accordance with:

    <ul>
      <li>Your internal security policies</li>
      <li>Applicable regulatory and compliance requirements</li>
      <li>Contractually agreed retention and deletion rules</li>
    </ul>
  </Step>
</Steps>

***

## Export Data Format

The exported `.tgz` archive contains a **manifest JSON file** and **encrypted JSONL records** containing the PCI token data.

```
export-<export-id>.tgz
├── manifest.json
└── tokens.jsonl.enc
```

### Encryption Details

The export uses a **hybrid encryption scheme**:

1. **AES encryption** is used to encrypt the JSONL records file
2. The **AES key** is encrypted using **RSA-OAEP-256** with your provided OV certificate's public key
3. The encrypted AES key, **initialization vector (IV)**, and **authentication tag** are stored in the manifest

### Manifest Format

The `manifest.json` file contains metadata about the export and encryption parameters:

```json theme={null}
{
  "version": "1.0",
  "export_id": "<uuid>",
  "created_at": "2025-01-15T10:43:00Z",
  "guardian_instance": "my-cluster-id.on-hellgate.cloud",
  "encryption": {
    "algorithm": "RSA-OAEP-256",
    "recipient": {
      "subject": "O=Acme Payments GmbH, C=DE",
      "issuer": "CN=DigiCert TLS RSA4096 Root G5, O=DigiCert Inc, C=US",
      "serial": "0f:4a:2b:...",
      "fingerprint": "sha256:3c:5d:8e:..."
    },
    "encrypted_key": "<base64>",
    "iv": "<base64>",
    "tag": "<base64>"
  },
  "content": {
    "record_count": 142857,
    "checksum": "sha256:<hex>"
  }
}
```

| Field                              | Description                                        |
| ---------------------------------- | -------------------------------------------------- |
| `version`                          | Export format version                              |
| `export_id`                        | Unique identifier for this export                  |
| `created_at`                       | Timestamp when the export was created              |
| `guardian_instance`                | The Guardian instance identifier                   |
| `encryption.algorithm`             | The RSA encryption algorithm used (`RSA-OAEP-256`) |
| `encryption.recipient.subject`     | Certificate subject (organization identity)        |
| `encryption.recipient.issuer`      | Certificate issuer (CA)                            |
| `encryption.recipient.serial`      | Certificate serial number (hex)                    |
| `encryption.recipient.fingerprint` | Certificate fingerprint (SHA-256)                  |
| `encryption.encrypted_key`         | AES key encrypted with recipient's public key      |
| `encryption.iv`                    | Initialization vector for AES encryption           |
| `encryption.tag`                   | Authentication tag for AES-GCM                     |
| `content.record_count`             | Total number of records in the export              |
| `content.checksum`                 | SHA-256 checksum of the decrypted JSONL content    |

### Record Format

The `records.jsonl.enc` file contains **encrypted JSONL** (JSON Lines) data. After decryption, each line is a JSON object representing a PCI token record.

Each record follows the PCI token payload structure with the following differences:

* The `account_number` field contains the **unmasked** full account number (instead of `masked_account_number`)
* All other fields match the standard PCI token API response format
* Metadata is included if present

```json theme={null}
{
  "id": "8744c9ea-a02b-4ae6-875c-b64fc333e3ef",
  "card": {
    "cardholder_name": "John Doe",
    "expiry_month": 12,
    "expiry_year": 2025,
    "account_number": "4111111111111111",
    "scheme": "visa"
  },
  "created_at": "2023-10-01T12:00:00Z",
  "expires_at": "2025-10-01T12:00:00Z",
  "metadata": {
    "my_key_one": "my_value_one",
    "my_key_two": "my_value_two"
  }
}
```

### Decryption Process

To decrypt the export:

1. Extract the `.tgz` archive
2. Read `manifest.json` to obtain encryption parameters
3. Decrypt the AES key using your private key
4. Use the decrypted AES key, IV, and tag to decrypt `records.jsonl.enc`
5. Verify the checksum in the manifest matches the decrypted content
6. Process the JSONL file line by line (each line is a complete JSON object)

***

## Common Issues & Troubleshooting

<AccordionGroup>
  <Accordion title="We only have a public key, not a certificate.">
    A raw public key without a CA-issued certificate cannot be accepted.
    Please provide an OV (or higher) X.509 certificate containing the public key.
  </Accordion>

  <Accordion title="Our certificate is Domain Validated (DV).">
    DV certificates do not provide organizational identity validation and are therefore not sufficient.
    Please use an OV or EV certificate.
  </Accordion>

  <Accordion title="The download link has expired.">
    Submit a new request referencing the original request ID.
    A new link can be issued after any required re-validation.
  </Accordion>
</AccordionGroup>