README

Laravel package for preparing CDAC e-Hastakshar PDF requests, signing request XML, handling eSign responses, and storing signed PDFs.

This package intentionally does not register routes, controllers, or views. Host applications should implement their own user flow and call the package service.

Installation

From Packagist:

composer require mozhuilungdsuo/laravel-cdac-e-hastakshar
php artisan vendor:publish --tag=cdac-e-hastakshar-config

Install Requirements

This package requires the PHP Imagick extension because uploaded PDFs/images are converted to page images before the signature placeholder is prepared. It also requires the PHP OpenSSL extension to parse the signer certificate and extract the eSign UID token from successful responses.

Composer will fail with requires ext-imagick * but it is not present or requires ext-openssl * but it is not present until the extensions are installed for the same PHP binary used by Composer.

On macOS with Homebrew:

brew install imagemagick
pecl install imagick
php --ini
php -m | grep -i imagick
php -m | grep -i openssl

On Ubuntu/Debian:

sudo apt-get update
sudo apt-get install php-imagick
sudo systemctl restart apache2
# or, for PHP-FPM:
sudo systemctl restart php*-fpm
php -m | grep -i imagick
php -m | grep -i openssl

If you use a versioned PHP package on Ubuntu/Debian, install the matching extension package:

sudo apt-get install php8.3-imagick
# replace 8.3 with your PHP version

On RHEL/CentOS/Fedora:

sudo dnf install php-pecl-imagick
sudo systemctl restart httpd
php -m | grep -i imagick
php -m | grep -i openssl

Confirm PHP can see the extension:

php -v
composer -vvv about
php -m | grep imagick
php -m | grep openssl

Keys

Private keys and certificates are intentionally not shipped with the package. Add them to the root folder of the app, commonly:

keys/
  eSign_Staging_Private.key

Configure the path:

ESIGN_ASP_ID=your-asp-id
ESIGN_PRIVATE_KEY=keys/eSign_Staging_Private.key
ESIGN_PRIVATE_KEY_PASSPHRASE=
ESIGN_SIGNATURE_PAGES=last

ESIGN_SIGNATURE_PAGES controls where the visible signer text is placed. Use last for the last page only, or all for every page.

Usage

Inject Mozhuilungdsuo\LaravelCdacEHastakshar\Services\EsignService in your own controller.

use Illuminate\Http\Request;
use Mozhuilungdsuo\LaravelCdacEHastakshar\Services\EsignService;
use RuntimeException;

class EsignController
{
    public function index()
    {
        return view('esign.index');
    }

    public function store(Request $request, EsignService $esign)
    {
        $validated = $request->validate([
            'document' => ['required', 'file', 'mimes:pdf,jpg,jpeg,png', 'max:20480'],
            'signer_name' => ['nullable', 'string', 'max:120'],
            'signature_pages' => ['nullable', 'in:last,all'],
        ]);
        $signerName = $validated['signer_name'] ?? $request->user()?->name;
        $signaturePages = $validated['signature_pages'] ?? null;
        $uidToken = $request->user()?->esign_uid_token;

        $payload = $esign->createRequest($validated['document'], $signerName, $signaturePages, $uidToken);

        // Optional but recommended: persist $payload['transaction_id'] against
        // the current officer/user so the unauthenticated callback can save
        // $result['uid_token'] to the correct account.

        return view('esign.redirect', $payload);
    }

    public function response(Request $request, EsignService $esign)
    {
        $responseXml = (string) $request->input('eSignResponse', '');

        if ($responseXml === '') {
            return view('esign.result', [
                'status' => 'failed',
                'message' => 'The eSign response was empty.',
            ]);
        }

        try {
            $result = $esign->completeResponse($responseXml);
        } catch (RuntimeException $exception) {
            return view('esign.result', [
                'status' => 'failed',
                'message' => $exception->getMessage(),
            ]);
        }

        if ($result['uid_token'] !== null) {
            // Look up the officer/user by $result['transaction_id'] and save
            // this 72-character token for future createRequest() calls.
        }

        if ($result['signer_name'] !== null) {
            // Optional: store or display the signer name from the certificate CN.
        }

        return view('esign.result', [
            'status' => 'completed',
            'transactionId' => $result['transaction_id'],
            'downloadUrl' => route('esign.download', $result['transaction_id']),
        ]);
    }

    public function download(string $transactionId, EsignService $esign)
    {
        return $esign->signedDownloadResponse($transactionId);
    }
}

Create resources/views/esign/index.blade.php in the host app for the upload form:

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <title>{{ __('eSign document') }}</title>
    </head>
    <body>
        <main style="max-width: 720px; margin: 48px auto; font-family: sans-serif;">
            <h1>{{ __('eSign document') }}</h1>
            <p>{{ __('Upload a PDF or image to prepare it for CDAC e-Hastakshar.') }}</p>

            <form method="POST" action="{{ route('esign.store') }}" enctype="multipart/form-data">
                @csrf

                <div>
                    <label for="signer_name">{{ __('Signer name') }}</label>
                    <input
                        id="signer_name"
                        type="text"
                        name="signer_name"
                        value="{{ old('signer_name', auth()->user()?->name) }}"
                        maxlength="120"
                    >
                </div>

                @error('signer_name')
                    <p style="color: #b91c1c;">{{ $message }}</p>
                @enderror

                <div>
                    <label for="signature_pages">{{ __('Signer text pages') }}</label>
                    <select id="signature_pages" name="signature_pages">
                        <option value="last" @selected(old('signature_pages', config('esign.signature_pages', 'last')) !== 'all')>
                            {{ __('Last page') }}
                        </option>
                        <option value="all" @selected(old('signature_pages', config('esign.signature_pages', 'last')) === 'all')>
                            {{ __('All pages') }}
                        </option>
                    </select>
                </div>

                @error('signature_pages')
                    <p style="color: #b91c1c;">{{ $message }}</p>
                @enderror

                <div>
                    <label for="document">{{ __('Document') }}</label>
                    <input
                        id="document"
                        type="file"
                        name="document"
                        accept=".pdf,.jpg,.jpeg,.png,application/pdf,image/jpeg,image/png"
                        required
                    >
                </div>

                @error('document')
                    <p style="color: #b91c1c;">{{ $message }}</p>
                @enderror

                <button type="submit" style="margin-top: 16px;">
                    {{ __('Start eSign') }}
                </button>
            </form>
        </main>
    </body>
</html>

Create resources/views/esign/redirect.blade.php in the host app to submit the generated request to CDAC:

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <title>{{ __('Redirecting to eSign') }}</title>
    </head>
    <body>
        <form action="{{ $endpoint }}" method="post" id="esign-request-form">
            <input type="hidden" id="eSignRequest" name="eSignRequest" value="{{ $request_xml }}">
            <input type="hidden" id="aspTxnID" name="aspTxnID" value="{{ $txn }}">
            <input type="hidden" id="Content-Type" name="Content-Type" value="application/xml">
            <noscript>
                <button type="submit">{{ __('Continue to eSign') }}</button>
            </noscript>
        </form>

        <script>
            document.getElementById('esign-request-form').submit();
        </script>
    </body>
</html>

Create resources/views/esign/result.blade.php in the host app for success/failure responses:

<!DOCTYPE html>
<html lang="{{ str_replace('_', '-', app()->getLocale()) }}">
    <head>
        <meta charset="utf-8">
        <meta name="viewport" content="width=device-width, initial-scale=1">
        <title>{{ __('eSign result') }}</title>
    </head>
    <body>
        <main style="max-width: 720px; margin: 48px auto; font-family: sans-serif;">
            @if ($status === 'completed')
                <h1>{{ __('eSign completed') }}</h1>
                <p>{{ __('The signed PDF has been saved and is ready to download.') }}</p>
                <p>{{ __('Transaction') }}: {{ $transactionId }}</p>
                <a href="{{ $downloadUrl }}">{{ __('Download') }}</a>
            @else
                <h1>{{ __('eSign failed') }}</h1>
                <p>{{ $message }}</p>
            @endif
        </main>
    </body>
</html>

Example host-app routes:

use App\Http\Controllers\EsignController;
use Illuminate\Support\Facades\Route;

Route::get('esign', [EsignController::class, 'index'])->name('esign.index');
Route::post('esign', [EsignController::class, 'store'])->name('esign.store');
Route::post('esign/response', [EsignController::class, 'response'])->name('esign.response');
Route::get('esign/{transactionId}/download', [EsignController::class, 'download'])->name('esign.download');

For Laravel's application bootstrap middleware configuration, exclude the callback route from CSRF validation:

$middleware->validateCsrfTokens(except: [
    'esign/response',
]);

UID Token Reuse

For the first eSign by an officer/user, call createRequest() without a UID token. The generated request XML will keep ekycId="", so CDAC will perform the normal Aadhaar authentication flow.

After CDAC posts back a successful response, completeResponse() returns uid_token when it can extract the 72-character token from UserX509Certificate. It also returns signer_name from the certificate common name (CN) when available:

$result = $esign->completeResponse($responseXml);

if ($result['uid_token'] !== null) {
    // Save this against the officer/eSign user in your application.
}

if ($result['signer_name'] !== null) {
    // Example: YANGER LONGKUMER
}

If you only need to inspect the response certificate and do not need to complete the PDF signing flow, use:

$details = $esign->certificateDetailsFromResponse($responseXml);

$details['uid_token'];   // 72-character UID token, or null
$details['signer_name']; // certificate CN, or null

For the next eSign by the same officer/user, pass the saved token as the fourth argument:

$payload = $esign->createRequest(
    document: $validated['document'],
    signerName: $signerName,
    signaturePages: $signaturePages,
    uidToken: $user->esign_uid_token,
);

The package validates supplied UID tokens as exactly 72 characters and places the token in the request XML as ekycId="...".

The response callback is commonly excluded from authentication and CSRF protection, so do not rely on auth()->user() inside the callback. Persist the returned $payload['transaction_id'] before redirecting to CDAC, map it to your officer/user, then use $result['transaction_id'] in the callback to find the same user and save $result['uid_token'].

Dependencies

The package declares its runtime dependencies in composer.json, including:

robrichards/xmlseclibs
tecnickcom/tc-lib-pdf
tecnickcom/tc-font-mirror
ext-imagick
ext-openssl

Composer will install those dependencies when this package is installed.

mozhuilungdsuo / laravel-cdac-e-hastakshar

Maintainers

Package info

Statistics

Security