README

PHP SDK for format-preserving and AES-GCM encryption via Sevola service.

Features

• AES "transit" and "rest" encryption for arbitrary payloads
• FF1 format-preserving encryption using Ubiq Security library
• Key retrieval from Sevola API
• PHP 8.2+ compatibility
• Thread-safe operations
• Configurable timeout and base URL
• Comprehensive error handling

Installation

Via Composer

composer require ifabula/sevola-sdk-php

Or add to your composer.json:

{
    "require": {
        "ifabula/sevola-sdk-php": "^1.0.0"
    },
    "repositories": [
        {
            "type": "path",
            "url": "./sevola-sdk-php"
        }
    ]
}

Then run:

composer install

Quick Start

1. Basic Usage

<?php

require 'vendor/autoload.php';

use Ifabula\Sevola\EncryptClient;

// Create client with API key
$client = EncryptClient::new('your-api-key');

// Encrypt data at rest
$plaintext = 'Hello, World!';
$encrypted = $client->encryptData($plaintext);

// Decrypt data
$decrypted = $client->decryptData($encrypted);

echo "Original: $plaintext\n";
echo "Encrypted: $encrypted\n";
echo "Decrypted: $decrypted\n";

2. Advanced Configuration

<?php

require 'vendor/autoload.php';

use Ifabula\Sevola\EncryptClient;
use Ifabula\Sevola\EncryptClientOptions;

// Create client with custom options
$options = new EncryptClientOptions(
    apiKey: 'your-api-key',
    baseURL: 'https://your-sevola-server.com',
    timeout: 60
);
$client = EncryptClient::newWithOptions($options);

// Use transit encryption for data in motion
$encrypted = $client->encryptTransit('sensitive data');
$decrypted = $client->decryptTransit($encrypted);

echo "Transit encrypted: $encrypted\n";
echo "Transit decrypted: $decrypted\n";

3. FF1 Format-Preserving Encryption

<?php

require 'vendor/autoload.php';

use Ifabula\Sevola\EncryptClient;

$client = EncryptClient::new('your-api-key');

// Encrypt with FF1
$requests = [
    [
        'template' => 'numeric',
        'data' => '1234-5678-9012'
    ]
];

$results = $client->encryptDataFF1($requests);
foreach ($results as $result) {
    echo "Status: {$result['status']}\n";
    echo "Value: {$result['value']}\n";
}

// Decrypt with FF1
$decryptRequests = [
    [
        'template' => 'numeric',
        'value' => $results[0]['value']
    ]
];

$decryptResults = $client->decryptDataFF1($decryptRequests);
foreach ($decryptResults as $result) {
    echo "Status: {$result['status']}\n";
    echo "Data: {$result['data']}\n";
}

API Reference

Types

EncryptClientOptions

class EncryptClientOptions {
    public string $apiKey;     // Required: API key for authentication
    public string $baseURL;    // Optional: Base URL (default: "http://localhost:8082")
    public int $timeout;       // Optional: Timeout in seconds (default: 30)
}

Functions

EncryptClient::new(string $apiKey): EncryptClient

Creates a new client with default settings.

EncryptClient::newWithOptions(EncryptClientOptions $options): EncryptClient

Creates a new client with custom configuration.

Methods

encryptData(string $plaintext): string

Encrypts data using "rest" key type (for data at rest).

decryptData(string $cipherText): string

Decrypts data using "rest" key type.

encryptTransit(string $plaintext): string

Encrypts data using "transit" key type (for data in transit).

decryptTransit(string $cipherText): string

Decrypts data using "transit" key type.

encryptTransitDynamic(string $plaintext): string

Encrypts data using dynamic transit keys.

decryptTransitDynamic(string $cipherText): string

Decrypts data using dynamic transit keys.

encryptDataFF1(array $requests): array

Encrypts data using FF1 format-preserving encryption. Each request should have:

• template: "numeric" or "alfanum"
• data: The data to encrypt

Returns an array of results with status and value keys.

decryptDataFF1(array $requests): array

Decrypts data using FF1 format-preserving encryption. Each request should have:

• template: "numeric" or "alfanum"
• value: The encrypted value to decrypt

Returns an array of results with status and data keys.

Testing

Run the test suite:

# Run all tests
composer test

# Run tests with coverage
composer test -- --coverage

Building

Build the module:

# Install dependencies
composer install

# Run tests
composer test

Publishing

1. Tag a Release

# Tag the release
git tag v1.0.0
git push origin v1.0.0

2. Composer Package Repository

The package can be installed via Composer once published to a repository:

# Users can install with:
composer require ifabula/sevola-sdk-php

Dependencies

• PHP 8.2+ - Required for the library
• guzzlehttp/guzzle - HTTP client for API requests
• ubiqsecurity/ubiq-php - FF1 format-preserving encryption library
• ext-openssl - OpenSSL extension for cryptographic operations
• ext-json - JSON extension for API responses

Examples

See the examples/ directory for more usage examples.

License

MIT © PT Ifabula Digital Kreasi

Support

For issues and questions:

• Create an issue on GitLab
• Email: kasfi.tamiya@ifabula.com