Download the PHP package jatimprovcsirt/panda-php without Composer

PANDA PHP SDK

PANDA (Private And Secure Data Access) — AES-256-GCM field-level encryption SDK for PHP applications.

Requirements

• PHP ≥ 8.1 with ext-openssl
• Composer

Installation

Install the package via Composer:

1. PANDA Master Key Initialization (Langkah Pertama yang Wajib)

Sebelum menulis kode integrasi apapun, Anda harus menghasilkan kunci master lokal untuk aplikasi Anda. Ini adalah gerbang keamanan satu kali sebelum PANDA bisa beroperasi.

Langkah 1: Dapatkan PANDA Access Token

Anda harus memiliki PANDA Access Token untuk menginisialisasi kunci master aplikasi Anda.

Daftar aplikasi dan dapatkan token di: https://csirt.jatimprov.go.id/panda

[!NOTE] Setiap aplikasi memerlukan token unik. Token digunakan sebagai gerbang keamanan satu kali untuk inisialisasi kunci.

Langkah 2: Jalankan Perintah Init

Jalankan perintah berikut di direktori root proyek Anda. Ganti YOUR_TOKEN dengan PANDA Access Token yang diperoleh dari portal (panjang: 48 atau 64 karakter hex):

Setelah menjalankan perintah ini, wizard akan:

1. Memvalidasi token Anda
2. Meminta Anda memasukkan Key Identifier (KID) untuk kunci pertama
3. Menghasilkan kunci 256-bit yang aman secara kriptografis secara lokal
4. Menambahkan kunci dalam format base64 ke file .env Anda (misal: PANDA_KEY_OPD_DUKCAPIL_KEY_1=...)

[!NOTE] Untuk pengembangan lokal, Anda dapat menggunakan demo token bawaan: panda_demo_76d08573d453cdbdb4bf5704d13f8f54d57cd3c47c9b4be2

Langkah 2: Apa yang Terjadi?

Perintah init melakukan hal berikut:

1. Memvalidasi format token Anda.
2. Menghasilkan kunci 256-bit yang aman secara kriptografis secara lokal (token tidak pernah menerima kunci ini).
3. Secara otomatis menambahkan kunci dalam format base64 ke file .env Anda (misal: PANDA_KEY_OPD_DUKCAPIL_KEY_1=...).

Langkah 3: Restart Server/Terminal (Penting!)

[!IMPORTANT] Karena PHP membaca variabel environment dari .env saat startup:

• Jika menjalankan web server (misal php artisan serve, Apache, Nginx, Docker, php-fpm), Anda HARUS merestart server/container agar variabel environment baru terbaca.
• Jika menjalankan perintah di terminal/CMD, Anda HARUS membuka terminal baru atau reload variabel environment.

Menambahkan KID/Kunci Tambahan

Jika aplikasi Anda membutuhkan lebih dari satu kunci (misalnya untuk bidang data yang berbeda atau rotasi secara bertahap), gunakan perintah generate untuk menambahkan kunci tambahan tanpa memerlukan token:

[!NOTE] Perintah generate hanya dapat digunakan setelah inisialisasi awal dengan init. Tidak perlu token lagi untuk menambahkan kunci baru. Setelah kunci tersimpan di .env, operasi enkripsi/dekripsi sehari-hari tidak pernah menghubungi portal lagi.

Rotasi Kunci (Tanpa Portal)

Untuk merotasi kunci pada KID yang sudah ada, gunakan rotate-key. Perintah ini berjalan sepenuhnya lokal tanpa memerlukan token:

Menghapus Kunci (Crypto-Shred)

Referensi CLI

Mode Non-Interaktif (Flags untuk CI/CD)

Semua perintah CLI dapat digunakan dalam mode non-interaktif dengan menggunakan flag. Ini sangat berguna untuk:

• CI/CD pipelines - Otomatisasi tanpa interaksi pengguna
• Docker containers - Inisialisasi otomatis saat container start
• Infrastructure as Code - Integrasi dengan Terraform, Ansible, dll
• Automated testing - Setup dan teardown otomatis

Perintah Init - Mode Non-Interaktif

Flag init yang tersedia:

Perintah Generate - Mode Non-Interaktif

Flag generate yang tersedia:

Perintah Shred - Mode Non-Interaktif

Flag shred yang tersedia:

Perintah Migrate - Mode Non-Interaktif

Flag migrate yang tersedia:

Tabel Lengkap Referensi CLI

Infisical Setup (Production-Ready Alternative)

Untuk deployment produksi, disarankan menggunakan Infisical sebagai KeyProvider alih-alih LocalKeyProvider (env vars).

Setup Infisical Cloud

1. Buat Akun Infisical

   • Daftar di https://infisical.com (free tier tersedia)
   • Buat project baru
   • Buat environment (dev, staging, prod)

2. Buat Machine Identity

   • Buka "Machine Identities" di project Anda
   • Klik "Create Machine Identity"
   • Pilih environment yang diakses
   • Copy Client ID dan Client Secret

3. Upload Kunci Enkripsi

   • Buka "Secrets" di project
   • Pilih environment
   • Klik "Add Secret"
   • Secret Key: nik-key (atau KID Anda)
   • Secret Value: <base64-encoded-32-byte-key> (generate dengan openssl rand -base64 32)
4. Konfigurasi Aplikasi

Menggunakan InfisicalKeyProvider dalam Kode

Keuntungan Infisical:

• ✅ Production-ready dengan auto-renewal (tanpa token expiration)
• ✅ UI modern yang mudah digunakan
• ✅ Free tier untuk project kecil
• ✅ Cloud atau self-hosted options

Untuk setup lengkap Infisical, lihat Infisical Setup Guide.

2. Vanilla PHP Integration Guide

Follow these steps to integrate PANDA in a standard PHP project without any frameworks.

Step 1: Load Environment Variables

Make sure your project loads the .env file (using a library like vlucas/phpdotenv or similar):

Step 2: Initialize KeyProvider and FieldCipher

Instantiate the service classes:

Step 3: Encrypt Data (Before DB Storage)

Encrypt plaintext before writing it to a TEXT database column:

Step 4: Decrypt Data (From DB Query)

Retrieve the JSON envelope from the database and decrypt it:

Step 5: Setup Blind Index for Search Lookups

To query encrypted columns, you must compute and store a blind index hash in a separate database column (e.g. nik_bidx VARCHAR(64) indexed):

3. Laravel Integration Guide

Laravel integration provides automation using Eloquent casts, traits, and validation rules.

Step 1: Install Package and Publish Configuration

First, register configuration placeholders and set up local environment variables:

This:

1. Copies config/panda.php to your application config directory.
2. Appends PANDA_DEFAULT_KID=default-key and PANDA_ACCESS_TOKEN= to your .env file.

Step 2: Initialize Key

Run the init command to generate your local master key (as detailed in Section 1):

The wizard will prompt you for your Key Identifier (KID). Enter default-key when prompted.

[!IMPORTANT] Restart your Laravel development server (e.g. stop and restart php artisan serve or restart Docker containers) so Laravel can read the new environment keys.

Step 3: Generate Database Columns

Create a migration for your encrypted field and its blind index column using the helper command:

This creates a migration file in database/migrations/ which alters the target column to TEXT and adds a nik_bidx index column. Apply it:

Step 4: Configure the Eloquent Model

Open your Model file (e.g. app/Models/Citizen.php) and add the HasEncryptedFields trait and EncryptedCast cast:

Step 5: Save and Query Data

Now, encryption, decryption, and blind indexing are completely automated!

Saving

Reading

Querying (Search)

Controller Uniqueness Validation

Validate that an encrypted column is unique before saving using the UniqueEncrypted rule:

4. CodeIgniter 4 Integration Guide

Follow these steps to integrate PANDA in a CodeIgniter 4 application.

Step 1: Initialize Key & Restart

Initialize your local master key using the CLI command:

The wizard will prompt you for your Key Identifier (KID). Enter opd-dukcapil-key-1 when prompted.

Then, restart your development server (e.g. spark serve or php-fpm container).

Step 2: Access the Service Container

In CodeIgniter 4, PANDA registers as an optional service. Load the FieldCipher instance:

Step 3: Insert Encrypted Data with Blind Index

When saving a record, encrypt the plaintext field and generate the blind index manually before saving:

Step 4: Query and Read Decrypted Records

To retrieve records, search using the blind index hash and decrypt the returned envelope:

5. Database Refactoring & Zero-Downtime Migration Guide

If you have an existing application with a column containing plaintext data (e.g. nik VARCHAR(16) containing '3201012501990001'), follow this step-by-step workflow to migrate to encrypted and searchable storage without any system downtime.

Step-by-Step Refactor Flow

Step 1: Alter Database Column & Add Index Column

The existing plain-text column must be altered to TEXT (to fit the JSON envelope) and a separate index column (e.g. _bidx) must be added.

• Laravel Migration:

• CodeIgniter 4 / Vanilla SQL:

Step 2: Initialize PANDA Key

Initialize your local master key (as detailed in Section 1) and make sure your server is restarted.

Step 3: Run Chunked Migration Command

To convert all existing plaintext records in the database to encrypted envelopes, run the migrate CLI command:

This reads your DB in chunks (default: 100 rows), encrypts plaintext entries, updates them, and checkpoints its state in a panda_migration_state table so it can safely resume if interrupted.

Step 4: Update Application Code

• Laravel: Update the model with HasEncryptedFields and EncryptedCast (as shown in Section 3).
• CodeIgniter / Vanilla: Update CRUD operations to encrypt on write, compute blind indexes, and query using where on the _bidx column (as shown in Section 4).

Step 5: Backfill Blind Indexes for Existing Records

Since the CLI migration command only converts plaintext to encrypted envelopes, your database now has encrypted values but empty _bidx columns. You must backfill the blind indexes.

• Laravel script:

• CodeIgniter 4 / Vanilla PHP script:

Once backfilled, your zero-downtime database migration is complete!

Security

See SECURITY.md for responsible disclosure.

License

MIT