asn1.rst (13313B)
1 .. _mozilla_projects_nss_nss_tech_notes_nss_tech_note1: 2 3 Legacy ASN.1 and DER Decoders 4 ============================= 5 6 .. container:: 7 8 NSS 3.6 contains several decoders for ASN.1 and DER.Two of them are extensively used and are part 9 of the public NSS API : 10 11 #. The "classic" ASN.1 decoder, written by Lisa Repka . This was written to be a generic decoder, 12 that includes both DER (Distinguished Encoding Rules) and BER (Basic Encoding Rules).† It 13 handles both streaming and non-streaming input. 14 #. The "QuickDER" decoder, written by Julien Pierre for NSS 3.6 . This decoder was written when 15 performance issues were discovered with the classic decoder. It can only decode DER .† It does 16 not handle streaming input, and requires that all input be present before beginning to decode. 17 18 Despite their differences, the two decoders have a lot in common. QuickDER was written to be as 19 compatible as possible with the classic decoder, in order to ease migration to it in areas of 20 critical performance bottlenecks. For this reason, I will first describe all the common 21 functionality of the two decoders, before outlining their differences. 22 The main non-streaming APIs for these two decoders have an identical prototype : 23 24 - SECStatus SEC_ASN1DecodeItem(PRArenaPool \*pool, void \*dest, const SEC_ASN1Template \*t, 25 SECItem \*item); 26 - SECStatus SEC_QuickDERDecodeItem(PRArenaPool\* arena, void\* dest, const SEC_ASN1Template\* 27 templateEntry, SECItem\* src); 28 29 Here is a description of the arguments : 30 31 - *SECItem\* src*\ † is a structure containing a pointer to the binary data to be decoded, as 32 well as its size. 33 - *const SEC_ASN1Template\* templateEntry* is a pointer to one or more `decoder 34 templates <#templates>`__. The number of required templates is determined by the type of the 35 first template.When multiple templates are required, the pointer must point to a 36 NULL-terminated array of templates. The syntax of these templates is identical for both 37 decoders, except where noted. A "NULL Template" is a template that is all zeros, having a zero 38 kind.† The term "NULL-terminated array", as used throughout this document, means an array of 39 templates, the last of which is a NULL template. 40 - *void\* dest* is a pointer to the target area. This is where the decoder stores its output. 41 The type is undefined as it is completely dependent on the content of the decoder templates.† 42 This typically points to a struct that is described (or partially described) by the templates. 43 - *PRArenaPool\* arena* is a pointer to an NSPR arena pool. This is the arena pool from which 44 the decoder will allocate memory as needed. 45 46 Decoder templates : 47 The SEC_ASN1Template structure tells the decoder what to do with the input data. This structure 48 contains four fields : 49 50 - *kind* . This 32-bit field tells the decoder what to do with a particular component within the 51 input data. It is made of two parts : the lower byte, which can contain `ASN.1 52 tags <#asn.1_tags>`__, and the upper 3 bytes, which can contain `decoder 53 modifiers <#decoder_modifiers>`__. If only an ASN.1 tag is specified without a modifier, then 54 the decoder will enforce the presence of a component of that type, and fail if it does not 55 match. If kind is an ASN.1 SEQUENCE tag (SEC_ASN1_SEQUENCE), then you must specify additional 56 templates in a NULL-terminated array to define the content of the of the ASN.1 SEQUENCE. If 57 kind is the SEC_ASN1_CHOICE modifier, you must also specify additional templates in a NULL 58 terminated array to list the various possible types that this component can have. In all other 59 cases, only the first template structure passed to the decoder will be considered, even if 60 additonal templates are passed in an array. When only one template is needed, you do not need 61 a NULL template to terminate the array. 62 - *offset*\ † . This field does not apply to all template types. It is only needed if the 63 template instructs the decoder to save some data, such as for primitive component types, or 64 for some modifiers where noted.When needed, it tells the decoder where in the target data to 65 save the current component. It is normally relative to the dest argument passed to the 66 decoder. If templates are nested, the offset applies to the location of the current component 67 within the target component, typically the decoded SEQUENCE. 68 - *sub*\ † . This field does not apply to all template types. If kind contains the 69 SEC_ASN1_INLINE or SEC_ASN1_POINTER modifiers, then it must point to the required subtemplate. 70 If kind contains the SEC_ASN1_XTRN or SEC_ASN1_DYNAMIC modifiers, this is a pointer to a 71 callback function that will dynamically return the required subtemplate. 72 - *size*\ † . This field does not apply to all template types. It is only required for 73 dynamically allocating memory for the structure if the template is being included from an 74 ASN.1 SEQUENCE or SEQUENCE OF, or if dynamic allocation was requested from the parent template 75 using the SEC_ASN1_POINTER modifier 76 77 Here is a description of the various tags and modifiers that apply to the kind field. 78 *ASN.1 tags* 79 80 | ASN.1 tags are specified in the lower byte of the kind field of the template, as noted above. 81 | The following is not an attempt to explain ASN.1 tags or their purposes. Rather, the goal here 82 is to explain what type of tags the decoder supports and which macros should be used when 83 defining tags in decoder templates. It should be noted that we only support an older 84 specification of ASN.1; multibyte tags are not currently supported. 85 86 The 8-bit ASN.1 tags that we support are made of three parts : 87 88 #. The ASN.1 component class type. It is specified in the upper 2 tag bits (number 6 and 7). 89 There are four classes of ASN.1 tags : universal, application-specific, context-specific, and 90 private. You can specify the class of the tag using the macros SEC_ASN1_UNIVERSAL, 91 SEC_ASN1_APPLICATION, SEC_ASN1_CONTEXT_SPECIFIC and SEC_ASN1_PRIVATE. Universal is the default 92 tag class and does not have to be specified, as the value of the class type is zero. 93 94 #. The method type : whether the component type is constructed or primitive. This information is 95 stored in the next lowest tag bit (number 5). You can use the macro SEC_ASN1_CONSTRUCTED for a 96 constructed component type. A SEC_ASN1_PRIMITIVE macro is also provided, but does not need to 97 be included as it is zero. 98 99 #. | The tag number. It is stored in the lower 5 tag bits (number 0 through 4). The ASN.1 100 standard only defines tag numbers in the universal class. If you are using a tag of a 101 different classes, you can define your own tag number macros or specify the tag value within 102 the template definition. The following macros are provided for tag numbers within the 103 universal class : 104 | SEC_ASN1_BOOLEAN, SEC_ASN1_INTEGER, SEC_ASN1_BIT_STRING, SEC_ASN1_OCTET_STRING, 105 SEC_ASN1_NULL, SEC_ASN1_OBJECT_ID, SEC_ASN1_OBJECT_DESCRIPTOR,† SEC_ASN1_REAL, 106 SEC_ASN1_ENUMERATED, SEC_ASN1_EMBEDDED_PDV, SEC_ASN1_UTF8_STRING, SEC_ASN1_SEQUENCE, 107 SEC_ASN1_SET, SEC_ASN1_NUMERIC_STRING, SEC_ASN1_PRINTABLE_STRING, SEC_ASN1_T61_STRING, 108 SEC_ASN1_TELETEX_STRING, SEC_ASN1_T61_STRING, SEC_ASN1_VIDEOTEX_STRING, SEC_ASN1_IA5_STRING, 109 SEC_ASN1_UTC_TIME, SEC_ASN1_GENERALIZED_TIME, SEC_ASN1_GRAPHIC_STRING, 110 SEC_ASN1_VISIBLE_STRING, SEC_ASN1_GENERAL_STRING, SEC_ASN1_UNIVERSAL_STRING, 111 SEC_ASN1_BMP_STRING 112 113 Note that for SEC_ASN1_SET and SEC_ASN1_SEQUENCE types, you must also include the method type 114 macro SEC_ASN1_CONSTRUCTED to construct a fully valid tag, as defined by the ASN.1 standard . 115 116 *Decoder modifiers :* 117 These modifiers are also specified in the kind field of the template structure. All the values 118 are in the 9 - 31 bit range. 119 120 - *SEC_ASN1_OPTIONAL*: tells the decoder that this component is optional. If the component in 121 the input data does not match this template, the decoder will continue processing the input 122 data using the next available template. 123 - *SEC_ASN1_EXPLICIT*: tells the decoder that explicit tagging is being used. This is always a 124 constructed type. It requires a subtemplate defining the types of the data within. 125 - *SEC_ASN1_ANY*: allows the decoder to match this template with any component type, regardless 126 of the tag in the input data. If used in conjunction with SEC_ASN1_OPTIONAL as part of a 127 sequence, this must be the last template in the template array. 128 - *SEC_ASN1_INLINE*: recurse into the specified subtemplate to continue processing. This is 129 typically used for SEC_ASN1_SEQUENCE or SEC_ASN1_CHOICE definitions, which always need to be 130 the first template in a template array of their own. 131 - *SEC_ASN1_POINTER*: similar to SEC_ASN1_INLINE, except that the memory in the target will be 132 allocated dynamically and a pointer to the dynamically allocated memory will be stored in the 133 *dest* struct at the *offset*. This requires that the subtemplate contains a non-zero size 134 field. 135 - *SEC_ASN1_GROUP*: can only be used in conjunction with a SEC_ASN1_SET or SEC_ASN1_SEQUENCE. It 136 tells the decoder that the component is an ASN.1 SET OF or SEQUENCE OF respectively. You can 137 also use the macros SEC_ASN1_SET_OF and SEC_ASN1_SEQUENCE_OF which define both the tag number 138 and this modifier (but still need the method type, this may be a bug). 139 - *SEC_ASN1_DYNAMIC* or *SEC_ASN1_XTRN* : specifies that the component format is defined in a 140 dynamic subtemplate. There is no difference between the two macros. The sub field of the 141 template points to a callback function of type SEC_ASN1TemplateChooser that returns the 142 subtemplate depending on the component data. 143 - *SEC_ASN1_SKIP*: specifies that the decoder should skip decoding of the component. 144 SEC_ASN1DecodeItem can only skip required components and will assert if you try to skip an 145 OPTIONAL component. SEC_QuickDERDecodeItem supports skipping the decoding of OPTIONAL 146 components if you define the tag of the component in the template 147 - *SEC_ASN1_INNER*: recurse into the component and saves its content, without the surrounding 148 ASN.1 tag and length 149 - *SEC_ASN1_SAVE*: saves the component data, but does not proceed to the next component if 150 within a SEQUENCE template array. This means the next template will reprocess the same 151 component. 152 - *SEC_ASN1_SKIP_REST*: abort the decoding. This is used in a template array within a SEQUENCE, 153 if you don't care about the fields at the end of it. SEC_ASN1DecodeItem only supports this 154 modifier in the top-level template. SEC_QuickDERDecodeItem allows it at any nested sublevel. 155 - *SEC_ASN1_CHOICE*: allows decoding of components that are of variable type. This must be the 156 first template in a NULL-terminated array. The offset parameter specifies where to store the 157 type identifier in the target data . Subsequent templates specify a custom identifier for each 158 possible component type in the size parameter . 159 - *SEC_ASN1_DEBUG_BREAK*: makes the decoder assert when processing the template. This option is 160 only supported with SEC_QuickDERDecodeItem . It is useful to debug your templates or when 161 writing new templates if they don't work. 162 163 | 164 | *Differences between SEC_ASN1DecodeItem and SEC_QuickDERDecodeItem* 165 166 #. The arena argument is required to be non-NULL for SEC_QuickDERDecodeItem . With 167 SEC_ASN1DecodeItem, it can be NULL, and if so, the decoder will allocate from the heap using 168 PR_Malloc . However, this usage is strongly discouraged and we recommend that you always use 169 an arena pool even with SEC_ASN1DecodeItem. See `bug 170 175163 <http://bugzilla.mozilla.org/show_bug.cgi?id=175163>`__ for more information about the 171 reason for this recommendation. 172 #. SEC_ASN1DecodeItem will make a copy of the input data into the decoded target as needed, while 173 SEC_QuickDERDecodeItem will generate output with pointers into the input. This means that if 174 you use SEC_QuickDERDecodeItem, you must always be careful not to free the input as long as 175 you intend to use the decoded structure. Ideally, you should allocate the input data out of 176 the same arena that you are passing to the decoder. This will allow you to free both the input 177 data and the decoded data at once when freeing the arena. 178 #. SEC_ASN1DecodeItem can decode both BER and DER data, while SEC_QuickDERDecodeItem can only 179 decode DER data. 180 #. SEC_QuickDERDecodeItem does not support streaming data. This feature will most likely never be 181 added, as this decoder gets most of its extra speed from not making a copy of the input data, 182 which would be required when streaming. 183 #. SEC_QuickDERDecodeItem supports SEC_ASN1_OPTIONAL together with SEC_ASN1_SKIP 184 #. SEC_ASN1_DEBUG_BREAK is not supported by SEC_ASN1DecodeItem