asn1.h@ 52600

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

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

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

Download in other formats: