spc.h@ 56291

Last change on this file since 56291 was 56291, checked in by vboxsync, 9 years ago
include: Updated (C) year.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 17.0 KB

Line
1	/** @file
2	* IPRT - Crypto - Microsoft SPC / Authenticode.
3	*/
4
5	/*
6	* Copyright (C) 2006-2015 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_crypto_spc_h
27	#define ___iprt_crypto_spc_h
28
29	#include <iprt/asn1.h>
30	#include <iprt/crypto/x509.h>
31	#include <iprt/crypto/pkcs7.h>
32	#include <iprt/md5.h>
33	#include <iprt/sha.h>
34
35
36	RT_C_DECLS_BEGIN
37
38	/** @defgroup grp_rt_spc RTCrSpc - Microsoft Authenticode
39	* @ingroup grp_rt_crypto
40	* @{
41	*/
42
43	/**
44	* PE Image page hash table, generic union.
45	*
46	* @remarks This table isn't used by ldrPE.cpp, it walks the table in a generic
47	* fashion using the hash size. So, we can ditch it if we feel like it.
48	*/
49	typedef union RTCRSPCPEIMAGEPAGEHASHES
50	{
51	/** MD5 page hashes. */
52	struct
53	{
54	/** The file offset. */
55	uint32_t offFile;
56	/** The hash. */
57	uint8_t abHash[RTSHA1_HASH_SIZE];
58	} aMd5[1];
59
60	/** SHA-1 page hashes. */
61	struct
62	{
63	/** The file offset. */
64	uint32_t offFile;
65	/** The hash. */
66	uint8_t abHash[RTSHA1_HASH_SIZE];
67	} aSha1[1];
68
69	/** SHA-256 page hashes. */
70	struct
71	{
72	/** The file offset. */
73	uint32_t offFile;
74	/** The hash. */
75	uint8_t abHash[RTSHA256_HASH_SIZE];
76	} aSha256[1];
77
78	/** SHA-512 page hashes. */
79	struct
80	{
81	/** The file offset. */
82	uint32_t offFile;
83	/** The hash. */
84	uint8_t abHash[RTSHA512_HASH_SIZE];
85	} aSha512[1];
86	} RTCRSPCPEIMAGEPAGEHASHES;
87	/** Pointer to a PE image page hash table union. */
88	typedef RTCRSPCPEIMAGEPAGEHASHES *PRTCRSPCPEIMAGEPAGEHASHES;
89	/** Pointer to a const PE image page hash table union. */
90	typedef RTCRSPCPEIMAGEPAGEHASHES const *PCRTCRSPCPEIMAGEPAGEHASHES;
91
92
93	/**
94	* Serialization wrapper for raw RTCRSPCPEIMAGEPAGEHASHES data.
95	*/
96	typedef struct RTCRSPCSERIALIZEDPAGEHASHES
97	{
98	/** The page hashes are within a set. Dunno if there could be multiple
99	* entries in this set, never seen it yet, so I doubt it. */
100	RTASN1SETCORE SetCore;
101	/** Octet string containing the raw data. */
102	RTASN1OCTETSTRING RawData;
103
104	/** Pointer to the hash data within that string.
105	* The hash algorithm is given by the object attribute type in
106	* RTCRSPCSERIALIZEDOBJECTATTRIBUTE. It is generally the same as for the
107	* whole image hash. */
108	PCRTCRSPCPEIMAGEPAGEHASHES pData;
109	/** Field the user can use to store the number of pages in pData. */
110	uint32_t cPages;
111	} RTCRSPCSERIALIZEDPAGEHASHES;
112	/** Pointer to a serialized wrapper for page hashes. */
113	typedef RTCRSPCSERIALIZEDPAGEHASHES *PRTCRSPCSERIALIZEDPAGEHASHES;
114	/** Pointer to a const serialized wrapper for page hashes. */
115	typedef RTCRSPCSERIALIZEDPAGEHASHES const *PCRTCRSPCSERIALIZEDPAGEHASHES;
116	RTASN1TYPE_STANDARD_PROTOTYPES(RTCRSPCSERIALIZEDPAGEHASHES, RTDECL, RTCrSpcSerializedPageHashes, SetCore.Asn1Core);
117
118	RTDECL(int) RTCrSpcSerializedPageHashes_UpdateDerivedData(PRTCRSPCSERIALIZEDPAGEHASHES pThis);
119
120
121	/**
122	* Data type selection for RTCRSPCSERIALIZEDOBJECTATTRIBUTE.
123	*/
124	typedef enum RTCRSPCSERIALIZEDOBJECTATTRIBUTETYPE
125	{
126	/** Invalid zero entry. */
127	RTCRSPCSERIALIZEDOBJECTATTRIBUTETYPE_INVALID = 0,
128	/** Not present pro forma. */
129	RTCRSPCSERIALIZEDOBJECTATTRIBUTETYPE_NOT_PRESENT,
130	/** Unknown object. */
131	RTCRSPCSERIALIZEDOBJECTATTRIBUTETYPE_UNKNOWN,
132	/** SHA-1 page hashes (pPageHashes). */
133	RTCRSPCSERIALIZEDOBJECTATTRIBUTETYPE_PAGE_HASHES_V1,
134	/** SHA-256 page hashes (pPageHashes). */
135	RTCRSPCSERIALIZEDOBJECTATTRIBUTETYPE_PAGE_HASHES_V2,
136	/** End of valid values. */
137	RTCRSPCSERIALIZEDOBJECTATTRIBUTETYPE_END,
138	/** Blow up the type to at least 32-bits. */
139	RTCRSPCSERIALIZEDOBJECTATTRIBUTETYPE_32BIT_HACK
140	} RTCRSPCSERIALIZEDOBJECTATTRIBUTETYPE;
141
142	/**
143	* One serialized object attribute (PE image data).
144	*/
145	typedef struct RTCRSPCSERIALIZEDOBJECTATTRIBUTE
146	{
147	/** Sequence core. */
148	RTASN1SEQUENCECORE SeqCore;
149	/** The attribute type. */
150	RTASN1OBJID Type;
151	/** The allocation of the data type. */
152	RTASN1ALLOCATION Allocation;
153	/** Indicates the valid value in the union. */
154	RTCRSPCSERIALIZEDOBJECTATTRIBUTETYPE enmType;
155	/** Union with data format depending on the Type. */
156	union
157	{
158	/** The unknown value (RTCRSPCSERIALIZEDOBJECTATTRIBUTETYPE_UNKNOWN). */
159	PRTASN1CORE pCore;
160	/** Page hashes (RTCRSPCSERIALIZEDOBJECTATTRIBUTETYPE_PAGE_HASHES_V1 or
161	* RTCRSPCSERIALIZEDOBJECTATTRIBUTETYPE_PAGE_HASHES_V2). */
162	PRTCRSPCSERIALIZEDPAGEHASHES pPageHashes;
163	} u;
164	} RTCRSPCSERIALIZEDOBJECTATTRIBUTE;
165	/** Pointer to a serialized object attribute. */
166	typedef RTCRSPCSERIALIZEDOBJECTATTRIBUTE *PRTCRSPCSERIALIZEDOBJECTATTRIBUTE;
167	/** Pointer to a const serialized object attribute. */
168	typedef RTCRSPCSERIALIZEDOBJECTATTRIBUTE const *PCRTCRSPCSERIALIZEDOBJECTATTRIBUTE;
169	RTASN1TYPE_STANDARD_PROTOTYPES(RTCRSPCSERIALIZEDOBJECTATTRIBUTE, RTDECL, RTCrSpcSerializedObjectAttribute, SeqCore.Asn1Core);
170
171	/** @name RTCRSPCSERIALIZEDOBJECTATTRIBUTE::Type values
172	* @{ */
173	/** Serialized object attribute type for page hashes version 1. */
174	#define RTCRSPC_PE_IMAGE_HASHES_V1_OID "1.3.6.1.4.1.311.2.3.1"
175	/** Serialized object attribute type for page hashes version 2. */
176	#define RTCRSPC_PE_IMAGE_HASHES_V2_OID "1.3.6.1.4.1.311.2.3.2"
177	/** @} */
178
179
180	/*
181	* Set of serialized object attributes (PE image data).
182	*/
183	RTASN1_IMPL_GEN_SET_OF_TYPEDEFS_AND_PROTOS(RTCRSPCSERIALIZEDOBJECTATTRIBUTES, RTCRSPCSERIALIZEDOBJECTATTRIBUTE, RTDECL,
184	RTCrSpcSerializedObjectAttributes);
185
186	/** The UUID found in RTCRSPCSERIALIZEDOBJECT::Uuid for
187	* RTCRSPCSERIALIZEDOBJECTATTRIBUTES. */
188	#define RTCRSPCSERIALIZEDOBJECT_UUID_STR "d586b5a6-a1b4-6624-ae05-a217da8e60d6"
189
190
191	/**
192	* Decoded encapsulated data type selection in RTCRSPCSERIALIZEDOBJECT.
193	*/
194	typedef enum RTCRSPCSERIALIZEDOBJECTTYPE
195	{
196	/** Invalid zero value. */
197	RTCRSPCSERIALIZEDOBJECTTYPE_INVALID = 0,
198	/** Serialized object attributes (RTCRSPCSERIALIZEDOBJECT_UUID_STR / pAttribs). */
199	RTCRSPCSERIALIZEDOBJECTTYPE_ATTRIBUTES,
200	/** End of valid values. */
201	RTCRSPCSERIALIZEDOBJECTTYPE_END,
202	/** MAke sure the type is at least 32-bit wide. */
203	RTCRSPCSERIALIZEDOBJECTTYPE_32BIT_HACK = 0x7fffffff
204	} RTCRSPCSERIALIZEDOBJECTTYPE;
205
206	/**
207	* A serialized object (PE image data).
208	*/
209	typedef struct RTCRSPCSERIALIZEDOBJECT
210	{
211	/** Sequence core. */
212	RTASN1SEQUENCECORE SeqCore;
213	/** The UUID of the data object. */
214	RTASN1OCTETSTRING Uuid;
215	/** Serialized data object. */
216	RTASN1OCTETSTRING SerializedData;
217
218	/** Indicates the valid pointer in the union. */
219	RTCRSPCSERIALIZEDOBJECTTYPE enmType;
220	/** Union of pointers shadowing SerializedData.pEncapsulated. */
221	union
222	{
223	/** Generic core pointer. */
224	PRTASN1CORE pCore;
225	/** Pointer to decoded data if Uuid is RTCRSPCSERIALIZEDOBJECT_UUID_STR. */
226	PRTCRSPCSERIALIZEDOBJECTATTRIBUTES pData;
227	} u;
228	} RTCRSPCSERIALIZEDOBJECT;
229	/** Pointer to a serialized object (PE image data). */
230	typedef RTCRSPCSERIALIZEDOBJECT *PRTCRSPCSERIALIZEDOBJECT;
231	/** Pointer to a const serialized object (PE image data). */
232	typedef RTCRSPCSERIALIZEDOBJECT const *PCRTCRSPCSERIALIZEDOBJECT;
233	RTASN1TYPE_STANDARD_PROTOTYPES(RTCRSPCSERIALIZEDOBJECT, RTDECL, RTCrSpcSerializedObject, SeqCore.Asn1Core);
234
235
236	/**
237	* RTCRSPCSTRING choices.
238	*/
239	typedef enum RTCRSPCSTRINGCHOICE
240	{
241	/** Invalid zero value. */
242	RTCRSPCSTRINGCHOICE_INVALID = 0,
243	/** Not present. */
244	RTCRSPCSTRINGCHOICE_NOT_PRESENT,
245	/** UCS-2 string (pUcs2). */
246	RTCRSPCSTRINGCHOICE_UCS2,
247	/** ASCII string (pAscii). */
248	RTCRSPCSTRINGCHOICE_ASCII,
249	/** End of valid values. */
250	RTCRSPCSTRINGCHOICE_END,
251	/** Blow the type up to 32-bit. */
252	RTCRSPCSTRINGCHOICE_32BIT_HACK = 0x7fffffff
253	} RTCRSPCSTRINGCHOICE;
254
255	/**
256	* Stupid microsoft choosy string type.
257	*/
258	typedef struct RTCRSPCSTRING
259	{
260	/** Dummy core. */
261	RTASN1DUMMY Dummy;
262	/** Allocation of what the pointer below points to. */
263	RTASN1ALLOCATION Allocation;
264	/** Pointer choice.*/
265	RTCRSPCSTRINGCHOICE enmChoice;
266	/** Pointer union. */
267	union
268	{
269	/** Tag 0, implicit: UCS-2 (BMP) string. */
270	PRTASN1STRING pUcs2;
271	/** Tag 1, implicit: ASCII (IA5) string. */
272	PRTASN1STRING pAscii;
273	} u;
274	} RTCRSPCSTRING;
275	/** Pointer to a stupid microsoft string choice. */
276	typedef RTCRSPCSTRING *PRTCRSPCSTRING;
277	/** Pointer to a const stupid microsoft string choice. */
278	typedef RTCRSPCSTRING const *PCRTCRSPCSTRING;
279	RTASN1TYPE_STANDARD_PROTOTYPES(RTCRSPCSTRING, RTDECL, RTCrSpcString, Dummy.Asn1Core);
280
281
282	/**
283	* RTCRSPCSTRING choices.
284	*/
285	typedef enum RTCRSPCLINKCHOICE
286	{
287	/** Invalid zero value. */
288	RTCRSPCLINKCHOICE_INVALID = 0,
289	/** Not present. */
290	RTCRSPCLINKCHOICE_NOT_PRESENT,
291	/** URL (ASCII) string (pUrl). */
292	RTCRSPCLINKCHOICE_URL,
293	/** Serialized object (pMoniker). */
294	RTCRSPCLINKCHOICE_MONIKER,
295	/** Filename (pT2). */
296	RTCRSPCLINKCHOICE_FILE,
297	/** End of valid values. */
298	RTCRSPCLINKCHOICE_END,
299	/** Blow the type up to 32-bit. */
300	RTCRSPCLINKCHOICE_32BIT_HACK = 0x7fffffff
301	} RTCRSPCLINKCHOICE;
302
303	/**
304	* PE image data link.
305	*/
306	typedef struct RTCRSPCLINK
307	{
308	/** Dummy core. */
309	RTASN1DUMMY Dummy;
310	/** Allocation of what the pointer below points to. */
311	RTASN1ALLOCATION Allocation;
312	/** Pointer choice.*/
313	RTCRSPCLINKCHOICE enmChoice;
314	/** Pointer union. */
315	union
316	{
317	/** Tag 0, implicit: An URL encoded as an IA5 STRING. */
318	PRTASN1STRING pUrl;
319	/** Tag 1, implicit: A serialized object. */
320	PRTCRSPCSERIALIZEDOBJECT pMoniker;
321	/** Tag 2, explicit: The default, a file name.
322	* Documented to be set to "<<<Obsolete>>>" when used. */
323	struct
324	{
325	/** Context tag 2. */
326	RTASN1CONTEXTTAG2 CtxTag2;
327	/** The file name string. */
328	RTCRSPCSTRING File;
329	} *pT2;
330	} u;
331	} RTCRSPCLINK;
332	/** Poitner to a PE image data link. */
333	typedef RTCRSPCLINK *PRTCRSPCLINK;
334	/** Poitner to a const PE image data link. */
335	typedef RTCRSPCLINK const *PCRTCRSPCLINK;
336	RTASN1TYPE_STANDARD_PROTOTYPES(RTCRSPCLINK, RTDECL, RTCrSpcLink, Dummy.Asn1Core);
337
338
339	#if 0 /** @todo Might not be the correct bit order. */
340	/**
341	* Flag values for RTCRSPCPEIMAGEDATA::Flags and RTCRSPCPEIMAGEDATA::fFlags.
342	*/
343	typedef enum RTCRSPCPEIMAGEFLAGS
344	{
345	RTCRSPCPEIMAGEFLAGS_INCLUDE_RESOURCES = 0,
346	RTCRSPCPEIMAGEFLAGS_INCLUDE_DEBUG_INFO = 1,
347	RTCRSPCPEIMAGEFLAGS_IMPORT_ADDRESS_TABLE = 2
348	} RTCRSPCPEIMAGEFLAGS;
349	#endif
350
351
352	/**
353	* Authenticode PE Image data.
354	*/
355	typedef struct RTCRSPCPEIMAGEDATA
356	{
357	/** Sequence core. */
358	RTASN1SEQUENCECORE SeqCore;
359	/** One of the RTCRSPCPEIMAGEFLAGS value, default is
360	* RTCRSPCPEIMAGEFLAGS_INCLUDE_RESOURCES. Obsolete with v2 page hashes? */
361	RTASN1BITSTRING Flags;
362	/** Tag 0, explicit: Link to the data. */
363	struct
364	{
365	/** Context tag 0. */
366	RTASN1CONTEXTTAG0 CtxTag0;
367	/** Link to the data. */
368	RTCRSPCLINK File;
369	} T0;
370	} RTCRSPCPEIMAGEDATA;
371	/** Pointer to a authenticode PE image data representation. */
372	typedef RTCRSPCPEIMAGEDATA *PRTCRSPCPEIMAGEDATA;
373	/** Pointer to a const authenticode PE image data representation. */
374	typedef RTCRSPCPEIMAGEDATA const *PCRTCRSPCPEIMAGEDATA;
375	RTASN1TYPE_STANDARD_PROTOTYPES(RTCRSPCPEIMAGEDATA, RTDECL, RTCrSpcPeImageData, SeqCore.Asn1Core);
376
377	/** The object ID for SpcPeImageData. */
378	#define RTCRSPCPEIMAGEDATA_OID "1.3.6.1.4.1.311.2.1.15"
379
380
381	/**
382	* Data type selection for RTCRSPCATTRIBUTETYPEANDOPTIONALVALUE.
383	*/
384	typedef enum RTCRSPCAAOVTYPE
385	{
386	/** Invalid zero entry. */
387	RTCRSPCAAOVTYPE_INVALID = 0,
388	/** Not present (pro forma). */
389	RTCRSPCAAOVTYPE_NOT_PRESENT,
390	/** Unknown object. */
391	RTCRSPCAAOVTYPE_UNKNOWN,
392	/** PE image data (pPeImage). */
393	RTCRSPCAAOVTYPE_PE_IMAGE_DATA,
394	/** End of valid values. */
395	RTCRSPCAAOVTYPE_END,
396	/** Blow up the type to at least 32-bits. */
397	RTCRSPCAAOVTYPE_32BIT_HACK
398	} RTCRSPCAAOVTYPE;
399
400	/**
401	* Authenticode attribute type and optional value.
402	*
403	* Note! Spec says the value should be explicitly tagged, but in real life
404	* it isn't. So, not very optional?
405	*/
406	typedef struct RTCRSPCATTRIBUTETYPEANDOPTIONALVALUE
407	{
408	/** Sequence core. */
409	RTASN1SEQUENCECORE SeqCore;
410	/** An object ID indicating the type of the value. */
411	RTASN1OBJID Type;
412	/** Allocation of the optional data value. */
413	RTASN1ALLOCATION Allocation;
414	/** The valid pointer. */
415	RTCRSPCAAOVTYPE enmType;
416	/** The value part depends on the Type. */
417	union
418	{
419	/** RTCRSPCAAOVTYPE_UNKNOWN / Generic. */
420	PRTASN1CORE pCore;
421	/** RTCRSPCAAOVTYPE_PE_IMAGE_DATA / RTCRSPCPEIMAGEDATA_OID. */
422	PRTCRSPCPEIMAGEDATA pPeImage;
423	} uValue;
424	} RTCRSPCATTRIBUTETYPEANDOPTIONALVALUE;
425	/** Pointer to a authentication attribute type and optional value
426	* representation. */
427	typedef RTCRSPCATTRIBUTETYPEANDOPTIONALVALUE *PRTCRSPCATTRIBUTETYPEANDOPTIONALVALUE;
428	/** Pointer to a const authentication attribute type and optional value
429	* representation. */
430	typedef RTCRSPCATTRIBUTETYPEANDOPTIONALVALUE const *PCRTCRSPCATTRIBUTETYPEANDOPTIONALVALUE;
431	RTASN1TYPE_STANDARD_PROTOTYPES(RTCRSPCATTRIBUTETYPEANDOPTIONALVALUE, RTDECL, RTCrSpcAttributeTypeAndOptionalValue, SeqCore.Asn1Core);
432
433
434	/**
435	* Authenticode indirect data content.
436	*/
437	typedef struct RTCRSPCINDIRECTDATACONTENT
438	{
439	/** Sequence core. */
440	RTASN1SEQUENCECORE SeqCore;
441	/** Additional data. */
442	RTCRSPCATTRIBUTETYPEANDOPTIONALVALUE Data;
443	/** The whole image digest. */
444	RTCRPKCS7DIGESTINFO DigestInfo;
445	} RTCRSPCINDIRECTDATACONTENT;
446	/** Pointer to a authenticode indirect data content representation. */
447	typedef RTCRSPCINDIRECTDATACONTENT *PRTCRSPCINDIRECTDATACONTENT;
448	/** Pointer to a const authenticode indirect data content representation. */
449	typedef RTCRSPCINDIRECTDATACONTENT const *PCRTCRSPCINDIRECTDATACONTENT;
450	RTASN1TYPE_STANDARD_PROTOTYPES(RTCRSPCINDIRECTDATACONTENT, RTDECL, RTCrSpcIndirectDataContent, SeqCore.Asn1Core);
451
452	/** The object ID for SpcIndirectDataContent. */
453	#define RTCRSPCINDIRECTDATACONTENT_OID "1.3.6.1.4.1.311.2.1.4"
454
455	/**
456	* Check the sanity of an Authenticode SPCIndirectDataContent object.
457	*
458	* @returns IPRT status code
459	* @param pIndData The Authenticode SPCIndirectDataContent to
460	* check.
461	* @param pSignedData The related signed data object.
462	* @param fFlags RTCRSPCINDIRECTDATACONTENT_SANITY_F_XXX.
463	* @param pErrInfo Optional error info.
464	*/
465	RTDECL(int) RTCrSpcIndirectDataContent_CheckSanityEx(PCRTCRSPCINDIRECTDATACONTENT pIndData, PCRTCRPKCS7SIGNEDDATA pSignedData,
466	uint32_t fFlags, PRTERRINFO pErrInfo);
467	/** @name RTCRSPCINDIRECTDATACONTENT_SANITY_F_XXX for RTCrSpcIndirectDataContent_CheckSanityEx.
468	* @{ */
469	/** The digest hash algorithm must be known to IPRT. */
470	#define RTCRSPCINDIRECTDATACONTENT_SANITY_F_ONLY_KNOWN_HASH RT_BIT_32(0)
471	/** PE image signing, check expectations of the spec. */
472	#define RTCRSPCINDIRECTDATACONTENT_SANITY_F_PE_IMAGE RT_BIT_32(1)
473	/** @} */
474
475	/**
476	* Gets the first SPC serialized object attribute in a SPC PE image.
477	*
478	* @returns Pointer to the attribute with the given type, NULL if not found.
479	* @param pThis The Authenticode SpcIndirectDataContent.
480	*/
481	RTDECL(PCRTCRSPCSERIALIZEDOBJECTATTRIBUTE)
482	RTCrSpcIndirectDataContent_GetPeImageObjAttrib(PCRTCRSPCINDIRECTDATACONTENT pThis,
483	RTCRSPCSERIALIZEDOBJECTATTRIBUTETYPE enmType);
484
485	/** @} */
486
487	RT_C_DECLS_END
488
489	#endif
490

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

source: vbox/trunk/include/iprt/crypto/spc.h@ 56291

Download in other formats: