X-Git-Url: http://www.git.cypherpunks.ru/?a=blobdiff_plain;f=doc%2Fexamples.rst;h=25e2cf4a2e740b04fde0bb4fbb8b9339697518b0;hb=5da3ff1e270f6ca27d15d19a7249c0791f46b2a2;hp=e95369c84f3f1f9155329e36fdb814fb6fd1fad9;hpb=f8f92c66af855c581d4b6e8b824da63f6987cc33;p=pyderasn.git diff --git a/doc/examples.rst b/doc/examples.rst index e95369c..25e2cf4 100644 --- a/doc/examples.rst +++ b/doc/examples.rst @@ -179,9 +179,10 @@ it's DER encoded representation is already in ``raw`` variable):: >>> crt, tail = Certificate().decode(raw) >>> crt - Certificate SEQUENCE[TBSCertificate SEQUENCE[[0] EXPLICIT Version - INTEGER v3 OPTIONAL, CertificateSerialNumber INTEGER 61595, - AlgorithmIdentifier SEQUENCE[OBJECT IDENTIFIER 1.2.840.113549.1.1.5... + Certificate SEQUENCE[tbsCertificate: TBSCertificate SEQUENCE[ + version: [0] EXPLICIT Version INTEGER v3 OPTIONAL; + serialNumber: CertificateSerialNumber INTEGER 61595; + signature: AlgorithmIdentifier SEQUENCE[OBJECT IDENTIFIER 1.2.840.113549.1.1.5... Pretty printing --------------- @@ -236,12 +237,12 @@ Let's parse that output, human:: :: - 52-2 [1,1,1054]-4 . . . . eContent: [0] EXPLICIT BER OCTET STRING 1046 bytes + 52-2∞ [1,1,1054]∞ . . . . eContent: [0] EXPLICIT BER OCTET STRING 1046 bytes ^ ^ ^ ^ 12 13 9 10 :0: - Offset of the object, where its DER encoding begins. + Offset of the object, where its DER/BER encoding begins. Pay attention that it does **not** include explicit tag. :1: If explicit tag exists, then this is its length (tag + encoded length). @@ -272,24 +273,18 @@ Let's parse that output, human:: Possible other flags like OPTIONAL and DEFAULT, if value equals to the default one, specified in the schema. :12: - Only applicable to BER encoded data. If object has indefinite length - encoding, then subtract 2 bytes EOC from its length. If object has - explicit tag with indefinite length, then subtract another EOC bytes. - In example above, ``eContent`` field has both indefinite field encoding - and indefinite length explicit tag. ``BIT STRING``, ``OCTET STRING`` - (and its derivatives), ``SEQUENCE``, ``SET``, ``SEQUENCE OF``, ``SET - OF``, ``ANY`` could have indefinite length coding. + Only applicable to BER encoded data. Indefinite length encoding mark. :13: Only applicable to BER encoded data. If object has BER-specific encoding, then ``BER`` will be shown. It does not depend on indefinite - length encoding. ``BOOLEAN``, ``BIT STRING``, ``OCTET STRING`` (and its - derivatives) could be BERed. + length encoding. ``EOC``, ``BOOLEAN``, ``BIT STRING``, ``OCTET STRING`` + (and its derivatives) could be BERed. As command line utility ----------------------- -You can decode DER files using command line abilities and get the same -picture as above by executing:: +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 @@ -326,6 +321,9 @@ good enough for the certificate above:: . . . 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``:: @@ -355,21 +353,56 @@ then you can pass it to pretty printer to see human readable OIDs:: 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 + Descriptive errors ------------------ -If you have bad DER, then errors will show you where error occurred:: +If you have bad DER/BER, then errors will show you where error occurred:: % python -m pyderasn --schema tests.test_crts:Certificate path/to/bad/file Traceback (most recent call last): [...] - pyderasn.DecodeError: UTCTime (tbsCertificate.validity.notAfter.utcTime) (at 328) invalid UTCTime format + pyderasn.DecodeError: UTCTime (tbsCertificate:validity:notAfter:utcTime) (at 328) invalid UTCTime format :: % python -m pyderasn path/to/bad/file [...] - pyderasn.DecodeError: UTCTime (0.SequenceOf.4.SequenceOf.1.UTCTime) (at 328) invalid UTCTime format + pyderasn.DecodeError: UTCTime (0:SequenceOf:4:SequenceOf:1:UTCTime) (at 328) invalid UTCTime format You can see, so called, decode path inside the structures: ``tbsCertificate`` -> ``validity`` -> ``notAfter`` -> ``utcTime`` and