asn1.h@ 51841

Last change on this file since 51841 was 51770, checked in by vboxsync, 11 years ago
Merged in iprt++ dev branch.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 84.6 KB

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

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

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

Download in other formats: