Fix #287: Use DER by default

Author: andrivet

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 3.0.0
+current_version = 3.0.1
 commit = True
 tag = True
 

CHANGELOG.rst

@@ -1,6 +1,11 @@
 Changelog
 =========
 
+3.0.1 (2025-05-02)
+------------------
+
+* Fix #288 - Use DER encoding by default as in previous versions
+
 3.0.0 (2025-03-03)
 ------------------
 

README.rst

@@ -6,8 +6,8 @@
     :target: https://github.com/andrivet/python-asn1
     :alt: GitHub Actions
 
-.. |docs| image:: https://readthedocs.org/projects/python-asn1/badge/?style=flat
-    :target: https://readthedocs.org/projects/python-asn1
+.. |docs| image:: https://app.readthedocs.org/projects/python-asn1/badge/?style=flat
+    :target: https://python-asn1.readthedocs.io/en/latest/
     :alt: Documentation Status
 
 .. |version| image:: https://img.shields.io/pypi/v/asn1.svg?style=flat

docs/conf.py

@@ -27,7 +27,7 @@
 year = '2007-2022'
 author = 'Sebastien Andrivet'
 copyright = '{0}, {1}'.format(year, author)
-version = release = '3.0.0'
+version = release = '3.0.1'
 
 pygments_style = 'trac'
 templates_path = ['.']

docs/usage.rst

@@ -141,10 +141,52 @@ If you want to precisely specify the ASN.1 type, you have to use the `Encoder.en
 
 This also allows to encode data progressively, without having to keep everything in memory.
 
+DER and CER
+-----------
+
+The encoder uses DER (Distinguished Encoding Rules) encoding by default. If you want to use CER (Canonical Encoding Rules) encoding,
+you can do so by calling the `Encoder.start()` method with a stream as argument:
+
+.. code-block:: python
+
+        stream = open('output.cer', 'wb')
+        encoder = asn1.Encoder()
+        encoder.start(stream)
+
+You can explicitly specify the CER encoding without using a stream:
+
+.. code-block:: python
+
+        encoder = asn1.Encoder()
+        encoder.start(Encoder.CER)
+
+You can explicitly specify the DER encoding when using a stream:
+
+.. code-block:: python
+
+        stream = open('output.cer', 'wb')
+        encoder = asn1.Encoder()
+        encoder.start(stream, Encoder.DER)
+
+DER has the advantage to be predicatable: there is one and only one way to encode a message using DER. DER is
+commonly used in security-related applications such as X.509 digital certificates. DER uses definite lengths for all
+encoded messages. This means that the length of the encoded message is known in advance. This is useful for encoding
+messages that are fixed in size or that do not change in size over time. The disadvantage of DER is that the encoded
+binary data are kept in memory until the encoding is finished. This can be a problem for very large messages.
+
+CER is similar to DER, but it uses indefinite lengths. This means that the length of the encoded message is not
+known in advance. This is useful for encoding messages that may be very large or that may change in size over time.
+The advantage of CER is that the encoded binary data are not kept in memory until the encoding is finished. This
+means that the encoder can start writing the encoded message to a file or a stream as soon as it is available.
+
+IMPORTANT: There was a mistake in version 3.0.0 of Python-ASN1 where the encoder used CER encoding by default contrary to the
+previous versions that were using DER. This was fixed in version 3.0.1: CER is the default encoding when using a stream.
+Otherwise, DER is the default encoding.
+
 Decoding
 --------
 
-If you want to decode ASN.1 from DER or BER encoded bytes, use code such as:
+If you want to decode ASN.1 from BER (DER, CER, ...) encoded bytes, use code such as:
 
 .. code-block:: python
 
@@ -201,8 +243,7 @@ Constants
 
 A few constants are defined in the `asn1` module. The
 constants immediately below correspond to ASN.1 tag numbers.
-They can be used as
-the ``nr`` parameter of the
+They can be used as the ``nr`` parameter of the
 `Encoder.write()` method, and are returned as the
 first part of a ``(nr, typ, cls)`` tuple as returned by
 `Decoder.peek()` and

examples/examples.py

@@ -30,20 +30,23 @@ def example2():
     print('Example 2')
     with open('example2.der', 'wb') as f:
         encoder = asn1.Encoder()
-        encoder.start(f)
+        encoder.start(f, asn1.Encoding.DER)  # CER is the default when using a stream
         encoder.write('1.2.3', asn1.Numbers.ObjectIdentifier)
+        encoder.output()  # Do nt forget to call output() to flush the buffer
+
 
 def example3():
-    """Encoding of a complex data."""
+    """Encoding of complex data."""
     print('Example 3')
     with open('example3.der', 'wb') as f:
         encoder = asn1.Encoder()
-        encoder.start(f)
+        encoder.start(f, asn1.Encoding.DER)  # CER is the default when using a stream
         encoder.write(['test1', 'test2', [
             1,
             0.125,
             b'\x01\x02\x03'
         ]])
+        encoder.output()  # Do nt forget to call output() to flush the buffer
     print()
 
 
@@ -180,6 +183,24 @@ def example8():
     print()
 
 
+def example9():
+    """Using CER encoding with a stream (file)."""
+    with open('exmple9.cer', 'wb') as f:
+        encoder = asn1.Encoder()
+        encoder.start(f)
+        encoder.write('1.2.3', asn1.Numbers.ObjectIdentifier)
+        # No need to call encoder.output() with CER encoding and a stream
+
+
+def example10():
+    """Using DER encoding with a stream (file)."""
+    with open('exmple10.der', 'wb') as f:
+        encoder = asn1.Encoder()
+        encoder.start(f, asn1.Encoding.DER)
+        encoder.write('1.2.3', asn1.Numbers.ObjectIdentifier)
+        encoder.output()  # Do nt forget to call output() to flush the buffer
+
+
 example1()
 example2()
 example3()
@@ -188,3 +209,5 @@ def example8():
 example6()
 example7()
 example8()
+example9()
+example10()

setup.py

@@ -29,7 +29,7 @@ def read(*names, **kwargs):
 
 setup(
     name='asn1',
-    version='3.0.0',
+    version='3.0.1',
     license='BSD',
     description='Python-ASN1 is a simple ASN.1 encoder and decoder for Python 2.7+ and 3.5+.',
     long_description='%s\n%s' % (