Initial description of planned ASN1 changes.

1 files changed, 103 insertions, 0 deletions

diff --git a/README.ASN1 b/README.ASN1
new file mode 100644
index 000000000..35b8c5805
--- /dev/null
+++ b/README.ASN1
@@ -0,0 +1,103 @@
+
+OpenSSL ASN1 Revision
+=====================
+
+This branch will ultimately contain the revised OpenSSL ASN1 code.
+
+For some time it is likely to be unstable, non-portable and may not even
+compile at all: you have been warned! 
+
+Anyone who generally avoids OpenSSL ASN1 should steer well clear of this
+for now.
+
+Current OpenSSL ASN1 problems
+=============================
+
+OK why does the OpenSSL ASN1 code need revising in the first place? Well
+there are lots of reasons some of which are included below...
+
+1. The code is difficult to read and write. For every single ASN1 structure
+(e.g. SEQUENCE) four functions need to be written for new, free, encode and
+decode operations. This is a very painful and error prone operation. Very few
+people have ever written any OpenSSL ASN1 and those that have usually wish
+they hadn't.
+
+2. Partly because of 1. the code is bloated and takes up a disproportionate
+amount of space. The SEQUENCE encoder is particularly bad: it essentially
+contains two copies of the same operation, one to compute the SEQUENCE length
+and the other two encode it.
+
+3. The code is memory based: that is it expects to be able to read the whole
+structure from memory. This is fine for small structures but if you have a
+(say) 1Gb PKCS#7 signedData structure it isn't such a good idea...
+
+4. The code for the ASN1 IMPLICIT tag is evil. It is handled by temporarily
+changing the tag to the expected one, attempting to read it, then changing it
+back again. This means that decode buffers have to be writable even though they
+are ultimately unchanged. This gets in the way of constification.
+
+5. The handling of EXPLICIT isn't much better. It adds a chunk of code into 
+the decoder and encoder for every EXPLICIT tag.
+
+6. APPLICATION and PRIVATE tags aren't even supported at all.
+
+7. Even IMPLICIT isn't complete: there is no support for implicitly tagged
+types that are not OPTIONAL.
+
+8. Much of the code assumes that a tag will fit in a single octet. This is
+only true if the tag is 30 or less (mercifully tags over 30 are rare).
+
+9. The ASN1 CHOICE type has to be largely handled manually, there aren't any
+macros that properly support it.
+
+10. Encoders have no concept of OPTIONAL and have no error checking. If the
+passed structure contains a NULL in a mandatory field it will not be encoded,
+resulting in an invalid structure.
+
+11. It is tricky to add ASN1 encoders and decoders to external applications.
+
+Template model
+==============
+
+One of the major problems with revision is the sheer volume of the ASN1 code.
+Attempts to change (for example) the IMPLICIT behaviour would result in a
+modification of *every* single decode function. 
+
+I decided to adopt a template based approach. I'm using the term 'template'
+in a manner similar to SNACC templates: it has nothing to do with C++
+templates.
+
+A template is a description of an ASN1 modules as several constant C structures.
+It describes in a machine readable way exactly how the ASN1 structure should
+behave. If this template contains enough detail then it is possible to write
+versions of new, free, encode, decode (and possibly others operations) that
+operate on templates.
+
+Instead of having to write code to handle each operation only a single
+template needs to be written. If new operations are needed (such as a 'print'
+operation) only a single new template based function needs to be written 
+which will then automatically handle all existing templates.
+
+Plans for revision
+==================
+
+The revision will consist of the following steps. Other than the first two
+these can be handled in any order.
+ 
+o Design and write template new, free, encode and decode operations, initially
+memory based.
+
+o Convert existing ASN1 code to template form.
+
+o Convert an existing ASN1 compiler (probably SNACC) to output templates
+in OpenSSL form.
+
+o Add support for BIO based ASN1 encoders and decoders to handle large
+structures, initially blocking I/O.
+
+o Add support for non blocking I/O: this is quite a bit harder than blocking
+I/O.
+
+o Add new ASN1 structures, such as OCSP, CRMF, S/MIME v3 (CMS), attribute
+certificates etc etc.
+