asn1.h@ 81025

Last change on this file since 81025 was 76585, checked in by vboxsync, 6 years ago
*: scm --fix-header-guard-endif
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 96.2 KB

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

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: