X509 Bundle Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require avkluchko/x509-bundle
   

   Ensure ext-openssl is enabled in your PHP environment.

2. Register Bundle (if not using Symfony Flex): Add to config/bundles.php:

   return [
       // ...
       AVKluchko\X509Bundle\X509Bundle::class => ['all' => true],
   ];
   

3. First Use Case: Parse a certificate in a controller or service:

   use AVKluchko\X509Bundle\Service\Parser;
   
   class CertificateController extends Controller {
       public function parseCertificate(Parser $parser) {
           $certData = $parser->parse(storage_path('app/cert.pem'));
           return response()->json($certData);
       }
   }
   

Implementation Patterns

Core Workflows

1. Certificate Parsing:

   • Use Parser service to extract details from .pem, .crt, or .der files:

     $parser->parse(file_get_contents('certificate.crt'));
     

   • Supports both file paths and raw certificate strings.

2. Validation:

   • Check certificate validity programmatically:

     $parser->validate($certData, new \DateTime());
     

3. Integration with Government Bundle:

   • If using avkluchko/government-bundle, leverage combined workflows for government-issued certificates (e.g., eIDAS compliance).

4. Dependency Injection:

   • Inject Parser into services/controllers for reusable logic:

     public function __construct(private Parser $parser) {}
     

Common Use Cases

• API Authentication: Validate client certificates in middleware:

  public function handle(Request $request, Closure $next) {
      $cert = $request->getClientCert();
      $parser->validate($cert, now());
      return $next($request);
  }
  

• Batch Processing: Parse multiple certificates in a loop:

  foreach (glob(storage_path('certs/*.pem')) as $cert) {
      $data = $parser->parse($cert);
      // Process $data
  }
  

Gotchas and Tips

Pitfalls

1. OpenSSL Dependency:

   • Forgetting to enable ext-openssl will cause runtime errors. Verify with:

     php -m | grep openssl
     

2. File vs. String Input:

   • parse() accepts both file paths and raw strings, but mixing them may cause issues. Stick to one format per operation.

3. Certificate Format:

   • The bundle assumes standard PEM/DER formats. Malformed certificates (e.g., concatenated PEMs) may require pre-processing.

4. Government Bundle Dependency:

   • If not using avkluchko/government-bundle, ignore its related features (e.g., GovernmentCertificateParser).

Debugging

• Validation Errors:
  • Use try-catch to handle exceptions:

    try {
        $parser->validate($cert, now());
    } catch (\AVKluchko\X509Bundle\Exception\InvalidCertificateException $e) {
        log::error($e->getMessage());
    }
    

• Log Raw Data:
  • For debugging, log the parsed certificate:

    log::debug('Certificate data:', $parser->parse($cert));
    

Extension Points

1. Custom Parsers:

   • Extend Parser to add domain-specific logic:

     class CustomParser extends Parser {
         public function extractCustomField($certData) {
             return $certData['extensions']['custom_field'] ?? null;
         }
     }
     

2. Configuration:

   • Override default settings via config/packages/avkluchko_x509.yaml:

     parser:
         default_format: 'PEM' # or 'DER'
     

3. Symfony Events:

   • Dispatch events for certificate parsing/validation (e.g., certificate.parsed). Requires manual event listener setup.