cryptlib  3.4.1
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Properties Macros
analyse.h
Go to the documentation of this file.
1 /****************************************************************************
2 * *
3 * cryptlib Source Analysis Header File *
4 * Copyright Peter Gutmann 1997-2010 *
5 * *
6 ****************************************************************************/
7 
8 #ifndef _ANALYSE_DEFINED
9 
10 #define _ANALYSE_DEFINED
11 
12 /* A symbolic define for the maximum possible error value when we're
13  checking ranges for status codes */
14 
15 #define MAX_ERROR CRYPT_ENVELOPE_RESOURCE
16 
17 /****************************************************************************
18 * *
19 * PREfast Analysis Support *
20 * *
21 ****************************************************************************/
22 
23 #if defined( _MSC_VER ) && defined( _PREFAST_ )
24 
25 /* Enable strict checking of PREfast annotations. This gets a bit ugly
26  because if a standard header that's included before us already
27  includes sal.h then we'll have __SPECSTRINGS_STRICT_LEVEL already
28  defined (the default is level 1, minimal warnings), so we undefine it
29  if necessary before setting it to the maximum warning level */
30 
31 #ifdef __SPECSTRINGS_STRICT_LEVEL
32  #undef __SPECSTRINGS_STRICT_LEVEL
33 #endif /* __SPECSTRINGS_STRICT_LEVEL */
34 #define __SPECSTRINGS_STRICT_LEVEL 3
35 
36 /* Include the PREfast code analysis header. Microsoft changed the notation
37  used from declspec SAL to attribute SAL some time between VC++ 2005 and
38  VC++ 2008, with all subsequent development effort going into attribute
39  SAL. The following annotations work with both declspec SAL and attribute
40  SAL, depending on which variant is in use.
41 
42  This is complicated somewhat by the fixer-upper nature of the SAL
43  material, many of the annotations aren't documented in MSDN, some are
44  only available in MS-internal versions of PREfast, and some are defined
45  to no-ops. In particular several of the more interesting annotations from
46  declspec SAL like __field_bcount, used to describe the extent of a fixed-
47  size buffer in a struct or on the stack (which were no-oped out in all
48  known MS-external versions) are no longer defined as no-ops in attribute
49  SAL, so we have to explicitly turn them into no-ops. Conversely, the
50  formerly no-oped __in_range in declspec SAL may now exist as _In_range_
51  in attribute SAL and appears to be used, or at least it's defined as
52  atributes rather than just being no-oped out */
53 
54 #include <specstrings.h>
55 
56 /* Function return value information. RETVAL_xxx annotations simply indicate
57  what the function returns, CHECK_RETVAL_xxx indicates that the caller must
58  check the return value:
59 
60  RETVAL Function returns a standard cryptlib status code.
61  RETVAL_BOOL As CHECK_RETVAL but result is a boolean value. This is
62  used for 'pure' boolean functions that simply return a
63  yes-or-no response about their input, for which there's
64  no specific failure or success code.
65  RETVAL_ENUM As CHECK_RETVAL but result is an enum following the
66  rules for IN_ENUM further down.
67  RETVAL_LENGTH As CHECK_RETVAL but result is a LENGTH following the
68  rules for IN_LENGTH further down.
69  RETVAL_PTR As CHECK_RETVAL but result is a pointer, non-null on
70  success.
71  RETVAL_RANGE As CHECK_RETVAL but result must be in the range
72  { low...high } inclusive.
73  RETVAL_SPECIAL As RETVAL but OK_SPECIAL is treated as CRYPT_OK.
74  RETVAL_STRINGOP Function returns either an error code or a string
75  position/index, used for the strXYZ() functions.
76 
77  This is additionally complicated by the fact that attribute SAL doesn't
78  allow RETVAL in typedefs and function pointers (since they're not valid
79  as attributes there) so we have to use a special-case typedef/function-
80  pointer version that's no-oped out in attribute SAL but left in in
81  declspec SAL */
82 
83 #ifdef __ATTR_SAL /* Attribute SAL */
84 
85 #define CHECK_RETVAL _Check_return_ \
86  _Success_( result == CRYPT_OK )
87 #define CHECK_RETVAL_BOOL _Check_return_ \
88  _Success_( result == TRUE )
89 #define CHECK_RETVAL_ENUM( name ) \
90  _Check_return_ \
91  _Success_( result >= name##_NONE && result < name##_LAST )
92 #define CHECK_RETVAL_LENGTH _Check_return_ \
93  _Success_( result >= 0 && result <= MAX_INTLENGTH - 1 )
94 #define CHECK_RETVAL_PTR _Check_return_ \
95  _Success_( result != NULL )
96 #define CHECK_RETVAL_RANGE( low, high ) \
97  _Check_return_ \
98  _Success_( result >= ( low ) && result <= ( high ) )
99 #define CHECK_RETVAL_SPECIAL _Check_return_ \
100  _Success_( result == CRYPT_OK || result == OK_SPECIAL )
101 #define CHECK_RETVAL_STRINGOP( length ) \
102  _Check_return_ \
103  _Success_( result >= 0 )
104 
105 #define CHECK_RETVAL_FNPTR
106 #define CHECK_RETVAL_BOOL_FNPTR
107 #define CHECK_RETVAL_LENGTH_FNPTR
108 #define CHECK_RETVAL_PTR_FNPTR
109 #define CHECK_RETVAL_SPECIAL_FNPTR
110 
111 #define RETVAL _Success_( result == CRYPT_OK )
112 #define RETVAL_BOOL _Success_( result == TRUE )
113 #define RETVAL_RANGE( low, high ) _Success_( result >= ( low ) && result <= ( high ) )
114 #define RETVAL_SPECIAL _Success_( result == CRYPT_OK || result == OK_SPECIAL )
115 
116 #define RETVAL_FNPTR
117 
118 #else /* Declspec SAL */
119 
120 #define CHECK_RETVAL __checkReturn \
121  __success( result == CRYPT_OK ) \
122  __range( MAX_ERROR, CRYPT_OK )
123 #define CHECK_RETVAL_BOOL __checkReturn \
124  __success( result == TRUE ) \
125  __range( FALSE, TRUE )
126 #define CHECK_RETVAL_ENUM( name ) \
127  __checkReturn \
128  __success( result >= name##_NONE && result < name##_LAST ) \
129  __range( name##_NONE, name##_LAST - 1 )
130 #define CHECK_RETVAL_LENGTH __checkReturn \
131  __success( result >= 0 && result <= MAX_INTLENGTH - 1 ) \
132  __range( MAX_ERROR, MAX_INTLENGTH - 1 )
133 #define CHECK_RETVAL_PTR __checkReturn \
134  __success( result != NULL )
135 #define CHECK_RETVAL_RANGE( low, high ) \
136  __checkReturn \
137  __success( result >= ( low ) && result <= ( high ) ) \
138  __range( MAX_ERROR, ( high ) )
139 #define CHECK_RETVAL_SPECIAL __checkReturn \
140  __success( result == CRYPT_OK || result == OK_SPECIAL ) \
141  __range( MAX_ERROR, CRYPT_OK )
142 #define CHECK_RETVAL_STRINGOP( length ) \
143  __checkReturn \
144  __success( result >= 0 ) \
145  __range( MAX_ERROR, length )
146 
147 #define CHECK_RETVAL_FNPTR __checkReturn \
148  __success( result == CRYPT_OK ) \
149  __range( MAX_ERROR, CRYPT_OK )
150 #define CHECK_RETVAL_BOOL_FNPTR __checkReturn \
151  __success( result == TRUE ) \
152  __range( FALSE, TRUE )
153 #define CHECK_RETVAL_LENGTH_FNPTR __checkReturn \
154  __success( result >= 0 && result <= MAX_INTLENGTH - 1 ) \
155  __range( MAX_ERROR, MAX_INTLENGTH - 1 )
156 #define CHECK_RETVAL_PTR_FNPTR __checkReturn \
157  __success( result != NULL )
158 #define CHECK_RETVAL_SPECIAL_FNPTR __checkReturn \
159  __success( result == CRYPT_OK || result == OK_SPECIAL ) \
160  __range( MAX_ERROR, CRYPT_OK )
161 
162 #define RETVAL __success( result == CRYPT_OK ) \
163  __range( MAX_ERROR, CRYPT_OK )
164 #define RETVAL_BOOL __success( result == TRUE ) \
165  __range( FALSE, TRUE )
166 #define RETVAL_RANGE( low, high ) __success( result >= ( low ) && result <= ( high ) ) \
167  __range( MAX_ERROR, ( high ) )
168 #define RETVAL_SPECIAL __success( result == CRYPT_OK || result == OK_SPECIAL ) \
169  __range( MAX_ERROR, CRYPT_OK )
170 
171 #define RETVAL_FNPTR __success( result == CRYPT_OK ) \
172  __range( MAX_ERROR, CRYPT_OK )
173 
174 #endif /* Declspec vs. Attribute SAL */
175 
176 /* When we return from an error handler, returning an error status means
177  that the function succeeded, since it's forwarding a status that it was
178  given rather than reporting its own status. In this case returning an
179  error code indicates success */
180 
181 #ifdef __ATTR_SAL /* Attribute SAL */
182 
183 #define CHECK_RETVAL_ERROR _Check_return_ \
184  _Success_( result < CRYPT_OK - 1 )
185 
186 #else /* Declspec SAL */
187 
188 #define CHECK_RETVAL_ERROR __checkReturn \
189  __success( result < CRYPT_OK - 1 ) \
190  __range( MAX_ERROR, CRYPT_OK - 1 )
191 
192 #endif /* Declspec vs. Attribute SAL */
193 
194 /* Numeric parameter checking:
195 
196  INT Value must be between 1 and MAX_INTLENGTH - 1
197  INT_SHORT As INT but upper bound is MAX_INTLENGTH_SHORT - 1 rather
198  than MAX_INTLENGTH - 1.
199 
200  In addition to these we allow the OPT specifier to indicate that the
201  value may be NULL for OUT parameters, the OPT suffix to indicate that the
202  value may be CRYPT_UNUSED, and the Z suffix to indicate that the lower
203  bound may be zero. This is used for two cases, either when the lower
204  bound is explicitly zero or when it's set on error to xyz_NONE, which
205  would normally be an invalid value for the non-_Z parameter */
206 
207 #if VC_GE_2008( _MSC_VER ) /* Attribute SAL */
208 
209 #define IN_INT _In_ _In_range_( 1, MAX_INTLENGTH - 1 )
210 #define IN_INT_OPT _In_ _In_range_( CRYPT_UNUSED, MAX_INTLENGTH - 1 )
211 #define IN_INT_Z _In_ _In_range_( 0, MAX_INTLENGTH - 1 )
212 #define IN_INT_SHORT _In_ _In_range_( 1, MAX_INTLENGTH_SHORT - 1 )
213 #define IN_INT_SHORT_Z _In_ _In_range_( 0, MAX_INTLENGTH_SHORT - 1 )
214 
215 #define OUT_INT _Out_ _Out_range_( 1, MAX_INTLENGTH - 1 )
216 #define OUT_INT_Z _Out_ _Out_range_( 0, MAX_INTLENGTH - 1 )
217 #define OUT_INT_SHORT_Z _Out_ _Out_range_( 0, MAX_INTLENGTH_SHORT - 1 )
218 #define OUT_OPT_INT_Z _Out_opt_ _Out_range_( 0, MAX_INTLENGTH - 1 )
219 
220 #else /* Declspec SAL */
221 
222 #define IN_INT __in __in_range( 1, MAX_INTLENGTH - 1 )
223 #define IN_INT_OPT __in __in_range( CRYPT_UNUSED, MAX_INTLENGTH - 1 )
224 #define IN_INT_Z __in __in_range( 0, MAX_INTLENGTH - 1 )
225 #define IN_INT_SHORT __in __in_range( 1, MAX_INTLENGTH_SHORT - 1 )
226 #define IN_INT_SHORT_Z __in __in_range( 0, MAX_INTLENGTH_SHORT - 1 )
227 
228 #define OUT_INT __out __out_range( 1, MAX_INTLENGTH - 1 )
229 #define OUT_INT_Z __out __out_range( 0, MAX_INTLENGTH - 1 )
230 #define OUT_INT_SHORT_Z __out __out_range( 0, MAX_INTLENGTH_SHORT - 1 )
231 #define OUT_OPT_INT_Z __out_opt __out_range( 0, MAX_INTLENGTH - 1 )
232 
233 #endif /* Declspec vs. Attribute SAL */
234 
235 /* Special-case parameter checking:
236 
237  ALGO Value must be a cryptlib encryption algorithm.
238  ATTRIBUTE Value must be a cryptlib attribute.
239  BOOL Value must be boolean.
240  BYTE Value must be a single-byte value.
241  CHAR Value must be a 7-bit ASCII character.
242  ERROR Value must be a cryptlib error status code.
243  HANDLE Value must be a cryptlib handle.
244  MESSAGE Value must be a cryptlib message type.
245  MODE Value must be a cryptlib encryption mode.
246  PORT Value must be a network port.
247  RANGE User-specified range check.
248  STATUS Value must be cryptlib status code
249 
250  In addition to these we allow the OPT specifier to indicate that the
251  value may be NULL for OUT parameters.
252 
253  We also allow an OPT suffix to indicate the use of don't-care values,
254  typically CRYPT_UNUSED */
255 
256 #if VC_GE_2008( _MSC_VER ) /* Attribute SAL */
257 
258 #define IN_ALGO _In_ _In_range_( CRYPT_ALGO_NONE + 1, CRYPT_ALGO_LAST - 1 )
259 #define IN_ALGO_OPT _In_ _In_range_( CRYPT_ALGO_NONE, CRYPT_ALGO_LAST - 1 )
260 #define IN_ATTRIBUTE _In_ _In_range_( CRYPT_ATTRIBUTE_NONE + 1, CRYPT_IATTRIBUTE_LAST - 1 )
261 #define IN_ATTRIBUTE_OPT _In_ _In_range_( CRYPT_ATTRIBUTE_NONE, CRYPT_IATTRIBUTE_LAST - 1 )
262 #define IN_BYTE _In_ _In_range_( 0, 0xFF )
263 #define IN_CHAR _In_ _In_range_( 0, 0x7F )
264 #define IN_ERROR _In_ _In_range_( MAX_ERROR, -1 )
265 #define IN_HANDLE _In_ _In_range_( SYSTEM_OBJECT_HANDLE, MAX_OBJECTS - 1 )
266 #define IN_HANDLE_OPT _In_ _In_range_( CRYPT_UNUSED, MAX_OBJECTS - 1 )
267 #define IN_KEYID _In_ _In_range_( CRYPT_KEYID_NONE + 1, CRYPT_KEYID_LAST - 1 )
268 #define IN_KEYID_OPT _In_ _In_range_( CRYPT_KEYID_NONE, CRYPT_KEYID_LAST - 1 )
269 #define IN_MESSAGE _In_ _In_range_( MESSAGE_NONE + 1, IMESSAGE_LAST - 1 )
270 #define IN_MODE _In_ _In_range_( CRYPT_MODE_NONE + 1, CRYPT_MODE_LAST - 1 )
271 #define IN_MODE_OPT _In_ _In_range_( CRYPT_MODE_NONE, CRYPT_MODE_LAST - 1 )
272 #define IN_PORT _In_ _In_range_( 22, 65535L )
273 #define IN_PORT_OPT _In_ _In_range_( CRYPT_UNUSED, 65535L )
274 #define IN_RANGE( min, max ) _In_ _In_range_( ( min ), ( max ) )
275 #define IN_RANGE_FIXED( value ) _In_ _In_range_( ( value ), ( value ) )
276 #define IN_STATUS _In_ _In_range_( MAX_ERROR, CRYPT_OK )
277 
278 #define INOUT_HANDLE _Inout_ \
279  _In_range_( SYSTEM_OBJECT_HANDLE, MAX_OBJECTS - 1 ) \
280  _Out_range_( SYSTEM_OBJECT_HANDLE, MAX_OBJECTS - 1 )
281 #define INOUT_RANGE( min, max ) _Inout_ \
282  _In_range_( ( min ), ( max ) ) \
283  _Out_range_( ( min ), ( max ) )
284 
285 #define OUT_ALGO_Z _Out_ _Out_range_( CRYPT_ALGO_NONE, CRYPT_ALGO_LAST - 1 )
286 #define OUT_OPT_ALGO_Z _Out_opt_ _Out_range_( CRYPT_ALGO_NONE, CRYPT_ALGO_LAST - 1 )
287 #define OUT_ATTRIBUTE_Z _Out_ _Out_range_( CRYPT_ATTRIBUTE_NONE, CRYPT_IATTRIBUTE_LAST - 1 )
288 #define OUT_OPT_ATTRIBUTE_Z _Out_opt_ _Out_range_( CRYPT_ATTRIBUTE_NONE, CRYPT_IATTRIBUTE_LAST - 1 )
289 #define OUT_BOOL _Out_ _Out_range_( FALSE, TRUE )
290 #define OUT_OPT_BOOL _Out_opt_ _Out_range_( FALSE, TRUE )
291 #define OUT_OPT_BYTE _Out_opt_ _Out_range_( 0, 0xFF )
292 #define OUT_ERROR _Out_ _Out_range_( MAX_ERROR, -1 )
293 #define OUT_HANDLE_OPT _Out_ _Out_range_( CRYPT_ERROR, MAX_OBJECTS - 1 )
294 #define OUT_OPT_HANDLE_OPT _Out_opt_ _Out_range_( SYSTEM_OBJECT_HANDLE, MAX_OBJECTS - 1 )
295 #define OUT_PORT_Z _Out_ _Out_range_( 0, 65535L )
296 #define OUT_RANGE( min, max ) _Out_ _Out_range_( ( min ), ( max ) )
297 #define OUT_OPT_RANGE( min, max ) _Out_opt_ _Out_range_( ( min ), ( max ) )
298 #define OUT_STATUS _Out_ _Out_range_( MAX_ERROR, CRYPT_OK )
299 
300 #else /* Declspec SAL */
301 
302 #define IN_ALGO __in __in_range( CRYPT_ALGO_NONE + 1, CRYPT_ALGO_LAST - 1 )
303 #define IN_ALGO_OPT __in __in_range( CRYPT_ALGO_NONE, CRYPT_ALGO_LAST - 1 )
304 #define IN_ATTRIBUTE __in __in_range( CRYPT_ATTRIBUTE_NONE + 1, CRYPT_IATTRIBUTE_LAST - 1 )
305 #define IN_ATTRIBUTE_OPT __in __in_range( CRYPT_ATTRIBUTE_NONE, CRYPT_IATTRIBUTE_LAST - 1 )
306 #define IN_BYTE __in __in_range( 0, 0xFF )
307 #define IN_CHAR __in __in_range( 0, 0x7F )
308 #define IN_ERROR __in __in_range( MAX_ERROR, -1 )
309 #define IN_HANDLE __in __in_range( SYSTEM_OBJECT_HANDLE, MAX_OBJECTS - 1 )
310 #define IN_HANDLE_OPT __in __in_range( CRYPT_UNUSED, MAX_OBJECTS - 1 )
311 #define IN_KEYID __in __in_range( CRYPT_KEYID_NONE + 1, CRYPT_KEYID_LAST - 1 )
312 #define IN_KEYID_OPT __in __in_range( CRYPT_KEYID_NONE, CRYPT_KEYID_LAST - 1 )
313 #define IN_MESSAGE __in __in_range( MESSAGE_NONE + 1, IMESSAGE_LAST - 1 )
314 #define IN_MODE __in __in_range( CRYPT_MODE_NONE + 1, CRYPT_MODE_LAST - 1 )
315 #define IN_MODE_OPT __in __in_range( CRYPT_MODE_NONE, CRYPT_MODE_LAST - 1 )
316 #define IN_PORT __in __in_range( 22, 65535L )
317 #define IN_PORT_OPT __in __in_range( CRYPT_UNUSED, 65535L )
318 #define IN_RANGE( min, max ) __in __in_range( ( min ), ( max ) )
319 #define IN_RANGE_FIXED( value ) __in __in_range( ( value ), ( value ) )
320 #define IN_STATUS __in __in_range( MAX_ERROR, CRYPT_OK )
321 
322 #define INOUT_HANDLE __inout \
323  __in_range( SYSTEM_OBJECT_HANDLE, MAX_OBJECTS - 1 ) \
324  __out_range( SYSTEM_OBJECT_HANDLE, MAX_OBJECTS - 1 )
325 #define INOUT_RANGE( min, max ) __inout \
326  __in_range( ( min ), ( max ) ) \
327  __out_range( ( min ), ( max ) )
328 
329 #define OUT_ALGO_Z __out __out_range( CRYPT_ALGO_NONE, CRYPT_ALGO_LAST - 1 )
330 #define OUT_OPT_ALGO_Z __out_opt __out_range( CRYPT_ALGO_NONE, CRYPT_ALGO_LAST - 1 )
331 #define OUT_ATTRIBUTE_Z __out __out_range( CRYPT_ATTRIBUTE_NONE, CRYPT_IATTRIBUTE_LAST - 1 )
332 #define OUT_OPT_ATTRIBUTE_Z __out_opt __out_range( CRYPT_ATTRIBUTE_NONE, CRYPT_IATTRIBUTE_LAST - 1 )
333 #define OUT_BOOL __out __out_range( FALSE, TRUE )
334 #define OUT_OPT_BOOL __out_opt __out_range( FALSE, TRUE )
335 #define OUT_OPT_BYTE __out_opt __out_range( 0, 0xFF )
336 #define OUT_ERROR __out __out_range( MAX_ERROR, -1 )
337 #define OUT_HANDLE_OPT __out __out_range( CRYPT_ERROR, MAX_OBJECTS - 1 )
338 #define OUT_OPT_HANDLE_OPT __out_opt __out_range( SYSTEM_OBJECT_HANDLE, MAX_OBJECTS - 1 )
339 #define OUT_PORT_Z __out __out_range( 0, 65535L )
340 #define OUT_RANGE( min, max ) __out __out_range( ( min ), ( max ) )
341 #define OUT_OPT_RANGE( min, max ) __out_opt __out_range( ( min ), ( max ) )
342 #define OUT_STATUS __out __out_range( MAX_ERROR, CRYPT_OK )
343 
344 #endif /* Declspec vs. Attribute SAL */
345 
346 /* Length parameter checking:
347 
348  LENGTH Value must be between 1 and MAX_INTLENGTH - 1.
349  LENGTH_FIXED Value must be a single fixed length, used for polymorphic
350  functions of which this specific instance takes a fixed-
351  size parameter, or otherwise in cases where a length
352  parameter is supplied mostly just to allow bounds
353  checking.
354  LENGTH_MIN As LENGTH but lower bound is user-specified.
355  LENGTH_Z As LENGTH but lower bound may be zero.
356 
357  LENGTH_SHORT As LENGTH but upper bound is MAX_INTLENGTH_SHORT - 1
358  rather than MAX_INTLENGTH - 1.
359  LENGTH_SHORT_MIN As LENGTH_SHORT but lower bound is user-specified.
360  LENGTH_SHORT_Z As LENGTH_SHORT but lower bound may be non-zero.
361 
362  In addition to these we allow the OPT specifier and OPT and Z suffixes as
363  before */
364 
365 #if VC_GE_2008( _MSC_VER ) /* Attribute SAL */
366 
367 #define IN_LENGTH _In_ _In_range_( 1, MAX_INTLENGTH - 1 )
368 #define IN_LENGTH_OPT _In_ _In_range_( CRYPT_UNUSED, MAX_INTLENGTH - 1 )
369 #define IN_LENGTH_FIXED( size ) _In_ _In_range_( ( size ), ( size ) )
370 #define IN_LENGTH_MIN( min ) _In_ _In_range_( ( min ), MAX_INTLENGTH - 1 )
371 #define IN_LENGTH_Z _In_ _In_range_( 0, MAX_INTLENGTH - 1 )
372 
373 #define IN_LENGTH_SHORT _In_ _In_range_( 1, MAX_INTLENGTH_SHORT - 1 )
374 #define IN_LENGTH_SHORT_OPT _In_ _In_range_( CRYPT_UNUSED, MAX_INTLENGTH_SHORT - 1 )
375  /* This really is a _OPT and not a _INDEF in
376  the one place where it's used */
377 #define IN_LENGTH_SHORT_MIN( min ) _In_ _In_range_( ( min ) , MAX_INTLENGTH_SHORT - 1 )
378 #define IN_LENGTH_SHORT_Z _In_ _In_range_( 0, MAX_INTLENGTH_SHORT - 1 )
379 
380 #define INOUT_LENGTH_Z _Inout_ \
381  _In_range_( 0, MAX_INTLENGTH - 1 ) \
382  _Out_range_( 0, MAX_INTLENGTH - 1 )
383 #define INOUT_LENGTH_SHORT_Z _Inout_ \
384  _In_range_( 0, MAX_INTLENGTH_SHORT - 1 ) \
385  _Out_range_( 0, MAX_INTLENGTH_SHORT - 1 )
386 
387 #define OUT_LENGTH _Out_ _Out_range_( 1, MAX_INTLENGTH - 1 )
388 #define OUT_LENGTH_MIN( min ) _Out_ _Out_range_( ( min ), MAX_INTLENGTH - 1 )
389 #define OUT_OPT_LENGTH_MIN( min ) _Out_opt_ _Out_range_( ( min ), MAX_INTLENGTH - 1 )
390 #define OUT_LENGTH_Z _Out_ _Out_range_( 0, MAX_INTLENGTH - 1 )
391 #define OUT_OPT_LENGTH_Z _Out_opt_ _Out_range_( 0, MAX_INTLENGTH - 1 )
392 
393 #define OUT_LENGTH_SHORT _Out_ _Out_range_( 1, MAX_INTLENGTH_SHORT - 1 )
394 #define OUT_LENGTH_SHORT_Z _Out_ _Out_range_( 0, MAX_INTLENGTH_SHORT - 1 )
395 #define OUT_OPT_LENGTH_SHORT_Z _Out_opt_ _Out_range_( 0, MAX_INTLENGTH_SHORT - 1 )
396 
397 #else /* Declspec SAL */
398 
399 #define IN_LENGTH __in __in_range( 1, MAX_INTLENGTH - 1 )
400 #define IN_LENGTH_OPT __in __in_range( CRYPT_UNUSED, MAX_INTLENGTH - 1 )
401 #define IN_LENGTH_FIXED( size ) __in __in_range( ( size ), ( size ) )
402 #define IN_LENGTH_MIN( min ) __in __in_range( ( min ), MAX_INTLENGTH - 1 )
403 #define IN_LENGTH_Z __in __in_range( 0, MAX_INTLENGTH - 1 )
404 
405 #define IN_LENGTH_SHORT __in __in_range( 1, MAX_INTLENGTH_SHORT - 1 )
406 #define IN_LENGTH_SHORT_OPT __in __in_range( CRYPT_UNUSED, MAX_INTLENGTH_SHORT - 1 )
407  /* This really is a _OPT and not a _INDEF in
408  the one place where it's used */
409 #define IN_LENGTH_SHORT_MIN( min ) __in __in_range( ( min ) , MAX_INTLENGTH_SHORT - 1 )
410 #define IN_LENGTH_SHORT_Z __in __in_range( 0, MAX_INTLENGTH_SHORT - 1 )
411 
412 #define INOUT_LENGTH_Z __inout \
413  __in_range( 0, MAX_INTLENGTH - 1 ) \
414  __out_range( 0, MAX_INTLENGTH - 1 )
415 #define INOUT_LENGTH_SHORT_Z __inout \
416  __in_range( 0, MAX_INTLENGTH_SHORT - 1 ) \
417  __out_range( 0, MAX_INTLENGTH_SHORT - 1 )
418 
419 #define OUT_LENGTH __out __out_range( 1, MAX_INTLENGTH - 1 )
420 #define OUT_LENGTH_MIN( min ) __out __out_range( ( min ), MAX_INTLENGTH - 1 )
421 #define OUT_OPT_LENGTH_MIN( min ) __out_opt __out_range( ( min ), MAX_INTLENGTH - 1 )
422 #define OUT_LENGTH_Z __out __out_range( 0, MAX_INTLENGTH - 1 )
423 #define OUT_OPT_LENGTH_Z __out_opt __out_range( 0, MAX_INTLENGTH - 1 )
424 
425 #define OUT_LENGTH_SHORT __out __out_range( 1, MAX_INTLENGTH_SHORT - 1 )
426 #define OUT_LENGTH_SHORT_Z __out __out_range( 0, MAX_INTLENGTH_SHORT - 1 )
427 #define OUT_OPT_LENGTH_SHORT_Z __out_opt __out_range( 0, MAX_INTLENGTH_SHORT - 1 )
428 
429 #endif /* Declspec vs. Attribute SAL */
430 
431 /* Special-case length checking:
432 
433  LENGTH_ATTRIBUTE Value must be a valid length for an attribute.
434  LENGTH_DNS Value must be a valid length for DNS data or a URL.
435  LENGTH_DNS_Z Value must be a valid length for DNS data or a URL,
436  including zero-length output, which is returned on error.
437  LENGTH_ERRORMESSAGE Value must be a valid length for an extended error
438  string.
439  LENGTH_HASH Value must be a valid length for a hash.
440  LENGTH_INDEF As LENGTH but may also be CRYPT_UNUSED for indefinite-
441  length encoded data.
442  LENGTH_IV Value must be a valid length for a cipher block.
443  Technically this isn't always an IV, but this is about
444  the best name to give it.
445  LENGTH_KEY Value must be a valid length for a conventional
446  encryption key.
447  LENGTH_KEYID Value must be a valid length for a key ID lookup.
448  LENGTH_NAME Value must be a valid length for an object name or
449  similar type of string, e.g. a database name or a
450  password (this is a bit of a catch-all value for
451  strings, unfortunately there's no easily descriptive
452  name for the function it performs).
453  LENGTH_OID Value must be a valid length for an OID.
454  LENGTH_PKC Value must be a valid length for PKC data.
455  LENGTH_PKC_Z Value must be a valid length for PKC data, including
456  zero-length output, which is returned on error.
457 
458  In addition to these we allow the OPT specifier and Z suffix as before */
459 
460 #if VC_GE_2008( _MSC_VER ) /* Attribute SAL */
461 
462 #define IN_LENGTH_ATTRIBUTE _In_ _In_range_( 1, MAX_ATTRIBUTE_SIZE )
463 #define IN_LENGTH_DNS _In_ _In_range_( 1, MAX_DNS_SIZE )
464 #define IN_LENGTH_DNS_Z _In_ _In_range_( 0, MAX_DNS_SIZE )
465 #define IN_LENGTH_ERRORMESSAGE _In_ _In_range_( 1, MAX_ERRORMESSAGE_SIZE )
466 #define IN_LENGTH_HASH _In_ _In_range_( 16, CRYPT_MAX_HASHSIZE )
467 #define IN_LENGTH_INDEF _In_ _In_range_( CRYPT_UNUSED, MAX_INTLENGTH - 1 )
468 #define IN_LENGTH_IV _In_ _In_range_( 1, CRYPT_MAX_IVSIZE )
469 #define IN_LENGTH_IV_Z _In_ _In_range_( 0, CRYPT_MAX_IVSIZE )
470 #define IN_LENGTH_KEY _In_ _In_range_( MIN_KEYSIZE, CRYPT_MAX_KEYSIZE )
471 #define IN_LENGTH_KEYID _In_ _In_range_( MIN_NAME_LENGTH, MAX_ATTRIBUTE_SIZE )
472 #define IN_LENGTH_KEYID_Z _In_ _In_range_( 0, MAX_ATTRIBUTE_SIZE )
473 #define IN_LENGTH_NAME _In_ _In_range_( MIN_NAME_LENGTH, MAX_ATTRIBUTE_SIZE )
474 #define IN_LENGTH_NAME_Z _In_ _In_range_( 0, MAX_ATTRIBUTE_SIZE )
475 #define IN_LENGTH_OID _In_ _In_range_( 7, MAX_OID_SIZE )
476 #define IN_LENGTH_PKC _In_ _In_range_( 1, CRYPT_MAX_PKCSIZE )
477 #define IN_LENGTH_PKC_Z _In_ _In_range_( 0, CRYPT_MAX_PKCSIZE )
478 
479 #define OUT_LENGTH_DNS_Z _Out_ _Out_range_( 0, MAX_DNS_SIZE )
480 #define OUT_OPT_LENGTH_HASH_Z _Out_opt_ _Out_range_( 0, CRYPT_MAX_HASHSIZE )
481 #define OUT_LENGTH_PKC_Z _Out_ _Out_range_( 0, CRYPT_MAX_PKCSIZE )
482 #define OUT_LENGTH_INDEF _Out_ _Out_range_( CRYPT_UNUSED, MAX_INTLENGTH - 1 )
483 #define OUT_OPT_LENGTH_INDEF _Out_opt_ _Out_range_( CRYPT_UNUSED, MAX_INTLENGTH - 1 )
484 
485 #else /* Declspec SAL */
486 
487 #define IN_LENGTH_ATTRIBUTE __in __in_range( 1, MAX_ATTRIBUTE_SIZE )
488 #define IN_LENGTH_DNS __in __in_range( 1, MAX_DNS_SIZE )
489 #define IN_LENGTH_DNS_Z __in __in_range( 0, MAX_DNS_SIZE )
490 #define IN_LENGTH_ERRORMESSAGE __in __in_range( 1, MAX_ERRORMESSAGE_SIZE )
491 #define IN_LENGTH_HASH __in __in_range( 16, CRYPT_MAX_HASHSIZE )
492 #define IN_LENGTH_INDEF __in __in_range( CRYPT_UNUSED, MAX_INTLENGTH - 1 )
493 #define IN_LENGTH_IV __in __in_range( 1, CRYPT_MAX_IVSIZE )
494 #define IN_LENGTH_IV_Z __in __in_range( 0, CRYPT_MAX_IVSIZE )
495 #define IN_LENGTH_KEY __in __in_range( MIN_KEYSIZE, CRYPT_MAX_KEYSIZE )
496 #define IN_LENGTH_KEYID __in __in_range( MIN_NAME_LENGTH, MAX_ATTRIBUTE_SIZE )
497 #define IN_LENGTH_KEYID_Z __in __in_range( 0, MAX_ATTRIBUTE_SIZE )
498 #define IN_LENGTH_NAME __in __in_range( MIN_NAME_LENGTH, MAX_ATTRIBUTE_SIZE )
499 #define IN_LENGTH_NAME_Z __in __in_range( 0, MAX_ATTRIBUTE_SIZE )
500 #define IN_LENGTH_OID __in __in_range( 7, MAX_OID_SIZE )
501 #define IN_LENGTH_PKC __in __in_range( 1, CRYPT_MAX_PKCSIZE )
502 #define IN_LENGTH_PKC_Z __in __in_range( 0, CRYPT_MAX_PKCSIZE )
503 
504 #define OUT_LENGTH_DNS_Z __out __out_range( 0, MAX_DNS_SIZE )
505 #define OUT_OPT_LENGTH_HASH_Z __out_opt __out_range( 0, CRYPT_MAX_HASHSIZE )
506 #define OUT_LENGTH_PKC_Z __out __out_range( 0, CRYPT_MAX_PKCSIZE )
507 #define OUT_LENGTH_INDEF __out __out_range( CRYPT_UNUSED, MAX_INTLENGTH - 1 )
508 #define OUT_OPT_LENGTH_INDEF __out_opt __out_range( CRYPT_UNUSED, MAX_INTLENGTH - 1 )
509 
510 #endif /* Declspec vs. Attribute SAL */
511 
512 /* ASN.1 parameter checking, enabled if ANALYSE_ASN1 is defined:
513 
514  TAG Value must be a valid tag or DEFAULT_TAG. Note that
515  this is the raw tag value before any DER encoding,
516  e.g. '0' rather than 'MAKE_CTAG( 0 )'.
517  TAG_EXT As IN_TAG but may also be ANY_TAG, is used internally
518  by the ASN.1 code to indicate a don't-care tag value.
519  TAG_ENCODED Value must be a valid DER-encoded tag value
520 
521  In addition to these we allow the EXT specifier to indicate that the
522  value may also be ANY_TAG (a don't-care value) or the hidden NO_TAG used
523  to handle reading of data when the tag has already been processed */
524 
525 #if VC_GE_2008( _MSC_VER ) /* Attribute SAL */
526 
527 #define IN_TAG _In_ _In_range_( DEFAULT_TAG, MAX_TAG_VALUE - 1 )
528 #define IN_TAG_EXT _In_ _In_range_( ANY_TAG, MAX_TAG_VALUE - 1 )
529 #define IN_TAG_ENCODED _In_ _In_range_( NO_TAG, MAX_TAG )
530 #define IN_TAG_ENCODED_EXT _In_ _In_range_( ANY_TAG, MAX_TAG )
531 
532 #define OUT_TAG_Z _Out_ _Out_range_( 0, MAX_TAG_VALUE - 1 )
533 #define OUT_TAG_ENCODED_Z _Out_ _Out_range_( 0, MAX_TAG )
534 
535 #else /* Declspec SAL */
536 
537 #define IN_TAG __in __in_range( DEFAULT_TAG, MAX_TAG_VALUE - 1 )
538 #define IN_TAG_EXT __in __in_range( ANY_TAG, MAX_TAG_VALUE - 1 )
539 #define IN_TAG_ENCODED __in __in_range( NO_TAG, MAX_TAG )
540 #define IN_TAG_ENCODED_EXT __in __in_range( ANY_TAG, MAX_TAG )
541 
542 #define OUT_TAG_Z __out __out_range( 0, MAX_TAG_VALUE - 1 )
543 #define OUT_TAG_ENCODED_Z __out __out_range( 0, MAX_TAG )
544 
545 #endif /* Declspec vs. Attribute SAL */
546 
547 /* Enumerated type checking. Due to the duality of 'int' and 'enum' under C
548  these can normally be mixed freely until it comes back to bite on systems
549  where the compiler doesn't treat them quite the same. The following
550  provides more strict type checking of enums than the compiler would
551  normally provide and relies on the enum being bracketed by xxx_NONE and
552  xxx_LAST.
553 
554  We also allow an OPT suffix to indicate the use of don't-care values,
555  denoted by xxx_NONE */
556 
557 #if VC_GE_2008( _MSC_VER ) /* Attribute SAL */
558 
559 #define IN_ENUM( name ) _In_ _In_range_( name##_NONE + 1, name##_LAST - 1 )
560 #define IN_ENUM_OPT( name ) _In_ _In_range_( name##_NONE, name##_LAST - 1 )
561 
562 #define INOUT_ENUM( name ) _Inout_ \
563  _In_range_( name##_NONE + 1, name##_LAST - 1 ) \
564  _Out_range_( name##_NONE + 1, name##_LAST - 1 )
565 
566 #define OUT_ENUM( name ) _Out_ _Out_range_( name##_NONE + 1, name##_LAST - 1 )
567 #define OUT_ENUM_OPT( name ) _Out_ _Out_range_( name##_NONE, name##_LAST - 1 )
568 
569 #else /* Declspec SAL */
570 
571 #define IN_ENUM( name ) __in __in_range( name##_NONE + 1, name##_LAST - 1 )
572 #define IN_ENUM_OPT( name ) __in __in_range( name##_NONE, name##_LAST - 1 )
573 
574 #define INOUT_ENUM( name ) __inout \
575  __in_range( name##_NONE + 1, name##_LAST - 1 ) \
576  __out_range( name##_NONE + 1, name##_LAST - 1 )
577 
578 #define OUT_ENUM( name ) __out __out_range( name##_NONE + 1, name##_LAST - 1 )
579 #define OUT_ENUM_OPT( name ) __out __out_range( name##_NONE, name##_LAST - 1 )
580 
581 #endif /* Declspec vs. Attribute SAL */
582 
583 /* Binary flag checking. This works as for enumerated type checking and
584  relies on the flag definition being bracketed by xxx_FLAG_NONE and
585  xxx_FLAG_MAX */
586 
587 #if VC_GE_2008( _MSC_VER ) /* Attribute SAL */
588 
589 #define IN_FLAGS( name ) _In_ _In_range_( 1, flags##_FLAG_MAX )
590 #define IN_FLAGS_Z( name ) _In_ _In_range_( flags##_FLAG_NONE, flags##_FLAG_MAX )
591 
592 #define INOUT_FLAGS( name ) _Inout_ _Inout_range_( flags##_FLAG_NONE, flags##_FLAG_MAX )
593 
594 #define OUT_FLAGS_Z( name ) _Out_ _Out_range_( flags##_FLAG_NONE, flags##_FLAG_MAX )
595 
596 #else /* Declspec SAL */
597 
598 #define IN_FLAGS( name ) __in __in_range( 1, flags##_FLAG_MAX )
599 #define IN_FLAGS_Z( name ) __in __in_range( flags##_FLAG_NONE, flags##_FLAG_MAX )
600 
601 #define INOUT_FLAGS( name ) __inout __inout_range( flags##_FLAG_NONE, flags##_FLAG_MAX )
602 
603 #define OUT_FLAGS_Z( name ) __out __out_range( flags##_FLAG_NONE, flags##_FLAG_MAX )
604 
605 #endif /* Declspec vs. Attribute SAL */
606 
607 /* Buffer parameter checking:
608 
609  IN_BUFFER For { buffer, length } values.
610  INOUT_BUFFER For in-place processing of { buffer, maxLength, *length }
611  values, e.g. decryption with padding removal.
612  OUT_BUFFER For filling of { buffer, maxLength, *length } values.
613 
614  INOUT_BUFFER_FIXED For in-place processing of { buffer, length } values,
615  e.g.filtering control chars in a string.
616  OUT_BUFFER_FIXED For filling of { buffer, length } values.
617 
618  In addition to these we allow the OPT specifier as before */
619 
620 #if VC_GE_2008( _MSC_VER ) /* Attribute SAL */
621 
622 /* Attribute SAL doesn't have any definitions covering various types of
623  ( max, count ) declarations so we have to define them ourselves */
624 
625 #define _Inout_bytecap_post_bytecount_(cap,count) _Pre_valid_bytecap_(cap) \
626  _Post_bytecount_(count)
627 #define _Inout_bytecap_post_bytecount_c_(cap,count) _Pre_valid_bytecap_(cap) \
628  _Post_bytecount_c_(count)
629 
630 #define _Out_bytecapcount_c_(count) _Pre_bytecap_c_(count) _Pre_invalid_ \
631  _Post_bytecount_c_(count)
632 #define _Out_bytecap_post_bytecount_c_(cap,count) _Pre_bytecap_(cap) _Pre_invalid_ \
633  _Post_bytecount_c_(count)
634 #define _Out_opt_bytecap_post_bytecount_c_(cap,count) _Pre_opt_bytecap_(cap) _Pre_invalid_ \
635  _Post_bytecount_c_(count)
636 
637 #define IN_BUFFER( count ) _In_bytecount_( count )
638 #define IN_BUFFER_C( count ) _In_bytecount_c_( count )
639 #define IN_BUFFER_OPT( count ) _In_opt_bytecount_( count )
640 #define IN_BUFFER_OPT_C( count ) _In_opt_bytecount_c_( count )
641 
642 #define INOUT_BUFFER( max, count ) _Inout_bytecap_post_bytecount_( max, count )
643 #define INOUT_BUFFER_C( max, count ) _Inout_bytecap_post_bytecount_c_( max, count )
644 #define INOUT_BUFFER_FIXED( count ) _Inout_bytecount_( count )
645 #define INOUT_BUFFER_OPT( max, count ) _Inout_opt_bytecap_( max, count )
646 
647 #define OUT_BUFFER( max, count ) _Out_bytecap_post_bytecount_( max, count )
648 #define OUT_BUFFER_C( max, count ) _Out_bytecap_post_bytecount_c_( max, count )
649 #define OUT_BUFFER_OPT( max, count ) _Out_opt_bytecap_post_bytecount_( max, count )
650 #define OUT_BUFFER_OPT_C( max, count ) _Out_opt_bytecap_post_bytecount_c_( max, count )
651 #define OUT_BUFFER_FIXED( count ) _Out_bytecapcount_( count )
652 #define OUT_BUFFER_FIXED_C( count ) _Out_bytecapcount_c_( count )
653 #define OUT_BUFFER_OPT_FIXED( count ) _Out_opt_bytecapcount_( count )
654 
655 #else /* Declspec SAL */
656 
657 #define IN_BUFFER( count ) __in_bcount( count )
658 #define IN_BUFFER_C( count ) __in_bcount( count )
659 #define IN_BUFFER_OPT( count ) __in_bcount_opt( count )
660 #define IN_BUFFER_OPT_C( count ) __in_bcount_opt( count )
661 
662 #define INOUT_BUFFER( max, count ) __inout_bcount( max, count )
663 #define INOUT_BUFFER_C( max, count ) __inout_bcount( max, count )
664 #define INOUT_BUFFER_FIXED( count ) __inout_bcount_full( count )
665 #define INOUT_BUFFER_OPT( max, count ) __inout_bcount_opt( max, count )
666 
667 #define OUT_BUFFER( max, count ) __out_bcount_part( max, count )
668 #define OUT_BUFFER_C( max, count ) __out_bcount_part( max, count )
669 #define OUT_BUFFER_OPT( max, count ) __out_bcount_part_opt( max, count )
670 #define OUT_BUFFER_OPT_C( max, count ) __out_bcount_part_opt( max, count )
671 #define OUT_BUFFER_FIXED( count ) __out_bcount_full( count )
672 #define OUT_BUFFER_FIXED_C( count ) __out_bcount_full( count )
673 #define OUT_BUFFER_OPT_FIXED( count ) __out_bcount_full_opt( count )
674 
675 #endif /* Declspec vs. Attribute SAL */
676 
677 /* Array parameter checking:
678 
679  ARRAY For { fooType foo[], int fooCount } values */
680 
681 #if VC_GE_2008( _MSC_VER ) /* Attribute SAL */
682 
683 #define IN_ARRAY( count ) _In_count_( count )
684 #define IN_ARRAY_C( count ) _In_count_c_( count )
685 #define IN_ARRAY_OPT( count ) _In_opt_count_( count )
686 #define IN_ARRAY_OPT_C( count ) _In_opt_count_c_( count )
687 
688 #define INOUT_ARRAY( count ) _Inout_cap_( count )
689 #define INOUT_ARRAY_C( count ) _Inout_cap_c_( count )
690 
691 #define OUT_ARRAY( count ) _Out_cap_( count )
692 #define OUT_ARRAY_C( count ) _Out_cap_c_( count )
693 #define OUT_ARRAY_OPT( count ) _Out_opt_cap_( count )
694 #define OUT_ARRAY_OPT_C( count ) _Out_opt_cap_c_( count )
695 
696 #else /* Declspec SAL */
697 
698 #define IN_ARRAY( count ) __in_ecount( count )
699 #define IN_ARRAY_C( count ) __in_ecount( count )
700 #define IN_ARRAY_OPT( count ) __in_ecount_opt( count )
701 #define IN_ARRAY_OPT_C( count ) __in_ecount_opt( count )
702 
703 #define INOUT_ARRAY( count ) __inout_ecount( count )
704 #define INOUT_ARRAY_C( count ) __inout_ecount( count )
705 
706 #define OUT_ARRAY( count ) __out_ecount( count )
707 #define OUT_ARRAY_C( count ) __out_ecount( count )
708 #define OUT_ARRAY_OPT( count ) __out_ecount_opt( count )
709 #define OUT_ARRAY_OPT_C( count ) __out_ecount_opt( count )
710 
711 #endif /* Declspec vs. Attribute SAL */
712 
713 /* Structures that encapsulate data-handling operations:
714 
715  ARRAY Array of total allocated size 'max', currently filled
716  to 'count' elements.
717  BUFFER Buffer of total allocated size 'max', currently filled
718  to 'count' bytes.
719  BUFFER_FIXED Buffer of total allocated and filled size 'max'.
720 
721  In addition to these we allow the OPT specifier as before, and the
722  UNSPECIFIED specifier to indicate that the fill state of the buffer
723  isn't specified or at least is too complex to describe to PREfast, for
724  example an I/O buffer that acts as BUFFER on read but BUFFER_FIXED on
725  write */
726 
727 #if VC_GE_2008( _MSC_VER ) /* Attribute SAL */
728 
729 #define ARRAY( max, count ) /* No equivalent in attribute SAL */
730 #define ARRAY_FIXED( max ) /* No equivalent in attribute SAL */
731 #define BUFFER( max, count ) /* No equivalent in attribute SAL */
732 #define BUFFER_OPT( max, count ) /* No equivalent in attribute SAL */
733 #define BUFFER_FIXED( max ) /* No equivalent in attribute SAL */
734 #define BUFFER_OPT_FIXED( max ) /* No equivalent in attribute SAL */
735 #define BUFFER_UNSPECIFIED( max ) /* No equivalent in attribute SAL */
736 
737 #else /* Declspec SAL */
738 
739 #define ARRAY( max, count ) __field_ecount_part( ( max ), ( count ) )
740 #define ARRAY_FIXED( max ) __field_ecount_full( max )
741 #define BUFFER( max, count ) __field_bcount_part( ( max ), ( count ) )
742 #define BUFFER_OPT( max, count ) __field_bcount_part_opt( ( max ), ( count ) )
743 #define BUFFER_FIXED( max ) __field_bcount_full( max )
744 #define BUFFER_OPT_FIXED( max ) __field_bcount_full_opt( max )
745 #define BUFFER_UNSPECIFIED( max ) __field_bcount( max )
746 
747 #endif /* Declspec vs. Attribute SAL */
748 
749 /* Memory-allocation functions that allocate and return a block of
750  initialised memory. Although this is documented as being usable for
751  functions that take parameters "void **ptr, int *length', this doesn't
752  actually work because when you get down to the attribute level you've
753  got
754  "([Pre(ValidElements="*length")] void **ptr, [Pre(Valid=SA_No)]int *length",
755  and since the *length value isn't valid at this point PREfast produces an
756  error 6525 "Invalid size specification". The way to make it valid is to
757  switch to
758  "[Pre(ValidElements="length")] void **ptr, [Pre(Valid=SA_Yes)]int length)",
759  but we don't know the length when the function is called. Although we
760  could break the annotations down into two special cases, one for
761  "int length" (Valid=SA_Yes) and the other for "int *length" (Valid=SA_No),
762  this is getting kind of messy, and PREfast doesn't seem to produce any
763  better diagnostics for this than a more generic __deref_out/_Deref_out_,
764  so we just use __deref_out for now */
765 
766 #if VC_GE_2008( _MSC_VER ) /* Attribute SAL */
767 
768 #if 0 /* See comment above */
769 #define OUT_BUFFER_ALLOC( length ) _Out_capcount_( length )
770 #define OUT_BUFFER_ALLOC_OPT( length ) _Out_opt_capcount_( length )
771 #else
772 #define OUT_BUFFER_ALLOC( length ) _Deref_out_
773 #define OUT_BUFFER_ALLOC_OPT( length ) _Deref_out_opt_
774 #endif /* 0 */
775 
776 #else /* Declspec SAL */
777 
778 #define OUT_BUFFER_ALLOC( length ) __deref_out_bcount_full( length )
779 #define OUT_BUFFER_ALLOC_OPT( length ) __deref_out_bcount_full_opt( length )
780 
781 #endif /* Declspec vs. Attribute SAL */
782 
783 /* Typeless annotations used in situations where the size or type is
784  implicit, e.g. a pointer to a structure. The annotation 'IN' is
785  implied by 'const' so we wouldn't normally use it, but it can be useful
786  when we're re-prototyping a non-cryptlib function that doesn't use
787  'const's */
788 
789 #if VC_GE_2008( _MSC_VER ) /* Attribute SAL */
790 
791 #ifdef IN /* Defined to no-ops in some versions of windef.h */
792  #undef IN
793  #undef OUT
794 #endif
795 
796 #define IN _In_
797 #define IN_OPT _In_opt_
798 #define INOUT _Inout_
799 #define INOUT_OPT _Inout_opt_
800 #define OUT _Out_
801 #define OUT_OPT _Out_opt_
802 
803 #else /* Declspec SAL */
804 
805 #define IN __in
806 #define IN_OPT __in_opt
807 #define INOUT __inout
808 #define INOUT_OPT __inout_opt
809 #define OUT __out
810 #define OUT_OPT __out_opt
811 
812 #endif /* Declspec vs. Attribute SAL */
813 
814 /* Pointer annotations */
815 
816 #if VC_GE_2008( _MSC_VER ) /* Attribute SAL */
817 
818 #define INOUT_PTR _Deref_inout_bound_
819  /* There's no _Deref_inout_, the _bound_
820  veriant seems to work though */
821 #define OUT_PTR _Deref_out_
822 #define OUT_OPT_PTR _Deref_out_opt_
823 #define OUT_OPT_PTR_OPT _Deref_opt_out_opt_
824 
825 #else /* Declspec SAL */
826 
827 #define INOUT_PTR __deref_inout
828 #define OUT_PTR __deref_out
829 #define OUT_OPT_PTR __deref_out_opt
830 #define OUT_OPT_PTR_OPT __deref_opt_out_opt
831 
832 #endif /* Declspec vs. Attribute SAL */
833 
834 /* Other annotations:
835 
836  CALLBACK_FUNCTION Function is a callback function (no-one seems to know
837  what this annotation actually does).
838  FORMAT_STRING Argument is a printf-style format string.
839  IN_STRING Argument is a null-terminated string.
840  TYPECAST Type cast, e.g. from void * to struct foo * */
841 
842 #if VC_GE_2008( _MSC_VER ) /* Attribute SAL */
843 
844 #define ANALYSER_HINT( expr ) __analysis_assume( expr )
845  /* Attribute SAL has no equivalent for this,
846  but __analysis_assume() still works */
847 #define CALLBACK_FUNCTION /* No equivalent in attribute SAL */
848 #define FORMAT_STRING _Printf_format_string_
849 #define IN_STRING _In_z_
850 #define IN_STRING_OPT _In_opt_z_
851 #define TYPECAST( type ) /* No equivalent in attribute SAL */
852 
853 #else /* Declspec SAL */
854 
855 #define ANALYSER_HINT( expr ) __analysis_assume( expr )
856 #define CALLBACK_FUNCTION __callback
857 #define FORMAT_STRING __format_string
858 #define IN_STRING __in_z
859 #define IN_STRING_OPT __in_z_opt
860 #define TYPECAST( type ) __typefix( type )
861 
862 #endif /* Declspec vs. Attribute SAL */
863 
864 #endif /* PREfast */
865 
866 /* Handling of C'0x analysis */
867 
868 #if defined( _MSC_VER ) && !VC_16BIT( _MSC_VER )
869 
870 #define STDC_NONNULL_ARG( argIndex )
871 #define STDC_PRINTF_FN( formatIndex, argIndex )
872 #define STDC_PURE __declspec( noalias )
873 #if defined( _MSC_VER ) && defined( _PREFAST_ )
874  /* The use of the declspec annotation cancels the ability to use attribute
875  SAL, so if we're using that we have to no-op out this definition since
876  there's no attribute SAL equivalent */
877  #ifdef __ATTR_SAL
878  #define STDC_UNUSED
879  #else
880  #define STDC_UNUSED __reserved
881  #endif /* Declspec vs. attribute SAL */
882 #else
883  #define STDC_UNUSED
884 #endif /* VC++ with/without PREfast */
885 
886 #endif /* VC++ */
887 
888 /****************************************************************************
889 * *
890 * gcc/C'0x Analysis Support *
891 * *
892 ****************************************************************************/
893 
894 #if defined( __GNUC__ ) && ( __GNUC__ >= 4 )
895 
896 /* Future versions of the C standard will support the ability to annotate
897  functions to allow the compiler to perform extra checking and assist with
898  code generation. Currently only gcc supports this annotation (and even
899  that in a gcc-specific manner), in order to handle this we define macros
900  for the proposed C-standard annotation, which defines attributes of the
901  form "stdc_<name>", although how they'll be applied is still undecided.
902 
903  Unfortunately neither gcc's STDC_NONNULL_ARG nor its CHECK_RETVAL
904  checking work properly. CHECK_RETVAL is the least broken since it merely
905  fails to report a return value being unchecked in many cases while
906  reporting unnecessary false positives in others, but STDC_NONNULL_ARG is
907  downright dangerous since it'll break correctly functioning code.
908 
909  The problem with CHECK_RETVAL is that it regards any "use" of the return
910  value of a function, for example assigning it to a variable that's never
911  used, as fulfilling the conditions for "use", and therefore issues no
912  warning. On the other hand the standard "(void)" cast that's been used
913  to indicate that you genuinely want to ignore the return value of a
914  function since circa 1979 with lint is ignored, resulting in warnings
915  where there shouldn't be any.
916 
917  STDC_NONNULL_ARG on the other hand is far more broken since the warnings
918  are issued by the front-end before data flow analysis occurs (so many
919  cases of NULL pointer use are missed) but then the optimiser takes the
920  annotation to mean that that value can never be NULL and *removes any
921  code that might check for a NULL pointer*! This is made even worse by
922  the awkward way that the annotation works, requiring hand-counting the
923  parameters and providing an index into the parameter list instead of
924  placing it next to the parameter as for STDC_UNUSED.
925 
926  For both of these issues the gcc maintainers' response was "not our
927  problem/it's behaving as intended" */
928 
929 #define STDC_NONNULL_ARG( argIndex ) \
930  __attribute__(( nonnull argIndex ))
931 #define STDC_PRINTF_FN( formatIndex, argIndex ) \
932  __attribute__(( format( printf, formatIndex, argIndex ) ))
933 #define STDC_PURE __attribute__(( pure ))
934 #define STDC_UNUSED __attribute__(( unused ))
935 
936 /* The return-value-checking annotation should really be
937  STDC_WARN_UNUSED_RESULT but since the PREfast attributes are defined and
938  widely used within cryptlib while the C standard ones don't even
939  officially exist yet, we allow the PREfast naming to take precedence */
940 
941 #define CHECK_RETVAL \
942  __attribute__(( warn_unused_result ))
943 #define CHECK_RETVAL_BOOL CHECK_RETVAL
944 #define CHECK_RETVAL_ENUM( name ) CHECK_RETVAL
945 #define CHECK_RETVAL_LENGTH CHECK_RETVAL
946 #define CHECK_RETVAL_PTR CHECK_RETVAL
947 #define CHECK_RETVAL_RANGE( low, high ) CHECK_RETVAL
948 #define CHECK_RETVAL_SPECIAL CHECK_RETVAL
949 #define CHECK_RETVAL_STRINGOP( length ) CHECK_RETVAL
950 
951 #define CHECK_RETVAL_FNPTR CHECK_RETVAL
952 #define CHECK_RETVAL_BOOL_FNPTR CHECK_RETVAL
953 #define CHECK_RETVAL_LENGTH_FNPTR CHECK_RETVAL
954 #define CHECK_RETVAL_PTR_FNPTR CHECK_RETVAL
955 #define CHECK_RETVAL_SPECIAL_FNPTR CHECK_RETVAL
956 
957 #define CHECK_RETVAL_ERROR CHECK_RETVAL
958 
959 /* gcc's handling of both warn_unused_result and nonnull is just too broken
960  to safely use it in any production code, because of this we require the
961  use to be explicitly enabled. Since clang/LLVM share the gcc front-end
962  and do actually get things right, we don't disable them if we're using
963  clang */
964 
965 #if !( defined( USE_GCC_ATTRIBUTES ) || defined( __clang_analyzer__ ) )
966  #undef STDC_NONNULL_ARG
967  #define STDC_NONNULL_ARG( argIndex )
968  #undef CHECK_RETVAL
969  #define CHECK_RETVAL
970 #endif /* gcc with use of dangerous attributes disabled */
971 
972 /* clang/LLVM uses gcc as a front-end so we can also end up in the gcc case
973  if we're using clang. The following defines are for clang with gcc as a
974  front-end */
975 
976 #ifdef __clang_analyzer__
977 
978 /* Since clang, unlike gcc, gets CHECK_RETVAL and STDC_NONNULL_ARG right, we
979  can enable it not only for cryptlib functions but also for C library
980  ones. To do this we override at-risk functions with our own ones whose
981  prototypes allow for extended checking with clang */
982 
983 CHECK_RETVAL \
984  void *_checked_malloc( size_t size );
985 STDC_NONNULL_ARG( ( 1 ) ) \
986  void _checked_free( void *ptr );
987 
988 #define malloc( x ) _checked_malloc( x )
989 #define free( x ) _checked_free( x )
990 
991 CHECK_RETVAL STDC_NONNULL_ARG( ( 1, 2 ) ) \
992  int _checked_memcmp( const void *ptr1, const void *ptr2, size_t num );
993 STDC_NONNULL_ARG( ( 1, 2 ) ) \
994  void *_checked_memcpy( void *dest, const void *src, size_t num );
995 STDC_NONNULL_ARG( ( 1, 2 ) ) \
996  void *_checked_memmove( void *dest, const void *src, size_t num );
997 STDC_NONNULL_ARG( ( 1 ) ) \
998  void *_checked_memset( void *ptr, int value, size_t num );
999 
1000 #define memcmp( x, y, z ) _checked_memcmp( x, y, z )
1001 #define memcpy( x, y, z ) _checked_memcpy( x, y, z )
1002 #define memmove( x, y, z ) _checked_memmove( x, y, z )
1003 #define memset( x, y, z ) _checked_memset( x, y, z )
1004 
1005 /* Unfortunately clang doesn't provide any real means of guiding the
1006  analyser, the best that we can do is use an ENSURES() */
1007 
1008 #define ANALYSER_HINT( expr ) ENSURES( expr )
1009 
1010 #endif /* clang/LLVM */
1011 
1012 /* gcc can also provide approximate guessing at buffer overflows. This is
1013  sufficiently hit-and-miss, and subject to platform-specific false
1014  positives and other glitches, that we only enable it for the test build
1015  in case it catches something there. clang does a much better job at
1016  finding issues without all of the accompanying problems */
1017 
1018 #ifdef USE_GCC_ATTRIBUTES
1019 
1020 #define bos( x ) __builtin_object_size( x, 0 )
1021 
1022 #undef memcpy
1023 #define memcpy( dest, src, count ) \
1024  __builtin___memcpy_chk( dest, src, count, bos( dest ) )
1025 #undef memmove
1026 #define memmove( dest, src, count ) \
1027  __builtin___memmove_chk( dest, src, count, bos( dest ) )
1028 #undef memset
1029 #define memset( ptr, value, count ) \
1030  __builtin___memset_chk( ptr, value, count, bos( ptr ) )
1031 #undef strcpy
1032 #define strcpy( dest, src ) \
1033  __builtin___strcpy_chk( dest, src, bos( dest ) )
1034 #undef strncpy
1035 #define strncpy( dest, src, size ) \
1036  __builtin___strncpy_chk( dest, src, size, bos( dest ) )
1037 #undef strcat
1038 #define strcat( dest, src ) \
1039  __builtin___strcat_chk( dest, src, bos( dest ) )
1040 
1041 #endif /* gcc on the test platform */
1042 
1043 #endif /* gcc/C'0x */
1044 
1045 /****************************************************************************
1046 * *
1047 * No Analysis *
1048 * *
1049 ****************************************************************************/
1050 
1051 #ifndef CHECK_RETVAL
1052 
1053 #define CHECK_RETVAL
1054 #define CHECK_RETVAL_BOOL
1055 #define CHECK_RETVAL_ENUM( name )
1056 #define CHECK_RETVAL_LENGTH
1057 #define CHECK_RETVAL_PTR
1058 #define CHECK_RETVAL_RANGE( low, high )
1059 #define CHECK_RETVAL_SPECIAL
1060 #define CHECK_RETVAL_STRINGOP( length )
1061 
1062 #define CHECK_RETVAL_FNPTR
1063 #define CHECK_RETVAL_BOOL_FNPTR
1064 #define CHECK_RETVAL_LENGTH_FNPTR
1065 #define CHECK_RETVAL_PTR_FNPTR
1066 #define CHECK_RETVAL_SPECIAL_FNPTR
1067 
1068 #define CHECK_RETVAL_ERROR
1069 
1070 #endif /* No basic analysis support */
1071 
1072 #ifndef RETVAL
1073 
1074 #define RETVAL
1075 #define RETVAL_BOOL
1076 #define RETVAL_RANGE( low, high )
1077 
1078 #define RETVAL_FNPTR
1079 
1080 #define IN_INT
1081 #define IN_INT_OPT
1082 #define IN_INT_Z
1083 #define IN_INT_SHORT
1084 #define IN_INT_SHORT_Z
1085 #define OUT_INT_Z
1086 #define OUT_INT_SHORT_Z
1087 #define OUT_OPT_INT_Z
1088 
1089 #define IN_ALGO
1090 #define IN_ALGO_OPT
1091 #define IN_ATTRIBUTE
1092 #define IN_ATTRIBUTE_OPT
1093 #define IN_BYTE
1094 #define IN_CHAR
1095 #define IN_ERROR
1096 #define IN_HANDLE
1097 #define IN_HANDLE_OPT
1098 #define IN_KEYID
1099 #define IN_KEYID_OPT
1100 #define IN_MESSAGE
1101 #define IN_MODE
1102 #define IN_MODE_OPT
1103 #define IN_PORT
1104 #define IN_PORT_OPT
1105 #define IN_RANGE( min, max )
1106 #define IN_RANGE_FIXED( value )
1107 #define IN_STATUS
1108 #define INOUT_HANDLE
1109 #define INOUT_RANGE( min, max )
1110 #define OUT_ALGO_Z
1111 #define OUT_OPT_ALGO_Z
1112 #define OUT_ATTRIBUTE_Z
1113 #define OUT_OPT_ATTRIBUTE_Z
1114 #define OUT_BOOL
1115 #define OUT_OPT_BOOL
1116 #define OUT_OPT_BYTE
1117 #define OUT_ERROR
1118 #define OUT_HANDLE_OPT
1119 #define OUT_OPT_HANDLE_OPT
1120 #define OUT_PORT_Z
1121 #define OUT_RANGE( min, max )
1122 #define OUT_OPT_RANGE( min, max )
1123 #define OUT_STATUS
1124 
1125 #define IN_LENGTH
1126 #define IN_LENGTH_OPT
1127 #define IN_LENGTH_FIXED( size )
1128 #define IN_LENGTH_MIN( min )
1129 #define IN_LENGTH_Z
1130 #define IN_LENGTH_SHORT
1131 #define IN_LENGTH_SHORT_MIN( min )
1132 #define IN_LENGTH_SHORT_OPT
1133 #define IN_LENGTH_SHORT_Z
1134 #define INOUT_LENGTH_Z
1135 #define INOUT_LENGTH_SHORT_Z
1136 #define OUT_LENGTH
1137 #define OUT_LENGTH_Z
1138 #define OUT_OPT_LENGTH_Z
1139 #define OUT_LENGTH_SHORT
1140 #define OUT_OPT_LENGTH_SHORT_Z
1141 #define OUT_LENGTH_SHORT_Z
1142 
1143 #define IN_LENGTH_ATTRIBUTE
1144 #define IN_LENGTH_DNS
1145 #define IN_LENGTH_DNS_Z
1146 #define IN_LENGTH_ERRORMESSAGE
1147 #define IN_LENGTH_HASH
1148 #define IN_LENGTH_INDEF
1149 #define IN_LENGTH_IV
1150 #define IN_LENGTH_IV_Z
1151 #define IN_LENGTH_KEY
1152 #define IN_LENGTH_KEYID
1153 #define IN_LENGTH_KEYID_Z
1154 #define IN_LENGTH_NAME
1155 #define IN_LENGTH_NAME_Z
1156 #define IN_LENGTH_OID
1157 #define IN_LENGTH_PKC
1158 #define IN_LENGTH_PKC_Z
1159 #define OUT_LENGTH_DNS_Z
1160 #define OUT_OPT_LENGTH_HASH_Z
1161 #define OUT_LENGTH_PKC_Z
1162 #define OUT_LENGTH_INDEF
1163 #define OUT_OPT_LENGTH_INDEF
1164 
1165 #define IN_TAG
1166 #define IN_TAG_EXT
1167 #define IN_TAG_ENCODED
1168 #define IN_TAG_ENCODED_EXT
1169 #define OUT_TAG_Z
1170 #define OUT_TAG_ENCODED_Z
1171 
1172 #define IN_ENUM( name )
1173 #define IN_ENUM_OPT( name )
1174 #define INOUT_ENUM( name )
1175 #define OUT_ENUM( name )
1176 #define OUT_ENUM_OPT( name )
1177 
1178 #define IN_FLAGS( name )
1179 #define IN_FLAGS_Z( name )
1180 #define OUT_FLAGS_Z( name )
1181 
1182 #define IN_BUFFER( size )
1183 #define IN_BUFFER_C( size )
1184 #define IN_BUFFER_OPT( size )
1185 #define IN_BUFFER_OPT_C( count )
1186 #define INOUT_BUFFER( max, size )
1187 #define INOUT_BUFFER_C( max, size )
1188 #define INOUT_BUFFER_FIXED( size )
1189 #define INOUT_BUFFER_OPT( max, count )
1190 #define OUT_BUFFER( max, size )
1191 #define OUT_BUFFER_C( max, size )
1192 #define OUT_BUFFER_FIXED( max )
1193 #define OUT_BUFFER_FIXED_C( count )
1194 #define OUT_BUFFER_OPT( max, size )
1195 #define OUT_BUFFER_OPT_C( max, size )
1196 #define OUT_BUFFER_OPT_FIXED( max )
1197 
1198 #define IN_ARRAY( count )
1199 #define IN_ARRAY_C( count )
1200 #define IN_ARRAY_OPT( count )
1201 #define IN_ARRAY_OPT_C( count )
1202 #define INOUT_ARRAY( count )
1203 #define INOUT_ARRAY_C( count )
1204 #define OUT_ARRAY( count )
1205 #define OUT_ARRAY_C( count )
1206 #define OUT_ARRAY_OPT( count )
1207 #define OUT_ARRAY_OPT_C( count )
1208 
1209 #define ARRAY( max, count )
1210 #define ARRAY_FIXED( max )
1211 #define BUFFER( max, count )
1212 #define BUFFER_OPT( max, count )
1213 #define BUFFER_FIXED( max )
1214 #define BUFFER_OPT_FIXED( max )
1215 #define BUFFER_UNSPECIFIED( max )
1216 
1217 #define OUT_BUFFER_ALLOC( length )
1218 #define OUT_BUFFER_ALLOC_OPT( length )
1219 
1220 #define IN
1221 #define IN_OPT
1222 #define INOUT
1223 #define INOUT_OPT
1224 #define OUT
1225 #define OUT_OPT
1226 
1227 #define INOUT_PTR
1228 #define OUT_PTR
1229 #define OUT_OPT_PTR
1230 #define OUT_OPT_PTR_OPT
1231 
1232 #ifndef ANALYSER_HINT
1233  #define ANALYSER_HINT( expr )
1234 #endif /* ANALYSER_HINT */
1235 #if defined( __WINCE__ )
1236  /* The Windows CE SDK defines CALLBACK_FUNCTION itself but the CE version
1237  is never used by cryptlib so we simply undefine the CE version */
1238  #undef CALLBACK_FUNCTION
1239 #endif /* WinCE */
1240 #define CALLBACK_FUNCTION
1241 #define FORMAT_STRING
1242 #define IN_STRING
1243 #define IN_STRING_OPT
1244 #define TYPECAST( ctype )
1245 
1246 #endif /* No extended analysis support */
1247 
1248 #ifndef STDC_NONNULL_ARG
1249 
1250 #define STDC_NONNULL_ARG( argIndex )
1251 #define STDC_PRINTF_FN( formatIndex, argIndex )
1252 #define STDC_PURE
1253 #define STDC_UNUSED
1254 
1255 #endif /* No C'0x attribute support */
1256 
1257 #endif /* _ANALYSE_DEFINED */
Generated on Thu Jan 10 2013 10:00:50 for cryptlib by   doxygen 1.8.2