cryptlib  3.4.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Macros
certattr.h
Go to the documentation of this file.
1 /****************************************************************************
2 * *
3 * Certificate Attribute Routines Header File *
4 * Copyright Peter Gutmann 1997-2008 *
5 * *
6 ****************************************************************************/
7 
8 #ifndef _CERTATTR_DEFINED
9 
10 #define _CERTATTR_DEFINED
11 
12 /****************************************************************************
13 * *
14 * Type Information Flags *
15 * *
16 ****************************************************************************/
17 
18 /* The attribute type information. This is used to both check the validity
19  of encoded attribute data and to describe the structure of an attribute
20  when encoding it.
21 
22  The flags are broken down into the following groups:
23 
24  Attribute-specific flags that apply to an individual field or an
25  overall attribute.
26 
27  SET/SEQUENCE control flags that indicate the end of a SET/SEQUENCE or
28  nested SET/SEQUENCE. These are only used for encoding, for decoding the
29  decoder maintains a parse state stack driven by the encoded data
30  (actually that's not quite correct, when skipping to the end of some
31  SEQUENCEs containing type-and-value pairs we also use the flags to locate
32  the end of the SEQUENCE encoding/start of the next type-and-value entry).
33  The use of SEQEND gets extremely complicated in the presence of optional
34  nested SEQUENCEs because it's not certain how many levels we need to
35  undo. Consider for example name constraints:
36 
37  SEQUENCE {
38  permittedSubtrees [ 0 ] SEQUENCE OF {
39  SEQUENCE { GeneralName }
40  } OPTIONAL,
41  excludedSubtrees [ 1 ] SEQUENCE OF {
42  SEQUENCE { GeneralName }
43  } OPTIONAL,
44  }
45 
46  Is the value at the end FL_SEQEND or FL_SEQEND_3? If excludedSubtrees
47  are absent then it's FL_SEQEND but if we're encoding the excluded
48  subtree then it's FL_SEQEND_3. Because of this ambiguity the current
49  encoding routines simply assume that once they reach the end of an
50  extension there's an implicit FL_SEQEND_whatever there. Luckily all of
51  the ambiguous decoding-level points occur at the end of extensions so
52  this is a workable way to handle things.
53 
54  Decoding level flags that indicate the compliance level at which this
55  attribute is decoded.
56 
57  The object subtypes for which an attribute is valid. CRLs actually
58  contain two sets of extensions, one for the entire CRL (crlExtensions)
59  and the other for each entry in the CRL (crlEntryExtension). Sorting
60  out whether we're adding a CRL extension or per-entry extension is
61  handled by the higher-level code which references the CRL attribute list
62  or per-entry attribute list as appropriate.
63 
64  The total-attribute flags are:
65 
66  FL_ATTR_ATTRSTART/FL_ATTR_ATTREND: Marks the start and end of an
67  attribute. This has to be done explicitly because there's no other
68  field or flag that we can guarantee will always be set for the first
69  or last field in an attribute and never for any other field.
70 
71  FL_ATTR_NOCOPY: The attribute is regarded as sensitive and therefore
72  shouldn't be copied from source to destination (e.g. from a
73  certificate request into a certificate) when the other attributes
74  are copied.
75 
76  FL_ATTR_CRITICAL: The overall extension is marked critical when encoding.
77 
78  The attribute field flags are:
79 
80  FL_DEFAULT: The field has a default value that's set if no field data
81  is present.
82 
83  FL_EXPLICIT: The field is explicitly tagged so instead of being en/
84  decoded using the tag for the field it's given a second level of
85  tagging that encapsulates the field's actual tag type.
86 
87  FL_IDENTIFIER: Used to mark the encapsulating SEQUENCE in fields of the
88  type:
89 
90  SEQUENCE {
91  identifier OBJECT IDENTIFIER
92  data ANY DEFINED BY identifier
93  }
94 
95  for which the field identified by a CRYPT_CERTINFO_xxx is the 'data'
96  field and the whole is only encoded if the data field is present.
97 
98  FL_MULTIVALUED: If a cryptlib-level attribute is part of a SET OF x/
99  SEQUENCE OF x then this flag is set to indicate that more than one
100  instance can exist at the same time. If this flag isn't set then
101  cryptlib will detect that an attribute of that type already exists
102  and refuse to allow a second instance to be added.
103 
104  FL_EMPTYOK: Used for a SET/SEQUENCE consisting of nothing but OPTIONAL
105  elements to indicate that it's OK to end up with a zero-length
106  entry, by default we don't allow an empty SET/SEQUENCE since if the
107  data didn't match any of the optional elements then the decoder
108  would get stuck in an endless loop. At the moment this is OK
109  because the only time we can have an empty SEQUENCE is for the
110  basicConstraints extension, which is an entire extension for which
111  the termination point is easily detected.
112 
113  FL_NONENCODING: The field is read and written but not associated with
114  any user data. This is used for fields such as version numbers that
115  aren't used for encoding user-supplied data but that must be read and
116  written when processing an attribute
117 
118  FL_OPTIONAL: The field is optional.
119 
120  FL_SETOF: Applied to the encapsulating SET/SEQUENCE of a SET OF x/
121  SEQUENCE OF x to indicate that one or more inner fields may be
122  present. The field marked with FL_SETOF in the encoding/decoding
123  table is bookmarked, if all of the SET/SEQUENCE data isn't read the
124  first time through then the decoding table position is restarted
125  from the bookmark until the SET/SEQUENCE data is exhausted */
126 
127 /* Type information and whole-attribute flags */
128 
129 #define FL_VALID_CERT 0x0001 /* Valid in a certificate */
130 #define FL_VALID_ATTRCERT 0x0002 /* Valid in an attribute cert */
131 #define FL_VALID_CRL 0x0004 /* Valid in a CRL */
132 #define FL_VALID_CERTREQ 0x0008 /* Valid in a cert.request */
133 #define FL_VALID_REVREQ 0x0010 /* Valid in a rev.request */
134 #define FL_VALID_OCSPREQ 0x0010 /* Valid in an OCSP request */
135 #define FL_VALID_OCSPRESP 0x0010 /* Valid in an OCSP response */
136 
137 #define FL_LEVEL_OBLIVIOUS 0x0000 /* Process at oblivious compliance level */
138 #define FL_LEVEL_REDUCED 0x0100 /* Process at reduced compliance level */
139 #define FL_LEVEL_STANDARD 0x0200 /* Process at standard compliance level */
140 #define FL_LEVEL_PKIX_PARTIAL 0x0300 /* Process at partial PKIX compliance level */
141 #define FL_LEVEL_PKIX_FULL 0x0400 /* Process at full PKIX compliance level */
142 
143 #define FL_ATTR_NOCOPY 0x1000 /* Attr.isn't copied when attrs.copied */
144 #define FL_ATTR_CRITICAL 0x2000 /* Extension is marked critical */
145 #define FL_ATTR_ATTRSTART 0x4000 /* Start-of-attribute marker */
146 #define FL_ATTR_ATTREND 0x8000 /* End-of-attribute marker */
147 
148 #define FL_VALID_MASK 0x1F /* Mask for type-validity value */
149 #define FL_LEVEL_SHIFT 8 /* Shift amount to get into range 0...n */
150 #define FL_LEVEL_MASK 7 /* Mask for compliance level value */
151 
152 /* Encoding flags */
153 
154 #define FL_SEQEND 0x0001 /* End of constructed object */
155 #define FL_SEQEND_2 0x0002 /* End of cons.obj + one nesting lvl.*/
156 #define FL_SEQEND_3 0x0003 /* End of cons.obj + two nesting lvls.*/
157 #define FL_SEQEND_4 0x0004 /* End of cons.obj + three nesting lvls.*/
158 #define FL_SEQEND_5 0x0005 /* End of cons.obj + four nesting lvls.*/
159 #define FL_SEQEND_6 0x0006 /* End of cons.obj + four nesting lvls.*/
160 #define FL_SEQEND_7 0x0007 /* End of cons.obj + four nesting lvls.*/
161 
162 #define FL_SEQEND_MASK 7 /* Mask for sequence control value */
163 
164 #define FL_OPTIONAL 0x0010 /* Field is optional */
165 #define FL_DEFAULT 0x0020 /* Field has default value */
166 #define FL_EXPLICIT 0x0040 /* Field is explicitly tagged */
167 #define FL_IDENTIFIER 0x0080 /* Following field contains selection OID */
168 #define FL_SETOF 0x0100 /* Start of SET/SEQ OF values */
169 #define FL_EMPTYOK 0x0200 /* SET/SEQ may be empty */
170 #define FL_NONENCODING 0x0400 /* Field is a non-encoding value */
171 #define FL_MULTIVALUED 0x0800 /* Field can occur multiple times */
172 
173 /* If a constructed field is nested (for example a SEQUENCE OF SEQUENCE)
174  then the FL_SEQEND may need to denote multiple levels of unnesting. This
175  is done by using FL_SEQEND_n, the following macro can be used to extract
176  the actual level of nesting */
177 
178 #define decodeNestingLevel( value ) ( ( value ) & FL_SEQEND_MASK )
179 
180 /* In order to be able to process broken certificates we allow for
181  processing them at various levels of standards compliance. If the
182  current processing level is below that required for the extension then
183  we skip it and treat it as a blob extension */
184 
185 #define decodeComplianceLevel( value ) \
186  ( ( ( value ) >> FL_LEVEL_SHIFT ) & FL_LEVEL_MASK )
187 
188 /* Determine whether an attribute information entry represents the start of
189  the attribute */
190 
191 #define isAttributeStart( attributeInfoPtr ) \
192  ( ( attributeInfoPtr )->typeInfoFlags & FL_ATTR_ATTRSTART )
193 
194 /****************************************************************************
195 * *
196 * Special-case Field Values *
197 * *
198 ****************************************************************************/
199 
200 /* Some fields have an intrinsic value but no explicitly set value (that is,
201  their mere presence communicates the information they are intended to
202  convey but the fields themselves contain no actual data). This applies
203  for fields that contain OIDs that denote certain things such as
204  certificate policies or key usage. To denote these identifier fields
205  the field type is set to FIELDTYPE_IDENTIFIER (note that we start the
206  values at -2 rather than -1, which is the CRYPT_ERROR value). When a
207  field of this type is encountered no data value is recorded but the OID
208  for the field is written to the certificate when the field is encoded.
209  The parentheses are to catch potential erroneous use in an expression */
210 
211 #define FIELDTYPE_IDENTIFIER ( -2 )
212 
213 /* Some fields have no set value (these arise from ANY DEFINED BY
214  definitions) or an opaque value (typically fixed parameters for type-and-
215  value pairs). To denote these fields the field type is set to
216  FIELDTYPE_BLOB. However this causes problems with type-checking since
217  now absolutely anything can be passed in as valid data. To allow at
218  least some type-checking we provide a hint as to the general encoding of
219  the blob, which can be one of SEQUENCE, BIT STRING, or a genuine blob
220  used in ANY DEFINED BY constructions, for which we can at least check
221  that it's some sort of ASN.1 object. There are also two cases in which
222  an ANY blob is used where it'd be possible to use more specific blobs
223  for OBJECT IDENTIFIERs and GeneralNames and that's in { OID, value }
224  selection lists in which the ANY blob acts spefically as an end-of-
225  list marker as well as being just a catchall type */
226 
227 #define FIELDTYPE_BLOB_ANY ( -3 )
228 #define FIELDTYPE_BLOB_BITSTRING ( -4 )
229 #define FIELDTYPE_BLOB_SEQUENCE ( -5 )
230 
231 /* When a field contains a CHOICE it can contain any one of the CHOICE
232  fields, as opposed to a FL_SETOF which can contain any of the fields that
233  follow it. Currently the only CHOICE fields contain OIDs as choices, the
234  CHOICE fieldtype indicates that the value is stored in the field itself
235  but the encoding is handled via a separate encoding table pointed to by
236  extraData that maps the value to an OID */
237 
238 #define FIELDTYPE_CHOICE ( -6 )
239 
240 /* Some fields are composite fields that contain complete certificate data
241  structures. To denote these fields the field type is a special code that
242  specifies the type and the value member contains the handle or the data
243  member contains a pointer to the composite object */
244 
245 #define FIELDTYPE_DN ( -7 )
246 
247 /* As an extension of the above, some fields are complex enough to require
248  complete alternative encoding tables. The most obvious one is
249  GeneralName but this is also used for some CHOICE types where the value
250  selects a particular OID or entry from an alternative encoding table. In
251  this case the extraData member is a pointer to the alternative encoding
252  table */
253 
254 #define FIELDTYPE_SUBTYPED ( -8 )
255 
256 /* Another variant of FIELDTYPE_DN is one where the field can contain one of
257  a number of string types chosen from the ASN.1 string menagerie. The two
258  main classes that seem to be popular in standards are the DirectoryString,
259  { BMPString | PrintableString | TeletexString | UniversalString |
260  UTF8String } and DisplayText, { BMPString | IA5String | UTF8String |
261  VisibleString }. Rather than adding a list of the different string
262  types all marked as optional to the en/decoding tables (so that the
263  decoder stops whenever it reaches the one that matches the string value
264  being decoded) we provide a single TextString meta-type which has a
265  custom decoding routine that makes the appropriate choice between the
266  union of all of the above types */
267 
268 #define FIELDTYPE_TEXTSTRING ( -9 )
269 
270 /* Usually the field ID for the first field in an entry (the one containing
271  the OID) is the overall attribute ID, however there are one or two
272  exceptions in which the attribute ID and field ID are the same but are
273  given in separate fields (examples of this are the altNames, which have
274  a single field ID SUBJECT/ISSUERALTNAME that applies to the attribute as
275  a whole but also to the one and only field in it.
276 
277  If this happens the field ID for the attribute as a whole is given the
278  value FIELDID_FOLLOWS to indicate that the actual ID is present at a
279  later point, with the first field that isn't a FIELDID_FOLLOWS code being
280  treated as the attribute ID */
281 
282 #define FIELDID_FOLLOWS ( -10 )
283 
284 /* Since there are multiple blob fields (due to the use of typing hints) we
285  need a macro to determine whether a field is a blob of any form. The
286  odd-looking range comparison below is because the fields have negative
287  values */
288 
289 #define isBlobField( field ) \
290  ( ( field ) <= FIELDTYPE_BLOB_ANY && \
291  ( field ) >= FIELDTYPE_BLOB_SEQUENCE )
292 
293 /****************************************************************************
294 * *
295 * Attribute Data Structures *
296 * *
297 ****************************************************************************/
298 
299 /* The structure to store en/decoding information for an attribute field */
300 
301 typedef struct {
302  /* Information on the overall attribute. These fields are only set
303  for overall attribute definitions */
304  const BYTE FAR_BSS *oid; /* OID for this attribute */
305 
306  /* Information on this particular field in the attribute. The fieldType
307  is the field as defined (e.g. SEQUENCE, INTEGER), the
308  fieldEncodingType is the field as encoded: 0 if it's the same as the
309  field type or the tag if it's a tagged field. The default tagging
310  is to use implicit tags (e.g. [ 0 ] IMPLICIT SEQUENCE) with a field of
311  type fieldType and encoding of type fieldEncodedType. If FL_EXPLICIT
312  is set it's an explicitly tagged field and both fields are used for
313  the encoding */
314  const CRYPT_ATTRIBUTE_TYPE fieldID; /* Magic ID for this field */
315 #ifndef NDEBUG
316  const char *description; /* Text description */
317 #endif /* NDEBUG */
318  const int fieldType; /* ASN.1 tag/type for this field */
319  const int fieldEncodedType; /* ASN.1 tag for field as encoded */
320 
321  /* General status information */
322  const int typeInfoFlags; /* Attribute-processing */
323  const int encodingFlags; /* Encoding flags */
324 
325  /* Information to allow validity checking for this field */
326  const int lowRange; /* Min/max allowed if numeric/boolean */
327  const int highRange; /* Min/max length if string */
328  const int defaultValue; /* Default value if FL_DEFAULT set,
329  length if FIELDTYPE_BLOB */
330 
331  /* Extra data needed to process this field, either a pointer to an
332  alternative encoding table or a pointer to the validation function to
333  allow extended validity checking */
334  const void *extraData;
335  } ATTRIBUTE_INFO;
336 
337 /* When building the debug version of the code we include a text string
338  describing the field which is being processed, this makes it easier to
339  track down the point in a certificate where cryptlib finds a problem */
340 
341 #ifndef NDEBUG
342  #define DESCRIPTION( text ) text,
343 #else
344  #define DESCRIPTION( text )
345 #endif /* NDEBUG */
346 
347 /* Attribute information flags. These are:
348 
349  FLAG_BLOB: Disables all type-checking on the field, needed to handle
350  some certificates that have invalid field encodings.
351 
352  FLAG_BLOB_PAYLOAD: Disables type checking on the field payload, for
353  example checking that the chars in the string are valid for the
354  given ASN.1 string type.
355 
356  FLAG_CRITICAL: The extension containing the field is marked criticial.
357 
358  FLAG_DEFAULTVALUE: The field has a value which is equal to the default
359  for this field, so it doesn't get encoded. This flag is set
360  during the encoding pre-processing pass.
361 
362  FLAG_IGNORED: The field is recognised but was ignored at this compliance
363  level. This prevents the certificate from being rejected if the
364  field is marked critical.
365 
366  FLAG_LOCKED: The attribute can't be deleted once set, needed to handle
367  fields that are added internally by cryptlib that shouldn't be
368  deleted by users once set.
369 
370  FLAG_MULTIVALUED: Multiple instantiations of this field are allowed */
371 
372 #define ATTR_FLAG_NONE 0x0000 /* No flag */
373 #define ATTR_FLAG_CRITICAL 0x0001 /* Critical cert extension */
374 #define ATTR_FLAG_LOCKED 0x0002 /* Field can't be modified */
375 #define ATTR_FLAG_BLOB 0x0004 /* Non-type-checked blob data */
376 #define ATTR_FLAG_BLOB_PAYLOAD 0x0008 /* Payload is non-type-checked blob data */
377 #define ATTR_FLAG_MULTIVALUED 0x0010 /* Multiple instances allowed */
378 #define ATTR_FLAG_DEFAULTVALUE 0x0020 /* Field has default value */
379 #define ATTR_FLAG_IGNORED 0x0040 /* Attribute ignored at this compl.level */
380 #define ATTR_FLAG_MAX 0x007F /* Maximum possible flag value */
381 
382 /* When comparing attribute fields we only want to compare relevant data and
383  not incidental flags related to parsing or encoding actions. The following
384  mask defines the attribute flags that we want to compare */
385 
386 #define ATTR_FLAGS_COMPARE_MASK ( ATTR_FLAG_CRITICAL )
387 
388 /* The structure to hold a field of a certificate attribute */
389 
390 typedef struct AL {
391  /* Identification and encoding information for this attribute field or
392  attribute. This consists of the field ID for the attribute as a
393  whole (e.g. CRYPT_CERTINFO_NAMECONSTRAINTS), for the attribute field
394  (that is, one field of a full attribute, e.g.
395  CRYPT_CERTINFO_EXCLUDEDSUBTREES) and for the subfield of the attribute
396  field in the case of composite fields like GeneralNames, a pointer to
397  the sync point used when encoding the attribute, and the encoded size
398  of this field. If it's a special-case attribute field such as a blob
399  field or a field with a fixed default value that's present only for
400  encoding purposes then the attributeID and fieldID are set to special
401  values decoded by the isXXX() macros further down. The subFieldID is
402  only set if the fieldID is for a GeneralName field.
403 
404  Although the field type information is contained in the
405  attributeInfoPtr it's sometimes needed before this has been set up
406  to handle special formatting requirements, for example to enable
407  special-case handling for a DN attribute field or to specify that an
408  OID needs to be decoded into its string representation before being
409  returned to the caller. Because of this we store a copy of the field
410  type information here to allow for this special processing */
412  CRYPT_ATTRIBUTE_TYPE fieldID; /* Attribute field ID */
413  CRYPT_ATTRIBUTE_TYPE subFieldID; /* Attribute subfield ID */
414  const ATTRIBUTE_INFO *attributeInfoPtr; /* Pointer to encoding sync point */
415  int encodedSize; /* Encoded size of this field */
416  int fieldType; /* Attribute field type */
417  int flags; /* Flags for this field */
418 
419  /* Sometimes a field is part of a constructed object or even a nested
420  series of constructed objects (these are always SEQUENCEs). Since
421  this is purely an encoding issue there are no attribute list entries
422  for the SEQUENCE fields so when we perform the first pass over the
423  attribute list prior to encoding we remember the lengths of the
424  SEQUENCEs for later use. Since we can have nested SEQUENCEs
425  containing a given field we store the lengths and pointers to the
426  ATTRIBUTE_INFO table entries used to encode them in a fifo with the
427  innermost one first and successive outer ones following it */
429  int sizeFifo[ ENCODING_FIFO_SIZE + 2 ];
430  /* Encoded size of SEQUENCE containing
431  this field, if present */
433  const ATTRIBUTE_INFO *encodingFifo[ ENCODING_FIFO_SIZE + 2 ];
434  /* Encoding table entry used to encode
435  this SEQUENCE */
436  int fifoEnd; /* End of list of SEQUENCE sizes */
437  int fifoPos; /* Current position in list */
438 
439  /* The data payload for this attribute field or attribute. If it's
440  numeric data such as a simple boolean, bitstring, or small integer,
441  we store it in the intValue member. If it's an OID or some form of
442  string we store it in the variable-length buffer */
443  long intValue; /* Integer value for simple types */
445  void *value; /* Attribute value */
446  int valueLength; /* Attribute value length */
447 
448  /* The OID, for blob-type attributes */
449  BYTE *oid; /* Attribute OID */
450 
451  /* The previous and next list element in the linked list of elements */
452  struct AL *prev, *next;
453 
454  /* Variable-length storage for the attribute data */
456  } ATTRIBUTE_LIST;
457 
458 /****************************************************************************
459 * *
460 * Attribute Functions *
461 * *
462 ****************************************************************************/
463 
464 /* The validation function used to perform additional validation on fields */
465 
467  int ( *VALIDATION_FUNCTION )( const ATTRIBUTE_LIST *attributeListPtr );
468 
469 /* Look up an ATTRIBUTE_INFO entry based on an OID */
470 
472 const ATTRIBUTE_INFO *oidToAttribute( IN_ENUM( ATTRIBUTE ) \
474  IN_BUFFER( oidLength ) const BYTE *oid,
476 
477 /* Select the appropriate attribute info table for encoding/type checking */
478 
479 CHECK_RETVAL STDC_NONNULL_ARG( ( 2, 3 ) ) \
480 int getAttributeInfo( IN_ENUM( ATTRIBUTE ) const ATTRIBUTE_TYPE attributeType,
483 
484 /* Get the encoded tag for a field */
485 
487 int getFieldEncodedTag( const ATTRIBUTE_INFO *attributeInfoPtr );
488 
489 /* Get the attribute and attributeID for a field ID */
490 
493  const ATTRIBUTE_TYPE attributeType,
494  IN_ATTRIBUTE \
500 
501 /* Find the start of an attribute from an arbitrary position in an attribute
502  list */
503 
506 
507 /* Write an attribute field */
508 
510 int writeAttributeField( INOUT_OPT STREAM *stream,
511  INOUT ATTRIBUTE_LIST *attributeListPtr,
512  IN_RANGE( 0, 4 ) const int complianceLevel );
513 
514 #endif /* _CERTATTR_DEFINED */