arpa2.quickder 1.4.0

Quick DER -- Abstract Base Classes for generated ASN.1 handlers

Embedding Quick DER into Python

This description explains how Quick DER is mapped into Python. The design is made to facilitate similar structural traversals in Python as in C, albeit through a different mechanism. Much like the C headers, the structures are generated and placed into modules that are delivered along with Quick DER for Python.

General Description

The implementation of Quick DER in Python centers around classes that encapsulate the logic of various ASN.1 objects. Constructed types such as CHOICE, SEQUENCE and SET have named fields, which map to attributes that can be addressed directly by adding .fielfname to the instance.

Although in C we need to explicitly traverse SEQUENCE OF and SET OF on account of their variable-sized structures, this has been encapsulated into the Python API, and such structures show up as either a list or a set that can be manipulated as is normal under Python.

ASN.1 objects typed by ANY are left as they are, and provided as a (binary) Python string, holding the header and contents. You can use it in any way you like, but if you know the class, you can instantiate it as though you received the data over a protocol.

It is possible to create custom classes, by setting up the right internal variables in a subclass or instance of ASN1Object, but this is not for the faint of heart; there are ways of crashing the program in the current system. The same risk does not occur with generated include files. So, the best way to create handlers for custom structures is by mapping a custom ASN.1 specification through the asn2quickder compiler.

Building DER is the reverse process, and it can follow the same process.

Using the Generated Classes

The package for Quick DER is quick_der. It provides a function der_unpack() which expects a class (that must be a subclass of ASN1Object) and a Python string holding the byte sequence to decode. It will return an instance of the given class, with all the pleasantries of using it.

Given such an instance, entries in it can be manipulated as expected. It should be noted that the data in each output of der_unpack() is shared, meaning that you could traverse to an object within the parsed structure, change it, and then repack the overall structure, to find the changes made in the embedded object. If this is not what you need, you should clone() the respective object.

Any ASN1Object may be turned into DER bytes through its _der_pack() method (not an ASN.1 name) or the packages der_pack() function. This uses the information stored in the object to find the format for packing. In general, using Quick DER under Python means that you are using classes, not packer descriptions such as in C. It marks the differences between the languages.

In case you are wondering why the package quick_der explicitly mentions DER again in der_pack() and der_unpack() functions: we can see ways of expanding this approach with encodings for BER, XER, one of the JER encodings, PER, CER and so on. This might work through multiple inheritance of the objects, that could incorporate a possible future Quick XER module, and so on. Factories may do this appropriately for your platform. One day, who knows!

Example Code

Kerberos is completely defined in terms of ASN.1, so it serves as a good example. Instead of the binary transmission format that defies manipulation and perhaps even reading of parts, we can turn it into a Python object, work on it and generate the binary transmission format when the need arises.

The asn2quickder compiler produces Python packages for many specifications, ready to be loaded as modules. For example, a Kerberos Ticket is defined by the name Ticket in RFC 4120, so it can be reached under quickder.rfc.rfc4120.Ticket and used just like a custom class that would implement a Kerberos Ticket:

from quickder.rfc.rfc4120 import Ticket

def show_ticket (der):
        """Access individual parts of the Ticket, and print them.
           Then compose the owner's name from its constituent parts.
        """
        tkt = Ticket (der)
        print 'Ticket for Realm', tkt.realm
        print '       has name-type', tkt.sname.name_type
        for nm in tkt.sname.name_string:
                print '       has name-string component', nm
        owner = '/'.join (tkt.sname.name_string) + '@' + tkt.realm
        print 'In short, it is for', owner

def rebase_ticket (der, newrealm):
        """This violates RFC 4120, but is still a nice demo of modifying
           DER data in Python.  The violation is caused by the mismatch
           of the realm with the encrypted copy in tkt.enc_part
        """
        tkt = Ticket (der)
        tkt.realm = newrealm
        return tkt._der_pack ()