]> Cypherpunks.ru repositories - pyderasn.git/blobdiff - doc/examples.rst
BER usage documentation
[pyderasn.git] / doc / examples.rst
index a9e57b66e2e88d8623e5b971660de824fa1a8f01..1d836f53549a33e3900766cea81a3dcd238c6381 100644 (file)
@@ -218,24 +218,30 @@ There is huge output. Let's pretty print it::
 
 Let's parse that output, human::
 
-       10-2 [1,1,   1]  . . version: [0] EXPLICIT Version INTEGER v3 OPTIONAL
-       ^  ^  ^ ^    ^   ^   ^        ^            ^       ^       ^  ^
-       0  1  2 3    4   5   6        7            8       9       10 11
+       10-2 [1,1,   1]    . . version: [0] EXPLICIT Version INTEGER v3 OPTIONAL
+       ^  ^  ^ ^    ^     ^   ^        ^            ^       ^       ^  ^
+       0  1  2 3    4     5   6        7            8       9       10 11
 
 ::
 
-       20   [1,1,   9]  . . . algorithm: OBJECT IDENTIFIER 1.2.840.113549.1.1.5
-       ^     ^ ^    ^   ^     ^          ^                 ^
-       0     2 3    4   5     6          9                 10
+       20   [1,1,   9]    . . . algorithm: OBJECT IDENTIFIER 1.2.840.113549.1.1.5
+       ^     ^ ^    ^     ^     ^          ^                 ^
+       0     2 3    4     5     6          9                 10
 
 ::
 
-       33   [0,0, 278]  . . issuer: Name CHOICE rdnSequence
-       ^     ^ ^    ^   ^   ^       ^    ^      ^
-       0     2 3    4   5   6       8    9      10
+       33   [0,0, 278]    . . issuer: Name CHOICE rdnSequence
+       ^     ^ ^    ^     ^   ^       ^    ^      ^
+       0     2 3    4     5   6       8    9      10
+
+::
+
+       52-2 [1,1,1054]-4  . . . . 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).
@@ -265,12 +271,25 @@ Let's parse that output, human::
 :11:
  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.
+: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.
 
 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
 
@@ -339,7 +358,7 @@ then you can pass it to pretty printer to see human readable OIDs::
 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):
@@ -364,9 +383,10 @@ Let's create some simple self-signed X.509 certificate from the ground::
     tbs = TBSCertificate()
     tbs["serialNumber"] = CertificateSerialNumber(10143011886257155224)
 
-    sign_algo_id = AlgorithmIdentifier()
-    sign_algo_id["algorithm"] = ObjectIdentifier("1.2.840.113549.1.1.5")
-    sign_algo_id["parameters"] = Any(Null())
+    sign_algo_id = AlgorithmIdentifier((
+        ("algorithm", ObjectIdentifier("1.2.840.113549.1.1.5")),
+        ("parameters", Any(Null())),
+    ))
     tbs["signature"] = sign_algo_id
 
     rdnSeq = RDNSequence()
@@ -378,20 +398,26 @@ Let's create some simple self-signed X.509 certificate from the ground::
             ("2.5.4.3", PrintableString, "false.example.com"),
             ("1.2.840.113549.1.9.1", IA5String, "false@example.com"),
     ):
-        attr = AttributeTypeAndValue()
-        attr["type"] = AttributeType(oid)
-        attr["value"] = AttributeValue(klass(text))
-        rdn = RelativeDistinguishedName()
-        rdn.append(attr)
-        rdnSeq.append(rdn)
-    issuer = Name()
-    issuer["rdnSequence"] = rdnSeq
+        rdnSeq.append(
+            RelativeDistinguishedName((
+                AttributeTypeAndValue((
+                    ("type", AttributeType(oid)),
+                    ("value", AttributeValue(klass(text))),
+                )),
+            ))
+        )
+    issuer = Name(("rdnSequence", rdnSeq))
     tbs["issuer"] = issuer
     tbs["subject"] = issuer
 
-    validity = Validity()
-    validity["notBefore"] = Time(("utcTime", UTCTime(datetime(2009, 10, 8, 0, 25, 53))))
-    validity["notAfter"] = Time(("utcTime", UTCTime(datetime(2010, 10, 8, 0, 25, 53))))
+    validity = Validity((
+        ("notBefore", Time(
+            ("utcTime", UTCTime(datetime(2009, 10, 8, 0, 25, 53))),
+        )),
+        ("notAfter", Time(
+            ("utcTime", UTCTime(datetime(2010, 10, 8, 0, 25, 53))),
+        )),
+    ))
     tbs["validity"] = validity
 
     spki = SubjectPublicKeyInfo()
@@ -424,13 +450,13 @@ fields automatic decoding::
 
     class AttributeTypeAndValue(Sequence):
         schema = (
-            ("type", AttributeType(defines=("value", {
+            ((("type",), AttributeType(defines=("value", {
                 id_at_countryName: PrintableString(),
                 id_at_stateOrProvinceName: PrintableString(),
                 id_at_localityName: PrintableString(),
                 id_at_organizationName: PrintableString(),
                 id_at_commonName: PrintableString(),
-            }))),
+            }))),),
             ("value", AttributeValue()),
         )