Php Asn1 Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require genkgo/php-asn1
   

   Ensure your PHP version is ≥8.1 and includes either gmp or bcmath.

2. First Use Case: Encode a simple ASN.1 structure (e.g., a DER-encoded X.509 certificate component):

   use FG\ASN1\Universal\Integer;
   use FG\ASN1\Universal\Sequence;
   
   $version = new Integer(2); // Version 2
   $binary = $version->getBinary();
   echo base64_encode($binary); // Output: MIIA
   

3. Where to Look First:

   • Examples: Browse the examples directory for practical use cases.
   • Universal Types: Focus on FG\ASN1\Universal\* classes (e.g., Integer, Sequence, ObjectIdentifier) for common ASN.1 constructs.
   • TemplateParser: Use FG\ASN1\TemplateParser for strict validation of decoded binary data.

Implementation Patterns

Encoding Workflows

1. Building Complex Structures: Use Sequence or Set to group primitive types (e.g., Integer, IA5String):

   use FG\ASN1\Universal\Sequence;
   use FG\ASN1\Universal\Integer;
   use FG\ASN1\Universal\IA5String;
   
   $sequence = new Sequence(
       new Integer(123),
       new IA5String('test@example.com')
   );
   $binary = $sequence->getBinary();
   

2. Reusing OIDs: Leverage predefined OIDs (e.g., OID::RSA_ENCRYPTION) to avoid hardcoding:

   use FG\ASN1\OID;
   $oid = new ObjectIdentifier(OID::RSA_ENCRYPTION);
   

3. Context-Specific Constraints: Use FG\ASN1\ContextSpecific\* for tagged data (e.g., in PKCS#7 or CMS):

   use FG\ASN1\ContextSpecific\ContextSpecific;
   $taggedData = new ContextSpecific(0, new Integer(42)); // Tag 0
   

Decoding Workflows

1. Flexible Parsing: Parse binary data without a schema:

   use FG\ASN1\ASNObject;
   $asnObject = ASNObject::fromBinary($binaryData);
   

2. Strict Validation: Use TemplateParser to enforce structure:

   use FG\ASN1\TemplateParser;
   $template = [
       Identifier::SEQUENCE => [
           Identifier::INTEGER,
           Identifier::IA5_STRING,
       ]
   ];
   $parser = new TemplateParser();
   $object = $parser->parseBinary($binaryData, $template);
   

3. Iterative Navigation: Traverse decoded objects with array access or iterators:

   foreach ($asnObject as $child) {
       if ($child instanceof Integer) {
           echo $child->getValue(); // Output: 123
       }
   }
   

Integration Tips

1. PKI Use Cases:

   • Generate CSRs or CRLs by combining Sequence, Set, and ObjectIdentifier.
   • Example: Build a SubjectPublicKeyInfo structure for X.509 certificates.

2. Binary Data Handling:

   • Use base64_encode()/base64_decode() for transport/storage (e.g., in databases or APIs).

3. Error Handling:

   • Wrap parsing in try-catch blocks to handle malformed ASN.1 data:

     try {
         $object = ASNObject::fromBinary($binaryData);
     } catch (\Exception $e) {
         log::error("Invalid ASN.1 data: " . $e->getMessage());
     }
     

Gotchas and Tips

Pitfalls

1. Encoding Rules:

   • Defaults to DER encoding (strict, canonical). For BER, use ASNObject::fromBinary() with explicit tagging.
   • DER requires definite-length encoding for some types (e.g., OCTET_STRING), which may fail if data exceeds 127 bytes without proper handling.

2. OID Resolution:

   • OIDs like 1.2.3 are case-sensitive. Use OID::* constants (e.g., OID::PKCS7_DATA) where available.
   • Custom OIDs must be valid per ITU-T X.660.

3. TemplateParser Strictness:

   • Throws exceptions on mismatched structures. Use try-catch or validate templates against known schemas (e.g., RFC 5280 for X.509).

4. PHP Extensions:

   • Missing gmp/bcmath: Large integers (e.g., RSA moduli) will fail. Install extensions or use bcmath as a fallback.

5. Binary Data Corruption:

   • Ensure binary data is not modified after decoding (e.g., avoid substr() on raw ASN.1 blobs). Re-encode if changes are needed.

Debugging Tips

1. Inspect Raw Binary: Use bin2hex() to debug binary data:

   echo bin2hex($binaryData); // Hex dump for manual inspection
   

2. Validate with OpenSSL: Cross-check generated DER with OpenSSL:

   openssl asn1parse -in certificate.der
   

3. Template Debugging: Test templates incrementally:

   $template = [Identifier::SEQUENCE => [Identifier::INTEGER]]; // Start simple
   

Extension Points

1. Custom Types: Extend FG\ASN1\ASNObject to support domain-specific ASN.1 constructs:

   class CustomType extends ASNObject {
       protected $value;
       public function __construct($value) { $this->value = $value; }
       public function getBinary() { /* Implement custom encoding */ }
   }
   

2. OID Registry: Extend FG\ASN1\OID with custom OIDs:

   class ExtendedOID extends OID {
       const CUSTOM_OID = '1.3.6.1.4.1.12345';
   }
   

3. Performance:

   • Cache parsed templates or OID lookups if used repeatedly.
   • For large datasets, stream binary data instead of loading entirely into memory.

Configuration Quirks

1. CURL for OID Names:

   • The package fetches OID names dynamically (e.g., 2.5.4.3 → cn). Disable this behavior by setting:

     FG\ASN1\OID::setFetchOidNames(false);
     

   • Requires curl extension if enabled.

2. Strict Mode: Enable strict ASN.1 validation (e.g., for security-sensitive data):

   FG\ASN1\ASNObject::setStrictMode(true);