updated docs

vakata · Dec 11, 2018 · 1e3cc9f · 1e3cc9f
1 parent 71be092
commit 1e3cc9f
Show file tree

Hide file tree

Showing 13 changed files with 315 additions and 566 deletions.
diff --git a/.codeclimate.yml b/.codeclimate.yml
diff --git a/.scrutinizr.yml b/.scrutinizr.yml
@@ -0,0 +1,29 @@
+imports:
+    - php
+
+tools:
+    external_code_coverage:
+        timeout: 600
+
+    php_code_sniffer:       true
+
+    php_cpd:                true
+
+    php_cs_fixer:           true
+
+    php_mess_detector:      true
+
+    php_pdepend:            true
+
+    php_loc:                true
+
+    php_analyzer:
+        config:
+            doc_comment_fixes:
+                enabled:    true
+
+    sensiolabs_security_checker: true
+
+changetracking:
+    bug_patterns: ["\bfix(?:es|ed)?\b"]
+    feature_patterns: ["\badd(?:s|ed)?\b", "\bimplement(?:s|ed)?\b"]
diff --git a/.travis.yml b/.travis.yml
@@ -1,8 +1,6 @@
 language: php
 
 php:
-  - 5.4
-  - 5.6
   - 7.0
 
 # This triggers builds to run on the new TravisCI infrastructure.
@@ -14,11 +12,8 @@ before_script:
   - travis_retry composer update ${COMPOSER_FLAGS} --no-interaction --prefer-source
 
 script:
-  - vendor/bin/phpunit
+  - vendor/bin/phpunit --coverage-clover=coverage.clover
 
 after_script:
-  - vendor/bin/test-reporter
-
-addons:
-  code_climate:
-    repo_token: 29b69ace6a940f3f6be9f7d9cbfb61ca5d69467b179ec53c7b1d77ebc85cd6c1
+    - bash -c 'wget https://scrutinizer-ci.com/ocular.phar'
+    - bash -c 'php ocular.phar code-coverage:upload --format=php-clover coverage.clover'
diff --git a/README.md b/README.md
@@ -3,8 +3,8 @@
 [![Latest Version on Packagist][ico-version]][link-packagist]
 [![Software License][ico-license]](LICENSE.md)
 [![Build Status][ico-travis]][link-travis]
-[![Code Climate][ico-cc]][link-cc]
-[![Tests Coverage][ico-cc-coverage]][link-cc]
+[![Scrutinizer Code Quality][ico-code-quality]][link-scrutinizer]
+[![Code Coverage][ico-scrutinizer]][link-scrutinizer]
 
 Am ASN1 encoder / decoder.
 
@@ -18,206 +18,32 @@ $ composer require vakata/asn1
 
 ## Usage
 
-``` php
-// Example 0: Working with the example Timestamp class
-// generate a timestamp request (there is a generateRequestFromData method as well)
-$tsq = Timestamp::generateRequestFromFile('/path/to/file/to/timestamp');
-// parse a timestamp request (there is a parseRequestFromFile method as well)
-$src = Timestamp::parseRequestFromData($tsq);
-// parse a timestamp response (there is a parseResponseFromData method as well)
-$tsr = Timestamp::parseResponseFromFile('/path/to/timestamp/response');
-
-// Example 1: generating a Timestamp Request (using the raw ASN1 class)
-
-// first configure the mapping (the structure)
-$tsq = [
-    'tag' => ASN1::TYPE_SEQUENCE,
-    'children' => [
-        'version' => [
-            'tag' => ASN1::TYPE_INTEGER,
-            'mapping' => [1=>'v1','v2','v3']
-        ],
-        'messageImprint' => [
-            'tag' => ASN1::TYPE_SEQUENCE,
-            'children' => [
-               'hashAlgorithm' => [
-                    'tag' => ASN1::TYPE_SEQUENCE,
-                    'children' => [
-                        "algorithm" => [
-                            'tag' => ASN1::TYPE_OBJECT_IDENTIFIER
-                        ],
-                        'parameters' => [
-                            'tag' => ASN1::TYPE_ANY,
-                            'optional' => true
-                        ]
-                    ]
-               ],
-               'hashedMessage' => [
-                    'tag' => ASN1::TYPE_OCTET_STRING
-               ]
-            ]
-        ],
-        'reqPolicy' => [
-            'tag' => ASN1::TYPE_OBJECT_IDENTIFIER,
-            'optional' => true
-        ],
-        'nonce' => [
-            'tag' => ASN1::TYPE_INTEGER,
-            'optional' => true
-        ],
-        'certReq' => [
-            'tag' => ASN1::TYPE_BOOLEAN,
-            'optional' => true
-        ]
-    ]
-];
+The main part of the library are the `Decoder` and `Encoder` classes.
 
-// then collect all values
-$src = [
-    'version' => 'v1',
-    'messageImprint' => [
-        'hashAlgorithm' => [ "algorithm" => 'sha1' ],
-        'hashedMessage' => base64_encode(sha1("asdf", true)),
-    ],
-    'certReq' => true,
-    'nonce' => rand(0, PHP_INT_MAX)
-];
+```php
+// first create an instance (there is a fromFile static method as well)
+$decoded = \vakata\asn1\Decoder::fromString("...ASN1 data here ...");
+// you can then inspect the parsed raw data
+$decoded->structure(); // more info
+$decoded->values(); // just values
+// or map the data to an existing map
+$decoded->map($mapArray);
 
-// finally produce the TSQ
-$res = ASN1::encodeDER($src, $tsq); // raw output
-// the result can be checked using:
-// openssl ts -query -in FILE.tsq -text
-
-// Example 2: decode a DER encoded object (Time-Stamp Request)
-ASN1::decodeDER($res); // deeply nested definition
+// the encoder on the otherhand needs some data and a map
+\vakata\asn1\Encoder::encode($dataArray, $mapArray);
+```
 
-// Example 3: decode a DER using a map (the one from the previous example)
-ASN1::decodeDER($res, $tsq); // the same as `$src`
+There are helper classes in the `structures` namespace - these help with working with common known structures. All the structures have `fromString` and `fromFile` static constructor methods, and a `toArray` method.
 
-// Example 4: partially decode a DER encoded Time-Stamp Response:
-$tsr = [
-    'tag' => ASN1::TYPE_SEQUENCE,
-    'children' => [
-        'status' => [
-            'tag' => ASN1::TYPE_SEQUENCE,
-            'children' => [
-                'status' => [
-                    'tag' => ASN1::TYPE_INTEGER,
-                    'mapping' => [
-                        'granted',
-                        'grantedWithMods',
-                        'rejection',
-                        'waiting',
-                        'revocationWarning',
-                        'revocationNotification'
-                    ]
-                ],
-                'statusString' => [
-                    'tag' => ASN1::TYPE_SEQUENCE,
-                    'children' => [
-                        'data' => [
-                            'tag' =>ASN1::TYPE_UTF8_STRING
-                        ]
-                    ]
-                ],
-                'failInfo' => [
-                    'tag' => ASN1::TYPE_BIT_STRING,
-                    'optional' => true
-                ]
-            ]
-        ],
-        'timeStampToken' => [
-            'tag' => ASN1::TYPE_SEQUENCE,
-            'optional' => true,
-            'children' => [
-                'contentType' => ['tag' => ASN1::TYPE_OBJECT_IDENTIFIER ],
-                'signedData' => [
-                    'tag' => ASN1::TYPE_SEQUENCE,
-                    'children' => [
-                        'version' => ['tag' => ASN1::TYPE_INTEGER ],
-                        'algorithms' => [
-                            'tag' => ASN1::TYPE_SET,
-                            'children' => [
-                                'hashAlgorithm' => [
-                                     'tag' => ASN1::TYPE_SEQUENCE,
-                                     'children' => [
-                                         "algorithm" => [
-                                             'tag' => ASN1::TYPE_OBJECT_IDENTIFIER
-                                         ],
-                                         'parameters' => [
-                                             'tag' => ASN1::TYPE_ANY,
-                                             'optional' => true
-                                         ]
-                                     ]
-                                ],
-                            ],
-                        ],
-                        "tokenInfo" => ['tag' => ASN1::TYPE_ANY_RAW]
-                    ]
-                ]
-            ]
-        ]
-    ]
-];
-$res = ASN1::decodeDER($rawInput, $tsr);
-if (in_array($res['status']['status'], [ 'granted', 'grantedWithMods'])) {
-    // timestamp was granted - we can now extract all related data
-    $token = [
-        'tag' => ASN1::TYPE_SEQUENCE,
-        'children' => [
-            'version' => ['tag' => ASN1::TYPE_INTEGER, 'mapping' => [1 => 'v1','v2','v3'] ],
-            'policy' =>  ['tag' => ASN1::TYPE_OBJECT_IDENTIFIER, 'optional' => true ],
-            'messageImprint' => [
-                'tag' => ASN1::TYPE_SEQUENCE,
-                'children' => [
-                   'hashAlgorithm' => [
-                        'tag' => ASN1::TYPE_SEQUENCE,
-                        'children' => [
-                            "algorithm" => [
-                                'tag' => ASN1::TYPE_OBJECT_IDENTIFIER
-                            ],
-                            'parameters' => [
-                                'tag' => ASN1::TYPE_ANY,
-                                'optional' => true
-                            ]
-                        ]
-                   ],
-                   'hashedMessage' => [
-                        'tag' => ASN1::TYPE_OCTET_STRING,
-                        'optional' => true // non-optional
-                   ]
-                ]
-            ],
-            'serialNumber' => ['tag' => ASN1::TYPE_INTEGER, 'optional' => true ], // non-optional
-            'genTime' => ['tag' => ASN1::TYPE_GENERALIZED_TIME], // GeneralizedTime (non-optional]
-            'accuracy' => [
-                'tag' => ASN1::TYPE_SEQUENCE,
-                'optional' => true,
-                'children' => [
-                    'seconds' => ['tag' => ASN1::TYPE_ANY, 'optional' => true ],
-                    'millis' => ['tag' => ASN1::TYPE_ANY, 'optional' => true ],
-                    'micros' => ['tag' => ASN1::TYPE_ANY, 'optional' => true ],
-                ]
-            ],
-            'ordering' => [
-                'tag' => ASN1::TYPE_BOOLEAN,
-                'optional' => true
-            ],
-            'nonce' => [
-                'tag' => ASN1::TYPE_INTEGER,
-                'optional' => true
-            ],
-            'tsa' => ['tag' => ASN1::TYPE_ANY_RAW, 'optional' => true]
-        ]
-    ];
-    $token = ASN1::decodeDER(
-        $res['timeStampToken']["signedData"]["tokenInfo"][1],
-        $token
-    );
-}
+``` php
+// Timestamp example:
+\vakata\asn1\structures\TimestampRequest::fromString($tsq)->toArray();
+\vakata\asn1\structures\TimestampResponse::fromFile('/path/to/timestamp/response')->toArray();
+\vakata\asn1\structures\TimestampRequest::generateFromFile('/path/to/file/to/timestamp');
+// You can also work with Certificate, CRL, OCSPRequest, OCSPResponse, P7S
 ```
 
-Read more in the [API docs](docs/README.md)
+Read more in the [API docs](api.md)
 
 ## Testing
 
@@ -254,7 +80,7 @@ The MIT License (MIT). Please see [License File](LICENSE.md) for more informatio
 
 [link-packagist]: https://packagist.org/packages/vakata/asn1
 [link-travis]: https://travis-ci.org/vakata/asn1
-[link-scrutinizer]: https://scrutinizer-ci.com/g/vakata/asn1/code-structure
+[link-scrutinizer]: https://scrutinizer-ci.com/g/vakata/asn1
 [link-code-quality]: https://scrutinizer-ci.com/g/vakata/asn1
 [link-downloads]: https://packagist.org/packages/vakata/asn1
 [link-author]: https://github.com/vakata