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

> How to import PCI tokens into Guardian.

You can import PCI tokens into your Guardian instance. The data must be provided as a **PKI-encrypted `.tgz` archive** via **SFTP**.

***

## Step-by-Step Process

<Steps>
  <Step title="Step 1 – Request the public key certificate">
    Contact Hellgate Support to request the public key certificate for token import encryption.
    Include in your request:

    <ul>
      <li><strong>Target Cluster ID</strong> (the Guardian instance where tokens will be imported)</li>
      <li><strong>Point of contact</strong> for follow-up questions</li>
    </ul>
  </Step>

  <Step title="Step 2 – Prepare the import data">
    Prepare your PCI token data in JSONL format (JSON Lines), where each line is a complete JSON object.
  </Step>

  <Step title="Step 3 – Encrypt and package the data">
    Encrypt your data using the provided Starfish certificate and package it as a <code>.tgz</code> archive.
  </Step>

  <Step title="Step 4 – Upload the encrypted archive">
    Upload the encrypted <code>.tgz</code> archive to a SFTP location.

    <Check>
      Verify that the upload completed successfully and that the file is accessible at the specified location.
    </Check>
  </Step>

  <Step title="Step 5 – Provide SFTP location">
    Contact Hellgate Support and provide the SFTP location where the encrypted <code>.tgz</code> archive was made available.
  </Step>
</Steps>

***

## Import Data Format

The imported `.tgz` archive must contain a **manifest JSON file** and **encrypted JSONL records** containing the PCI token data.

```
import.tgz
├── manifest.json
└── tokens.jsonl.enc
```

### Encryption Details

The import 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 Hellgate's provided certificate's public key
3. The encrypted AES key, **initialization vector (IV)**, and **authentication tag** must be stored in the manifest

### Manifest Format

The `manifest.json` file must contain metadata about the import and encryption parameters:

```json theme={null}
{
  "version": "1.0",
  "import_id": "<uuid>",
  "created_at": "2025-01-15T10:43:00Z",
  "target_guardian_instance": "my-cluster-id.on-hellgate.cloud",
  "encryption": {
    "algorithm": "RSA-OAEP-256",
    "recipient": {
      "subject": "O=Starfish GmbH & Co. KG, 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`                          | Import format version                              |
| `import_id`                        | Unique identifier for this import                  |
| `created_at`                       | Timestamp when the import was created              |
| `target_guardian_instance`         | The target 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 Starfish'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 import              |
| `content.checksum`                 | SHA-256 checksum of the decrypted JSONL content    |

### Record Format

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

Each record must follow this structure:

```json theme={null}
{
  "card": {
    "cardholder_name": "John Doe",
    "expiry_month": 12,
    "expiry_year": 2025,
    "account_number": "4111111111111111",
    "scheme": "visa"
  },
  "metadata": {
    "my_key_one": "my_value_one",
    "my_key_two": "my_value_two"
  }
}
```

***

## Common Issues & Troubleshooting

<AccordionGroup>
  <Accordion title="How do I request the public key certificate?">
    Contact Hellgate Support with your import request details. The certificate will be provided in PEM format.
  </Accordion>

  <Accordion title="What if my data format doesn't match?">
    Ensure your JSONL records follow the exact format specified. Each line must be a valid JSON object with the required card fields.
  </Accordion>

  <Accordion title="How long does the import process take?">
    Import times vary based on the volume of data. Starfish will notify you once the import is complete or if any issues arise.
  </Accordion>

  <Accordion title="What happens if the SFTP upload fails?">
    Contact Hellgate Support immediately. You may need to re-upload the archive or provide an alternative delivery method.
  </Accordion>
</AccordionGroup>