Metadata-Version: 2.1
Name: arpa2.quickder
Version: 1.4.0
Summary: Quick DER -- Abstract Base Classes for generated ASN.1 handlers
Home-page: https://gitlab.com/arpa2/quick-der
Author: Rick van Rein (for the ARPA2 Quick DER project)
Author-email: rick@openfortress.nl
License: UNKNOWN
Description: # Embedding Quick DER into Python
        
        <img alt="Quick DER logo" src="quick-der-logo.png" style="float: right;"/>
        
        > *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 ()
        
        
Platform: UNKNOWN
Description-Content-Type: text/markdown
Provides-Extra: TOOLS
