1PHPASN1 2======= 3 4[![Build Status](https://secure.travis-ci.org/fgrosse/PHPASN1.png?branch=master)](http://travis-ci.org/fgrosse/PHPASN1) 5[![PHP 7 ready](http://php7ready.timesplinter.ch/fgrosse/PHPASN1/badge.svg)](https://travis-ci.org/fgrosse/PHPASN1) 6[![Coverage Status](https://coveralls.io/repos/fgrosse/PHPASN1/badge.svg?branch=master&service=github)](https://coveralls.io/github/fgrosse/PHPASN1?branch=master) 7 8[![Latest Stable Version](https://poser.pugx.org/fgrosse/phpasn1/v/stable.png)](https://packagist.org/packages/fgrosse/phpasn1) 9[![Total Downloads](https://poser.pugx.org/fgrosse/phpasn1/downloads.png)](https://packagist.org/packages/fgrosse/phpasn1) 10[![Latest Unstable Version](https://poser.pugx.org/fgrosse/phpasn1/v/unstable.png)](https://packagist.org/packages/fgrosse/phpasn1) 11[![License](https://poser.pugx.org/fgrosse/phpasn1/license.png)](https://packagist.org/packages/fgrosse/phpasn1) 12 13A PHP Framework that allows you to encode and decode arbitrary [ASN.1][3] structures 14using the [ITU-T X.690 Encoding Rules][4]. 15This encoding is very frequently used in [X.509 PKI environments][5] or the communication between heterogeneous computer systems. 16 17The API allows you to encode ASN.1 structures to create binary data such as certificate 18signing requests (CSR), X.509 certificates or certificate revocation lists (CRL). 19PHPASN1 can also read [BER encoded][6] binary data into separate PHP objects that can be manipulated by the user and reencoded afterwards. 20 21The **changelog** can now be found at [CHANGELOG.md](CHANGELOG.md). 22 23## Dependencies 24 25PHPASN1 requires at least `PHP 7.0` and either the `gmp` or `bcmath` extension. 26Support for older PHP versions (i.e. PHP 5.6) was dropped starting with `v2.0`. 27If you must use an outdated PHP version consider using [PHPASN v1.5][13]. 28 29For the loading of object identifier names directly from the web [curl][7] is used. 30 31## Installation 32 33The preferred way to install this library is to rely on [Composer][2]: 34 35```bash 36$ composer require fgrosse/phpasn1 37``` 38 39## Usage 40 41### Encoding ASN.1 Structures 42 43PHPASN1 offers you a class for each of the implemented ASN.1 universal types. 44The constructors should be pretty self explanatory so you should have no big trouble getting started. 45All data will be encoded using [DER encoding][8] 46 47```php 48use FG\ASN1\OID; 49use FG\ASN1\Universal\Integer; 50use FG\ASN1\Universal\Boolean; 51use FG\ASN1\Universal\Enumerated; 52use FG\ASN1\Universal\IA5String; 53use FG\ASN1\Universal\ObjectIdentifier; 54use FG\ASN1\Universal\PrintableString; 55use FG\ASN1\Universal\Sequence; 56use FG\ASN1\Universal\Set; 57use FG\ASN1\Universal\NullObject; 58 59$integer = new Integer(123456); 60$boolean = new Boolean(true); 61$enum = new Enumerated(1); 62$ia5String = new IA5String('Hello world'); 63 64$asnNull = new NullObject(); 65$objectIdentifier1 = new ObjectIdentifier('1.2.250.1.16.9'); 66$objectIdentifier2 = new ObjectIdentifier(OID::RSA_ENCRYPTION); 67$printableString = new PrintableString('Foo bar'); 68 69$sequence = new Sequence($integer, $boolean, $enum, $ia5String); 70$set = new Set($sequence, $asnNull, $objectIdentifier1, $objectIdentifier2, $printableString); 71 72$myBinary = $sequence->getBinary(); 73$myBinary .= $set->getBinary(); 74 75echo base64_encode($myBinary); 76``` 77 78 79### Decoding binary data 80 81Decoding BER encoded binary data is just as easy as encoding it: 82 83```php 84use FG\ASN1\ASNObject; 85 86$base64String = ... 87$binaryData = base64_decode($base64String); 88$asnObject = ASNObject::fromBinary($binaryData); 89 90 91// do stuff 92``` 93 94If you already know exactly how your expected data should look like you can use the `FG\ASN1\TemplateParser`: 95 96```php 97use FG\ASN1\TemplateParser; 98 99// first define your template 100$template = [ 101 Identifier::SEQUENCE => [ 102 Identifier::SET => [ 103 Identifier::OBJECT_IDENTIFIER, 104 Identifier::SEQUENCE => [ 105 Identifier::INTEGER, 106 Identifier::BITSTRING, 107 ] 108 ] 109 ] 110]; 111 112// if your binary data is not matching the template you provided this will throw an `\Exception`: 113$parser = new TemplateParser(); 114$object = $parser->parseBinary($data, $template); 115 116// there is also a convenience function if you parse binary data from base64: 117$object = $parser->parseBase64($data, $template); 118``` 119 120You can use this function to make sure your data has exactly the format you are expecting. 121 122### Navigating decoded data 123 124All constructed classes (i.e. `Sequence` and `Set`) can be navigated by array access or using an iterator. 125You can find examples 126[here](https://github.com/fgrosse/PHPASN1/blob/f6442cadda9d36f3518c737e32f28300a588b777/tests/ASN1/Universal/SequenceTest.php#L148-148), 127[here](https://github.com/fgrosse/PHPASN1/blob/f6442cadda9d36f3518c737e32f28300a588b777/tests/ASN1/Universal/SequenceTest.php#L121) and 128[here](https://github.com/fgrosse/PHPASN1/blob/f6442cadda9d36f3518c737e32f28300a588b777/tests/ASN1/TemplateParserTest.php#L45). 129 130 131### Give me more examples! 132 133To see some example usage of the API classes or some generated output check out the [examples](https://github.com/fgrosse/PHPASN1/tree/master/examples). 134 135 136### How do I contribute? 137 138If you found an issue or have a question submit a github issue with detailed information. 139 140In case you already know what caused the issue and feel in the mood to fix it, your code contributions are always welcome. Just fork the repository, implement your changes and make sure that you covered everything with tests. 141Afterwards submit a pull request via github and be a little patient :) I usually try to comment and/or merge as soon as possible. 142 143#### Mailing list 144 145New features or questions can be discussed in [this google group/mailing list][12]. 146 147### Thanks 148 149To [all contributors][1] so far! 150 151## License 152 153This library is distributed under the [MIT License](LICENSE). 154 155[1]: https://github.com/fgrosse/PHPASN1/graphs/contributors 156[2]: https://getcomposer.org/ 157[3]: http://www.itu.int/ITU-T/asn1/ 158[4]: http://www.itu.int/ITU-T/recommendations/rec.aspx?rec=x.690 159[5]: http://en.wikipedia.org/wiki/X.509 160[6]: http://en.wikipedia.org/wiki/X.690#BER_encoding 161[7]: http://php.net/manual/en/book.curl.php 162[8]: http://en.wikipedia.org/wiki/X.690#DER_encoding 163[9]: https://styleci.io 164[10]: https://coveralls.io/github/fgrosse/PHPASN1 165[11]: https://github.com/fgrosse/PHPASN1/blob/master/tests/ASN1/TemplateParserTest.php#L16 166[12]: https://groups.google.com/d/forum/phpasn1 167[13]: https://packagist.org/packages/fgrosse/phpasn1#1.5.2 168