Documentation

andrivet · andrivet · commit b1bfab67f938 · 2025-03-03T11:34:28.000+01:00
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -1,6 +1,16 @@
 Changelog
 =========
 
+3.0.0 (2025-03-03)
+------------------
+
+* Encoding and decoding of the ASN.1 REAL type
+* Support of indefinite lengths
+* Encoding and decoding of complex data (lists, sets, ...)
+* Add support for streams (file-like objects) when encoding and decoding
+* Optionally return the number of unused bits when decoding a BitString (see also #276)
+* #286 - Add ASN.1:2008 compliance test suite
+
 2.8.0 (2025-02-20)
 ------------------
 
diff --git a/MANIFEST.in b/MANIFEST.in
@@ -3,6 +3,7 @@ graft examples
 graft src
 graft ci
 graft tests
+graft stubs
 
 include .coveragerc
 include .cookiecutterrc
diff --git a/README.rst b/README.rst
@@ -38,10 +38,10 @@ Python-ASN1 is a simple ASN.1 encoder and decoder for Python 2.7 and 3.5+.
 Features
 ========
 
-- Support BER (parser) and DER (parser and generator) encoding (except indefinite lengths)
+- Support BER (parser) and DER (parser and generator) encoding (including indefinite lengths)
 - 100% python, compatible with version 2.7, 3.5 and higher
 - Can be integrated by just including a file into your project
-
+- Support most common ASN.1 types including REAL (encoding and decoding).
 
 Dependencies
 ==============
diff --git a/docs/usage.rst b/docs/usage.rst
@@ -30,19 +30,13 @@ Null             0x05       None        None
 ObjectIdentifier 0x06       str
 Real             0x09       float       float
 Enumerated       0x0A       int
-UTCTime          0x17
-GeneralizedTime  0x18
-Date             0x1F
-TimeOfDay        0x20
-DateTime         0x21
-Duration         0x22
 ================ ========== =========== =============
 
 Because ASN.1 has more data types than Python, the situation arises that one Python
 type corresponds to multiple ASN.1 types. In this situation, the to be encoded
 ASN.1 type cannot be determined from the Python type. The solution
 implemented in Python-ASN1 is that the most frequently used type will be the
-implicit default. This is indicated in the `Encoding` column.
+implicit default. This is indicated in the ``Encoding`` column.
 If another type is desired than that must be specified
 explicitly through the API.
 
@@ -175,7 +169,7 @@ You can decode complex data structures. The decoder will automatically map ASN.1
 
 .. code-block:: python
 
-  import asn1
+    import asn1
 
     with open('example7.der', 'rb') as f:
         decoder = asn1.Decoder()
@@ -184,6 +178,24 @@ You can decode complex data structures. The decoder will automatically map ASN.1
         print(tag)
         pprint.pprint(value)
 
+You can ask the decoder to return the number of unused bits when decoding a BitString:
+
+.. code-block:: python
+
+    import asn1
+
+    encoded = b'\x23\x0C\x03\x02\x00\x0B\x03\x02\x00\x0B\x03\x02\x04\x0F'
+    decoder = asn1.Decoder()
+    decoder.start(encoded)
+    tag, (value, unused) = decoder.read(asn1.ReadFlags.WithUnused)
+    print('Tag: ', tag)
+    print('Value: ', value)
+    print('Unused bits: ', unused)
+
+The flag ``ReadFlags.WithUnused`` can be used with any ASN.1 type. When used, the read method will return a tuple with the value and the number of unused bits.
+If the type is not a BitString, the number of unused bits is always 0.
+
+
 Constants
 ---------
 
@@ -242,12 +254,12 @@ and constructed) for ASN.1 data types. As above they can be used with the
 `Decoder.peek()` and
 `Decoder.read()`.
 
-================== ===========
-Constant           Value (hex)
-================== ============
-Types.Constructed  0x20
-Types.Primitive    0x00
-================== ===========
+=================== ===========
+Constant            Value (hex)
+=================== ===========
+Types.Constructed   0x20
+Types.Primitive     0x00
+=================== ===========
 
 Finally the constants below define the different ASN.1 classes. As above
 they can be used with the `Encoder.write()` and are
diff --git a/examples/examples.py b/examples/examples.py
@@ -16,6 +16,7 @@
 
 
 def example1():
+    """Encoding an object identifier."""
     print('Example 1')
     encoder = asn1.Encoder()
     encoder.start()
@@ -25,13 +26,15 @@ def example1():
 
 
 def example2():
+    """Encoding an object identifier directly to a file."""
     print('Example 2')
     with open('example2.der', 'wb') as f:
         encoder = asn1.Encoder()
         encoder.start(f)
         encoder.write('1.2.3', asn1.Numbers.ObjectIdentifier)
 
 def example3():
+    """Encoding of a complex data."""
     print('Example 3')
     with open('example3.der', 'wb') as f:
         encoder = asn1.Encoder()
@@ -45,6 +48,7 @@ def example3():
 
 
 def example4():
+    """Decoding from a file."""
     print('Example 4')
     with open('example3.der', 'rb') as f:
         decoder = asn1.Decoder()
@@ -56,10 +60,11 @@ def example4():
 
 
 def example5():
+    """Decoding of a bit string with unused bits."""
     print('Example 5')
-    example5 = b'\x23\x0C\x03\x02\x00\x0B\x03\x02\x00\x0B\x03\x02\x04\x0F'
+    encoded = b'\x23\x0C\x03\x02\x00\x0B\x03\x02\x00\x0B\x03\x02\x04\x0F'
     decoder = asn1.Decoder()
-    decoder.start(example5)
+    decoder.start(encoded)
     tag, (val, unused) = decoder.read(asn1.ReadFlags.WithUnused)
     print('Tag:', tag)
     print('Value:', val)
@@ -68,6 +73,7 @@ def example5():
 
 
 def example6():
+    """Encoding of sequences."""
     print('Example 6')
     encoder = asn1.Encoder()
     encoder.start()
@@ -85,87 +91,89 @@ def example6():
 
 
 def example7():
+    """Decoding of sequences."""
     print('Example 7')
-    example7 = b'\x30\x80\x13\x05\x74\x65\x73\x74\x31\x13\x05\x74\x65\x73\x74\x32\x30\x80\x02\x01\x01\x09\x03\x80\xFD\x01\x04\x03\x01\x02\x03\x00\x00\x00\x00'
+    encoded = b'\x30\x80\x13\x05\x74\x65\x73\x74\x31\x13\x05\x74\x65\x73\x74\x32\x30\x80\x02\x01\x01\x09\x03\x80\xFD\x01\x04\x03\x01\x02\x03\x00\x00\x00\x00'
     decoder = asn1.Decoder()
-    decoder.start(example7)
+    decoder.start(encoded)
     tag, value = decoder.read()
     print(tag)
     pprint.pprint(value)
     print()
 
 
 def example8():
+    """Decoding of a complex data."""
     print('Example 8')
-    example8 = (b'\x30\x82\x04\x0e\x30\x82\x03\x77\xa0\x03\x02\x01\x02\x02\x02\x15'
-                b'\x30\x30\x0d\x06\x09\x2a\x86\x48\x86\xf7\x0d\x01\x01\x05\x05\x00'
-                b'\x30\x81\xbb\x31\x0b\x30\x09\x06\x03\x55\x04\x06\x13\x02\x2d\x2d'
-                b'\x31\x12\x30\x10\x06\x03\x55\x04\x08\x13\x09\x53\x6f\x6d\x65\x53'
-                b'\x74\x61\x74\x65\x31\x11\x30\x0f\x06\x03\x55\x04\x07\x13\x08\x53'
-                b'\x6f\x6d\x65\x43\x69\x74\x79\x31\x19\x30\x17\x06\x03\x55\x04\x0a'
-                b'\x13\x10\x53\x6f\x6d\x65\x4f\x72\x67\x61\x6e\x69\x7a\x61\x74\x69'
-                b'\x6f\x6e\x31\x1f\x30\x1d\x06\x03\x55\x04\x0b\x13\x16\x53\x6f\x6d'
-                b'\x65\x4f\x72\x67\x61\x6e\x69\x7a\x61\x74\x69\x6f\x6e\x61\x6c\x55'
-                b'\x6e\x69\x74\x31\x1e\x30\x1c\x06\x03\x55\x04\x03\x13\x15\x6c\x6f'
-                b'\x63\x61\x6c\x68\x6f\x73\x74\x2e\x6c\x6f\x63\x61\x6c\x64\x6f\x6d'
-                b'\x61\x69\x6e\x31\x29\x30\x27\x06\x09\x2a\x86\x48\x86\xf7\x0d\x01'
-                b'\x09\x01\x16\x1a\x72\x6f\x6f\x74\x40\x6c\x6f\x63\x61\x6c\x68\x6f'
-                b'\x73\x74\x2e\x6c\x6f\x63\x61\x6c\x64\x6f\x6d\x61\x69\x6e\x30\x1e'
-                b'\x17\x0d\x30\x38\x30\x32\x30\x35\x30\x39\x32\x33\x33\x31\x5a\x17'
-                b'\x0d\x30\x39\x30\x32\x30\x34\x30\x39\x32\x33\x33\x31\x5a\x30\x81'
-                b'\xbb\x31\x0b\x30\x09\x06\x03\x55\x04\x06\x13\x02\x2d\x2d\x31\x12'
-                b'\x30\x10\x06\x03\x55\x04\x08\x13\x09\x53\x6f\x6d\x65\x53\x74\x61'
-                b'\x74\x65\x31\x11\x30\x0f\x06\x03\x55\x04\x07\x13\x08\x53\x6f\x6d'
-                b'\x65\x43\x69\x74\x79\x31\x19\x30\x17\x06\x03\x55\x04\x0a\x13\x10'
-                b'\x53\x6f\x6d\x65\x4f\x72\x67\x61\x6e\x69\x7a\x61\x74\x69\x6f\x6e'
-                b'\x31\x1f\x30\x1d\x06\x03\x55\x04\x0b\x13\x16\x53\x6f\x6d\x65\x4f'
-                b'\x72\x67\x61\x6e\x69\x7a\x61\x74\x69\x6f\x6e\x61\x6c\x55\x6e\x69'
-                b'\x74\x31\x1e\x30\x1c\x06\x03\x55\x04\x03\x13\x15\x6c\x6f\x63\x61'
-                b'\x6c\x68\x6f\x73\x74\x2e\x6c\x6f\x63\x61\x6c\x64\x6f\x6d\x61\x69'
-                b'\x6e\x31\x29\x30\x27\x06\x09\x2a\x86\x48\x86\xf7\x0d\x01\x09\x01'
-                b'\x16\x1a\x72\x6f\x6f\x74\x40\x6c\x6f\x63\x61\x6c\x68\x6f\x73\x74'
-                b'\x2e\x6c\x6f\x63\x61\x6c\x64\x6f\x6d\x61\x69\x6e\x30\x81\x9f\x30'
-                b'\x0d\x06\x09\x2a\x86\x48\x86\xf7\x0d\x01\x01\x01\x05\x00\x03\x81'
-                b'\x8d\x00\x30\x81\x89\x02\x81\x81\x00\xd5\x18\xcd\x40\x91\x90\x27'
-                b'\x5a\x77\x37\x22\xca\xba\x05\xdf\x13\x31\xe8\x74\x43\x4f\x7e\x08'
-                b'\xa3\xa5\x76\xcd\x7b\xdd\x37\xd0\x7f\x12\x9e\x81\x73\x87\x55\x66'
-                b'\x0d\xda\x68\xee\x38\xeb\x34\xe2\xf4\xeb\x95\xd5\xe0\xde\xef\x08'
-                b'\x57\xf9\x03\x14\x69\xa8\x6f\x7c\xa4\xfa\x64\x51\x39\x36\xd5\x09'
-                b'\x37\x61\x83\x13\x8c\x41\x25\xba\x60\x91\x20\x86\x5b\x60\xb5\xe2'
-                b'\x83\x65\x66\xad\x06\xb3\x45\x71\x83\x67\xd2\xe5\x5f\x40\x42\x4b'
-                b'\x37\xf8\x87\xd0\x09\x49\xb8\xad\x34\x76\xa3\x1b\xbf\xc1\x0f\xb7'
-                b'\xfb\x43\xbe\x62\x33\x02\x02\x10\x61\x02\x03\x01\x00\x01\xa3\x82'
-                b'\x01\x1d\x30\x82\x01\x19\x30\x1d\x06\x03\x55\x1d\x0e\x04\x16\x04'
-                b'\x14\x0a\x4b\xfa\x87\x54\x17\x7e\x30\xb4\x21\x71\x56\x51\x0f\xd2'
-                b'\x91\xc3\x30\x02\x36\x30\x81\xe9\x06\x03\x55\x1d\x23\x04\x81\xe1'
-                b'\x30\x81\xde\x80\x14\x0a\x4b\xfa\x87\x54\x17\x7e\x30\xb4\x21\x71'
-                b'\x56\x51\x0f\xd2\x91\xc3\x30\x02\x36\xa1\x81\xc1\xa4\x81\xbe\x30'
-                b'\x81\xbb\x31\x0b\x30\x09\x06\x03\x55\x04\x06\x13\x02\x2d\x2d\x31'
-                b'\x12\x30\x10\x06\x03\x55\x04\x08\x13\x09\x53\x6f\x6d\x65\x53\x74'
-                b'\x61\x74\x65\x31\x11\x30\x0f\x06\x03\x55\x04\x07\x13\x08\x53\x6f'
-                b'\x6d\x65\x43\x69\x74\x79\x31\x19\x30\x17\x06\x03\x55\x04\x0a\x13'
-                b'\x10\x53\x6f\x6d\x65\x4f\x72\x67\x61\x6e\x69\x7a\x61\x74\x69\x6f'
-                b'\x6e\x31\x1f\x30\x1d\x06\x03\x55\x04\x0b\x13\x16\x53\x6f\x6d\x65'
-                b'\x4f\x72\x67\x61\x6e\x69\x7a\x61\x74\x69\x6f\x6e\x61\x6c\x55\x6e'
-                b'\x69\x74\x31\x1e\x30\x1c\x06\x03\x55\x04\x03\x13\x15\x6c\x6f\x63'
-                b'\x61\x6c\x68\x6f\x73\x74\x2e\x6c\x6f\x63\x61\x6c\x64\x6f\x6d\x61'
-                b'\x69\x6e\x31\x29\x30\x27\x06\x09\x2a\x86\x48\x86\xf7\x0d\x01\x09'
-                b'\x01\x16\x1a\x72\x6f\x6f\x74\x40\x6c\x6f\x63\x61\x6c\x68\x6f\x73'
-                b'\x74\x2e\x6c\x6f\x63\x61\x6c\x64\x6f\x6d\x61\x69\x6e\x82\x02\x15'
-                b'\x30\x30\x0c\x06\x03\x55\x1d\x13\x04\x05\x30\x03\x01\x01\xff\x30'
-                b'\x0d\x06\x09\x2a\x86\x48\x86\xf7\x0d\x01\x01\x05\x05\x00\x03\x81'
-                b'\x81\x00\x4e\x12\x46\x58\xa3\x57\xc5\x9a\xab\xfa\x32\xf5\xde\x87'
-                b'\xfb\x77\xa8\x79\x38\x1d\x4f\xd3\x7c\x3a\x16\x60\x82\x7d\x92\xa1'
-                b'\x58\xd2\x53\x7b\x11\x90\xec\x6d\xb0\xb0\x58\xee\x33\xb4\x7b\x1d'
-                b'\xb8\x95\xd8\x98\xc3\x10\x81\x83\x08\x46\xe8\x9a\xb9\x6c\xbf\x8f'
-                b'\x9e\x73\xf7\x61\x89\xc4\x6a\x1b\xc1\x98\xc6\xab\xfc\x91\xb6\x59'
-                b'\xb8\xa5\x05\x91\x2a\xbb\xc4\x30\x16\x53\xbf\x1a\xfe\x2f\x01\x25'
-                b'\xae\xef\xc7\xb9\xfa\xa5\x53\xf8\xd9\xf5\x8f\xae\x91\xea\x57\x28'
-                b'\xfa\xdf\x34\x03\x29\xe8\x97\xee\x2e\x9e\x8a\x62\x45\xc7\xfc\x58'
-                b'\xb4\x5a')
+    encoded = (b'\x30\x82\x04\x0e\x30\x82\x03\x77\xa0\x03\x02\x01\x02\x02\x02\x15'
+               b'\x30\x30\x0d\x06\x09\x2a\x86\x48\x86\xf7\x0d\x01\x01\x05\x05\x00'
+               b'\x30\x81\xbb\x31\x0b\x30\x09\x06\x03\x55\x04\x06\x13\x02\x2d\x2d'
+               b'\x31\x12\x30\x10\x06\x03\x55\x04\x08\x13\x09\x53\x6f\x6d\x65\x53'
+               b'\x74\x61\x74\x65\x31\x11\x30\x0f\x06\x03\x55\x04\x07\x13\x08\x53'
+               b'\x6f\x6d\x65\x43\x69\x74\x79\x31\x19\x30\x17\x06\x03\x55\x04\x0a'
+               b'\x13\x10\x53\x6f\x6d\x65\x4f\x72\x67\x61\x6e\x69\x7a\x61\x74\x69'
+               b'\x6f\x6e\x31\x1f\x30\x1d\x06\x03\x55\x04\x0b\x13\x16\x53\x6f\x6d'
+               b'\x65\x4f\x72\x67\x61\x6e\x69\x7a\x61\x74\x69\x6f\x6e\x61\x6c\x55'
+               b'\x6e\x69\x74\x31\x1e\x30\x1c\x06\x03\x55\x04\x03\x13\x15\x6c\x6f'
+               b'\x63\x61\x6c\x68\x6f\x73\x74\x2e\x6c\x6f\x63\x61\x6c\x64\x6f\x6d'
+               b'\x61\x69\x6e\x31\x29\x30\x27\x06\x09\x2a\x86\x48\x86\xf7\x0d\x01'
+               b'\x09\x01\x16\x1a\x72\x6f\x6f\x74\x40\x6c\x6f\x63\x61\x6c\x68\x6f'
+               b'\x73\x74\x2e\x6c\x6f\x63\x61\x6c\x64\x6f\x6d\x61\x69\x6e\x30\x1e'
+               b'\x17\x0d\x30\x38\x30\x32\x30\x35\x30\x39\x32\x33\x33\x31\x5a\x17'
+               b'\x0d\x30\x39\x30\x32\x30\x34\x30\x39\x32\x33\x33\x31\x5a\x30\x81'
+               b'\xbb\x31\x0b\x30\x09\x06\x03\x55\x04\x06\x13\x02\x2d\x2d\x31\x12'
+               b'\x30\x10\x06\x03\x55\x04\x08\x13\x09\x53\x6f\x6d\x65\x53\x74\x61'
+               b'\x74\x65\x31\x11\x30\x0f\x06\x03\x55\x04\x07\x13\x08\x53\x6f\x6d'
+               b'\x65\x43\x69\x74\x79\x31\x19\x30\x17\x06\x03\x55\x04\x0a\x13\x10'
+               b'\x53\x6f\x6d\x65\x4f\x72\x67\x61\x6e\x69\x7a\x61\x74\x69\x6f\x6e'
+               b'\x31\x1f\x30\x1d\x06\x03\x55\x04\x0b\x13\x16\x53\x6f\x6d\x65\x4f'
+               b'\x72\x67\x61\x6e\x69\x7a\x61\x74\x69\x6f\x6e\x61\x6c\x55\x6e\x69'
+               b'\x74\x31\x1e\x30\x1c\x06\x03\x55\x04\x03\x13\x15\x6c\x6f\x63\x61'
+               b'\x6c\x68\x6f\x73\x74\x2e\x6c\x6f\x63\x61\x6c\x64\x6f\x6d\x61\x69'
+               b'\x6e\x31\x29\x30\x27\x06\x09\x2a\x86\x48\x86\xf7\x0d\x01\x09\x01'
+               b'\x16\x1a\x72\x6f\x6f\x74\x40\x6c\x6f\x63\x61\x6c\x68\x6f\x73\x74'
+               b'\x2e\x6c\x6f\x63\x61\x6c\x64\x6f\x6d\x61\x69\x6e\x30\x81\x9f\x30'
+               b'\x0d\x06\x09\x2a\x86\x48\x86\xf7\x0d\x01\x01\x01\x05\x00\x03\x81'
+               b'\x8d\x00\x30\x81\x89\x02\x81\x81\x00\xd5\x18\xcd\x40\x91\x90\x27'
+               b'\x5a\x77\x37\x22\xca\xba\x05\xdf\x13\x31\xe8\x74\x43\x4f\x7e\x08'
+               b'\xa3\xa5\x76\xcd\x7b\xdd\x37\xd0\x7f\x12\x9e\x81\x73\x87\x55\x66'
+               b'\x0d\xda\x68\xee\x38\xeb\x34\xe2\xf4\xeb\x95\xd5\xe0\xde\xef\x08'
+               b'\x57\xf9\x03\x14\x69\xa8\x6f\x7c\xa4\xfa\x64\x51\x39\x36\xd5\x09'
+               b'\x37\x61\x83\x13\x8c\x41\x25\xba\x60\x91\x20\x86\x5b\x60\xb5\xe2'
+               b'\x83\x65\x66\xad\x06\xb3\x45\x71\x83\x67\xd2\xe5\x5f\x40\x42\x4b'
+               b'\x37\xf8\x87\xd0\x09\x49\xb8\xad\x34\x76\xa3\x1b\xbf\xc1\x0f\xb7'
+               b'\xfb\x43\xbe\x62\x33\x02\x02\x10\x61\x02\x03\x01\x00\x01\xa3\x82'
+               b'\x01\x1d\x30\x82\x01\x19\x30\x1d\x06\x03\x55\x1d\x0e\x04\x16\x04'
+               b'\x14\x0a\x4b\xfa\x87\x54\x17\x7e\x30\xb4\x21\x71\x56\x51\x0f\xd2'
+               b'\x91\xc3\x30\x02\x36\x30\x81\xe9\x06\x03\x55\x1d\x23\x04\x81\xe1'
+               b'\x30\x81\xde\x80\x14\x0a\x4b\xfa\x87\x54\x17\x7e\x30\xb4\x21\x71'
+               b'\x56\x51\x0f\xd2\x91\xc3\x30\x02\x36\xa1\x81\xc1\xa4\x81\xbe\x30'
+               b'\x81\xbb\x31\x0b\x30\x09\x06\x03\x55\x04\x06\x13\x02\x2d\x2d\x31'
+               b'\x12\x30\x10\x06\x03\x55\x04\x08\x13\x09\x53\x6f\x6d\x65\x53\x74'
+               b'\x61\x74\x65\x31\x11\x30\x0f\x06\x03\x55\x04\x07\x13\x08\x53\x6f'
+               b'\x6d\x65\x43\x69\x74\x79\x31\x19\x30\x17\x06\x03\x55\x04\x0a\x13'
+               b'\x10\x53\x6f\x6d\x65\x4f\x72\x67\x61\x6e\x69\x7a\x61\x74\x69\x6f'
+               b'\x6e\x31\x1f\x30\x1d\x06\x03\x55\x04\x0b\x13\x16\x53\x6f\x6d\x65'
+               b'\x4f\x72\x67\x61\x6e\x69\x7a\x61\x74\x69\x6f\x6e\x61\x6c\x55\x6e'
+               b'\x69\x74\x31\x1e\x30\x1c\x06\x03\x55\x04\x03\x13\x15\x6c\x6f\x63'
+               b'\x61\x6c\x68\x6f\x73\x74\x2e\x6c\x6f\x63\x61\x6c\x64\x6f\x6d\x61'
+               b'\x69\x6e\x31\x29\x30\x27\x06\x09\x2a\x86\x48\x86\xf7\x0d\x01\x09'
+               b'\x01\x16\x1a\x72\x6f\x6f\x74\x40\x6c\x6f\x63\x61\x6c\x68\x6f\x73'
+               b'\x74\x2e\x6c\x6f\x63\x61\x6c\x64\x6f\x6d\x61\x69\x6e\x82\x02\x15'
+               b'\x30\x30\x0c\x06\x03\x55\x1d\x13\x04\x05\x30\x03\x01\x01\xff\x30'
+               b'\x0d\x06\x09\x2a\x86\x48\x86\xf7\x0d\x01\x01\x05\x05\x00\x03\x81'
+               b'\x81\x00\x4e\x12\x46\x58\xa3\x57\xc5\x9a\xab\xfa\x32\xf5\xde\x87'
+               b'\xfb\x77\xa8\x79\x38\x1d\x4f\xd3\x7c\x3a\x16\x60\x82\x7d\x92\xa1'
+               b'\x58\xd2\x53\x7b\x11\x90\xec\x6d\xb0\xb0\x58\xee\x33\xb4\x7b\x1d'
+               b'\xb8\x95\xd8\x98\xc3\x10\x81\x83\x08\x46\xe8\x9a\xb9\x6c\xbf\x8f'
+               b'\x9e\x73\xf7\x61\x89\xc4\x6a\x1b\xc1\x98\xc6\xab\xfc\x91\xb6\x59'
+               b'\xb8\xa5\x05\x91\x2a\xbb\xc4\x30\x16\x53\xbf\x1a\xfe\x2f\x01\x25'
+               b'\xae\xef\xc7\xb9\xfa\xa5\x53\xf8\xd9\xf5\x8f\xae\x91\xea\x57\x28'
+               b'\xfa\xdf\x34\x03\x29\xe8\x97\xee\x2e\x9e\x8a\x62\x45\xc7\xfc\x58'
+               b'\xb4\x5a')
 
     decoder = asn1.Decoder()
-    decoder.start(example8)
+    decoder.start(encoded)
     tag, value = decoder.read()
     print(tag)
     pprint.pprint(value)
diff --git a/src/asn1.py b/src/asn1.py
@@ -725,16 +725,17 @@ def peek(self):  # type: () -> Union[Tag, None]
     def read(self, flags=ReadFlags.OnlyValue):  # type: (ReadFlags) -> Tuple[Union[Tag, None], Any]
         """
         This method decodes one ASN.1 tag from the input and returns it as a
-        ``(tag, value, unused)`` tuple. ``tag`` is a 3-tuple ``(nr, typ, cls)``,
+        ``(tag, value)`` tuple. ``tag`` is a 3-tuple ``(nr, typ, cls)``,
         while ``value`` is a Python object representing the ASN.1 value.
+        The number of unused bits can be requested in the ``flags`` parameter.
+        When ``ReadFlags.OnlyValue`` is specified, the method the tuple ``(tag, (value, unused))``.
         ``unused`` is the number of unused bits removed from the value.
-        The offset in the input is increased so that the next `Decoder.read()`
-        or `Decoder.read_with_unused()` call will return the next tag. In case
-        no more data is available from the input, this method returns ``None``
+        The offset in the input is increased so that the next `Decoder.read()` call will return the next tag.
+        In case no more data is available from the input, this method returns ``None``
         to signal end-of-file.
 
         Args:
-            flags (DecoderFlags): Return only the value or the value and the number of unused bits as a tuple.
+            flags (asn1.DecoderFlags): Return only the value or the value and the number of unused bits as a tuple.
 
         Returns:
             `Tag`, value: The current ASN.1 tag, its value and the
