Xmlseclibs Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require rnijveld/xmlseclibs
   

   Add to composer.json if not auto-loaded:

   "autoload": {
       "psr-4": {
           "App\\": "app/",
           "Rn\\Xml\\": "vendor/rnijveld/xmlseclibs/src/"
       }
   }
   

   Run composer dump-autoload.

2. First Use Case: Sign an XML document:

   use Rn\Xml\Security\Keys\Key;
   use Rn\Xml\Security\Signer;
   
   $key = new Key('-----BEGIN PRIVATE KEY-----MII...', '-----BEGIN CERTIFICATE-----MII...');
   $signer = new Signer($key);
   $signedXml = $signer->signXmlString($xmlString, 'id-of-element-to-sign');
   

3. Where to Look First:

   • Source Code (if available)
   • tests/ directory for usage examples.
   • Rn\Xml\Security namespace for core classes.

Implementation Patterns

Common Workflows

1. Signing XML:

   $key = new Key($privateKey, $certificate);
   $signer = new Signer($key, ['signatureAlgorithm' => 'rsa-sha256']);
   $signedXml = $signer->signXmlString($xml, 'elementId');
   

2. Verifying XML:

   $verifier = new Verifier();
   $result = $verifier->verifyXmlString($signedXml, $publicKey);
   

3. Encrypting/Decrypting:

   $encryptor = new Encryptor($key);
   $encrypted = $encryptor->encryptXmlString($xml);
   $decrypted = $encryptor->decryptXmlString($encrypted);
   

Integration Tips

• Laravel Facades (Optional): Create a facade for cleaner syntax:

  // app/XmlSecurityFacade.php
  namespace App\Facades;
  use Rn\Xml\Security\Signer;
  use Illuminate\Support\Facades\Facade;
  
  class XmlSecurityFacade extends Facade {
      protected static function getFacadeAccessor() { return 'xml.security'; }
  }
  

  Register in config/app.php:

  'xml.security' => \App\Services\XmlSecurityService::class,
  

• Service Container Binding:

  // app/Providers/AppServiceProvider.php
  public function register() {
      $this->app->bind('xml.security', function() {
          return new Signer(new Key($privateKey, $certificate));
      });
  }
  

• Middleware for API Security:

  // app/Http/Middleware/VerifyXmlSignature.php
  public function handle($request, Closure $next) {
      $verifier = new Verifier();
      if (!$verifier->verifyXmlString($request->xml, $publicKey)) {
          abort(403, 'Invalid signature');
      }
      return $next($request);
  }
  

Gotchas and Tips

Pitfalls

1. Key Format:

   • Ensure private keys are in PEM format (not DER).
   • Certificates must include the full chain (intermediate + root).

2. XML Structure:

   • The id attribute for signing must be unique in the XML.
   • Canonicalization issues may arise if XML is malformed (e.g., unescaped characters).

3. Performance:

   • Large XML files may cause memory issues. Stream processing (e.g., SimpleXML with libxml_disable_entity_loader) can help.

4. Namespace Conflicts:

   • XML namespaces in the document must match those in the key/certificate (e.g., x509v3 extensions).

Debugging

• Enable Verbose Output:

  $signer = new Signer($key, ['verbose' => true]);
  

  Logs canonicalized XML and signing steps.

• Check Canonicalization: Compare outputs of canonicalizeXmlString() to isolate issues.

• Validate Keys:

  $key->validate(); // Throws exception if key is invalid.
  

Extension Points

1. Custom Canonicalization: Override Rn\Xml\Security\Canonicalizer for non-standard XML processing.

2. Key Management: Extend Rn\Xml\Security\Keys\Key to support additional formats (e.g., PKCS#11).

3. Event Hooks: Use Laravel events to log/signature operations:

   event(new XmlSigned($signedXml, $key));
   

Config Quirks

• Default Algorithms: Override defaults in the constructor:

  $signer = new Signer($key, [
      'signatureAlgorithm' => 'rsa-sha512',
      'digestAlgorithm' => 'sha512'
  ]);
  

• Key Passwords: For encrypted keys, use:

  $key = new Key($privateKey, $certificate, 'password');