README

Laravel package for consuming the Cosmian KMS REST crypto API through Laravel's HTTP client.

Requirements

PHP 8.0 or newer (Laravel 12 requires PHP 8.2 or newer; Laravel 13 requires PHP 8.3 or newer)
Laravel 9, 10, 11, 12, or 13

Installation

Install the package with Composer:

composer require rdgoserafim/laravel-cosmian-client-sdk

Laravel discovers the service provider and facade automatically. Publish the configuration file:

php artisan vendor:publish --tag=cosmian-kms-config

Add the connection settings to .env:

COSMIAN_KMS_URL=http://localhost:9998
COSMIAN_KMS_API_KEY=your-api-key
COSMIAN_KMS_TIMEOUT=30
COSMIAN_KMS_RETRY_TIMES=3
COSMIAN_KMS_VERIFY_SSL=true
COSMIAN_KMS_API_MODE=jose

The published config/cosmian-kms.php contains all available options. Keep SSL verification enabled outside controlled local development environments.

API modes

COSMIAN_KMS_API_MODE selects the payload contract used against the KMS /v1/crypto endpoints:

jose (default): the real Cosmian KMS REST crypto API, documented in integrations/jose. Payloads use JOSE flattened JWE/JWS with base64url (no padding) fields. Supported by Cosmian KMS 5.x, including 5.26.0.
legacy: the payload shape used by version 1.x of this package (key_id, plaintext, payload, standard base64). Use it only when the KMS sits behind a gateway that implements the v1 contract.

Running Cosmian KMS locally

Cosmian KMS is a key management server used to create, store, and operate cryptographic keys. For local development, run the official image and expose its HTTP API on port 9998:

docker run -p 9998:9998 ghcr.io/cosmian/kms:latest

With Laravel running directly on the host, configure the SDK in .env as follows:

COSMIAN_KMS_URL=http://localhost:9998
COSMIAN_KMS_API_KEY=
COSMIAN_KMS_TIMEOUT=30
COSMIAN_KMS_RETRY_TIMES=3
COSMIAN_KMS_VERIFY_SSL=true

The container started by the command above does not require an API key by default, so keep COSMIAN_KMS_API_KEY empty. If authentication is enabled in your Cosmian deployment, set it to the bearer token accepted by that server.

When Laravel also runs in Docker, localhost points to the Laravel container itself. Set COSMIAN_KMS_URL to the KMS container's Docker network address instead, such as http://cosmian-kms:9998, where cosmian-kms is the service or container name.

Usage

Use dependency injection through the contract:

use Cosmian\LaravelKmsSdk\Contracts\CosmianKmsInterface;

final class EncryptionService
{
    public function __construct(private CosmianKmsInterface $kms)
    {
    }

    public function encrypt(string $value): array
    {
        return $this->kms->encrypt('my-key-id', $value, [
            'algorithm' => 'A256GCM',
        ]);
    }
}

Or use the facade:

use Cosmian\LaravelKmsSdk\Facades\CosmianKms;

// Keys: the JOSE algorithm determines the key type (A*GCM/HS* → oct,
// RS*/PS*/RSA-* → RSA, ES* → EC with the matching curve, EdDSA → OKP).
$key = CosmianKms::generateKey('A256GCM');
$rsa = CosmianKms::generateKey('RS256', ['bits' => 2048]); // RSA key pair
$imported = CosmianKms::importKey($jwk);

// Encrypt/decrypt: encrypt() returns a flattened JWE DTO; decrypt() accepts
// the same DTO (the key id is resolved from the JWE protected header).
$jwe = CosmianKms::encrypt($key['kid'], 'sensitive value');
$jweRsa = CosmianKms::encrypt($rsa['kid_public'], 'sensitive value', [
    'alg' => 'RSA-OAEP-256',
    'enc' => 'A256GCM',
]);
$plaintext = CosmianKms::decrypt($rsa['kid'], $jweRsa);

// Sign/verify: sign() returns a detached JWS DTO; verify() accepts it.
$jws = CosmianKms::sign($rsa['kid'], 'message', ['alg' => 'RS256']);
$valid = CosmianKms::verify($rsa['kid_public'], $jws, 'message');

// HMAC (jose mode only).
$hmacKey = CosmianKms::generateKey('HS256');
$mac = CosmianKms::mac($hmacKey['kid'], 'data');
$valid = CosmianKms::macVerify($hmacKey['kid'], $mac, 'data');

CosmianKms::deleteKey($key['kid']);

The JWE/JWS DTOs expose toArray() for storage or transport and JoseJwe::fromArray() / JoseJws::fromArray() to rehydrate them.

Error handling

Failed requests throw Cosmian\LaravelKmsSdk\Exceptions\CosmianKmsException. The exception exposes the API message, HTTP status, and raw response body:

use Cosmian\LaravelKmsSdk\Exceptions\CosmianKmsException;

try {
    $key = CosmianKms::generateKey('A256GCM');
} catch (CosmianKmsException $exception) {
    report($exception);

    $status = $exception->statusCode();
    $body = $exception->responseBody();
}

Every request uses Bearer authentication and the configured timeout, SSL verification, and retry count. Request and response metadata are logged at debug level; keys, plaintexts, signatures, API keys, and response bodies are never written to logs.

REST API contract

In jose mode (default) the client targets the Cosmian KMS REST crypto API (/v1/crypto) and uses the field names kid, alg, enc, data, protected, encrypted_key, iv, ciphertext, tag, signature and mac, as defined by the Cosmian JOSE integration. Plaintext, signing payloads and MAC data are base64url-encoded (no padding) before transmission. Key generation infers the JOSE key type from the algorithm (A*GCM/HS* → oct, RS*/PS*/RSA-* → RSA, ES* → EC with the matching P-* curve, EdDSA → OKP/Ed25519); pass kty, crv or bits in the options to override.

Not covered by this SDK: POST /v1/crypto/keys/unwrap, key tag management, GET /.well-known/jwks.json, and the Vault/SPIRE routes added in 5.26.0.

Migrating from v1

Version 2.0 aligns the client with the real Cosmian KMS API. Breaking changes:

listKeys() was removed — the KMS REST crypto API has no listing endpoint.
encrypt() and sign() now return JoseJwe / JoseJws DTOs instead of plain arrays.
decrypt() expects the complete JoseJwe returned by encrypt() instead of a ciphertext string.
verify() expects the complete JoseJws returned by sign() instead of a signature string.
Payloads use base64url without padding instead of standard base64.

To keep the v1 behavior while you migrate, set COSMIAN_KMS_API_MODE=legacy. In legacy mode the payload shapes are unchanged; encrypt()/sign() still return the DTOs, but populated only with the ciphertext/signature fields, and decrypt()/verify() still accept plain strings.

Testing

composer install
composer test

rdgoserafim / laravel-cosmian-client-sdk

Package info

Security

Statistics