1/*
2 * Copyright (c) 2003-2004,2008,2010 Apple Inc. All Rights Reserved.
3 *
4 * @APPLE_LICENSE_HEADER_START@
5 *
6 * This file contains Original Code and/or Modifications of Original Code
7 * as defined in and that are subject to the Apple Public Source License
8 * Version 2.0 (the 'License'). You may not use this file except in
9 * compliance with the License. Please obtain a copy of the License at
10 * http://www.opensource.apple.com/apsl/ and read it before using this
11 * file.
12 *
13 * The Original Code and all software distributed under the License are
14 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
15 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
16 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
18 * Please see the License for the specific language governing rights and
19 * limitations under the License.
20 *
21 * @APPLE_LICENSE_HEADER_END@
22 */
23/*
24 * pkcs12Templates.h
25 *
26 *******************************************************************
27 *
28 * In a probably vain attempt to clarify the structure of a PKCS12
29 * PFX, here is a high-level summary.
30 *
31 * The top level item in P12 is a PFX.
32 *
33 * PFX = {
34 *  	int version;
35 *		ContentInfo authSafe;	-- from PKCS7
36 *		MacData mac;			-- optional, password integrity version
37 * }
38 *
39 * The authSafe in a PFX has two legal contentTypes in the P12
40 * world, CT_Data (password integrity mode) or CT_SignedData
41 * (public key integrity mode). The current version of this library
42 * only supports password integrity mode. Thus the integrity of
43 * the whole authSafe item is protected by a MAC in the PFX.
44 *
45 * The authSafe.content field is a BER-encoded AuthenticatedSafe.
46 *
47 * AuthenticatedSafe = {
48 *		SEQUENCE OF ContentInfo;
49 * }
50 *
51 * OK. Each ContentInfo in an AuthenticatedSafe can either be type
52 * CT_Data, CT_EnvData, or CT_EncryptedData. In the latter cases the
53 * content is decrypted to produce an encoded SafeContents; in the
54 * former case the content *is* an encoded SafeContents.
55 *
56 * A SafeContents is a sequence of SafeBags.
57 *
58 * Each SafeBag can be of several types:
59 *
60 *		BT_KeyBag
61 *		BT_ShroudedKeyBag
62 *		BT_CertBag
63 *		BT_CrlBag
64 *		BT_SecretBag
65 *		BT_SafeContentsBag
66 *
67 */
68
69#ifndef	_PKCS12_TEMPLATES_H_
70#define _PKCS12_TEMPLATES_H_
71
72#include <Security/keyTemplates.h>	/* for NSS_Attribute */
73#include <Security/pkcs7Templates.h>			/* will be lib-specific place */
74
75#ifdef __cplusplus
76extern "C" {
77#endif
78
79/*
80 * MacData ::= SEQUENCE {
81 * 		mac 		DigestInfo,
82 *		macSalt	    OCTET STRING,
83 *		iterations	INTEGER DEFAULT 1
84 * }
85 */
86typedef struct {
87	NSS_P7_DigestInfo	mac;
88	SecAsn1Item			macSalt;
89	SecAsn1Item			iterations;	// optional
90} NSS_P12_MacData;
91
92extern const SecAsn1Template NSS_P12_MacDataTemplate[];
93
94/*
95 * PFX ::= SEQUENCE {
96 *   	version		INTEGER {v3(3)}(v3,...),
97 *   	authSafe	ContentInfo,
98 *   	macData    	MacData OPTIONAL
99 * }
100 */
101
102/*
103 * First the top level PFX with unparsed ContentInfo.content.
104 */
105typedef struct {
106	SecAsn1Item				version;
107	NSS_P7_RawContentInfo	authSafe;
108	NSS_P12_MacData			*macData;
109} NSS_P12_RawPFX;
110
111extern const SecAsn1Template NSS_P12_RawPFXTemplate[];
112
113/*
114 * And a PFX with a decoded ContentInfo.content.
115 */
116typedef struct {
117	SecAsn1Item					version;
118	NSS_P7_DecodedContentInfo	authSafe;
119	NSS_P12_MacData				*macData;
120} NSS_P12_DecodedPFX;
121
122extern const SecAsn1Template NSS_P12_DecodedPFXTemplate[];
123
124/*
125 * The CSSMOID_PKCS7_Data-style ContentInfo.content of a PFX
126 * contains an encoded AuthenticatedSafe.
127 *
128 * AuthenticatedSafe ::= SEQUENCE OF ContentInfo
129 * 		-- Data if unencrypted
130 * 		-- EncryptedData if password-encrypted
131 * 		-- EnvelopedData if public key-encrypted
132 */
133typedef struct {
134	NSS_P7_DecodedContentInfo		**info;
135} NSS_P12_AuthenticatedSafe;
136
137extern const SecAsn1Template NSS_P12_AuthenticatedSafeTemplate[];
138
139/*
140 * Individual BagTypes.
141 * Code on demand.
142 */
143typedef SecAsn1Item	NSS_P12_KeyBag;
144typedef NSS_EncryptedPrivateKeyInfo	NSS_P12_ShroudedKeyBag;
145typedef SecAsn1Item	NSS_P12_SecretBag;
146typedef SecAsn1Item	NSS_P12_SafeContentsBag;
147
148/*
149 * CertBag
150 *
151 * CertBag ::= SEQUENCE {
152 * 		certId BAG-TYPE.&id ({CertTypes}),
153 * 		certValue [0] EXPLICIT BAG-TYPE.&Type ({CertTypes}{@certId})
154 * }
155 *
156 * x509Certificate BAG-TYPE ::=
157 * 		{OCTET STRING IDENTIFIED BY {certTypes 1}}
158 * 			-- DER-encoded X.509 certificate stored in OCTET STRING
159 * sdsiCertificate BAG-TYPE ::=
160 * 		{IA5String IDENTIFIED BY {certTypes 2}}
161 * 			-- Base64-encoded SDSI certificate stored in IA5String
162 */
163typedef enum {
164	CT_Unknown,			// --> ASN_ANY
165	CT_X509,
166	CT_SDSI,
167} NSS_P12_CertBagType;
168
169typedef struct {
170	SecAsn1Oid			bagType;
171	NSS_P12_CertBagType	type;
172	SecAsn1Item			certValue;
173} NSS_P12_CertBag;
174
175extern const SecAsn1Template NSS_P12_CertBagTemplate[];
176
177/*
178 * CRLBag
179 *
180 * CRLBag ::= SEQUENCE {
181 * 		certId BAG-TYPE.&id ({CertTypes}),
182 * 		certValue [0] EXPLICIT BAG-TYPE.&Type ({CertTypes}{@certId})
183 * }
184 *
185 * x509Certificate BAG-TYPE ::=
186 * 		{OCTET STRING IDENTIFIED BY {certTypes 1}}
187 * 			-- DER-encoded X.509 certificate stored in OCTET STRING
188 * sdsiCertificate BAG-TYPE ::=
189 * 		{IA5String IDENTIFIED BY {certTypes 2}}
190 * 			-- Base64-encoded SDSI certificate stored in IA5String
191 */
192typedef enum {
193	CRT_Unknown,			// --> ASN_ANY
194	CRT_X509,
195} NSS_P12_CrlBagType;
196
197typedef struct {
198	SecAsn1Oid			bagType;
199	NSS_P12_CrlBagType	type;
200	SecAsn1Item			crlValue;
201} NSS_P12_CrlBag;
202
203extern const SecAsn1Template NSS_P12_CrlBagTemplate[];
204
205/*
206 * BagId OIDs map to one of these for convenience. Our dynamic
207 * template chooser drops one of these into NSS_P12_SafeBag.type
208 * on decode.
209 */
210typedef enum {
211	BT_None = 0,
212	BT_KeyBag,
213	BT_ShroudedKeyBag,
214	BT_CertBag,
215	BT_CrlBag,
216	BT_SecretBag,
217	BT_SafeContentsBag
218} NSS_P12_SB_Type;
219
220/*
221 * The ContentInfo.content values of each element in
222 * an AuthenticatedSafe map to a sequence of these - either directly
223 * (contentType CSSMOID_PKCS7_Data, octet string contents are
224 * the DER encoding of this) or indirectly (encrypted or
225 * shrouded, the decrypted content is the DER encoding of this).
226 */
227typedef struct {
228	SecAsn1Oid					bagId;
229	NSS_P12_SB_Type				type;
230	union {
231		NSS_P12_KeyBag			*keyBag;
232		NSS_P12_ShroudedKeyBag	*shroudedKeyBag;
233		NSS_P12_CertBag			*certBag;
234		NSS_P12_CrlBag			*crlBag;
235		NSS_P12_SecretBag		*secretBag;
236		NSS_P12_SafeContentsBag	*safeContentsBag;
237	} bagValue;
238	NSS_Attribute				**bagAttrs;		// optional
239} NSS_P12_SafeBag;
240
241extern const SecAsn1Template NSS_P12_SafeBagTemplate[];
242
243/*
244 * SafeContents, the contents of an element in an AuthenticatedSafe.
245 */
246typedef struct {
247	NSS_P12_SafeBag				**bags;
248}
249NSS_P12_SafeContents;
250
251extern const SecAsn1Template NSS_P12_SafeContentsTemplate[];
252
253/*
254 * PKCS12-specific algorithm parameters.
255 * A DER encoded version of this is the parameters value of
256 * a CSSM_X509_ALGORITHM_IDENTIFIER used in a
257 * NSS_P7_EncrContentInfo.encrAlg in P12 password privacy mode.
258 *
259 * pkcs-12PbeParams ::= SEQUENCE {
260 *		salt OCTET STRING,
261 *		iterations INTEGER
262 * }
263 *
264 * NOTE the P12 spec does place a limit on the value of iterations.
265 * I guess we have to assume in actual usage that it's
266 * restricted to (0..MAX), i.e., uint32-sized.
267 *
268 * We're also assuming that it is explicitly an unsigned value,
269 * so that the value bytes in the encoding of 0xff would be
270 * (0, 255).
271 */
272typedef struct {
273	SecAsn1Item		salt;
274	SecAsn1Item		iterations;
275} NSS_P12_PBE_Params;
276
277extern const SecAsn1Template NSS_P12_PBE_ParamsTemplate[];
278
279#ifdef __cplusplus
280}
281#endif
282
283#endif	/* _PKCS12_TEMPLATES_H_ */
284
285