From: Sergey Matveev Date: Sat, 15 Feb 2020 18:55:10 +0000 (+0300) Subject: Move CLI usage example to the library itself X-Git-Tag: 7.0~16 X-Git-Url: http://www.git.cypherpunks.ru/?p=pyderasn.git;a=commitdiff_plain;h=370a9698a2b53a681a0f94d371b3f889df55225f Move CLI usage example to the library itself --- diff --git a/doc/examples.rst b/doc/examples.rst index 953001a..fc6e7c8 100644 --- a/doc/examples.rst +++ b/doc/examples.rst @@ -186,115 +186,10 @@ it's DER encoded representation is already in ``raw`` variable):: :ref:`Look here ` for better pretty printing. -.. _cmdline: - As command line utility ----------------------- -You can decode DER/BER files using command line abilities and get the -same picture as above by executing:: - - $ python -m pyderasn --schema tests.test_crts:Certificate path/to/file - -If there is no schema for you file, then you can try parsing it without, -but of course IMPLICIT tags will often make it impossible. But result is -good enough for the certificate above:: - - $ python -m pyderasn path/to/file - 0 [1,3,1604] . >: SEQUENCE OF - 4 [1,3,1453] . . >: SEQUENCE OF - 8 [0,0, 5] . . . . >: [0] ANY - . . . . . A0:03:02:01:02 - 13 [1,1, 3] . . . . >: INTEGER 61595 - 18 [1,1, 13] . . . . >: SEQUENCE OF - 20 [1,1, 9] . . . . . . >: OBJECT IDENTIFIER 1.2.840.113549.1.1.5 - 31 [1,1, 0] . . . . . . >: NULL - 33 [1,3, 274] . . . . >: SEQUENCE OF - 37 [1,1, 11] . . . . . . >: SET OF - 39 [1,1, 9] . . . . . . . . >: SEQUENCE OF - 41 [1,1, 3] . . . . . . . . . . >: OBJECT IDENTIFIER 2.5.4.6 - 46 [1,1, 2] . . . . . . . . . . >: PrintableString PrintableString ES - [...] - 1409 [1,1, 50] . . . . . . >: SEQUENCE OF - 1411 [1,1, 8] . . . . . . . . >: OBJECT IDENTIFIER 1.3.6.1.5.5.7.1.1 - 1421 [1,1, 38] . . . . . . . . >: OCTET STRING 38 bytes - . . . . . . . . . 30:24:30:22:06:08:2B:06:01:05:05:07:30:01:86:16 - . . . . . . . . . 68:74:74:70:3A:2F:2F:6F:63:73:70:2E:69:70:73:63 - . . . . . . . . . 61:2E:63:6F:6D:2F - 1461 [1,1, 13] . . >: SEQUENCE OF - 1463 [1,1, 9] . . . . >: OBJECT IDENTIFIER 1.2.840.113549.1.1.5 - 1474 [1,1, 0] . . . . >: NULL - 1476 [1,2, 129] . . >: BIT STRING 1024 bits - . . . 68:EE:79:97:97:DD:3B:EF:16:6A:06:F2:14:9A:6E:CD - . . . 9E:12:F7:AA:83:10:BD:D1:7C:98:FA:C7:AE:D4:0E:2C - [...] - -Human readable OIDs -___________________ - -If you have got dictionaries with ObjectIdentifiers, like example one -from ``tests/test_crts.py``:: - - stroid2name = { - "1.2.840.113549.1.1.1": "id-rsaEncryption", - "1.2.840.113549.1.1.5": "id-sha1WithRSAEncryption", - [...] - "2.5.4.10": "id-at-organizationName", - "2.5.4.11": "id-at-organizationalUnitName", - } - -then you can pass it to pretty printer to see human readable OIDs:: - - $ python -m pyderasn --oids tests.test_crts:stroid2name path/to/file - [...] - 37 [1,1, 11] . . . . . . >: SET OF - 39 [1,1, 9] . . . . . . . . >: SEQUENCE OF - 41 [1,1, 3] . . . . . . . . . . >: OBJECT IDENTIFIER id-at-countryName (2.5.4.6) - 46 [1,1, 2] . . . . . . . . . . >: PrintableString PrintableString ES - 50 [1,1, 18] . . . . . . >: SET OF - 52 [1,1, 16] . . . . . . . . >: SEQUENCE OF - 54 [1,1, 3] . . . . . . . . . . >: OBJECT IDENTIFIER id-at-stateOrProvinceName (2.5.4.8) - 59 [1,1, 9] . . . . . . . . . . >: PrintableString PrintableString Barcelona - 70 [1,1, 18] . . . . . . >: SET OF - 72 [1,1, 16] . . . . . . . . >: SEQUENCE OF - 74 [1,1, 3] . . . . . . . . . . >: OBJECT IDENTIFIER id-at-localityName (2.5.4.7) - 79 [1,1, 9] . . . . . . . . . . >: PrintableString PrintableString Barcelona - [...] - -Decode paths -____________ - -Each decoded element has so-called decode path: sequence of structure -names it is passing during the decode process. Each element has its own -unique path inside the whole ASN.1 tree. You can print it out with -``--print-decode-path`` option:: - - $ python -m pyderasn --schema path.to:Certificate --print-decode-path path/to/file - 0 [1,3,1604] Certificate SEQUENCE [] - 4 [1,3,1453] . tbsCertificate: TBSCertificate SEQUENCE [tbsCertificate] - 10-2 [1,1, 1] . . version: [0] EXPLICIT Version INTEGER v3 OPTIONAL [tbsCertificate:version] - 13 [1,1, 3] . . serialNumber: CertificateSerialNumber INTEGER 61595 [tbsCertificate:serialNumber] - 18 [1,1, 13] . . signature: AlgorithmIdentifier SEQUENCE [tbsCertificate:signature] - 20 [1,1, 9] . . . algorithm: OBJECT IDENTIFIER 1.2.840.113549.1.1.5 [tbsCertificate:signature:algorithm] - 31 [0,0, 2] . . . parameters: [UNIV 5] ANY OPTIONAL [tbsCertificate:signature:parameters] - . . . . 05:00 - 33 [0,0, 278] . . issuer: Name CHOICE rdnSequence [tbsCertificate:issuer] - 33 [1,3, 274] . . . rdnSequence: RDNSequence SEQUENCE OF [tbsCertificate:issuer:rdnSequence] - 37 [1,1, 11] . . . . 0: RelativeDistinguishedName SET OF [tbsCertificate:issuer:rdnSequence:0] - 39 [1,1, 9] . . . . . 0: AttributeTypeAndValue SEQUENCE [tbsCertificate:issuer:rdnSequence:0:0] - 41 [1,1, 3] . . . . . . type: AttributeType OBJECT IDENTIFIER 2.5.4.6 [tbsCertificate:issuer:rdnSequence:0:0:type] - 46 [0,0, 4] . . . . . . value: [UNIV 19] AttributeValue ANY [tbsCertificate:issuer:rdnSequence:0:0:value] - . . . . . . . 13:02:45:53 - 46 [1,1, 2] . . . . . . . DEFINED BY 2.5.4.6: CountryName PrintableString ES [tbsCertificate:issuer:rdnSequence:0:0:value:DEFINED BY 2.5.4.6] - [...] - -Now you can print only the specified tree, for example signature algorithm:: - - $ python -m pyderasn --schema path.to:Certificate --decode-path-only tbsCertificate:signature path/to/file - 18 [1,1, 13] AlgorithmIdentifier SEQUENCE - 20 [1,1, 9] . algorithm: OBJECT IDENTIFIER 1.2.840.113549.1.1.5 - 31 [0,0, 2] . parameters: [UNIV 5] ANY OPTIONAL - . . 05:00 +:ref:`Read about using it as command line utility `. Descriptive errors ------------------ diff --git a/pyderasn.py b/pyderasn.py index 39d2f2f..58583b1 100755 --- a/pyderasn.py +++ b/pyderasn.py @@ -661,6 +661,115 @@ Various .. autoclass:: pyderasn.ObjNotReady .. autoclass:: pyderasn.InvalidValueType .. autoclass:: pyderasn.BoundsError + +.. _cmdline: + +Command-line usage +------------------ + +You can decode DER/BER files using command line abilities:: + + $ python -m pyderasn --schema tests.test_crts:Certificate path/to/file + +If there is no schema for your file, then you can try parsing it without, +but of course IMPLICIT tags will often make it impossible. But result is +good enough for the certificate above:: + + $ python -m pyderasn path/to/file + 0 [1,3,1604] . >: SEQUENCE OF + 4 [1,3,1453] . . >: SEQUENCE OF + 8 [0,0, 5] . . . . >: [0] ANY + . . . . . A0:03:02:01:02 + 13 [1,1, 3] . . . . >: INTEGER 61595 + 18 [1,1, 13] . . . . >: SEQUENCE OF + 20 [1,1, 9] . . . . . . >: OBJECT IDENTIFIER 1.2.840.113549.1.1.5 + 31 [1,1, 0] . . . . . . >: NULL + 33 [1,3, 274] . . . . >: SEQUENCE OF + 37 [1,1, 11] . . . . . . >: SET OF + 39 [1,1, 9] . . . . . . . . >: SEQUENCE OF + 41 [1,1, 3] . . . . . . . . . . >: OBJECT IDENTIFIER 2.5.4.6 + 46 [1,1, 2] . . . . . . . . . . >: PrintableString PrintableString ES + [...] + 1409 [1,1, 50] . . . . . . >: SEQUENCE OF + 1411 [1,1, 8] . . . . . . . . >: OBJECT IDENTIFIER 1.3.6.1.5.5.7.1.1 + 1421 [1,1, 38] . . . . . . . . >: OCTET STRING 38 bytes + . . . . . . . . . 30:24:30:22:06:08:2B:06:01:05:05:07:30:01:86:16 + . . . . . . . . . 68:74:74:70:3A:2F:2F:6F:63:73:70:2E:69:70:73:63 + . . . . . . . . . 61:2E:63:6F:6D:2F + 1461 [1,1, 13] . . >: SEQUENCE OF + 1463 [1,1, 9] . . . . >: OBJECT IDENTIFIER 1.2.840.113549.1.1.5 + 1474 [1,1, 0] . . . . >: NULL + 1476 [1,2, 129] . . >: BIT STRING 1024 bits + . . . 68:EE:79:97:97:DD:3B:EF:16:6A:06:F2:14:9A:6E:CD + . . . 9E:12:F7:AA:83:10:BD:D1:7C:98:FA:C7:AE:D4:0E:2C + [...] + +Human readable OIDs +___________________ + +If you have got dictionaries with ObjectIdentifiers, like example one +from ``tests/test_crts.py``:: + + stroid2name = { + "1.2.840.113549.1.1.1": "id-rsaEncryption", + "1.2.840.113549.1.1.5": "id-sha1WithRSAEncryption", + [...] + "2.5.4.10": "id-at-organizationName", + "2.5.4.11": "id-at-organizationalUnitName", + } + +then you can pass it to pretty printer to see human readable OIDs:: + + $ python -m pyderasn --oids tests.test_crts:stroid2name path/to/file + [...] + 37 [1,1, 11] . . . . . . >: SET OF + 39 [1,1, 9] . . . . . . . . >: SEQUENCE OF + 41 [1,1, 3] . . . . . . . . . . >: OBJECT IDENTIFIER id-at-countryName (2.5.4.6) + 46 [1,1, 2] . . . . . . . . . . >: PrintableString PrintableString ES + 50 [1,1, 18] . . . . . . >: SET OF + 52 [1,1, 16] . . . . . . . . >: SEQUENCE OF + 54 [1,1, 3] . . . . . . . . . . >: OBJECT IDENTIFIER id-at-stateOrProvinceName (2.5.4.8) + 59 [1,1, 9] . . . . . . . . . . >: PrintableString PrintableString Barcelona + 70 [1,1, 18] . . . . . . >: SET OF + 72 [1,1, 16] . . . . . . . . >: SEQUENCE OF + 74 [1,1, 3] . . . . . . . . . . >: OBJECT IDENTIFIER id-at-localityName (2.5.4.7) + 79 [1,1, 9] . . . . . . . . . . >: PrintableString PrintableString Barcelona + [...] + +Decode paths +____________ + +Each decoded element has so-called decode path: sequence of structure +names it is passing during the decode process. Each element has its own +unique path inside the whole ASN.1 tree. You can print it out with +``--print-decode-path`` option:: + + $ python -m pyderasn --schema path.to:Certificate --print-decode-path path/to/file + 0 [1,3,1604] Certificate SEQUENCE [] + 4 [1,3,1453] . tbsCertificate: TBSCertificate SEQUENCE [tbsCertificate] + 10-2 [1,1, 1] . . version: [0] EXPLICIT Version INTEGER v3 OPTIONAL [tbsCertificate:version] + 13 [1,1, 3] . . serialNumber: CertificateSerialNumber INTEGER 61595 [tbsCertificate:serialNumber] + 18 [1,1, 13] . . signature: AlgorithmIdentifier SEQUENCE [tbsCertificate:signature] + 20 [1,1, 9] . . . algorithm: OBJECT IDENTIFIER 1.2.840.113549.1.1.5 [tbsCertificate:signature:algorithm] + 31 [0,0, 2] . . . parameters: [UNIV 5] ANY OPTIONAL [tbsCertificate:signature:parameters] + . . . . 05:00 + 33 [0,0, 278] . . issuer: Name CHOICE rdnSequence [tbsCertificate:issuer] + 33 [1,3, 274] . . . rdnSequence: RDNSequence SEQUENCE OF [tbsCertificate:issuer:rdnSequence] + 37 [1,1, 11] . . . . 0: RelativeDistinguishedName SET OF [tbsCertificate:issuer:rdnSequence:0] + 39 [1,1, 9] . . . . . 0: AttributeTypeAndValue SEQUENCE [tbsCertificate:issuer:rdnSequence:0:0] + 41 [1,1, 3] . . . . . . type: AttributeType OBJECT IDENTIFIER 2.5.4.6 [tbsCertificate:issuer:rdnSequence:0:0:type] + 46 [0,0, 4] . . . . . . value: [UNIV 19] AttributeValue ANY [tbsCertificate:issuer:rdnSequence:0:0:value] + . . . . . . . 13:02:45:53 + 46 [1,1, 2] . . . . . . . DEFINED BY 2.5.4.6: CountryName PrintableString ES [tbsCertificate:issuer:rdnSequence:0:0:value:DEFINED BY 2.5.4.6] + [...] + +Now you can print only the specified tree, for example signature algorithm:: + + $ python -m pyderasn --schema path.to:Certificate --decode-path-only tbsCertificate:signature path/to/file + 18 [1,1, 13] AlgorithmIdentifier SEQUENCE + 20 [1,1, 9] . algorithm: OBJECT IDENTIFIER 1.2.840.113549.1.1.5 + 31 [0,0, 2] . parameters: [UNIV 5] ANY OPTIONAL + . . 05:00 """ from codecs import getdecoder