Eusig Bundle Laravel Package

Getting Started

Minimal Setup

1. Install Dependencies

   composer require authentin/eusig-bundle symfony/http-client nyholm/psr7
   

2. Configure DSS Endpoint Add to config/packages/eusig.yaml:

   eusig:
       dss:
           base_url: '%env(DSS_BASE_URL)%'  # e.g., http://localhost:8080/services/rest
   

3. Run DSS Locally (Optional)

   docker run -d -p 8080:8080 ghcr.io/authentin/dss:latest
   

4. First Use Case: Sign a PDF Inject SignerInterface into a controller and use:

   $signedPdf = $signer->sign(
       Document::fromLocalFile('/path/to/file.pdf'),
       new SignatureParameters(signatureLevel: SignatureLevel::PAdES_BASELINE_B)
   );
   

Implementation Patterns

Common Workflows

1. PDF Signing Pipeline

   // Controller
   public function signPdf(SignerInterface $signer, string $filePath): Response
   {
       $document = Document::fromLocalFile($filePath);
       $signed = $signer->sign($document, new SignatureParameters());
       return new Response($signed->content, 200, ['Content-Type' => 'application/pdf']);
   }
   

2. Validation Middleware

   // src/Middleware/ValidateSignature.php
   public function handle(Request $request, Closure $next)
   {
       if ($request->hasFile('signed_pdf')) {
           $validator = $this->container->get(ValidatorInterface::class);
           $result = $validator->validateSignature(
               Document::fromStream($request->file('signed_pdf')->getRealPath())
           );
           if (!$result->valid) {
               throw new \RuntimeException('Invalid signature');
           }
       }
       return $next($request);
   }
   

3. Batch Processing

   // Command
   protected function execute(InputInterface $input, OutputInterface $output): int
   {
       $signer = $this->container->get(SignerInterface::class);
       foreach ($this->getFilesToSign() as $file) {
           $signed = $signer->sign(Document::fromLocalFile($file), $this->params);
           file_put_contents($file . '.signed', $signed->content);
       }
       return Command::SUCCESS;
   }
   

Integration Tips

• Form Handling: Use Document::fromStream() for uploaded files:

  $document = Document::fromStream($request->file('document')->getRealPath());
  

• Error Handling: Wrap operations in try-catch for EusigException:

  try {
      $result = $validator->validateSignature($document);
  } catch (EusigException $e) {
      $this->addFlash('error', $e->getMessage());
  }
  

• Configuration Overrides: Extend eusig.yaml for project-specific defaults:

  eusig:
      defaults:
          signature_level: PAdES_BASELINE_LT  # Override globally
  

Gotchas and Tips

Pitfalls

1. DSS Connection Issues

   • Symptom: ClientException with "Connection refused".
   • Fix: Verify DSS container is running (docker ps) and base_url is correct.
   • Debug: Use symfony/http-client's debug mode:

     $client = new HttpClient(['debug' => true]);
     $this->container->set(SigningClientInterface::class, new DSSClient($client, $config));
     

2. PKCS12 Token Errors

   • Symptom: TokenException with "Invalid keystore".
   • Fix:
     • Ensure PKCS12_PATH points to a valid .p12 file.
     • Verify PKCS12_PASSWORD matches the keystore password.
     • Test the keystore with OpenSSL:

       openssl pkcs12 -info -in /path/to/keystore.p12
       

3. Signature Level Mismatch

   • Symptom: Validation fails with "Unsupported signature level".
   • Fix: Ensure the signature_level in SignatureParameters matches the DSS server's capabilities (check DSS logs or documentation).

Debugging Tips

• Enable DSS Logging: Add to eusig.yaml:

  eusig:
      dss:
          debug: true
  

• Inspect Documents: Use Document::toString() to verify content before signing:

  $doc = Document::fromLocalFile('/path/to/file.pdf');
  file_put_contents('debug.pdf', $doc->content); // Inspect manually
  

• Validator Details: Access full validation reports:

  $report = $validator->validateSignature($document);
  dump($report->details); // Array of signature-specific data
  

Extension Points

1. Custom Token Backend

   • Implement TokenInterface for HSM/remote providers:

     class RemoteToken implements TokenInterface {
         public function sign(Document $document, SignatureParameters $params): Document {
             // Call remote API
         }
     }
     

   • Register as a service with the authentin.eusig.token tag.

2. Signature Policy Overrides

   • Extend SignatureParameters for project-specific rules:

     class CustomParameters extends SignatureParameters {
         public function __construct() {
             parent::__construct(
                 signatureLevel: SignatureLevel::PAdES_BASELINE_LT,
                 customPolicy: 'MyCompanyPolicy'
             );
         }
     }
     

3. Event Listeners

   • Subscribe to eusig.signature.created events for post-signing actions:

     # config/services.yaml
     App\EventListener\SignatureLogger:
         tags:
             - { name: kernel.event_listener, event: eusig.signature.created, method: onSignatureCreated }
     

Configuration Quirks

• Default Values: The bundle provides sensible defaults (e.g., SHA256 digest). Override only if required.
• Environment Variables: Always use %env() for sensitive data (e.g., PKCS12_PASSWORD).
• Caching: DSS responses are not cached by default. For high-volume signing, implement a cache layer around SigningClientInterface.