VirtualBox

source: vbox/trunk/include/iprt/asn1.h@ 103224

Last change on this file since 103224 was 100490, checked in by vboxsync, 15 months ago

Forward ported r158258 from 6.1: Added RTAsn1DynType_SetToObjId for use in constructing a RTCRX509SUBJECTPUBLICKEYINFO structure for OpenSSL. bugref:10479 ticketf:21621

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 99.5 KB
Line 
1/** @file
2 * IPRT - Abstract Syntax Notation One (ASN.1).
3 */
4
5/*
6 * Copyright (C) 2006-2023 Oracle and/or its affiliates.
7 *
8 * This file is part of VirtualBox base platform packages, as
9 * available from https://www.virtualbox.org.
10 *
11 * This program is free software; you can redistribute it and/or
12 * modify it under the terms of the GNU General Public License
13 * as published by the Free Software Foundation, in version 3 of the
14 * License.
15 *
16 * This program is distributed in the hope that it will be useful, but
17 * WITHOUT ANY WARRANTY; without even the implied warranty of
18 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
19 * General Public License for more details.
20 *
21 * You should have received a copy of the GNU General Public License
22 * along with this program; if not, see <https://www.gnu.org/licenses>.
23 *
24 * The contents of this file may alternatively be used under the terms
25 * of the Common Development and Distribution License Version 1.0
26 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
27 * in the VirtualBox distribution, in which case the provisions of the
28 * CDDL are applicable instead of those of the GPL.
29 *
30 * You may elect to license modified versions of this file under the
31 * terms and conditions of either the GPL or the CDDL or both.
32 *
33 * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
34 */
35
36#ifndef IPRT_INCLUDED_asn1_h
37#define IPRT_INCLUDED_asn1_h
38#ifndef RT_WITHOUT_PRAGMA_ONCE
39# pragma once
40#endif
41
42#include <iprt/time.h>
43#include <iprt/stdarg.h>
44#include <iprt/errcore.h>
45#include <iprt/formats/asn1.h>
46
47
48RT_C_DECLS_BEGIN
49
50/** @defgroup grp_rt_asn1 RTAsn1 - Abstract Syntax Notation One
51 * @ingroup grp_rt
52 * @{
53 */
54
55
56/** Pointer to ASN.1 allocation information. */
57typedef struct RTASN1ALLOCATION *PRTASN1ALLOCATION;
58/** Pointer to ASN.1 array allocation information. */
59typedef struct RTASN1ARRAYALLOCATION *PRTASN1ARRAYALLOCATION;
60/** Pointer to a ASN.1 byte decoder cursor. */
61typedef struct RTASN1CURSOR *PRTASN1CURSOR;
62
63
64/**
65 * Sketch of a custom ASN.1 allocator virtual method table.
66 *
67 * Any information required by the allocator should be associated with this
68 * structure, i.e. use this as a kind of parent class. This saves storage in
69 * RTASN1ALLOCATORINFO and possibly reduces the number of parameters by one.
70 */
71typedef struct RTASN1ALLOCATORVTABLE
72{
73 /**
74 * Free a chunk of memory allocated by this allocator.
75 *
76 * @returns IPRT status code.
77 * @param pThis Pointer to the vtable structure.
78 * @param pAllocation Pointer to the allocation info structure.
79 * @param pv Pointer to the memory that shall be freed. Not NULL.
80 */
81 DECLCALLBACKMEMBER(void, pfnFree,(struct RTASN1ALLOCATORVTABLE const *pThis, PRTASN1ALLOCATION pAllocation,
82 void *pv));
83 /**
84 * Allocates a chunk of memory, all initialized to zero.
85 *
86 * @returns IPRT status code.
87 * @param pThis Pointer to the vtable structure.
88 * @param pAllocation Pointer to the allocation info structure.
89 * @param ppv Where to store the pointer on success.
90 * @param cb The minimum number of bytes to allocate. The actual
91 * number of bytes allocated shall be stored in
92 * pInfo->cbAllocated on success.
93 */
94 DECLCALLBACKMEMBER(int, pfnAlloc,(struct RTASN1ALLOCATORVTABLE const *pThis, PRTASN1ALLOCATION pAllocation,
95 void **ppv, size_t cb));
96 /**
97 * Reallocates a memory allocation.
98 *
99 * New memory does not need to be initialized, the caller takes care of that.
100 *
101 * This will not need to deal with free (@a cbNew == 0) or the initial
102 * allocation (@a pvOld == NULL), those calls will be directed to pfnFree and
103 * pfnAlloc respectively.
104 *
105 * @returns IPRT status code.
106 * @param pThis Pointer to the vtable structure.
107 * @param pAllocation Pointer to the allocation info structure.
108 * @param pvOld Pointer to the current allocation. Shall remain
109 * valid on failure, but may be invalid on success.
110 * @param ppvNew Where to store the pointer on success. Shall not be
111 * touched, except on successful returns.
112 * @param cbNew The new minimum allocation size. The actual number
113 * of bytes allocated shall be stored in
114 * pInfo->cbAllocated on success.
115 */
116 DECLCALLBACKMEMBER(int, pfnRealloc,(struct RTASN1ALLOCATORVTABLE const *pThis, PRTASN1ALLOCATION pAllocation,
117 void *pvOld, void **ppvNew, size_t cbNew));
118
119 /**
120 * Frees an array allocation (the array an all instances in it).
121 *
122 * @returns IPRT status code.
123 * @param pThis Pointer to the vtable structure.
124 * @param pAllocation Pointer to the allocation info structure.
125 * @param papvArray Pointer to the pointer array to be freed. Not NULL.
126 */
127 DECLCALLBACKMEMBER(void, pfnFreeArray,(struct RTASN1ALLOCATORVTABLE const *pThis, PRTASN1ARRAYALLOCATION pAllocation,
128 void **papvArray));
129 /**
130 * Grows the array to at least @a cMinEntries.
131 *
132 * The entries are initalized with ZEROs.
133 *
134 * @returns IPRT status code.
135 * @param pThis Pointer to the vtable structure.
136 * @param pAllocation Pointer to the allocation info structure.
137 * @param ppapvArray Pointer to the pointer to the array to be grown (or
138 * allocated).
139 * @param cMinEntries The minimum number of entries (array size and
140 * instantiated entries) that must be available
141 * on successful return.
142 */
143 DECLCALLBACKMEMBER(int, pfnGrowArray,(struct RTASN1ALLOCATORVTABLE const *pThis, PRTASN1ARRAYALLOCATION pAllocation,
144 void ***ppapvArray, uint32_t cMinEntries));
145 /**
146 * Shrinks the array (depends on allocator policy).
147 *
148 * If memory isn't freed, the implementation must fill the entries being
149 * shredded with ZEROs so the growth optimizations in RTAsn1MemResizeArray
150 * returns ZEROed entries.
151 *
152 * @returns IPRT status code.
153 * @param pThis Pointer to the vtable structure.
154 * @param pAllocation Pointer to the allocation info structure.
155 * @param ppapvArray Pointer to the pointer to the array to shrunk.
156 * @param cNew The new entry count.
157 * @param cCurrent The new entry count.
158 */
159 DECLCALLBACKMEMBER(void, pfnShrinkArray,(struct RTASN1ALLOCATORVTABLE const *pThis, PRTASN1ARRAYALLOCATION pAllocation,
160 void ***ppapvArray, uint32_t cNew, uint32_t cCurrent));
161} RTASN1ALLOCATORVTABLE;
162/** Pointer to an ASN.1 allocator vtable. */
163typedef RTASN1ALLOCATORVTABLE *PRTASN1ALLOCATORVTABLE;
164/** Pointer to a const ASN.1 allocator vtable. */
165typedef RTASN1ALLOCATORVTABLE const *PCRTASN1ALLOCATORVTABLE;
166
167/** The default ASN.1 allocator. */
168extern RTDATADECL(RTASN1ALLOCATORVTABLE const) g_RTAsn1DefaultAllocator;
169
170/** The Electric Fence ASN.1 allocator. */
171extern RTDATADECL(RTASN1ALLOCATORVTABLE const) g_RTAsn1EFenceAllocator;
172
173/** The safer ASN.1 allocator for sensitive data. */
174extern RTDATADECL(RTASN1ALLOCATORVTABLE const) g_RTAsn1SaferAllocator;
175
176
177/**
178 * Allocation information.
179 */
180typedef struct RTASN1ALLOCATION
181{
182 /** The number of bytes currently allocated. */
183 uint32_t cbAllocated;
184 /** Number of realloc calls. */
185 uint16_t cReallocs;
186 /** Reserved / padding. */
187 uint16_t uReserved0;
188 /** Allocator vtable, NULL for the default allocator. */
189 PCRTASN1ALLOCATORVTABLE pAllocator;
190} RTASN1ALLOCATION;
191
192
193/**
194 * Pointer array allocation information.
195 *
196 * Used by SET OF and SEQUENCE OF structures (typically automatically
197 * generated).
198 */
199typedef struct RTASN1ARRAYALLOCATION
200{
201 /** The size of the array entry. */
202 uint32_t cbEntry;
203 /** The size of the pointer array allocation. */
204 uint32_t cPointersAllocated;
205 /** Number of entry instances allocated. This can be greater than the
206 * official array size. */
207 uint32_t cEntriesAllocated;
208 /** Number of array resizing calls (for increasing growth rate).
209 * Maintained by RTAsn1MemResizeArray(). */
210 uint16_t cResizeCalls;
211 /** Reserved / padding. */
212 uint16_t uReserved0;
213 /** Allocator vtable, NULL for the default allocator. */
214 PCRTASN1ALLOCATORVTABLE pAllocator;
215} RTASN1ARRAYALLOCATION;
216
217
218/**
219 * Allocate a block of zero initialized memory.
220 *
221 * @returns IPRT status code.
222 * @param pAllocation The allocation record (initialized by
223 * RTAsn1CursorInitAllocation or similar).
224 * @param ppvMem Where to return the pointer to the block.
225 * @param cbMem The minimum number of bytes to allocate.
226 */
227RTDECL(int) RTAsn1MemAllocZ(PRTASN1ALLOCATION pAllocation, void **ppvMem, size_t cbMem);
228
229/**
230 * Allocates a block of memory initialized to the content of @a pvSrc.
231 *
232 * @returns IPRT status code.
233 * @param pAllocation The allocation record (initialized by
234 * RTAsn1CursorInitAllocation or similar).
235 * @param ppvMem Where to return the pointer to the block.
236 * @param pvSrc The source memory.
237 * @param cbMem The minimum number of bytes to allocate.
238 */
239RTDECL(int) RTAsn1MemDup(PRTASN1ALLOCATION pAllocation, void **ppvMem, void const *pvSrc, size_t cbMem);
240
241/**
242 * Free a memory block.
243 *
244 * @param pAllocation The allocation record (initialized by
245 * RTAsn1CursorInitAllocation or similar).
246 * @param pv The memory block to free. NULL will be ignored.
247 */
248RTDECL(void) RTAsn1MemFree(PRTASN1ALLOCATION pAllocation, void *pv);
249
250/**
251 * Initalize an allocation.
252 *
253 * @returns pAllocation
254 * @param pAllocation The allocation record (initialized by
255 * RTAsn1CursorInitAllocation or similar).
256 * @param pAllocator The allocator
257 */
258RTDECL(PRTASN1ALLOCATION) RTAsn1MemInitAllocation(PRTASN1ALLOCATION pAllocation, PCRTASN1ALLOCATORVTABLE pAllocator);
259
260/**
261 * Initalize an array allocation.
262 *
263 * @returns pAllocation
264 * @param pAllocation The allocation record (initialized by
265 * RTAsn1CursorInitAllocation or similar).
266 * @param pAllocator The allocator
267 * @param cbEntry The entry size.
268 */
269RTDECL(PRTASN1ARRAYALLOCATION) RTAsn1MemInitArrayAllocation(PRTASN1ARRAYALLOCATION pAllocation,
270 PCRTASN1ALLOCATORVTABLE pAllocator, size_t cbEntry);
271
272/**
273 * Resize an array with zero initialized memory.
274 *
275 * @returns IPRT status code.
276 * @param pAllocation The allocation record (initialized by
277 * RTAsn1CursorInitAllocation or similar).
278 * @param ppapvArray Pointer to the variable pointing to the array. This is
279 * both input and output. Remains valid on failure.
280 * @param cCurrent The current entry count. (Relevant for zero
281 * initialization of the new entries.)
282 * @param cNew The new entry count.
283 */
284RTDECL(int) RTAsn1MemResizeArray(PRTASN1ARRAYALLOCATION pAllocation, void ***ppapvArray, uint32_t cCurrent, uint32_t cNew);
285
286/**
287 * Frees an array and all its entries.
288 *
289 * @param pAllocation The array allocation record (initialized by
290 * RTAsn1CursorInitArrayAllocation or similar).
291 * @param papvArray The array to free. NULL is ignored.
292 */
293RTDECL(void) RTAsn1MemFreeArray(PRTASN1ARRAYALLOCATION pAllocation, void **papvArray);
294
295
296/** Pointer to a core ASN.1 encoding info structure. */
297typedef struct RTASN1CORE *PRTASN1CORE;
298/** Pointer to a const core ASN.1 encoding info structure. */
299typedef struct RTASN1CORE const *PCRTASN1CORE;
300
301RTDECL(int) RTAsn1ContentAllocZ(struct RTASN1CORE *pAsn1Core, size_t cb, PCRTASN1ALLOCATORVTABLE pAllocator);
302RTDECL(int) RTAsn1ContentDup(struct RTASN1CORE *pAsn1Core, void const *pvSrc, size_t cbSrc, PCRTASN1ALLOCATORVTABLE pAllocator);
303RTDECL(int) RTAsn1ContentReallocZ(struct RTASN1CORE *pAsn1Core, size_t cb, PCRTASN1ALLOCATORVTABLE pAllocator);
304RTDECL(void) RTAsn1ContentFree(struct RTASN1CORE *pAsn1Core);
305
306
307
308/**
309 * ASN.1 object enumeration callback.
310 *
311 * @returns IPRT status code. VINF_SUCCESS continues the enumberation, all
312 * others quit it and is returned to the caller's caller.
313 * @param pAsn1Core The ASN.1 object we're called back about.
314 * @param pszName The member name. Array member names ends with
315 * '[#]'.
316 * @param uDepth The current depth.
317 * @param pvUser Callback user parameter.
318 */
319typedef DECLCALLBACKTYPE(int, FNRTASN1ENUMCALLBACK,(struct RTASN1CORE *pAsn1Core, const char *pszName, uint32_t uDepth,
320 void *pvUser));
321/** Pointer to an ASN.1 object enumeration callback. */
322typedef FNRTASN1ENUMCALLBACK *PFNRTASN1ENUMCALLBACK;
323
324/**
325 * ASN.1 object encoding writer callback.
326 *
327 * @returns IPRT status code.
328 * @param pvBuf Pointer to the bytes to output.
329 * @param cbToWrite The number of bytes to write.
330 * @param pvUser Callback user parameter.
331 * @param pErrInfo Where to store extended error info. Optional.
332 */
333typedef DECLCALLBACKTYPE(int, FNRTASN1ENCODEWRITER,(const void *pvBuf, size_t cbToWrite, void *pvUser, PRTERRINFO pErrInfo));
334/** Pointer to an ASN.1 encoding writer callback. */
335typedef FNRTASN1ENCODEWRITER *PFNRTASN1ENCODEWRITER;
336
337/** @name ASN.1 Vtable Method Types
338 * @{ */
339
340/**
341 * Destructor.
342 *
343 * RTAsn1Destroy will first destroy all children by recursive calls to pfnEnum,
344 * afterwards it will call this method to release any memory or other resources
345 * associated with this object. The memory backing the object structure shall
346 * not be freed by this method.
347 *
348 * @param pThisCore Pointer to the ASN.1 core to destroy.
349 */
350typedef DECLCALLBACKTYPE(void, FNRTASN1COREVTDTOR,(PRTASN1CORE pThisCore));
351/** Pointer to a FNRTASN1COREVTDTOR method. */
352typedef FNRTASN1COREVTDTOR *PFNRTASN1COREVTDTOR;
353
354/**
355 * Enumerate members (not necessary for primitive objects).
356 *
357 * @returns IPRT status code, any non VINF_SUCCESS value stems from pfnCallback.
358 * @param pThisCore Pointer to the ASN.1 core to enumerate members of.
359 * @param pfnCallback The callback.
360 * @param uDepth The depth of this object. Children are at +1.
361 * @param pvUser Callback user argument.
362 */
363typedef DECLCALLBACKTYPE(int, FNRTASN1COREVTENUM,(PRTASN1CORE pThisCore, PFNRTASN1ENUMCALLBACK pfnCallback,
364 uint32_t uDepth, void *pvUser));
365/** Pointer to a FNRTASN1COREVTENUM method. */
366typedef FNRTASN1COREVTENUM *PFNRTASN1COREVTENUM;
367
368/**
369 * Clone method.
370 *
371 * @param pThisCore Pointer to the ASN.1 core to initialize as a clone
372 * of pSrcClone. (The caller is responsible for making
373 * sure there is sufficent space and such.)
374 * @param pSrcCore The object to clone.
375 * @param pAllocator The allocator to use.
376 */
377typedef DECLCALLBACKTYPE(int, FNRTASN1COREVTCLONE,(PRTASN1CORE pThisCore, PCRTASN1CORE pSrcCore,
378 PCRTASN1ALLOCATORVTABLE pAllocator));
379/** Pointer to a FNRTASN1COREVTCLONE method. */
380typedef FNRTASN1COREVTCLONE *PFNRTASN1COREVTCLONE;
381
382/**
383 * Compare method.
384 *
385 * The caller makes sure both cores are present and have the same Vtable.
386 *
387 * @returns 0 if equal, -1 if @a pLeft is smaller, 1 if @a pLeft is larger.
388 * @param pLeftCore Pointer to the ASN.1 core of the left side object.
389 * @param pRightCore Pointer to the ASN.1 core of the right side object.
390 */
391typedef DECLCALLBACKTYPE(int, FNRTASN1COREVTCOMPARE,(PCRTASN1CORE pLeftCore, PCRTASN1CORE pRightCore));
392/** Pointer to a FNRTASN1COREVTCOMPARE method. */
393typedef FNRTASN1COREVTCOMPARE *PFNRTASN1COREVTCOMPARE;
394
395/**
396 * Check sanity method.
397 *
398 * @returns IPRT status code.
399 * @param pThisCore Pointer to the ASN.1 core of the object to check out.
400 * @param fFlags See RTASN1_CHECK_SANITY_F_XXX.
401 * @param pErrInfo Where to return additional error details. Optional.
402 * @param pszErrorTag Tag for the additional error details.
403 */
404typedef DECLCALLBACKTYPE(int, FNRTASN1COREVTCHECKSANITY,(PCRTASN1CORE pThisCore, uint32_t fFlags,
405 PRTERRINFO pErrInfo, const char *pszErrorTag));
406/** Pointer to a FNRTASN1COREVTCHECKSANITY method. */
407typedef FNRTASN1COREVTCHECKSANITY *PFNRTASN1COREVTCHECKSANITY;
408
409/**
410 * Optional encoding preparations.
411 *
412 * On successful return, the pThisCore->cb value shall be valid and up to date.
413 * Will be called for any present object, including ones with default values and
414 * similar.
415 *
416 * @returns IPRT status code
417 * @param pThisCore Pointer to the ASN.1 core to enumerate members of.
418 * @param fFlags Encoding flags, RTASN1ENCODE_F_XXX.
419 * @param pErrInfo Where to return extra error information. Optional.
420 */
421typedef DECLCALLBACKTYPE(int, FNRTASN1COREVTENCODEPREP,(PRTASN1CORE pThisCore, uint32_t fFlags, PRTERRINFO pErrInfo));
422/** Pointer to a FNRTASN1COREVTENCODEWRITE method. */
423typedef FNRTASN1COREVTENCODEPREP *PFNRTASN1COREVTENCODEPREP;
424
425/**
426 * Optional encoder writer.
427 *
428 * This writes the header as well as all the content. Will be called for any
429 * present object, including ones with default values and similar.
430 *
431 * @returns IPRT status code.
432 * @param pThisCore Pointer to the ASN.1 core to enumerate members of.
433 * @param fFlags Encoding flags, RTASN1ENCODE_F_XXX.
434 * @param pfnWriter The output writer function.
435 * @param pvUser The user context for the writer function.
436 * @param pErrInfo Where to return extra error information. Optional.
437 */
438typedef DECLCALLBACKTYPE(int, FNRTASN1COREVTENCODEWRITE,(PRTASN1CORE pThisCore, uint32_t fFlags, PFNRTASN1ENCODEWRITER pfnWriter,
439 void *pvUser, PRTERRINFO pErrInfo));
440/** Pointer to a FNRTASN1COREVTENCODEWRITE method. */
441typedef FNRTASN1COREVTENCODEWRITE *PFNRTASN1COREVTENCODEWRITE;
442/** @} */
443
444/** Mask of common flags. These will be propagated during sanity checking.
445 * Bits not in this mask are type specfic. */
446#define RTASN1_CHECK_SANITY_F_COMMON_MASK UINT32_C(0xffff0000)
447
448/**
449 * ASN.1 core vtable.
450 */
451typedef struct RTASN1COREVTABLE
452{
453 /** The name. */
454 const char *pszName;
455 /** Size of the structure. */
456 uint32_t cbStruct;
457 /** The default tag, UINT8_MAX if not applicable. */
458 uint8_t uDefaultTag;
459 /** The default class and flags. */
460 uint8_t fDefaultClass;
461 /** Reserved for later / alignment. */
462 uint16_t uReserved;
463 /** @copydoc FNRTASN1COREVTDTOR */
464 PFNRTASN1COREVTDTOR pfnDtor;
465 /** @copydoc FNRTASN1COREVTENUM */
466 PFNRTASN1COREVTENUM pfnEnum;
467 /** @copydoc FNRTASN1COREVTCLONE */
468 PFNRTASN1COREVTCLONE pfnClone;
469 /** @copydoc FNRTASN1COREVTCOMPARE */
470 PFNRTASN1COREVTCOMPARE pfnCompare;
471 /** @copydoc FNRTASN1COREVTCHECKSANITY */
472 PFNRTASN1COREVTCHECKSANITY pfnCheckSanity;
473 /** @copydoc FNRTASN1COREVTENCODEPREP */
474 PFNRTASN1COREVTENCODEPREP pfnEncodePrep;
475 /** @copydoc FNRTASN1COREVTENUM */
476 PFNRTASN1COREVTENCODEWRITE pfnEncodeWrite;
477} RTASN1COREVTABLE;
478/** Pointer to an ASN.1 allocator vtable. */
479typedef struct RTASN1COREVTABLE *PRTASN1COREVTABLE;
480/** Pointer to a const ASN.1 allocator vtable. */
481typedef RTASN1COREVTABLE const *PCRTASN1COREVTABLE;
482
483
484/** @name Helper macros for prototyping standard functions for an ASN.1 type.
485 * @{ */
486
487#define RTASN1TYPE_STANDARD_PROTOTYPES_NO_GET_CORE(a_TypeNm, a_DeclMacro, a_ImplExtNm) \
488 a_DeclMacro(int) RT_CONCAT(a_ImplExtNm,_Init)(RT_CONCAT(P,a_TypeNm) pThis, PCRTASN1ALLOCATORVTABLE pAllocator); \
489 a_DeclMacro(int) RT_CONCAT(a_ImplExtNm,_Clone)(RT_CONCAT(P,a_TypeNm) pThis, RT_CONCAT(PC,a_TypeNm) pSrc, \
490 PCRTASN1ALLOCATORVTABLE pAllocator); \
491 a_DeclMacro(void) RT_CONCAT(a_ImplExtNm,_Delete)(RT_CONCAT(P,a_TypeNm) pThis); \
492 a_DeclMacro(int) RT_CONCAT(a_ImplExtNm,_Enum)(RT_CONCAT(P,a_TypeNm) pThis, PFNRTASN1ENUMCALLBACK pfnCallback, \
493 uint32_t uDepth, void *pvUser); \
494 a_DeclMacro(int) RT_CONCAT(a_ImplExtNm,_Compare)(RT_CONCAT(PC,a_TypeNm) pLeft, RT_CONCAT(PC,a_TypeNm) pRight); \
495 a_DeclMacro(int) RT_CONCAT(a_ImplExtNm,_DecodeAsn1)(PRTASN1CURSOR pCursor, uint32_t fFlags, RT_CONCAT(P,a_TypeNm) pThis,\
496 const char *pszErrorTag); \
497 a_DeclMacro(int) RT_CONCAT(a_ImplExtNm,_CheckSanity)(RT_CONCAT(PC,a_TypeNm) pThis, uint32_t fFlags, \
498 PRTERRINFO pErrInfo, const char *pszErrorTag)
499
500
501#define RTASN1TYPE_STANDARD_PROTOTYPES(a_TypeNm, a_DeclMacro, a_ImplExtNm, a_Asn1CoreNm) \
502 DECL_FORCE_INLINE(PRTASN1CORE) RT_CONCAT(a_ImplExtNm,_GetAsn1Core)(RT_CONCAT(PC,a_TypeNm) pThis) \
503 { return (PRTASN1CORE)&pThis->a_Asn1CoreNm; } \
504 DECLINLINE(bool) RT_CONCAT(a_ImplExtNm,_IsPresent)(RT_CONCAT(PC,a_TypeNm) pThis) \
505 { return pThis && RTASN1CORE_IS_PRESENT(&pThis->a_Asn1CoreNm); } \
506 RTASN1TYPE_STANDARD_PROTOTYPES_NO_GET_CORE(a_TypeNm, a_DeclMacro, a_ImplExtNm)
507
508
509/** Aliases two ASN.1 types, no method aliases. */
510#define RTASN1TYPE_ALIAS_TYPE_ONLY(a_TypeNm, a_AliasType) \
511 typedef a_AliasType a_TypeNm; \
512 typedef a_TypeNm *RT_CONCAT(P,a_TypeNm); \
513 typedef a_TypeNm const *RT_CONCAT(PC,a_TypeNm)
514
515/** Aliases two ASN.1 types and methods. */
516#define RTASN1TYPE_ALIAS(a_TypeNm, a_AliasType, a_ImplExtNm, a_AliasExtNm) \
517 typedef a_AliasType a_TypeNm; \
518 typedef a_TypeNm *RT_CONCAT(P,a_TypeNm); \
519 \
520 DECLINLINE(PRTASN1CORE) RT_CONCAT(a_ImplExtNm,_GetAsn1Core)(a_TypeNm const *pThis) \
521 { return RT_CONCAT(a_AliasExtNm,_GetAsn1Core)(pThis); } \
522 DECLINLINE(bool) RT_CONCAT(a_ImplExtNm,_IsPresent)(a_TypeNm const *pThis) \
523 { return RT_CONCAT(a_AliasExtNm,_IsPresent)(pThis); } \
524 \
525 DECLINLINE(int) RT_CONCAT(a_ImplExtNm,_Init)(RT_CONCAT(P,a_TypeNm) pThis, PCRTASN1ALLOCATORVTABLE pAllocator) \
526 { return RT_CONCAT(a_AliasExtNm,_Init)(pThis, pAllocator); } \
527 DECLINLINE(int) RT_CONCAT(a_ImplExtNm,_Clone)(RT_CONCAT(P,a_TypeNm) pThis, a_TypeNm const *pSrc, \
528 PCRTASN1ALLOCATORVTABLE pAllocator) \
529 { return RT_CONCAT(a_AliasExtNm,_Clone)(pThis, pSrc, pAllocator); } \
530 DECLINLINE(void) RT_CONCAT(a_ImplExtNm,_Delete)(RT_CONCAT(P,a_TypeNm) pThis) \
531 { RT_CONCAT(a_AliasExtNm,_Delete)(pThis); } \
532 DECLINLINE(int) RT_CONCAT(a_ImplExtNm,_Enum)(a_TypeNm *pThis, PFNRTASN1ENUMCALLBACK pfnCallback, \
533 uint32_t uDepth, void *pvUser) \
534 { return RT_CONCAT(a_AliasExtNm,_Enum)(pThis, pfnCallback, uDepth, pvUser); } \
535 DECLINLINE(int) RT_CONCAT(a_ImplExtNm,_Compare)(a_TypeNm const *pLeft, a_TypeNm const *pRight) \
536 { return RT_CONCAT(a_AliasExtNm,_Compare)(pLeft, pRight); } \
537 DECLINLINE(int) RT_CONCAT(a_ImplExtNm,_DecodeAsn1)(PRTASN1CURSOR pCursor, uint32_t fFlags, RT_CONCAT(P,a_TypeNm) pThis,\
538 const char *pszErrorTag) \
539 { return RT_CONCAT(a_AliasExtNm,_DecodeAsn1)(pCursor, fFlags, pThis, pszErrorTag); } \
540 DECLINLINE(int) RT_CONCAT(a_ImplExtNm,_CheckSanity)(a_TypeNm const *pThis, uint32_t fFlags, \
541 PRTERRINFO pErrInfo, const char *pszErrorTag) \
542 { return RT_CONCAT(a_AliasExtNm,_CheckSanity)(pThis, fFlags, pErrInfo, pszErrorTag); } \
543 \
544 typedef a_TypeNm const *RT_CONCAT(PC,a_TypeNm)
545
546/** @} */
547
548
549/**
550 * Core ASN.1 structure for storing encoding details and data location.
551 *
552 * This is used as a 'parent' for all other decoded ASN.1 based structures.
553 */
554typedef struct RTASN1CORE
555{
556 /** The tag.
557 * @remarks 32-bit should be enough for everyone... We don't currently
558 * implement decoding tags larger than 30 anyway. :-) */
559 uint32_t uTag;
560 /** Tag class and flags (ASN1_TAGCLASS_XXX and ASN1_TAGFLAG_XXX). */
561 uint8_t fClass;
562 /** The real tag value for IMPLICT tag overrides. */
563 uint8_t uRealTag;
564 /** The real class value for IMPLICT tag overrides. */
565 uint8_t fRealClass;
566 /** The size of the tag and length ASN.1 header. */
567 uint8_t cbHdr;
568 /** Length. */
569 uint32_t cb;
570 /** IPRT flags (RTASN1CORE_F_XXX). */
571 uint32_t fFlags;
572 /** Pointer to the data.
573 * After decoding this generally points to the encoded data content. When
574 * preparting something for encoding or otherwise constructing things in memory,
575 * this generally points heap memory or read-only constants.
576 * @sa RTAsn1ContentAllocZ, RTAsn1ContentReallocZ, RTAsn1ContentDup,
577 * RTAsn1ContentFree. */
578 RTCPTRUNION uData;
579 /** Pointer to the virtual method table for this object. Optional. */
580 PCRTASN1COREVTABLE pOps;
581} RTASN1CORE;
582/** The Vtable for a RTASN1CORE structure when not in some way use used as a
583 * parent type/class. */
584extern RTDATADECL(RTASN1COREVTABLE const) g_RTAsn1Core_Vtable;
585
586RTASN1TYPE_STANDARD_PROTOTYPES_NO_GET_CORE(RTASN1CORE, RTDECL, RTAsn1Core);
587
588/** @name RTASN1CORE_F_XXX - Flags for RTASN1CORE::fFlags
589 * @{ */
590/** Present/valid. */
591#define RTASN1CORE_F_PRESENT RT_BIT_32(0)
592/** Not present in stream, using default value. */
593#define RTASN1CORE_F_DEFAULT RT_BIT_32(1)
594/** The tag was overriden by an implict context tag or some such thing,
595 * RTASN1CORE::uImplicitTag hold the universal tag value if one exists. */
596#define RTASN1CORE_F_TAG_IMPLICIT RT_BIT_32(2)
597/** Primitive tag with the corresponding RTASN1XXX struct. */
598#define RTASN1CORE_F_PRIMITE_TAG_STRUCT RT_BIT_32(3)
599/** Dummy node typically used with choices, has children, not encoded, must be
600 * ignored. */
601#define RTASN1CORE_F_DUMMY RT_BIT_32(4)
602/** Allocated content (pointed to by uData).
603 * The content should is still be considered 104% read-only by anyone other
604 * than then type methods (pOps and associates). */
605#define RTASN1CORE_F_ALLOCATED_CONTENT RT_BIT_32(5)
606/** Decoded content (pointed to by uData).
607 * Mutually exclusive with RTASN1CORE_F_ALLOCATED_CONTENT. If neither is
608 * set, uData might be NULL or point to some shared static memory for
609 * frequently used values. */
610#define RTASN1CORE_F_DECODED_CONTENT RT_BIT_32(6)
611/** Indefinite length, still pending. */
612#define RTASN1CORE_F_INDEFINITE_LENGTH RT_BIT_32(7)
613/** @} */
614
615
616/** Checks whether an ASN.1 core object present in some way (default data,
617 * decoded data, ...). */
618#define RTASN1CORE_IS_PRESENT(a_pAsn1Core) ( RT_BOOL((a_pAsn1Core)->fFlags) )
619
620/** Checks whether an ASN.1 core object is a dummy object (and is present). */
621#define RTASN1CORE_IS_DUMMY(a_pAsn1Core) ( RT_BOOL((a_pAsn1Core)->fFlags & RTASN1CORE_F_DUMMY) )
622
623/**
624 * Calculates pointer to the raw ASN.1 record.
625 *
626 * ASSUMES that it's decoded content and that cbHdr and uData are both valid.
627 *
628 * @returns Byte pointer to the first tag byte.
629 * @param a_pAsn1Core The ASN.1 core.
630 */
631#define RTASN1CORE_GET_RAW_ASN1_PTR(a_pAsn1Core) ( (a_pAsn1Core)->uData.pu8 - (a_pAsn1Core)->cbHdr )
632
633/**
634 * Calculates the length of the raw ASN.1 record to go with the
635 * RTASN1CORE_GET_RAW_ASN1_PTR() result.
636 *
637 * ASSUMES that it's decoded content and that cbHdr and uData are both valid.
638 *
639 * @returns Size in bytes (uint32_t).
640 * @param a_pAsn1Core The ASN.1 core.
641 */
642#define RTASN1CORE_GET_RAW_ASN1_SIZE(a_pAsn1Core) ( (a_pAsn1Core)->cbHdr + (a_pAsn1Core)->cb )
643
644/**
645 * Retrievs the tag or implicit tag depending on the RTASN1CORE_F_TAG_IMPLICIT
646 * flag.
647 *
648 * @returns The ASN.1 tag of the object.
649 * @param a_pAsn1Core The ASN.1 core.
650 */
651#define RTASN1CORE_GET_TAG(a_pAsn1Core) ( !((a_pAsn1Core)->fFlags & RTASN1CORE_F_TAG_IMPLICIT) ? (a_pAsn1Core)->uTag : (a_pAsn1Core)->uRealTag )
652
653
654DECL_FORCE_INLINE(PRTASN1CORE) RTAsn1Core_GetAsn1Core(PCRTASN1CORE pThis)
655{
656 return (PRTASN1CORE)pThis;
657}
658
659
660DECL_FORCE_INLINE(bool) RTAsn1Core_IsPresent(PCRTASN1CORE pThis)
661{
662 return pThis && RTASN1CORE_IS_PRESENT(pThis);
663}
664
665
666RTDECL(int) RTAsn1Core_InitEx(PRTASN1CORE pAsn1Core, uint32_t uTag, uint8_t fClass, PCRTASN1COREVTABLE pOps, uint32_t fFlags);
667/**
668 * Initialize the ASN.1 core object representation to a default value.
669 *
670 * @returns VINF_SUCCESS
671 * @param pAsn1Core The ASN.1 core.
672 * @param uTag The tag number.
673 * @param fClass The tag class and flags.
674 */
675RTDECL(int) RTAsn1Core_InitDefault(PRTASN1CORE pAsn1Core, uint32_t uTag, uint8_t fClass);
676RTDECL(int) RTAsn1Core_CloneContent(PRTASN1CORE pThis, PCRTASN1CORE pSrc, PCRTASN1ALLOCATORVTABLE pAllocator);
677RTDECL(int) RTAsn1Core_CloneNoContent(PRTASN1CORE pThis, PCRTASN1CORE pSrc);
678RTDECL(int) RTAsn1Core_SetTagAndFlags(PRTASN1CORE pAsn1Core, uint32_t uTag, uint8_t fClass);
679RTDECL(int) RTAsn1Core_ChangeTag(PRTASN1CORE pAsn1Core, uint32_t uTag);
680RTDECL(void) RTAsn1Core_ResetImplict(PRTASN1CORE pThis);
681RTDECL(int) RTAsn1Core_CompareEx(PCRTASN1CORE pLeft, PCRTASN1CORE pRight, bool fIgnoreTagAndClass);
682
683
684/**
685 * Dummy ASN.1 object for use in choices and similar non-sequence structures.
686 *
687 * This allows hooking up destructors, enumerators and such, as well as not
688 * needing custom code for sequence-of / set-of collections.
689 */
690typedef struct RTASN1DUMMY
691{
692 /** Core ASN.1. */
693 RTASN1CORE Asn1Core;
694} RTASN1DUMMY;
695/** Pointer to a dummy record. */
696typedef RTASN1DUMMY *PRTASN1DUMMY;
697
698
699/**
700 * Initalizes a dummy ASN.1 object.
701 *
702 * @returns VINF_SUCCESS.
703 * @param pThis The dummy object.
704 */
705RTDECL(int) RTAsn1Dummy_InitEx(PRTASN1DUMMY pThis);
706
707/**
708 * Standard compliant initalizer.
709 *
710 * @returns VINF_SUCCESS.
711 * @param pThis The dummy object.
712 * @param pAllocator Ignored.
713 */
714DECLINLINE(int) RTAsn1Dummy_Init(PRTASN1DUMMY pThis, PCRTASN1ALLOCATORVTABLE pAllocator)
715{
716 NOREF(pAllocator);
717 return RTAsn1Dummy_InitEx(pThis);
718}
719
720
721/**
722 * ASN.1 sequence core (IPRT representation).
723 */
724typedef struct RTASN1SEQUENCECORE
725{
726 /** Core ASN.1 encoding details. */
727 RTASN1CORE Asn1Core;
728} RTASN1SEQUENCECORE;
729/** Pointer to an ASN.1 sequence core (IPRT representation). */
730typedef RTASN1SEQUENCECORE *PRTASN1SEQUENCECORE;
731/** Pointer to a const ASN.1 sequence core (IPRT representation). */
732typedef RTASN1SEQUENCECORE const *PCRTASN1SEQUENCECORE;
733
734RTDECL(int) RTAsn1SequenceCore_Init(PRTASN1SEQUENCECORE pSeqCore, PCRTASN1COREVTABLE pVtable);
735RTDECL(int) RTAsn1SequenceCore_Clone(PRTASN1SEQUENCECORE pSeqCore, PCRTASN1COREVTABLE pVtable, PCRTASN1SEQUENCECORE pSrc);
736
737/**
738 * ASN.1 sequence-of core (IPRT representation).
739 */
740#if 0
741typedef struct RTASN1SEQOFCORE
742{
743 /** Core ASN.1 encoding details. */
744 RTASN1CORE Asn1Core;
745} RTASN1SEQUENCECORE;
746/** Pointer to an ASN.1 sequence-of core (IPRT representation). */
747typedef RTASN1SEQUENCECORE *PRTASN1SEQUENCECORE;
748/** Pointer to a const ASN.1 sequence-of core (IPRT representation). */
749typedef RTASN1SEQUENCECORE const *PCRTASN1SEQUENCECORE;
750#else
751# define RTASN1SEQOFCORE RTASN1SEQUENCECORE
752# define PRTASN1SEQOFCORE PRTASN1SEQUENCECORE
753# define PCRTASN1SEQOFCORE PCRTASN1SEQUENCECORE
754#endif
755RTDECL(int) RTAsn1SeqOfCore_Init(PRTASN1SEQOFCORE pThis, PCRTASN1COREVTABLE pVtable);
756RTDECL(int) RTAsn1SeqOfCore_Clone(PRTASN1SEQOFCORE pThis, PCRTASN1COREVTABLE pVtable, PCRTASN1SEQOFCORE pSrc);
757
758
759/** Defines the typedefs and prototypes for a generic sequence-of/set-of type. */
760#define RTASN1_IMPL_GEN_SEQ_OR_SET_OF_TYPEDEFS_AND_PROTOS(a_CoreType, a_CoreMember, \
761 a_ThisType, a_ItemType, a_DeclMacro, a_ImplExtNm) \
762 typedef struct a_ThisType \
763 { \
764 /** Sequence/set core. */ \
765 a_CoreType a_CoreMember; \
766 /** The array allocation tracker. */ \
767 RTASN1ARRAYALLOCATION Allocation; \
768 /** Items in the array. */ \
769 uint32_t cItems; \
770 /** Array. */ \
771 RT_CONCAT(P,a_ItemType) *papItems; \
772 } a_ThisType; \
773 typedef a_ThisType *RT_CONCAT(P,a_ThisType); \
774 typedef a_ThisType const *RT_CONCAT(PC,a_ThisType); \
775 a_DeclMacro(int) RT_CONCAT(a_ImplExtNm,_Erase)(RT_CONCAT(P,a_ThisType) pThis, uint32_t iPosition); \
776 a_DeclMacro(int) RT_CONCAT(a_ImplExtNm,_InsertEx)(RT_CONCAT(P,a_ThisType) pThis, uint32_t iPosition, \
777 RT_CONCAT(PC,a_ItemType) pToClone, \
778 PCRTASN1ALLOCATORVTABLE pAllocator, uint32_t *piActualPos); \
779 /** Appends entry with default content, returns index or negative error code. */ \
780 DECLINLINE(int32_t) RT_CONCAT(a_ImplExtNm,_Append)(RT_CONCAT(P,a_ThisType) pThis) \
781 { \
782 uint32_t uPos = pThis->cItems; \
783 int rc = RT_CONCAT(a_ImplExtNm,_InsertEx)(pThis, uPos, NULL /*pToClone*/, pThis->Allocation.pAllocator, &uPos); \
784 if (RT_SUCCESS(rc)) \
785 return (int32_t)uPos; \
786 return rc; \
787 } \
788 RTASN1TYPE_STANDARD_PROTOTYPES(a_ThisType, a_DeclMacro, a_ImplExtNm, a_CoreMember.Asn1Core)
789
790/** Defines the typedefs and prototypes for a generic sequence-of type. */
791#define RTASN1_IMPL_GEN_SEQ_OF_TYPEDEFS_AND_PROTOS(a_SeqOfType, a_ItemType, a_DeclMacro, a_ImplExtNm) \
792 RTASN1_IMPL_GEN_SEQ_OR_SET_OF_TYPEDEFS_AND_PROTOS(RTASN1SEQUENCECORE, SeqCore, a_SeqOfType, a_ItemType, a_DeclMacro, a_ImplExtNm)
793
794
795/**
796 * ASN.1 set core (IPRT representation).
797 */
798typedef struct RTASN1SETCORE
799{
800 /** Core ASN.1 encoding details. */
801 RTASN1CORE Asn1Core;
802} RTASN1SETCORE;
803/** Pointer to an ASN.1 set core (IPRT representation). */
804typedef RTASN1SETCORE *PRTASN1SETCORE;
805/** Pointer to a const ASN.1 set core (IPRT representation). */
806typedef RTASN1SETCORE const *PCRTASN1SETCORE;
807
808RTDECL(int) RTAsn1SetCore_Init(PRTASN1SETCORE pThis, PCRTASN1COREVTABLE pVtable);
809RTDECL(int) RTAsn1SetCore_Clone(PRTASN1SETCORE pThis, PCRTASN1COREVTABLE pVtable, PCRTASN1SETCORE pSrc);
810
811/**
812 * ASN.1 set-of core (IPRT representation).
813 */
814#if 0
815typedef struct RTASN1SETOFCORE
816{
817 /** Core ASN.1 encoding details. */
818 RTASN1CORE Asn1Core;
819} RTASN1SETUENCECORE;
820/** Pointer to an ASN.1 set-of core (IPRT representation). */
821typedef RTASN1SETUENCECORE *PRTASN1SETUENCECORE;
822/** Pointer to a const ASN.1 set-of core (IPRT representation). */
823typedef RTASN1SETUENCECORE const *PCRTASN1SETUENCECORE;
824#else
825# define RTASN1SETOFCORE RTASN1SETCORE
826# define PRTASN1SETOFCORE PRTASN1SETCORE
827# define PCRTASN1SETOFCORE PCRTASN1SETCORE
828#endif
829RTDECL(int) RTAsn1SetOfCore_Init(PRTASN1SETOFCORE pThis, PCRTASN1COREVTABLE pVtable);
830RTDECL(int) RTAsn1SetOfCore_Clone(PRTASN1SETOFCORE pThis, PCRTASN1COREVTABLE pVtable, PCRTASN1SETOFCORE pSrc);
831
832
833/** Defines the typedefs and prototypes for a generic set-of type. */
834#define RTASN1_IMPL_GEN_SET_OF_TYPEDEFS_AND_PROTOS(a_SetOfType, a_ItemType, a_DeclMacro, a_ImplExtNm) \
835 RTASN1_IMPL_GEN_SEQ_OR_SET_OF_TYPEDEFS_AND_PROTOS(RTASN1SETCORE, SetCore, a_SetOfType, a_ItemType, a_DeclMacro, a_ImplExtNm)
836
837
838/*
839 * Declare sets and sequences of the core structure.
840 */
841RTASN1_IMPL_GEN_SEQ_OF_TYPEDEFS_AND_PROTOS(RTASN1SEQOFCORES, RTASN1CORE, RTDECL, RTAsn1SeqOfCores);
842RTASN1_IMPL_GEN_SET_OF_TYPEDEFS_AND_PROTOS(RTASN1SETOFCORES, RTASN1CORE, RTDECL, RTAsn1SetOfCores);
843
844
845/**
846 * ASN.1 null (IPRT representation).
847 */
848typedef struct RTASN1NULL
849{
850 /** Core ASN.1 encoding details. */
851 RTASN1CORE Asn1Core;
852} RTASN1NULL;
853/** Pointer to an ASN.1 null (IPRT representation). */
854typedef RTASN1NULL *PRTASN1NULL;
855/** Pointer to a const ASN.1 null (IPRT representation). */
856typedef RTASN1NULL const *PCRTASN1NULL;
857/** The Vtable for a RTASN1NULL structure. */
858extern RTDATADECL(RTASN1COREVTABLE const) g_RTAsn1Null_Vtable;
859
860RTASN1TYPE_STANDARD_PROTOTYPES(RTASN1NULL, RTDECL, RTAsn1Null, Asn1Core);
861
862
863/**
864 * ASN.1 integer (IPRT representation).
865 */
866typedef struct RTASN1INTEGER
867{
868 /** Core ASN.1 encoding details. */
869 RTASN1CORE Asn1Core;
870 /** The unsigned C representation of the 64 least significant bits.
871 * @note A ASN.1 integer doesn't define signed/unsigned and can have any
872 * length you like. Thus, the user needs to check the size and
873 * preferably use the access APIs for signed numbers. */
874 RTUINT64U uValue;
875} RTASN1INTEGER;
876/** Pointer to an ASN.1 integer (IPRT representation). */
877typedef RTASN1INTEGER *PRTASN1INTEGER;
878/** Pointer to a const ASN.1 integer (IPRT representation). */
879typedef RTASN1INTEGER const *PCRTASN1INTEGER;
880/** The Vtable for a RTASN1INTEGER structure. */
881extern RTDATADECL(RTASN1COREVTABLE const) g_RTAsn1Integer_Vtable;
882
883RTASN1TYPE_STANDARD_PROTOTYPES(RTASN1INTEGER, RTDECL, RTAsn1Integer, Asn1Core);
884
885/**
886 * Initializes an interger object to a default value.
887 * @returns VINF_SUCCESS.
888 * @param pInteger The integer object representation.
889 * @param uValue The default value (unsigned 64-bit).
890 * @param pAllocator The allocator (pro forma).
891 */
892RTDECL(int) RTAsn1Integer_InitDefault(PRTASN1INTEGER pInteger, uint64_t uValue, PCRTASN1ALLOCATORVTABLE pAllocator);
893
894RTDECL(int) RTAsn1Integer_InitU64(PRTASN1INTEGER pThis, uint64_t uValue, PCRTASN1ALLOCATORVTABLE pAllocator);
895
896/**
897 * Get the most significat bit that's set (1).
898 *
899 * @returns 0-base bit number, -1 if all clear.
900 * @param pInteger The integer to check.
901 */
902RTDECL(int32_t) RTAsn1Integer_UnsignedLastBit(PCRTASN1INTEGER pInteger);
903
904/**
905 * Compares two ASN.1 unsigned integers.
906 *
907 * @returns 0 if equal, -1 if @a pLeft is smaller, 1 if @a pLeft is larger.
908 * @param pLeft The first ASN.1 integer.
909 * @param pRight The second ASN.1 integer.
910 */
911RTDECL(int) RTAsn1Integer_UnsignedCompare(PCRTASN1INTEGER pLeft, PCRTASN1INTEGER pRight);
912
913/**
914 * Compares an ASN.1 unsigned integer with a uint64_t.
915 *
916 * @returns 0 if equal, -1 if @a pInteger is smaller, 1 if @a pInteger is
917 * larger.
918 * @param pInteger The ASN.1 integer to treat as unsigned.
919 * @param u64Const The uint64_t constant to compare with.
920 */
921RTDECL(int) RTAsn1Integer_UnsignedCompareWithU64(PCRTASN1INTEGER pInteger, uint64_t u64Const);
922
923/**
924 * Compares an ASN.1 unsigned integer with a uint32_t.
925 *
926 * @returns 0 if equal, -1 if @a pInteger is smaller, 1 if @a pInteger is
927 * larger.
928 * @param pInteger The ASN.1 integer to treat as unsigned.
929 * @param u32Const The uint32_t constant to compare with.
930 * @remarks We don't bother with U16 and U8 variants, just use this instead.
931 */
932RTDECL(int) RTAsn1Integer_UnsignedCompareWithU32(PCRTASN1INTEGER pInteger, uint32_t u32Const);
933
934
935/**
936 * Initializes a big integer number from an ASN.1 integer.
937 *
938 * @returns IPRT status code.
939 * @param pInteger The ASN.1 integer.
940 * @param pBigNum The big integer number structure to initialize.
941 * @param fBigNumInit Subset of RTBIGNUMINIT_F_XXX that concerns
942 * senitivity, signedness and endianness.
943 */
944RTDECL(int) RTAsn1Integer_ToBigNum(PCRTASN1INTEGER pInteger, PRTBIGNUM pBigNum, uint32_t fBigNumInit);
945RTDECL(int) RTAsn1Integer_FromBigNum(PRTASN1INTEGER pThis, PCRTBIGNUM pBigNum, PCRTASN1ALLOCATORVTABLE pAllocator);
946
947/**
948 * Converts the integer to a string.
949 *
950 * This will produce a hex represenation of the number. If it fits in 64-bit, a
951 * C style hex number will be produced. If larger than 64-bit, it will be
952 * printed as a space separated string of hex bytes.
953 *
954 * @returns IPRT status code.
955 * @param pThis The ASN.1 integer.
956 * @param pszBuf The output buffer.
957 * @param cbBuf The buffer size.
958 * @param fFlags Flags reserved for future exploits. MBZ.
959 * @param pcbActual Where to return the amount of buffer space used
960 * (i.e. including terminator). Optional.
961 *
962 * @remarks Currently assume unsigned number.
963 */
964RTDECL(int) RTAsn1Integer_ToString(PCRTASN1INTEGER pThis, char *pszBuf, size_t cbBuf, uint32_t fFlags, size_t *pcbActual);
965
966RTASN1_IMPL_GEN_SEQ_OF_TYPEDEFS_AND_PROTOS(RTASN1SEQOFINTEGERS, RTASN1INTEGER, RTDECL, RTAsn1SeqOfIntegers);
967RTASN1_IMPL_GEN_SET_OF_TYPEDEFS_AND_PROTOS(RTASN1SETOFINTEGERS, RTASN1INTEGER, RTDECL, RTAsn1SetOfIntegers);
968
969
970
971/**
972 * ASN.1 boolean (IPRT representation).
973 */
974typedef struct RTASN1BOOLEAN
975{
976 /** Core ASN.1 encoding details. */
977 RTASN1CORE Asn1Core;
978 /** The boolean value. */
979 bool fValue;
980} RTASN1BOOLEAN;
981/** Pointer to the IPRT representation of an ASN.1 boolean. */
982typedef RTASN1BOOLEAN *PRTASN1BOOLEAN;
983/** Pointer to the const IPRT representation of an ASN.1 boolean. */
984typedef RTASN1BOOLEAN const *PCRTASN1BOOLEAN;
985/** The Vtable for a RTASN1BOOLEAN structure. */
986extern RTDATADECL(RTASN1COREVTABLE const) g_RTAsn1Boolean_Vtable;
987
988RTASN1TYPE_STANDARD_PROTOTYPES(RTASN1BOOLEAN, RTDECL, RTAsn1Boolean, Asn1Core);
989
990/**
991 * Initializes a boolean object to a default value.
992 * @returns VINF_SUCCESS
993 * @param pBoolean The boolean object representation.
994 * @param fValue The default value.
995 * @param pAllocator The allocator (pro forma).
996 */
997RTDECL(int) RTAsn1Boolean_InitDefault(PRTASN1BOOLEAN pBoolean, bool fValue, PCRTASN1ALLOCATORVTABLE pAllocator);
998RTDECL(int) RTAsn1Boolean_Set(PRTASN1BOOLEAN pThis, bool fValue);
999
1000RTASN1_IMPL_GEN_SEQ_OF_TYPEDEFS_AND_PROTOS(RTASN1SEQOFBOOLEANS, RTASN1BOOLEAN, RTDECL, RTAsn1SeqOfBooleans);
1001RTASN1_IMPL_GEN_SET_OF_TYPEDEFS_AND_PROTOS(RTASN1SETOFBOOLEANS, RTASN1BOOLEAN, RTDECL, RTAsn1SetOfBooleans);
1002
1003
1004
1005/**
1006 * ASN.1 UTC and Generalized Time (IPRT representation).
1007 *
1008 * The two time types only differs in the precision the render (UTC time being
1009 * the one for which you go "WTF were they thinking?!!" for in 2014).
1010 */
1011typedef struct RTASN1TIME
1012{
1013 /** The core structure, either ASN1_TAG_UTC_TIME or
1014 * ASN1_TAG_GENERALIZED_TIME. */
1015 RTASN1CORE Asn1Core;
1016 /** The exploded time. */
1017 RTTIME Time;
1018} RTASN1TIME;
1019/** Pointer to an IPRT representation of ASN.1 UTC/Generalized time. */
1020typedef RTASN1TIME *PRTASN1TIME;
1021/** Pointer to a const IPRT representation of ASN.1 UTC/Generalized time. */
1022typedef RTASN1TIME const *PCRTASN1TIME;
1023/** The Vtable for a RTASN1TIME structure. */
1024extern RTDATADECL(RTASN1COREVTABLE const) g_RTAsn1Time_Vtable;
1025
1026RTASN1TYPE_STANDARD_PROTOTYPES(RTASN1TIME, RTDECL, RTAsn1Time, Asn1Core);
1027
1028RTASN1TYPE_STANDARD_PROTOTYPES(RTASN1TIME, RTDECL, RTAsn1UtcTime, Asn1Core);
1029RTASN1TYPE_STANDARD_PROTOTYPES(RTASN1TIME, RTDECL, RTAsn1GeneralizedTime, Asn1Core);
1030
1031/**
1032 * Compares two ASN.1 time values.
1033 *
1034 * @returns 0 if equal, -1 if @a pLeft is smaller, 1 if @a pLeft is larger.
1035 * @param pLeft The first ASN.1 time object.
1036 * @param pTsRight The second time to compare.
1037 */
1038RTDECL(int) RTAsn1Time_CompareWithTimeSpec(PCRTASN1TIME pLeft, PCRTTIMESPEC pTsRight);
1039
1040/**
1041 * Extended init function that lets you select the kind of time object (UTC or
1042 * generalized).
1043 */
1044RTDECL(int) RTAsn1Time_InitEx(PRTASN1TIME pThis, uint32_t uTag, PCRTASN1ALLOCATORVTABLE pAllocator);
1045
1046/**
1047 * Combines RTAsn1Time_InitEx() and RTAsn1Time_SetTime().
1048 */
1049RTDECL(int) RTAsn1Time_InitWithTime(PRTASN1TIME pThis, uint32_t uTag, PCRTASN1ALLOCATORVTABLE pAllocator, PCRTTIME pTime);
1050
1051/**
1052 * Sets the ASN.1 time value to @a pTime.
1053 *
1054 * @returns IPRT status code.
1055 * @param pThis The ASN.1 time object to modify.
1056 * @param pAllocator The allocator to use.
1057 * @param pTime The time to set.
1058 */
1059RTDECL(int) RTAsn1Time_SetTime(PRTASN1TIME pThis, PCRTASN1ALLOCATORVTABLE pAllocator, PCRTTIME pTime);
1060
1061/**
1062 * Sets the ASN.1 time value to @a pTimeSpec.
1063 *
1064 * @returns IPRT status code.
1065 * @param pThis The ASN.1 time object to modify.
1066 * @param pAllocator The allocator to use.
1067 * @param pTimeSpec The time to set.
1068 */
1069RTDECL(int) RTAsn1Time_SetTimeSpec(PRTASN1TIME pThis, PCRTASN1ALLOCATORVTABLE pAllocator, PCRTTIMESPEC pTimeSpec);
1070
1071/** @name Predicate macros for determing the exact type of RTASN1TIME.
1072 * @{ */
1073/** True if UTC time. */
1074#define RTASN1TIME_IS_UTC_TIME(a_pAsn1Time) ((a_pAsn1Time)->Asn1Core.uTag == ASN1_TAG_UTC_TIME)
1075/** True if generalized time. */
1076#define RTASN1TIME_IS_GENERALIZED_TIME(a_pAsn1Time) ((a_pAsn1Time)->Asn1Core.uTag == ASN1_TAG_GENERALIZED_TIME)
1077/** @} */
1078
1079RTASN1_IMPL_GEN_SEQ_OF_TYPEDEFS_AND_PROTOS(RTASN1SEQOFTIMES, RTASN1TIME, RTDECL, RTAsn1SeqOfTimes);
1080RTASN1_IMPL_GEN_SET_OF_TYPEDEFS_AND_PROTOS(RTASN1SETOFTIMES, RTASN1TIME, RTDECL, RTAsn1SetOfTimes);
1081
1082
1083
1084/**
1085 * ASN.1 object identifier (IPRT representation).
1086 */
1087typedef struct RTASN1OBJID
1088{
1089 /** Core ASN.1 encoding details. */
1090 RTASN1CORE Asn1Core;
1091 /** Coverning the paComponents memory allocation if there isn't enough room in
1092 * szObjId for both the dottet string and the component values. */
1093 RTASN1ALLOCATION Allocation;
1094 /** Pointer to an array with the component values.
1095 * This may point within szObjId if there is enough space for both there. */
1096 uint32_t const *pauComponents;
1097 /** The number of components in the object identifier.
1098 * This ASSUMES that nobody will be ever needing more than 255 components. */
1099 uint8_t cComponents;
1100 /** The dotted string representation of the object identifier.
1101 * If there is sufficient space after the string, we will place the array that
1102 * paComponents points to here and/or the raw content bytes (Asn1Core.uData).
1103 *
1104 * An analysis of dumpasn1.cfg, hl7.org and our own _OID defines indicates
1105 * that we need space for at least 10 components and 30-something chars. We've
1106 * allocated 87 bytes, which we ASSUME should be enough for everyone. */
1107 char szObjId[87];
1108} RTASN1OBJID;
1109/** Pointer to an ASN.1 object identifier representation. */
1110typedef RTASN1OBJID *PRTASN1OBJID;
1111/** Pointer to a const ASN.1 object identifier representation. */
1112typedef RTASN1OBJID const *PCRTASN1OBJID;
1113/** The Vtable for a RTASN1OBJID structure. */
1114extern RTDATADECL(RTASN1COREVTABLE const) g_RTAsn1ObjId_Vtable;
1115
1116RTASN1TYPE_STANDARD_PROTOTYPES(RTASN1OBJID, RTDECL, RTAsn1ObjId, Asn1Core);
1117
1118RTDECL(int) RTAsn1ObjId_InitFromString(PRTASN1OBJID pThis, const char *pszObjId, PCRTASN1ALLOCATORVTABLE pAllocator);
1119RTDECL(int) RTAsn1ObjId_SetFromString(PRTASN1OBJID pThis, const char *pszObjId, PCRTASN1ALLOCATORVTABLE pAllocator);
1120
1121/**
1122 * Compares an ASN.1 object identifier with a dotted object identifier string.
1123 *
1124 * @returns 0 if equal, -1 if @a pLeft is smaller, 1 if @a pLeft is larger.
1125 * @param pThis The ASN.1 object identifier.
1126 * @param pszRight The dotted object identifier string.
1127 */
1128RTDECL(int) RTAsn1ObjId_CompareWithString(PCRTASN1OBJID pThis, const char *pszRight);
1129
1130/**
1131 * Checks if an ASN.1 object identifier starts with the given dotted object
1132 * identifier string.
1133 *
1134 * The matching is only successful if the given string matches matches the last
1135 * component completely.
1136 *
1137 * @returns true / false.
1138 * @param pThis The ASN.1 object identifier.
1139 * @param pszStartsWith The dotted object identifier string.
1140 */
1141RTDECL(bool) RTAsn1ObjId_StartsWith(PCRTASN1OBJID pThis, const char *pszStartsWith);
1142
1143RTDECL(uint8_t) RTAsn1ObjIdCountComponents(PCRTASN1OBJID pThis);
1144RTDECL(uint32_t) RTAsn1ObjIdGetComponentsAsUInt32(PCRTASN1OBJID pThis, uint8_t iComponent);
1145RTDECL(uint32_t) RTAsn1ObjIdGetLastComponentsAsUInt32(PCRTASN1OBJID pThis);
1146
1147RTASN1_IMPL_GEN_SEQ_OF_TYPEDEFS_AND_PROTOS(RTASN1SEQOFOBJIDS, RTASN1OBJID, RTDECL, RTAsn1SeqOfObjIds);
1148RTASN1_IMPL_GEN_SET_OF_TYPEDEFS_AND_PROTOS(RTASN1SETOFOBJIDS, RTASN1OBJID, RTDECL, RTAsn1SetOfObjIds);
1149RTASN1_IMPL_GEN_SET_OF_TYPEDEFS_AND_PROTOS(RTASN1SETOFOBJIDSEQS, RTASN1SEQOFOBJIDS, RTDECL, RTAsn1SetOfObjIdSeqs);
1150
1151
1152/**
1153 * ASN.1 bit string (IPRT representation).
1154 */
1155typedef struct RTASN1BITSTRING
1156{
1157 /** Core ASN.1 encoding details. */
1158 RTASN1CORE Asn1Core;
1159 /** The number of bits. */
1160 uint32_t cBits;
1161 /** The max number of bits (given at decoding / construction). */
1162 uint32_t cMaxBits;
1163 /** Pointer to the bits. */
1164 RTCPTRUNION uBits;
1165 /** Pointer to user structure encapsulated in this string, if dynamically
1166 * allocated the EncapsulatedAllocation member can be used to track it and
1167 * trigger automatic cleanup on object destruction. If EncapsulatedAllocation
1168 * is zero, any object pointed to will only be deleted. */
1169 PRTASN1CORE pEncapsulated;
1170 /** Allocation tracking structure for pEncapsulated. */
1171 RTASN1ALLOCATION EncapsulatedAllocation;
1172} RTASN1BITSTRING;
1173/** Pointer to the IPRT representation of an ASN.1 bit string. */
1174typedef RTASN1BITSTRING *PRTASN1BITSTRING;
1175/** Pointer to the const IPRT representation of an ASN.1 bit string. */
1176typedef RTASN1BITSTRING const *PCRTASN1BITSTRING;
1177/** The Vtable for a RTASN1BITSTRING structure. */
1178extern RTDATADECL(RTASN1COREVTABLE const) g_RTAsn1BitString_Vtable;
1179
1180RTASN1TYPE_STANDARD_PROTOTYPES(RTASN1BITSTRING, RTDECL, RTAsn1BitString, Asn1Core);
1181
1182/**
1183 * Calculates pointer to the first bit.
1184 *
1185 * @returns Byte pointer to the first bit.
1186 * @param a_pBitString The ASN.1 bit string.
1187 */
1188#define RTASN1BITSTRING_GET_BIT0_PTR(a_pBitString) ( &(a_pBitString)->Asn1Core.uData.pu8[1] )
1189
1190/**
1191 * Calculates the size in bytes.
1192 *
1193 * @returns Rounded up size in bytes.
1194 * @param a_pBitString The ASN.1 bit string.
1195 */
1196#define RTASN1BITSTRING_GET_BYTE_SIZE(a_pBitString) ( ((a_pBitString)->cBits + 7U) >> 3 )
1197
1198RTDECL(int) RTAsn1BitString_InitWithData(PRTASN1BITSTRING pThis, void const *pvSrc, uint32_t cSrcBits,
1199 PCRTASN1ALLOCATORVTABLE pAllocator);
1200RTDECL(int) RTAsn1BitString_DecodeAsn1Ex(PRTASN1CURSOR pCursor, uint32_t fFlags, uint32_t cMaxBits, PRTASN1BITSTRING pThis,
1201 const char *pszErrorTag);
1202RTDECL(uint64_t) RTAsn1BitString_GetAsUInt64(PCRTASN1BITSTRING pThis);
1203RTDECL(int) RTAsn1BitString_RefreshContent(PRTASN1BITSTRING pThis, uint32_t fFlags,
1204 PCRTASN1ALLOCATORVTABLE pAllocator, PRTERRINFO pErrInfo);
1205RTDECL(bool) RTAsn1BitString_AreContentBitsValid(PCRTASN1BITSTRING pThis, uint32_t fFlags);
1206
1207RTASN1_IMPL_GEN_SEQ_OF_TYPEDEFS_AND_PROTOS(RTASN1SEQOFBITSTRINGS, RTASN1BITSTRING, RTDECL, RTAsn1SeqOfBitStrings);
1208RTASN1_IMPL_GEN_SET_OF_TYPEDEFS_AND_PROTOS(RTASN1SETOFBITSTRINGS, RTASN1BITSTRING, RTDECL, RTAsn1SetOfBitStrings);
1209
1210
1211/**
1212 * ASN.1 octet string (IPRT representation).
1213 */
1214typedef struct RTASN1OCTETSTRING
1215{
1216 /** Core ASN.1 encoding details. */
1217 RTASN1CORE Asn1Core;
1218 /** Pointer to user structure encapsulated in this string.
1219 *
1220 * If dynamically allocated the EncapsulatedAllocation member can be used to
1221 * track it and trigger automatic cleanup on object destruction. If
1222 * EncapsulatedAllocation is zero, any object pointed to will only be
1223 * deleted. */
1224 PRTASN1CORE pEncapsulated;
1225 /** Allocation tracking structure for pEncapsulated. */
1226 RTASN1ALLOCATION EncapsulatedAllocation;
1227} RTASN1OCTETSTRING;
1228/** Pointer to the IPRT representation of an ASN.1 octet string. */
1229typedef RTASN1OCTETSTRING *PRTASN1OCTETSTRING;
1230/** Pointer to the const IPRT representation of an ASN.1 octet string. */
1231typedef RTASN1OCTETSTRING const *PCRTASN1OCTETSTRING;
1232/** The Vtable for a RTASN1OCTETSTRING structure. */
1233extern RTDATADECL(RTASN1COREVTABLE const) g_RTAsn1OctetString_Vtable;
1234
1235RTASN1TYPE_STANDARD_PROTOTYPES(RTASN1OCTETSTRING, RTDECL, RTAsn1OctetString, Asn1Core);
1236
1237RTDECL(int) RTAsn1OctetString_AllocContent(PRTASN1OCTETSTRING pThis, void const *pvSrc, size_t cb,
1238 PCRTASN1ALLOCATORVTABLE pAllocator);
1239RTDECL(int) RTAsn1OctetString_SetContent(PRTASN1OCTETSTRING pThis, void const *pvSrc, size_t cbSrc,
1240 PCRTASN1ALLOCATORVTABLE pAllocator);
1241RTDECL(bool) RTAsn1OctetString_AreContentBytesValid(PCRTASN1OCTETSTRING pThis, uint32_t fFlags);
1242RTDECL(int) RTAsn1OctetString_RefreshContent(PRTASN1OCTETSTRING pThis, uint32_t fFlags,
1243 PCRTASN1ALLOCATORVTABLE pAllocator, PRTERRINFO pErrInfo);
1244
1245RTASN1_IMPL_GEN_SEQ_OF_TYPEDEFS_AND_PROTOS(RTASN1SEQOFOCTETSTRINGS, RTASN1OCTETSTRING, RTDECL, RTAsn1SeqOfOctetStrings);
1246RTASN1_IMPL_GEN_SET_OF_TYPEDEFS_AND_PROTOS(RTASN1SETOFOCTETSTRINGS, RTASN1OCTETSTRING, RTDECL, RTAsn1SetOfOctetStrings);
1247
1248
1249/**
1250 * ASN.1 string (IPRT representation).
1251 * All char string types except 'character string (29)'.
1252 */
1253typedef struct RTASN1STRING
1254{
1255 /** Core ASN.1 encoding details. */
1256 RTASN1CORE Asn1Core;
1257 /** Allocation tracking for pszUtf8. */
1258 RTASN1ALLOCATION Allocation;
1259 /** If conversion to UTF-8 was requested, we cache that here. */
1260 char const *pszUtf8;
1261 /** The length (chars, not code points) of the above UTF-8 string if
1262 * present. */
1263 uint32_t cchUtf8;
1264} RTASN1STRING;
1265/** Pointer to the IPRT representation of an ASN.1 string. */
1266typedef RTASN1STRING *PRTASN1STRING;
1267/** Pointer to the const IPRT representation of an ASN.1 string. */
1268typedef RTASN1STRING const *PCRTASN1STRING;
1269/** The Vtable for a RTASN1STRING structure. */
1270extern RTDATADECL(RTASN1COREVTABLE const) g_RTAsn1String_Vtable;
1271
1272RTASN1TYPE_STANDARD_PROTOTYPES(RTASN1STRING, RTDECL, RTAsn1String, Asn1Core);
1273
1274/** @name String type predicate macros.
1275 * @{ */
1276#define RTASN1STRING_IS_NUMERIC(a_pAsn1String) ( RTASN1CORE_GET_TAG(&(a_pAsn1String)->Asn1Core) == ASN1_TAG_NUMERIC_STRING )
1277#define RTASN1STRING_IS_PRINTABLE(a_pAsn1String) ( RTASN1CORE_GET_TAG(&(a_pAsn1String)->Asn1Core) == ASN1_TAG_PRINTABLE_STRING )
1278#define RTASN1STRING_IS_T61(a_pAsn1String) ( RTASN1CORE_GET_TAG(&(a_pAsn1String)->Asn1Core) == ASN1_TAG_T61_STRING )
1279#define RTASN1STRING_IS_VIDEOTEX(a_pAsn1String) ( RTASN1CORE_GET_TAG(&(a_pAsn1String)->Asn1Core) == ASN1_TAG_VIDEOTEX_STRING )
1280#define RTASN1STRING_IS_VISIBLE(a_pAsn1String) ( RTASN1CORE_GET_TAG(&(a_pAsn1String)->Asn1Core) == ASN1_TAG_VISIBLE_STRING )
1281#define RTASN1STRING_IS_IA5(a_pAsn1String) ( RTASN1CORE_GET_TAG(&(a_pAsn1String)->Asn1Core) == ASN1_TAG_IA5_STRING )
1282#define RTASN1STRING_IS_GRAPHIC(a_pAsn1String) ( RTASN1CORE_GET_TAG(&(a_pAsn1String)->Asn1Core) == ASN1_TAG_GRAPHIC_STRING )
1283#define RTASN1STRING_IS_GENERAL(a_pAsn1String) ( RTASN1CORE_GET_TAG(&(a_pAsn1String)->Asn1Core) == ASN1_TAG_GENERAL_STRING )
1284/** UTF-8. */
1285#define RTASN1STRING_IS_UTF8(a_pAsn1String) ( RTASN1CORE_GET_TAG(&(a_pAsn1String)->Asn1Core) == ASN1_TAG_UTF8_STRING )
1286/** UCS-2. */
1287#define RTASN1STRING_IS_BMP(a_pAsn1String) ( RTASN1CORE_GET_TAG(&(a_pAsn1String)->Asn1Core) == ASN1_TAG_BMP_STRING )
1288/** UCS-4. */
1289#define RTASN1STRING_IS_UNIVERSAL(a_pAsn1String) ( RTASN1CORE_GET_TAG(&(a_pAsn1String)->Asn1Core) == ASN1_TAG_UNIVERSAL_STRING )
1290/** @} */
1291
1292RTASN1TYPE_STANDARD_PROTOTYPES(RTASN1STRING, RTDECL, RTAsn1NumericString, Asn1Core);
1293RTASN1TYPE_STANDARD_PROTOTYPES(RTASN1STRING, RTDECL, RTAsn1PrintableString, Asn1Core);
1294RTASN1TYPE_STANDARD_PROTOTYPES(RTASN1STRING, RTDECL, RTAsn1T61String, Asn1Core);
1295RTASN1TYPE_STANDARD_PROTOTYPES(RTASN1STRING, RTDECL, RTAsn1VideoTexString, Asn1Core);
1296RTASN1TYPE_STANDARD_PROTOTYPES(RTASN1STRING, RTDECL, RTAsn1VisibleString, Asn1Core);
1297RTASN1TYPE_STANDARD_PROTOTYPES(RTASN1STRING, RTDECL, RTAsn1Ia5String, Asn1Core);
1298RTASN1TYPE_STANDARD_PROTOTYPES(RTASN1STRING, RTDECL, RTAsn1GraphicString, Asn1Core);
1299RTASN1TYPE_STANDARD_PROTOTYPES(RTASN1STRING, RTDECL, RTAsn1GeneralString, Asn1Core);
1300RTASN1TYPE_STANDARD_PROTOTYPES(RTASN1STRING, RTDECL, RTAsn1Utf8String, Asn1Core);
1301RTASN1TYPE_STANDARD_PROTOTYPES(RTASN1STRING, RTDECL, RTAsn1BmpString, Asn1Core);
1302RTASN1TYPE_STANDARD_PROTOTYPES(RTASN1STRING, RTDECL, RTAsn1UniversalString, Asn1Core);
1303
1304RTDECL(int) RTAsn1String_InitWithValue(PRTASN1STRING pThis, const char *pszUtf8Value, PCRTASN1ALLOCATORVTABLE pAllocator);
1305RTDECL(int) RTAsn1String_InitEx(PRTASN1STRING pThis, uint32_t uTag, void const *pvValue, size_t cbValue,
1306 PCRTASN1ALLOCATORVTABLE pAllocator);
1307
1308/**
1309 * Compares two strings values, extended version.
1310 *
1311 * @returns 0 if equal, -1 if @a pLeft is smaller, 1 if @a pLeft is larger.
1312 * @param pLeft The first string.
1313 * @param pRight The second string.
1314 * @param fTypeToo Set if the string types must match, false if
1315 * not.
1316 */
1317RTDECL(int) RTAsn1String_CompareEx(PCRTASN1STRING pLeft, PCRTASN1STRING pRight, bool fTypeToo);
1318RTDECL(int) RTAsn1String_CompareValues(PCRTASN1STRING pLeft, PCRTASN1STRING pRight);
1319
1320/**
1321 * Compares a ASN.1 string object with an UTF-8 string.
1322 *
1323 * @returns 0 if equal, -1 if @a pThis is smaller, 1 if @a pThis is larger.
1324 * @param pThis The ASN.1 string object.
1325 * @param pszString The UTF-8 string.
1326 * @param cchString The length of @a pszString, or RTSTR_MAX.
1327 */
1328RTDECL(int) RTAsn1String_CompareWithString(PCRTASN1STRING pThis, const char *pszString, size_t cchString);
1329
1330/**
1331 * Queries the UTF-8 length of an ASN.1 string object.
1332 *
1333 * This differs from RTAsn1String_QueryUtf8 in that it won't need to allocate
1334 * memory for the converted string, but just calculates the length.
1335 *
1336 * @returns IPRT status code.
1337 * @param pThis The ASN.1 string object.
1338 * @param pcch Where to return the string length.
1339 */
1340RTDECL(int) RTAsn1String_QueryUtf8Len(PCRTASN1STRING pThis, size_t *pcch);
1341
1342/**
1343 * Queries the UTF-8 string for an ASN.1 string object.
1344 *
1345 * This may fail as it may require memory to be allocated for storing the
1346 * string.
1347 *
1348 * @returns IPRT status code.
1349 * @param pString The ASN.1 string object. This is a const
1350 * parameter for making life easier on the caller,
1351 * however be aware that the object may be modified
1352 * by this call!
1353 * @param ppsz Where to return the pointer to the UTF-8 string.
1354 * Optional.
1355 * @param pcch Where to return the length (in 8-bit chars) to
1356 * of the UTF-8 string. Optional.
1357 */
1358RTDECL(int) RTAsn1String_QueryUtf8(PCRTASN1STRING pString, const char **ppsz, size_t *pcch);
1359RTDECL(int) RTAsn1String_RecodeAsUtf8(PRTASN1STRING pThis, PCRTASN1ALLOCATORVTABLE pAllocator);
1360
1361RTASN1_IMPL_GEN_SEQ_OF_TYPEDEFS_AND_PROTOS(RTASN1SEQOFSTRINGS, RTASN1STRING, RTDECL, RTAsn1SeqOfStrings);
1362RTASN1_IMPL_GEN_SET_OF_TYPEDEFS_AND_PROTOS(RTASN1SETOFSTRINGS, RTASN1STRING, RTDECL, RTAsn1SetOfStrings);
1363
1364
1365
1366/**
1367 * ASN.1 generic context specific tag (IPRT representation).
1368 *
1369 * Normally used to tag something that's optional, version specific or such.
1370 *
1371 * For the purpose of documenting the format with typedefs as well as possibly
1372 * making it a little more type safe, there's a set of typedefs for the most
1373 * commonly used tag values defined. These typedefs have are identical to
1374 * RTASN1CONTEXTTAG, except from the C++ type system point of view.
1375 */
1376typedef struct RTASN1CONTEXTTAG
1377{
1378 /** Core ASN.1 encoding details. */
1379 RTASN1CORE Asn1Core;
1380} RTASN1CONTEXTTAG;
1381/** Pointer to an ASN.1 context tag (IPRT thing). */
1382typedef RTASN1CONTEXTTAG *PRTASN1CONTEXTTAG;
1383/** Pointer to a const ASN.1 context tag (IPRT thing). */
1384typedef RTASN1CONTEXTTAG const *PCRTASN1CONTEXTTAG;
1385
1386RTDECL(int) RTAsn1ContextTagN_Init(PRTASN1CONTEXTTAG pThis, uint32_t uTag, PCRTASN1COREVTABLE pVtable);
1387RTDECL(int) RTAsn1ContextTagN_Clone(PRTASN1CONTEXTTAG pThis, PCRTASN1CONTEXTTAG pSrc, uint32_t uTag);
1388
1389
1390/** @internal */
1391#define RTASN1CONTEXTTAG_DO_TYPEDEF_AND_INLINE(a_uTag) \
1392 typedef struct RT_CONCAT(RTASN1CONTEXTTAG,a_uTag) { RTASN1CORE Asn1Core; } RT_CONCAT(RTASN1CONTEXTTAG,a_uTag); \
1393 typedef RT_CONCAT(RTASN1CONTEXTTAG,a_uTag) *RT_CONCAT(PRTASN1CONTEXTTAG,a_uTag); \
1394 DECLINLINE(int) RT_CONCAT3(RTAsn1ContextTag,a_uTag,_Init)(RT_CONCAT(PRTASN1CONTEXTTAG,a_uTag) pThis, \
1395 PCRTASN1COREVTABLE pVtable, PCRTASN1ALLOCATORVTABLE pAllocator) \
1396 { \
1397 NOREF(pAllocator); \
1398 return RTAsn1ContextTagN_Init((PRTASN1CONTEXTTAG)pThis, a_uTag, pVtable); \
1399 } \
1400 DECLINLINE(int) RT_CONCAT3(RTAsn1ContextTag,a_uTag,_Clone)(RT_CONCAT(PRTASN1CONTEXTTAG,a_uTag) pThis, \
1401 RT_CONCAT(RTASN1CONTEXTTAG,a_uTag) const *pSrc) \
1402 { return RTAsn1ContextTagN_Clone((PRTASN1CONTEXTTAG)pThis, (PCRTASN1CONTEXTTAG)pSrc, a_uTag); } \
1403 typedef RT_CONCAT(RTASN1CONTEXTTAG,a_uTag) const *RT_CONCAT(PCRTASN1CONTEXTTAG,a_uTag)
1404RTASN1CONTEXTTAG_DO_TYPEDEF_AND_INLINE(0);
1405RTASN1CONTEXTTAG_DO_TYPEDEF_AND_INLINE(1);
1406RTASN1CONTEXTTAG_DO_TYPEDEF_AND_INLINE(2);
1407RTASN1CONTEXTTAG_DO_TYPEDEF_AND_INLINE(3);
1408RTASN1CONTEXTTAG_DO_TYPEDEF_AND_INLINE(4);
1409RTASN1CONTEXTTAG_DO_TYPEDEF_AND_INLINE(5);
1410RTASN1CONTEXTTAG_DO_TYPEDEF_AND_INLINE(6);
1411RTASN1CONTEXTTAG_DO_TYPEDEF_AND_INLINE(7);
1412#undef RTASN1CONTEXTTAG_DO_TYPEDEF_AND_INLINE
1413
1414/** Helper for comparing optional context tags.
1415 * This will return if both are not present or if their precense differs.
1416 * @internal */
1417#define RTASN1CONTEXTTAG_COMPARE_PRESENT_RETURN_INTERNAL(a_iDiff, a_pLeft, a_pRight, a_uTag) \
1418 do { \
1419 /* type checks */ \
1420 RT_CONCAT(PCRTASN1CONTEXTTAG,a_uTag) const pMyLeftInternal = (a_pLeft); \
1421 RT_CONCAT(PCRTASN1CONTEXTTAG,a_uTag) const pMyRightInternal = (a_pRight); \
1422 (a_iDiff) = (int)RTASN1CORE_IS_PRESENT(&pMyLeftInternal->Asn1Core) \
1423 - (int)RTASN1CORE_IS_PRESENT(&pMyRightInternal->Asn1Core); \
1424 if ((a_iDiff) || !RTASN1CORE_IS_PRESENT(&pMyLeftInternal->Asn1Core)) return iDiff; \
1425 } while (0)
1426
1427/** @name Helpers for comparing optional context tags.
1428 * This will return if both are not present or if their precense differs.
1429 * @{ */
1430#define RTASN1CONTEXTTAG0_COMPARE_PRESENT_RETURN(a_iDiff, a_pLeft, a_pRight) RTASN1CONTEXTTAG_COMPARE_PRESENT_RETURN_INTERNAL(a_iDiff, a_pLeft, a_pRight, 0)
1431#define RTASN1CONTEXTTAG1_COMPARE_PRESENT_RETURN(a_iDiff, a_pLeft, a_pRight) RTASN1CONTEXTTAG_COMPARE_PRESENT_RETURN_INTERNAL(a_iDiff, a_pLeft, a_pRight, 1)
1432#define RTASN1CONTEXTTAG2_COMPARE_PRESENT_RETURN(a_iDiff, a_pLeft, a_pRight) RTASN1CONTEXTTAG_COMPARE_PRESENT_RETURN_INTERNAL(a_iDiff, a_pLeft, a_pRight, 2)
1433#define RTASN1CONTEXTTAG3_COMPARE_PRESENT_RETURN(a_iDiff, a_pLeft, a_pRight) RTASN1CONTEXTTAG_COMPARE_PRESENT_RETURN_INTERNAL(a_iDiff, a_pLeft, a_pRight, 3)
1434#define RTASN1CONTEXTTAG4_COMPARE_PRESENT_RETURN(a_iDiff, a_pLeft, a_pRight) RTASN1CONTEXTTAG_COMPARE_PRESENT_RETURN_INTERNAL(a_iDiff, a_pLeft, a_pRight, 4)
1435#define RTASN1CONTEXTTAG5_COMPARE_PRESENT_RETURN(a_iDiff, a_pLeft, a_pRight) RTASN1CONTEXTTAG_COMPARE_PRESENT_RETURN_INTERNAL(a_iDiff, a_pLeft, a_pRight, 5)
1436#define RTASN1CONTEXTTAG6_COMPARE_PRESENT_RETURN(a_iDiff, a_pLeft, a_pRight) RTASN1CONTEXTTAG_COMPARE_PRESENT_RETURN_INTERNAL(a_iDiff, a_pLeft, a_pRight, 6)
1437#define RTASN1CONTEXTTAG7_COMPARE_PRESENT_RETURN(a_iDiff, a_pLeft, a_pRight) RTASN1CONTEXTTAG_COMPARE_PRESENT_RETURN_INTERNAL(a_iDiff, a_pLeft, a_pRight, 7)
1438/** @} */
1439
1440
1441/**
1442 * Type information for dynamically bits (see RTASN1DYNTYPE).
1443 */
1444typedef enum RTASN1TYPE
1445{
1446 /** Not present. */
1447 RTASN1TYPE_NOT_PRESENT = 0,
1448 /** Generic ASN.1 for unknown tag/class. */
1449 RTASN1TYPE_CORE,
1450 /** ASN.1 NULL. */
1451 RTASN1TYPE_NULL,
1452 /** ASN.1 integer. */
1453 RTASN1TYPE_INTEGER,
1454 /** ASN.1 boolean. */
1455 RTASN1TYPE_BOOLEAN,
1456 /** ASN.1 character string. */
1457 RTASN1TYPE_STRING,
1458 /** ASN.1 octet string. */
1459 RTASN1TYPE_OCTET_STRING,
1460 /** ASN.1 bite string. */
1461 RTASN1TYPE_BIT_STRING,
1462 /** ASN.1 UTC or Generalize time. */
1463 RTASN1TYPE_TIME,
1464#if 0
1465 /** ASN.1 sequence core. */
1466 RTASN1TYPE_SEQUENCE_CORE,
1467 /** ASN.1 set core. */
1468 RTASN1TYPE_SET_CORE,
1469#endif
1470 /** ASN.1 object identifier. */
1471 RTASN1TYPE_OBJID,
1472 /** End of valid types. */
1473 RTASN1TYPE_END,
1474 /** Type size hack. */
1475 RTASN1TYPE_32BIT_HACK = 0x7fffffff
1476} RTASN1TYPE;
1477
1478
1479/**
1480 * ASN.1 dynamic type record.
1481 */
1482typedef struct RTASN1DYNTYPE
1483{
1484 /** Alternative interpretation provided by a user.
1485 * Before destroying this object, the user must explicitly free this and set
1486 * it to NULL, otherwise there will be memory leaks. */
1487 PRTASN1CORE pUser;
1488 /** The type of data we've got here. */
1489 RTASN1TYPE enmType;
1490 /** Union with data of the type dictated by enmType. */
1491 union
1492 {
1493 /** RTASN1TYPE_CORE. */
1494 RTASN1CORE Core;
1495 /** RTASN1TYPE_NULL. */
1496 RTASN1NULL Asn1Null;
1497 /** RTASN1TYPE_INTEGER. */
1498 RTASN1INTEGER Integer;
1499 /** RTASN1TYPE_BOOLEAN. */
1500 RTASN1BOOLEAN Boolean;
1501 /** RTASN1TYPE_STRING. */
1502 RTASN1STRING String;
1503 /** RTASN1TYPE_OCTET_STRING. */
1504 RTASN1OCTETSTRING OctetString;
1505 /** RTASN1TYPE_BIT_STRING. */
1506 RTASN1BITSTRING BitString;
1507 /** RTASN1TYPE_TIME. */
1508 RTASN1TIME Time;
1509#if 0
1510 /** RTASN1TYPE_SEQUENCE_CORE. */
1511 RTASN1SEQUENCECORE SeqCore;
1512 /** RTASN1TYPE_SET_CORE. */
1513 RTASN1SETCORE SetCore;
1514#endif
1515 /** RTASN1TYPE_OBJID. */
1516 RTASN1OBJID ObjId;
1517 } u;
1518} RTASN1DYNTYPE;
1519/** Pointer to an ASN.1 dynamic type record. */
1520typedef RTASN1DYNTYPE *PRTASN1DYNTYPE;
1521/** Pointer to a const ASN.1 dynamic type record. */
1522typedef RTASN1DYNTYPE const *PCRTASN1DYNTYPE;
1523RTASN1TYPE_STANDARD_PROTOTYPES(RTASN1DYNTYPE, RTDECL, RTAsn1DynType, u.Core);
1524RTDECL(int) RTAsn1DynType_SetToNull(PRTASN1DYNTYPE pThis);
1525RTDECL(int) RTAsn1DynType_SetToObjId(PRTASN1DYNTYPE pThis, PCRTASN1OBJID pSrc, PCRTASN1ALLOCATORVTABLE pAllocator);
1526
1527
1528/** @name Virtual Method Table Based API
1529 * @{ */
1530/**
1531 * Calls the destructor of the ASN.1 object.
1532 *
1533 * @param pThisCore The IPRT representation of an ASN.1 object.
1534 */
1535RTDECL(void) RTAsn1VtDelete(PRTASN1CORE pThisCore);
1536
1537/**
1538 * Deep enumeration of all descendants.
1539 *
1540 * @returns IPRT status code, any non VINF_SUCCESS value stems from pfnCallback.
1541 * @param pThisCore Pointer to the ASN.1 core to enumerate members of.
1542 * @param pfnCallback The callback.
1543 * @param uDepth The depth of this object. Children are at +1.
1544 * @param pvUser Callback user argument.
1545 * @param fDepthFirst When set, recurse into child objects before calling
1546 * pfnCallback on then. When clear, the child object
1547 * is first
1548 */
1549RTDECL(int) RTAsn1VtDeepEnum(PRTASN1CORE pThisCore, bool fDepthFirst, uint32_t uDepth,
1550 PFNRTASN1ENUMCALLBACK pfnCallback, void *pvUser);
1551
1552/**
1553 * Clones @a pSrcCore onto @a pThisCore.
1554 *
1555 * The caller must be sure that @a pSrcCore and @a pThisCore are of the same
1556 * types.
1557 *
1558 * @returns IPRT status code.
1559 * @param pThisCore Pointer to the ASN.1 core to clone onto. This shall
1560 * be uninitialized.
1561 * @param pSrcCore Pointer to the ASN.1 core to clone.
1562 * @param pAllocator The allocator to use.
1563 */
1564RTDECL(int) RTAsn1VtClone(PRTASN1CORE pThisCore, PRTASN1CORE pSrcCore, PCRTASN1ALLOCATORVTABLE pAllocator);
1565
1566/**
1567 * Compares two objects.
1568 *
1569 * @returns 0 if equal, -1 if @a pLeft is smaller, 1 if @a pLeft is larger.
1570 * @param pLeftCore Pointer to the ASN.1 core of the left side object.
1571 * @param pRightCore Pointer to the ASN.1 core of the right side object.
1572 */
1573RTDECL(int) RTAsn1VtCompare(PCRTASN1CORE pLeftCore, PCRTASN1CORE pRightCore);
1574
1575/**
1576 * Check sanity.
1577 *
1578 * A primary criteria is that the object is present and initialized.
1579 *
1580 * @returns IPRT status code.
1581 * @param pThisCore Pointer to the ASN.1 core of the object to check out.
1582 * @param fFlags See RTASN1_CHECK_SANITY_F_XXX.
1583 * @param pErrInfo Where to return additional error details. Optional.
1584 * @param pszErrorTag Tag for the additional error details.
1585 */
1586RTDECL(int) RTAsn1VtCheckSanity(PCRTASN1CORE pThisCore, uint32_t fFlags,
1587 PRTERRINFO pErrInfo, const char *pszErrorTag);
1588/** @} */
1589
1590
1591/** @defgroup rp_asn1_encode RTAsn1Encode - ASN.1 Encoding
1592 * @{ */
1593
1594/** @name RTASN1ENCODE_F_XXX
1595 * @{ */
1596/** Use distinguished encoding rules (DER) to encode the object. */
1597#define RTASN1ENCODE_F_DER UINT32_C(0x00000001)
1598/** Use base encoding rules (BER) to encode the object.
1599 * This is currently the same as DER for practical reasons. */
1600#define RTASN1ENCODE_F_BER RTASN1ENCODE_F_DER
1601/** Mask of valid encoding rules. */
1602#define RTASN1ENCODE_F_RULE_MASK UINT32_C(0x00000007)
1603/** @} */
1604
1605
1606/**
1607 * Recalculates cbHdr of and ASN.1 object.
1608 *
1609 * @returns IPRT status code.
1610 * @retval VINF_ASN1_NOT_ENCODED if the header size is zero (default value,
1611 * whatever).
1612 * @param pAsn1Core The object in question.
1613 * @param fFlags Valid combination of the RTASN1ENCODE_F_XXX
1614 * flags. Must include the encoding type.
1615 * @param pErrInfo Extended error info. Optional.
1616 */
1617RTDECL(int) RTAsn1EncodeRecalcHdrSize(PRTASN1CORE pAsn1Core, uint32_t fFlags, PRTERRINFO pErrInfo);
1618
1619/**
1620 * Prepares the ASN.1 structure for encoding.
1621 *
1622 * The preparations is mainly calculating accurate object size, but may also
1623 * involve operations like recoding internal UTF-8 strings to the actual ASN.1
1624 * format and other things that may require memory to allocated/reallocated.
1625 *
1626 * @returns IPRT status code
1627 * @param pRoot The root of the ASN.1 object tree to encode.
1628 * @param fFlags Valid combination of the RTASN1ENCODE_F_XXX
1629 * flags. Must include the encoding type.
1630 * @param pcbEncoded Where to return the encoded size. Optional.
1631 * @param pErrInfo Where to store extended error information.
1632 * Optional.
1633 */
1634RTDECL(int) RTAsn1EncodePrepare(PRTASN1CORE pRoot, uint32_t fFlags, uint32_t *pcbEncoded, PRTERRINFO pErrInfo);
1635
1636/**
1637 * Encodes and writes the header of an ASN.1 object.
1638 *
1639 * @returns IPRT status code.
1640 * @retval VINF_ASN1_NOT_ENCODED if nothing was written (default value,
1641 * whatever).
1642 * @param pAsn1Core The object in question.
1643 * @param fFlags Valid combination of the RTASN1ENCODE_F_XXX
1644 * flags. Must include the encoding type.
1645 * @param pfnWriter The output writer callback.
1646 * @param pvUser The user argument to pass to @a pfnWriter.
1647 * @param pErrInfo Where to store extended error information.
1648 * Optional.
1649 */
1650RTDECL(int) RTAsn1EncodeWriteHeader(PCRTASN1CORE pAsn1Core, uint32_t fFlags, FNRTASN1ENCODEWRITER pfnWriter, void *pvUser,
1651 PRTERRINFO pErrInfo);
1652
1653/**
1654 * Encodes and writes an ASN.1 object.
1655 *
1656 * @returns IPRT status code
1657 * @param pRoot The root of the ASN.1 object tree to encode.
1658 * @param fFlags Valid combination of the RTASN1ENCODE_F_XXX
1659 * flags. Must include the encoding type.
1660 * @param pfnWriter The output writer callback.
1661 * @param pvUser The user argument to pass to @a pfnWriter.
1662 * @param pErrInfo Where to store extended error information.
1663 * Optional.
1664 */
1665RTDECL(int) RTAsn1EncodeWrite(PCRTASN1CORE pRoot, uint32_t fFlags, FNRTASN1ENCODEWRITER pfnWriter, void *pvUser,
1666 PRTERRINFO pErrInfo);
1667
1668/**
1669 * Encodes and writes an ASN.1 object into a caller allocated memory buffer.
1670 *
1671 * @returns IPRT status code
1672 * @param pRoot The root of the ASN.1 object tree to encode.
1673 * @param fFlags Valid combination of the RTASN1ENCODE_F_XXX
1674 * flags. Must include the encoding type.
1675 * @param pvBuf The output buffer.
1676 * @param cbBuf The buffer size. This should have the size
1677 * returned by RTAsn1EncodePrepare().
1678 * @param pErrInfo Where to store extended error information.
1679 * Optional.
1680 */
1681RTDECL(int) RTAsn1EncodeToBuffer(PCRTASN1CORE pRoot, uint32_t fFlags, void *pvBuf, size_t cbBuf, PRTERRINFO pErrInfo);
1682
1683/**
1684 * Helper for when DER encoded ASN.1 is needed for something.
1685 *
1686 * Handy when interfacing with OpenSSL and the many d2i_Xxxxx OpenSSL functions,
1687 * but also handy when structures needs to be digested or similar during signing
1688 * or verification.
1689 *
1690 * We sometimes can use the data we've decoded directly, but often we have to
1691 * encode it into a temporary heap buffer.
1692 *
1693 * @returns IPRT status code, details in @a pErrInfo if present.
1694 * @param pRoot The ASN.1 root of the structure to be passed to OpenSSL.
1695 * @param ppbRaw Where to return the pointer to raw encoded data.
1696 * @param pcbRaw Where to return the size of the raw encoded data.
1697 * @param ppvFree Where to return what to pass to RTMemTmpFree, i.e. NULL
1698 * if we use the previously decoded data directly and
1699 * non-NULL if we had to allocate heap and encode it.
1700 * @param pErrInfo Where to return details about encoding issues. Optional.
1701 */
1702RTDECL(int) RTAsn1EncodeQueryRawBits(PRTASN1CORE pRoot, const uint8_t **ppbRaw, uint32_t *pcbRaw,
1703 void **ppvFree, PRTERRINFO pErrInfo);
1704
1705/** @} */
1706
1707
1708
1709/** @defgroup rp_asn1_cursor RTAsn1Cursor - BER, DER, and CER cursor
1710 * @{ */
1711
1712/**
1713 * ASN.1 decoder byte cursor.
1714 */
1715typedef struct RTASN1CURSOR
1716{
1717 /** Pointer to the current (next) byte. */
1718 uint8_t const *pbCur;
1719 /** Number of bytes left to decode. */
1720 uint32_t cbLeft;
1721 /** RTASN1CURSOR_FLAGS_XXX. */
1722 uint8_t fFlags;
1723 /** The cursor depth. */
1724 uint8_t cDepth;
1725 /** Two bytes reserved for future tricks. */
1726 uint8_t abReserved[2];
1727 /** Pointer to the primary cursor. */
1728 struct RTASN1CURSORPRIMARY *pPrimary;
1729 /** Pointer to the parent cursor. */
1730 struct RTASN1CURSOR *pUp;
1731 /** The error tag for this cursor level. */
1732 const char *pszErrorTag;
1733} RTASN1CURSOR;
1734
1735/** @name RTASN1CURSOR_FLAGS_XXX - Cursor flags.
1736 * @{ */
1737/** Enforce DER rules. */
1738#define RTASN1CURSOR_FLAGS_DER RT_BIT(1)
1739/** Enforce CER rules. */
1740#define RTASN1CURSOR_FLAGS_CER RT_BIT(2)
1741/** Pending indefinite length encoding. */
1742#define RTASN1CURSOR_FLAGS_INDEFINITE_LENGTH RT_BIT(3)
1743/** @} */
1744
1745
1746typedef struct RTASN1CURSORPRIMARY
1747{
1748 /** The normal cursor bits. */
1749 RTASN1CURSOR Cursor;
1750 /** For error reporting. */
1751 PRTERRINFO pErrInfo;
1752 /** The allocator virtual method table. */
1753 PCRTASN1ALLOCATORVTABLE pAllocator;
1754 /** Pointer to the first byte. Useful for calculating offsets. */
1755 uint8_t const *pbFirst;
1756} RTASN1CURSORPRIMARY;
1757typedef RTASN1CURSORPRIMARY *PRTASN1CURSORPRIMARY;
1758
1759
1760/**
1761 * Initializes a primary cursor.
1762 *
1763 * The primary cursor is special in that it stores information shared with the
1764 * sub-cursors created by methods like RTAsn1CursorGetContextTagNCursor and
1765 * RTAsn1CursorGetSequenceCursor. Even if just sharing a few items at present,
1766 * it still important to save every possible byte since stack space is scarce in
1767 * some of the execution environments.
1768 *
1769 * @returns Pointer to pCursor->Cursor.
1770 * @param pPrimaryCursor The primary cursor structure to initialize.
1771 * @param pvFirst The first byte to decode.
1772 * @param cb The number of bytes to decode.
1773 * @param pErrInfo Where to store error information.
1774 * @param pAllocator The allocator to use.
1775 * @param fFlags RTASN1CURSOR_FLAGS_XXX.
1776 * @param pszErrorTag The primary error tag.
1777 */
1778RTDECL(PRTASN1CURSOR) RTAsn1CursorInitPrimary(PRTASN1CURSORPRIMARY pPrimaryCursor, void const *pvFirst, uint32_t cb,
1779 PRTERRINFO pErrInfo, PCRTASN1ALLOCATORVTABLE pAllocator, uint32_t fFlags,
1780 const char *pszErrorTag);
1781
1782RTDECL(int) RTAsn1CursorInitSub(PRTASN1CURSOR pParent, uint32_t cb, PRTASN1CURSOR pChild, const char *pszErrorTag);
1783
1784/**
1785 * Initialize a sub-cursor for traversing the content of an ASN.1 object.
1786 *
1787 * @returns IPRT status code.
1788 * @param pParent The parent cursor.
1789 * @param pAsn1Core The ASN.1 object which content we should
1790 * traverse with the sub-cursor.
1791 * @param pChild The sub-cursor to initialize.
1792 * @param pszErrorTag The error tag of the sub-cursor.
1793 */
1794RTDECL(int) RTAsn1CursorInitSubFromCore(PRTASN1CURSOR pParent, PRTASN1CORE pAsn1Core,
1795 PRTASN1CURSOR pChild, const char *pszErrorTag);
1796
1797/**
1798 * Initalizes the an allocation structure prior to making an allocation.
1799 *
1800 * To try unify and optimize memory managment for decoding and in-memory
1801 * construction of ASN.1 objects, each allocation has an allocation structure
1802 * associated with it. This stores the allocator and keep statistics for
1803 * optimizing resizable allocations.
1804 *
1805 * @returns Pointer to the allocator info (for call in alloc parameter).
1806 * @param pCursor The cursor.
1807 * @param pAllocation The allocation structure to initialize.
1808 */
1809RTDECL(PRTASN1ALLOCATION) RTAsn1CursorInitAllocation(PRTASN1CURSOR pCursor, PRTASN1ALLOCATION pAllocation);
1810
1811/**
1812 * Initalizes the an array allocation structure prior to making an allocation.
1813 *
1814 * This is a special case of RTAsn1CursorInitAllocation. We store a little bit
1815 * more detail here in order to optimize growing and shrinking of arrays.
1816 *
1817 * @returns Pointer to the allocator info (for call in alloc parameter).
1818 * @param pCursor The cursor.
1819 * @param pAllocation The allocation structure to initialize.
1820 * @param cbEntry The array entry size.
1821 */
1822RTDECL(PRTASN1ARRAYALLOCATION) RTAsn1CursorInitArrayAllocation(PRTASN1CURSOR pCursor, PRTASN1ARRAYALLOCATION pAllocation,
1823 size_t cbEntry);
1824
1825/**
1826 * Wrapper around RTErrInfoSetV.
1827 *
1828 * @returns @a rc
1829 * @param pCursor The cursor.
1830 * @param rc The return code to return.
1831 * @param pszMsg Message format string.
1832 * @param ... Format arguments.
1833 */
1834RTDECL(int) RTAsn1CursorSetInfo(PRTASN1CURSOR pCursor, int rc, const char *pszMsg, ...) RT_IPRT_FORMAT_ATTR(3, 4);
1835
1836/**
1837 * Wrapper around RTErrInfoSetV.
1838 *
1839 * @returns @a rc
1840 * @param pCursor The cursor.
1841 * @param rc The return code to return.
1842 * @param pszMsg Message format string.
1843 * @param va Format arguments.
1844 */
1845RTDECL(int) RTAsn1CursorSetInfoV(PRTASN1CURSOR pCursor, int rc, const char *pszMsg, va_list va) RT_IPRT_FORMAT_ATTR(3, 0);
1846
1847/**
1848 * Checks that we've reached the end of the data for the cursor.
1849 *
1850 * This differs from RTAsn1CursorCheckEnd in that it does not consider the end
1851 * an error and therefore leaves the error buffer alone.
1852 *
1853 * @returns True if end, otherwise false.
1854 * @param pCursor The cursor we're decoding from.
1855 */
1856RTDECL(bool) RTAsn1CursorIsEnd(PRTASN1CURSOR pCursor);
1857
1858/**
1859 * Checks that we've reached the end of the data for the cursor.
1860 *
1861 * @returns IPRT status code.
1862 * @param pCursor The cursor we're decoding from.
1863 */
1864RTDECL(int) RTAsn1CursorCheckEnd(PRTASN1CURSOR pCursor);
1865
1866/**
1867 * Specialization of RTAsn1CursorCheckEnd for handling indefinite length sequences.
1868 *
1869 * Makes sure we've reached the end of the data for the cursor, and in case of a
1870 * an indefinite length sequence it may adjust sequence length and the parent
1871 * cursor.
1872 *
1873 * @returns IPRT status code.
1874 * @param pCursor The cursor we're decoding from.
1875 * @param pSeqCore The sequence core record.
1876 * @sa RTAsn1CursorCheckSetEnd, RTAsn1CursorCheckOctStrEnd,
1877 * RTAsn1CursorCheckEnd
1878 */
1879RTDECL(int) RTAsn1CursorCheckSeqEnd(PRTASN1CURSOR pCursor, PRTASN1SEQUENCECORE pSeqCore);
1880
1881/**
1882 * Specialization of RTAsn1CursorCheckEnd for handling indefinite length sets.
1883 *
1884 * Makes sure we've reached the end of the data for the cursor, and in case of a
1885 * an indefinite length sets it may adjust set length and the parent cursor.
1886 *
1887 * @returns IPRT status code.
1888 * @param pCursor The cursor we're decoding from.
1889 * @param pSetCore The set core record.
1890 * @sa RTAsn1CursorCheckSeqEnd, RTAsn1CursorCheckOctStrEnd,
1891 * RTAsn1CursorCheckEnd
1892 */
1893RTDECL(int) RTAsn1CursorCheckSetEnd(PRTASN1CURSOR pCursor, PRTASN1SETCORE pSetCore);
1894
1895/**
1896 * Specialization of RTAsn1CursorCheckEnd for handling indefinite length
1897 * constructed octet strings.
1898 *
1899 * This function must used when parsing the content of an octet string, like
1900 * for example the Content of a PKCS\#7 ContentInfo structure. It makes sure
1901 * we've reached the end of the data for the cursor, and in case of a an
1902 * indefinite length sets it may adjust set length and the parent cursor.
1903 *
1904 * @returns IPRT status code.
1905 * @param pCursor The cursor we're decoding from.
1906 * @param pOctetString The octet string.
1907 * @sa RTAsn1CursorCheckSeqEnd, RTAsn1CursorCheckSetEnd,
1908 * RTAsn1CursorCheckEnd
1909 */
1910RTDECL(int) RTAsn1CursorCheckOctStrEnd(PRTASN1CURSOR pCursor, PRTASN1OCTETSTRING pOctetString);
1911
1912
1913/**
1914 * Skips a given number of bytes.
1915 *
1916 * @returns @a pCursor
1917 * @param pCursor The cursor.
1918 * @param cb The number of bytes to skip.
1919 * @internal
1920 */
1921DECLINLINE(PRTASN1CURSOR) RTAsn1CursorSkip(PRTASN1CURSOR pCursor, uint32_t cb)
1922{
1923 if (cb <= pCursor->cbLeft)
1924 {
1925 pCursor->cbLeft -= cb;
1926 pCursor->pbCur += cb;
1927 }
1928 else
1929 {
1930 pCursor->pbCur += pCursor->cbLeft;
1931 pCursor->cbLeft = 0;
1932 }
1933
1934 return pCursor;
1935}
1936
1937/**
1938 * Low-level function for reading an ASN.1 header.
1939 *
1940 * @returns IPRT status code.
1941 * @param pCursor The cursor we're decoding from.
1942 * @param pAsn1Core The output object core.
1943 * @param pszErrorTag Error tag.
1944 * @internal
1945 */
1946RTDECL(int) RTAsn1CursorReadHdr(PRTASN1CURSOR pCursor, PRTASN1CORE pAsn1Core, const char *pszErrorTag);
1947
1948/**
1949 * Common helper for simple tag matching.
1950 *
1951 * @returns IPRT status code.
1952 * @param pCursor The cursor (for error reporting).
1953 * @param pAsn1Core The ASN.1 core structure.
1954 * @param uTag The expected tag.
1955 * @param fClass The expected class.
1956 * @param fString Set if it's a string type that shall follow
1957 * special CER and DER rules wrt to constructed and
1958 * primitive encoding.
1959 * @param fFlags The RTASN1CURSOR_GET_F_XXX flags.
1960 * @param pszErrorTag The error tag.
1961 * @param pszWhat The type/whatever name.
1962 */
1963RTDECL(int) RTAsn1CursorMatchTagClassFlagsEx(PRTASN1CURSOR pCursor, PRTASN1CORE pAsn1Core, uint32_t uTag, uint32_t fClass,
1964 bool fString, uint32_t fFlags, const char *pszErrorTag, const char *pszWhat);
1965
1966/**
1967 * Common helper for simple tag matching.
1968 *
1969 * @returns IPRT status code.
1970 * @param pCursor The cursor (for error reporting).
1971 * @param pAsn1Core The ASN.1 core structure.
1972 * @param uTag The expected tag.
1973 * @param fClass The expected class.
1974 * @param fFlags The RTASN1CURSOR_GET_F_XXX flags.
1975 * @param pszErrorTag The error tag.
1976 * @param pszWhat The type/whatever name.
1977 * @internal
1978 */
1979DECLINLINE(int) RTAsn1CursorMatchTagClassFlags(PRTASN1CURSOR pCursor, PRTASN1CORE pAsn1Core, uint32_t uTag, uint32_t fClass,
1980 uint32_t fFlags, const char *pszErrorTag, const char *pszWhat)
1981{
1982 if (pAsn1Core->uTag == uTag && pAsn1Core->fClass == fClass)
1983 return VINF_SUCCESS;
1984 return RTAsn1CursorMatchTagClassFlagsEx(pCursor, pAsn1Core, uTag, fClass, false /*fString*/, fFlags, pszErrorTag, pszWhat);
1985}
1986
1987
1988/**
1989 * Common helper for simple tag matching for strings.
1990 *
1991 * Check string encoding considerations.
1992 *
1993 * @returns IPRT status code.
1994 * @param pCursor The cursor (for error reporting).
1995 * @param pAsn1Core The ASN.1 core structure.
1996 * @param uTag The expected tag.
1997 * @param fClass The expected class.
1998 * @param fFlags The RTASN1CURSOR_GET_F_XXX flags.
1999 * @param pszErrorTag The error tag.
2000 * @param pszWhat The type/whatever name.
2001 * @internal
2002 */
2003DECLINLINE(int) RTAsn1CursorMatchTagClassFlagsString(PRTASN1CURSOR pCursor, PRTASN1CORE pAsn1Core, uint32_t uTag, uint32_t fClass,
2004 uint32_t fFlags, const char *pszErrorTag, const char *pszWhat)
2005{
2006 if (pAsn1Core->uTag == uTag && pAsn1Core->fClass == fClass)
2007 return VINF_SUCCESS;
2008 return RTAsn1CursorMatchTagClassFlagsEx(pCursor, pAsn1Core, uTag, fClass, true /*fString*/, fFlags, pszErrorTag, pszWhat);
2009}
2010
2011
2012
2013/** @name RTASN1CURSOR_GET_F_XXX - Common flags for all the getters.
2014 * @{ */
2015/** Used for decoding objects with implicit tags assigned to them. This only
2016 * works when calling getters with a unambigious types. */
2017#define RTASN1CURSOR_GET_F_IMPLICIT RT_BIT_32(0)
2018/** @} */
2019
2020/**
2021 * Read ANY object.
2022 *
2023 * @returns IPRT status code.
2024 * @param pCursor The cursor we're decoding from.
2025 * @param fFlags RTASN1CURSOR_GET_F_XXX.
2026 * @param pAsn1Core The output object core.
2027 * @param pszErrorTag Error tag.
2028 */
2029RTDECL(int) RTAsn1CursorGetCore(PRTASN1CURSOR pCursor, uint32_t fFlags, PRTASN1CORE pAsn1Core, const char *pszErrorTag);
2030
2031/**
2032 * Read a NULL object.
2033 *
2034 * @returns IPRT status code.
2035 * @param pCursor The cursor we're decoding from.
2036 * @param fFlags RTASN1CURSOR_GET_F_XXX.
2037 * @param pNull The output NULL object.
2038 * @param pszErrorTag Error tag.
2039 */
2040RTDECL(int) RTAsn1CursorGetNull(PRTASN1CURSOR pCursor, uint32_t fFlags, PRTASN1NULL pNull, const char *pszErrorTag);
2041
2042/**
2043 * Read an INTEGER object.
2044 *
2045 * @returns IPRT status code.
2046 * @param pCursor The cursor we're decoding from.
2047 * @param fFlags RTASN1CURSOR_GET_F_XXX.
2048 * @param pInteger The output integer object.
2049 * @param pszErrorTag Error tag.
2050 */
2051RTDECL(int) RTAsn1CursorGetInteger(PRTASN1CURSOR pCursor, uint32_t fFlags, PRTASN1INTEGER pInteger, const char *pszErrorTag);
2052
2053/**
2054 * Read an BOOLEAN object.
2055 *
2056 * @returns IPRT status code.
2057 * @param pCursor The cursor we're decoding from.
2058 * @param fFlags RTASN1CURSOR_GET_F_XXX.
2059 * @param pBoolean The output boolean object.
2060 * @param pszErrorTag Error tag.
2061 */
2062RTDECL(int) RTAsn1CursorGetBoolean(PRTASN1CURSOR pCursor, uint32_t fFlags, PRTASN1BOOLEAN pBoolean, const char *pszErrorTag);
2063
2064/**
2065 * Retrives an object identifier (aka ObjId or OID) item from the ASN.1 stream.
2066 *
2067 * @returns IPRT status code.
2068 * @param pCursor The cursor.
2069 * @param fFlags RTASN1CURSOR_GET_F_XXX.
2070 * @param pObjId The output ODI object.
2071 * @param pszErrorTag Error tag.
2072 */
2073RTDECL(int) RTAsn1CursorGetObjId(PRTASN1CURSOR pCursor, uint32_t fFlags, PRTASN1OBJID pObjId, const char *pszErrorTag);
2074
2075/**
2076 * Retrives and verifies an object identifier.
2077 *
2078 * @returns IPRT status code.
2079 * @param pCursor The cursor.
2080 * @param fFlags RTASN1CURSOR_GET_F_XXX.
2081 * @param pObjId Where to return the parsed object ID, optional.
2082 * @param pszExpectedObjId The expected object identifier (dotted).
2083 * @param pszErrorTag Error tag.
2084 */
2085RTDECL(int) RTAsn1CursorGetAndCheckObjId(PRTASN1CURSOR pCursor, uint32_t fFlags, PRTASN1OBJID pObjId,
2086 const char *pszExpectedObjId, const char *pszErrorTag);
2087
2088/**
2089 * Read an UTC TIME or GENERALIZED TIME object.
2090 *
2091 * @returns IPRT status code.
2092 * @param pCursor The cursor we're decoding from.
2093 * @param fFlags RTASN1CURSOR_GET_F_XXX.
2094 * @param pTime The output time object.
2095 * @param pszErrorTag Error tag.
2096 */
2097RTDECL(int) RTAsn1CursorGetTime(PRTASN1CURSOR pCursor, uint32_t fFlags, PRTASN1TIME pTime, const char *pszErrorTag);
2098
2099/**
2100 * Read an BIT STRING object (skips past the content).
2101 *
2102 * @returns IPRT status ocde.
2103 * @param pCursor The cursor.
2104 * @param fFlags RTASN1CURSOR_GET_F_XXX.
2105 * @param pBitString The output bit string object.
2106 * @param pszErrorTag Error tag.
2107 */
2108RTDECL(int) RTAsn1CursorGetBitString(PRTASN1CURSOR pCursor, uint32_t fFlags, PRTASN1BITSTRING pBitString,
2109 const char *pszErrorTag);
2110
2111/**
2112 * Read an BIT STRING object (skips past the content), extended version with
2113 * cMaxBits.
2114 *
2115 * @returns IPRT status ocde.
2116 * @param pCursor The cursor.
2117 * @param fFlags RTASN1CURSOR_GET_F_XXX.
2118 * @param cMaxBits The max length of the bit string in bits. Pass
2119 * UINT32_MAX if variable size.
2120 * @param pBitString The output bit string object.
2121 * @param pszErrorTag Error tag.
2122 */
2123RTDECL(int) RTAsn1CursorGetBitStringEx(PRTASN1CURSOR pCursor, uint32_t fFlags, uint32_t cMaxBits, PRTASN1BITSTRING pBitString,
2124 const char *pszErrorTag);
2125
2126/**
2127 * Read an OCTET STRING object (skips past the content).
2128 *
2129 * @returns IPRT status ocde.
2130 * @param pCursor The cursor.
2131 * @param fFlags RTASN1CURSOR_GET_F_XXX.
2132 * @param pOctetString The output octet string object.
2133 * @param pszErrorTag Error tag.
2134 */
2135RTDECL(int) RTAsn1CursorGetOctetString(PRTASN1CURSOR pCursor, uint32_t fFlags, PRTASN1OCTETSTRING pOctetString,
2136 const char *pszErrorTag);
2137
2138/**
2139 * Read any kind of string object, except 'character string (29)'.
2140 *
2141 * @returns IPRT status code.
2142 * @param pCursor The cursor we're decoding from.
2143 * @param fFlags RTASN1CURSOR_GET_F_XXX.
2144 * @param pString The output boolean object.
2145 * @param pszErrorTag Error tag.
2146 */
2147RTDECL(int) RTAsn1CursorGetString(PRTASN1CURSOR pCursor, uint32_t fFlags, PRTASN1STRING pString, const char *pszErrorTag);
2148
2149/**
2150 * Read a IA5 STRING object.
2151 *
2152 * @returns IPRT status code.
2153 * @param pCursor The cursor we're decoding from.
2154 * @param fFlags RTASN1CURSOR_GET_F_XXX.
2155 * @param pString The output boolean object.
2156 * @param pszErrorTag Error tag.
2157 */
2158RTDECL(int) RTAsn1CursorGetIa5String(PRTASN1CURSOR pCursor, uint32_t fFlags, PRTASN1STRING pString, const char *pszErrorTag);
2159
2160/**
2161 * Read a UTF8 STRING object.
2162 *
2163 * @returns IPRT status code.
2164 * @param pCursor The cursor we're decoding from.
2165 * @param fFlags RTASN1CURSOR_GET_F_XXX.
2166 * @param pString The output boolean object.
2167 * @param pszErrorTag Error tag.
2168 */
2169RTDECL(int) RTAsn1CursorGetUtf8String(PRTASN1CURSOR pCursor, uint32_t fFlags, PRTASN1STRING pString, const char *pszErrorTag);
2170
2171/**
2172 * Read a BMP STRING (UCS-2) object.
2173 *
2174 * @returns IPRT status code.
2175 * @param pCursor The cursor we're decoding from.
2176 * @param fFlags RTASN1CURSOR_GET_F_XXX.
2177 * @param pString The output boolean object.
2178 * @param pszErrorTag Error tag.
2179 */
2180RTDECL(int) RTAsn1CursorGetBmpString(PRTASN1CURSOR pCursor, uint32_t fFlags, PRTASN1STRING pString, const char *pszErrorTag);
2181
2182/**
2183 * Read a SEQUENCE object and create a cursor for its content.
2184 *
2185 * @returns IPRT status code.
2186 * @param pCursor The cursor we're decoding from.
2187 * @param fFlags RTASN1CURSOR_GET_F_XXX.
2188 * @param pSeqCore The output sequence core object.
2189 * @param pSeqCursor The output cursor for the sequence content.
2190 * @param pszErrorTag Error tag, this will be associated with the
2191 * returned cursor.
2192 */
2193RTDECL(int) RTAsn1CursorGetSequenceCursor(PRTASN1CURSOR pCursor, uint32_t fFlags,
2194 PRTASN1SEQUENCECORE pSeqCore, PRTASN1CURSOR pSeqCursor, const char *pszErrorTag);
2195
2196/**
2197 * Read a SET object and create a cursor for its content.
2198 *
2199 * @returns IPRT status code.
2200 * @param pCursor The cursor we're decoding from.
2201 * @param fFlags RTASN1CURSOR_GET_F_XXX.
2202 * @param pSetCore The output set core object.
2203 * @param pSetCursor The output cursor for the set content.
2204 * @param pszErrorTag Error tag, this will be associated with the
2205 * returned cursor.
2206 */
2207RTDECL(int) RTAsn1CursorGetSetCursor(PRTASN1CURSOR pCursor, uint32_t fFlags,
2208 PRTASN1SETCORE pSetCore, PRTASN1CURSOR pSetCursor, const char *pszErrorTag);
2209
2210/**
2211 * Read a given constructed context tag and create a cursor for its content.
2212 *
2213 * @returns IPRT status code.
2214 * @param pCursor The cursor we're decoding from.
2215 * @param fFlags RTASN1CURSOR_GET_F_XXX.
2216 * @param uExpectedTag The expected tag.
2217 * @param pVtable The vtable for the context tag node (see
2218 * RTASN1TMPL_PASS_XTAG).
2219 * @param pCtxTag The output context tag object.
2220 * @param pCtxTagCursor The output cursor for the context tag content.
2221 * @param pszErrorTag Error tag, this will be associated with the
2222 * returned cursor.
2223 *
2224 * @remarks There are specialized version of this function for each of the
2225 * numbered context tag structures, like for RTASN1CONTEXTTAG0 there is
2226 * RTAsn1CursorGetContextTag0Cursor.
2227 */
2228RTDECL(int) RTAsn1CursorGetContextTagNCursor(PRTASN1CURSOR pCursor, uint32_t fFlags, uint32_t uExpectedTag,
2229 PCRTASN1COREVTABLE pVtable, PRTASN1CONTEXTTAG pCtxTag, PRTASN1CURSOR pCtxTagCursor,
2230 const char *pszErrorTag);
2231
2232/**
2233 * Read a dynamic ASN.1 type.
2234 *
2235 * @returns IPRT status code.
2236 * @param pCursor The cursor we're decoding from.
2237 * @param fFlags RTASN1CURSOR_GET_F_XXX.
2238 * @param pDynType The output context tag object.
2239 * @param pszErrorTag Error tag.
2240 */
2241RTDECL(int) RTAsn1CursorGetDynType(PRTASN1CURSOR pCursor, uint32_t fFlags, PRTASN1DYNTYPE pDynType, const char *pszErrorTag);
2242
2243/**
2244 * Peeks at the next ASN.1 object.
2245 *
2246 * @returns IPRT status code.
2247 * @param pCursor The cursore we're decoding from.
2248 * @param pAsn1Core Where to store the output of the peek.
2249 */
2250RTDECL(int) RTAsn1CursorPeek(PRTASN1CURSOR pCursor, PRTASN1CORE pAsn1Core);
2251
2252/**
2253 * Checks if the next ASN.1 object matches the given tag and class/flags.
2254 *
2255 * @returns @c true on match, @c false on mismatch.
2256 * @param pCursor The cursore we're decoding from.
2257 * @param uTag The tag number to match against.
2258 * @param fClass The tag class and flags to match against.
2259 */
2260RTDECL(bool) RTAsn1CursorIsNextEx(PRTASN1CURSOR pCursor, uint32_t uTag, uint8_t fClass);
2261
2262
2263
2264/** @internal */
2265#define RTASN1CONTEXTTAG_IMPL_CURSOR_INLINES(a_uTag) \
2266 DECLINLINE(int) RT_CONCAT3(RTAsn1CursorGetContextTag,a_uTag,Cursor)(PRTASN1CURSOR pCursor, uint32_t fFlags, \
2267 PCRTASN1COREVTABLE pVtable, \
2268 RT_CONCAT(PRTASN1CONTEXTTAG,a_uTag) pCtxTag, \
2269 PRTASN1CURSOR pCtxTagCursor, const char *pszErrorTag) \
2270 { /* Constructed is automatically implied if you need a cursor to it. */ \
2271 return RTAsn1CursorGetContextTagNCursor(pCursor, fFlags, a_uTag, pVtable, (PRTASN1CONTEXTTAG)pCtxTag, pCtxTagCursor, pszErrorTag); \
2272 } \
2273 DECLINLINE(int) RT_CONCAT3(RTAsn1ContextTag,a_uTag,InitDefault)(RT_CONCAT(PRTASN1CONTEXTTAG,a_uTag) pCtxTag) \
2274 { /* Constructed is automatically implied if you need to init it with a default value. */ \
2275 return RTAsn1Core_InitDefault(&pCtxTag->Asn1Core, a_uTag, ASN1_TAGCLASS_CONTEXT | ASN1_TAGFLAG_CONSTRUCTED); \
2276 } \
2277 DECLINLINE(int) RT_CONCAT3(RTAsn1CursorIsConstructedContextTag,a_uTag,Next)(PRTASN1CURSOR pCursor) \
2278 { \
2279 return RTAsn1CursorIsNextEx(pCursor, a_uTag, ASN1_TAGCLASS_CONTEXT | ASN1_TAGFLAG_CONSTRUCTED); \
2280 } \
2281 DECLINLINE(int) RT_CONCAT3(RTAsn1CursorIsPrimitiveContextTag,a_uTag,Next)(PRTASN1CURSOR pCursor) \
2282 { \
2283 return RTAsn1CursorIsNextEx(pCursor, a_uTag, ASN1_TAGCLASS_CONTEXT | ASN1_TAGFLAG_PRIMITIVE); \
2284 } \
2285 DECLINLINE(int) RT_CONCAT3(RTAsn1CursorIsAnyContextTag,a_uTag,Next)(PRTASN1CURSOR pCursor) \
2286 { \
2287 return RTAsn1CursorIsNextEx(pCursor, a_uTag, ASN1_TAGCLASS_CONTEXT | ASN1_TAGFLAG_CONSTRUCTED) \
2288 || RTAsn1CursorIsNextEx(pCursor, a_uTag, ASN1_TAGCLASS_CONTEXT | ASN1_TAGFLAG_PRIMITIVE);\
2289 } \
2290
2291RTASN1CONTEXTTAG_IMPL_CURSOR_INLINES(0)
2292RTASN1CONTEXTTAG_IMPL_CURSOR_INLINES(1)
2293RTASN1CONTEXTTAG_IMPL_CURSOR_INLINES(2)
2294RTASN1CONTEXTTAG_IMPL_CURSOR_INLINES(3)
2295RTASN1CONTEXTTAG_IMPL_CURSOR_INLINES(4)
2296RTASN1CONTEXTTAG_IMPL_CURSOR_INLINES(5)
2297RTASN1CONTEXTTAG_IMPL_CURSOR_INLINES(6)
2298RTASN1CONTEXTTAG_IMPL_CURSOR_INLINES(7)
2299#undef RTASN1CONTEXTTAG_IMPL_CURSOR_INLINES
2300
2301
2302/**
2303 * Checks if the next object is a boolean.
2304 *
2305 * @returns true / false
2306 * @param pCursor The cursor we're decoding from.
2307 * @remarks May produce error info output on mismatch.
2308 */
2309DECLINLINE(bool) RTAsn1CursorIsBooleanNext(PRTASN1CURSOR pCursor)
2310{
2311 return RTAsn1CursorIsNextEx(pCursor, ASN1_TAG_BOOLEAN, ASN1_TAGFLAG_PRIMITIVE | ASN1_TAGCLASS_UNIVERSAL);
2312}
2313
2314
2315/**
2316 * Checks if the next object is a set.
2317 *
2318 * @returns true / false
2319 * @param pCursor The cursor we're decoding from.
2320 * @remarks May produce error info output on mismatch.
2321 */
2322DECLINLINE(bool) RTAsn1CursorIsSetNext(PRTASN1CURSOR pCursor)
2323{
2324 return RTAsn1CursorIsNextEx(pCursor, ASN1_TAG_SET, ASN1_TAGFLAG_CONSTRUCTED | ASN1_TAGCLASS_UNIVERSAL);
2325}
2326
2327
2328/** @} */
2329
2330
2331/** @name ASN.1 Utility APIs
2332 * @{ */
2333
2334/**
2335 * Dumps an IPRT representation of a ASN.1 object tree.
2336 *
2337 * @returns IPRT status code.
2338 * @param pAsn1Core The ASN.1 object which members should be dumped.
2339 * @param fFlags RTASN1DUMP_F_XXX.
2340 * @param uLevel The indentation level to start at.
2341 * @param pfnPrintfV The output function.
2342 * @param pvUser Argument to the output function.
2343 */
2344RTDECL(int) RTAsn1Dump(PCRTASN1CORE pAsn1Core, uint32_t fFlags, uint32_t uLevel, PFNRTDUMPPRINTFV pfnPrintfV, void *pvUser);
2345
2346/**
2347 * Queries the name for an object identifier.
2348 *
2349 * This API is very simple due to how we store the data.
2350 *
2351 * @returns IPRT status code.
2352 * @retval VINF_SUCCESS on success.
2353 * @retval VERR_NOT_FOUND if not found.
2354 * @retval VERR_BUFFER_OVERFLOW if more buffer space is required.
2355 *
2356 * @param pObjId The object ID to name.
2357 * @param pszDst Where to store the name if found.
2358 * @param cbDst The size of the destination buffer.
2359 */
2360RTDECL(int) RTAsn1QueryObjIdName(PCRTASN1OBJID pObjId, char *pszDst, size_t cbDst);
2361
2362/** @} */
2363
2364/** @} */
2365
2366RT_C_DECLS_END
2367
2368#endif /* !IPRT_INCLUDED_asn1_h */
2369
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette