Eusig Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require authentin/eusig
   

   Ensure your project meets PHP 8.0+ requirements.

2. Basic Usage Integrate the package via the EuSig facade or service container:

   use Authentin\EuSig\Facades\EuSig;
   
   $signature = EuSig::sign(
       data: 'Your data to sign',
       privateKey: file_get_contents('path/to/private.key'),
       algorithm: 'ES256' // eIDAS-compliant algorithm
   );
   

3. First Use Case Sign a PDF or XML payload for eIDAS compliance:

   $signedData = EuSig::signPdf(
       pdfContent: file_get_contents('document.pdf'),
       privateKey: 'private_key.pem',
       timestampUrl: 'http://timestamp.example.com'
   );
   

Key Files to Review

• config/eusig.php (default configuration)
• vendor/authentin/eusig/src/ (core logic and algorithms)

Implementation Patterns

Workflow: Signing & Verifying Documents

1. Signing Process

   // For XML/JSON
   $signedXml = EuSig::signXml(
       xmlData: $xmlString,
       privateKey: $key,
       certChain: $certChain // Optional for long-term validation
   );
   
   // For PDFs (via external library integration)
   $pdfSignature = EuSig::signPdfWithExternalTool(
       pdfPath: 'document.pdf',
       signature: $base64Signature,
       timestamp: 'timestamp_token'
   );
   

2. Verification

   $isValid = EuSig::verify(
       data: $originalData,
       signature: $signature,
       publicKey: $publicKey,
       certChain: $certChain // Required for trust chain validation
   );
   

Integration with Laravel

• Service Provider Binding Bind custom algorithms or storage adapters in AppServiceProvider:

  EuSig::extend('custom-algo', function () {
      return new CustomAlgorithm();
  });
  

• Request/Response Handling Use middleware to validate incoming signatures:

  public function handle(Request $request, Closure $next) {
      if ($request->has('signature')) {
          $valid = EuSig::verify(
              $request->data,
              $request->signature,
              config('eusig.public_key')
          );
          if (!$valid) abort(403);
      }
      return $next($request);
  }
  

Common Use Cases

Gotchas and Tips

Pitfalls

1. Algorithm Compliance

   • Only use eIDAS-approved algorithms (e.g., ES256, RS256). Custom algorithms may fail validation.
   • Avoid deprecated algorithms like SHA1 or MD5.

2. Key Management

   • Private keys must be PEM-encoded and protected (never commit to Git).
   • Use Laravel’s filesystem disk for secure key storage:

     $key = Storage::disk('secure')->get('private_key.pem');
     

3. Timestamping

   • If timestampUrl is misconfigured, signatures may fail long-term validation.
   • Test with a mock timestamp server before production.

4. Certificate Chains

   • Always include the full certificate chain (not just the leaf cert) for verification.
   • Use openssl x509 -text -noout to debug chain issues.

Debugging

• Enable Verbose Logging

  EuSig::setLogLevel(\Monolog\Logger::DEBUG);
  

• Validate Keys

  openssl rsa -check -in private_key.pem  # Check RSA keys
  openssl ec -in private_key.pem -text    # Check EC keys
  

Extension Points

1. Custom Algorithms Implement Authentin\EuSig\Contracts\Algorithm and register via:

   EuSig::extend('my-algo', MyCustomAlgorithm::class);
   

2. Storage Adapters Extend Authentin\EuSig\Storage\StorageInterface for custom key storage (e.g., AWS KMS).

3. Timestamp Providers Override the default timestamp service:

   EuSig::setTimestampProvider(new CustomTimestampProvider());
   

Configuration Quirks

• Default Values Check config/eusig.php for:
  • default_algorithm (must be eIDAS-compliant).
  • timestamp_timeout (adjust for slow servers).
• Environment Overrides Use .env to override sensitive values:

  EUSIG_PRIVATE_KEY=/path/to/key.pem
  EUSIG_TIMESTAMP_URL=https://tsa.example.com