1/*
2 * Copyright (c) 2004 Apple Computer, 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 * SecExternalRep.h - private classes representing external representations of
24 *					  SecKeychainItemRefs, used by SecImportExport.h
25 */
26
27#ifndef	_SECURITY_SEC_EXTERNAL_REP_H_
28#define _SECURITY_SEC_EXTERNAL_REP_H_
29
30#include "SecImportExport.h"
31
32/*
33 * mechanism to limit private key import
34 */
35typedef enum {
36	PIS_NoLimit,			// no limit
37	PIS_AllowOne,			// allow import of at most one
38	PIS_NoMore				// found one, no more allowed
39} ImpPrivKeyImportState;
40
41namespace Security
42{
43
44namespace KeychainCore
45{
46
47/*
48 * When exporting, each instance of this represents one keychain item we're
49 * exporting. Note that SecIdentityRefs are represented by two of these - one
50 * for the cert, one for the key.
51 */
52class SecExportRep
53{
54protected:
55	SecExportRep(
56		CFTypeRef						kcItemRef);
57
58public:
59	/* default constructor throws */
60	SecExportRep();
61
62	/*
63	 * Gleans SecExternalItemType from incoming type, throws MacOSError if
64	 * incoming type is bogus, and vends an instance of a suitable subclass.
65	 * Vended object holds a reference to kcItem for its lifetime.
66	 */
67	static SecExportRep *vend(
68		CFTypeRef						kcItemRef);
69
70	virtual ~SecExportRep();
71
72	/*
73	 * Append external representation to CFData.
74	 * Implemented in subclass.
75	 */
76	virtual OSStatus exportRep(
77		SecExternalFormat					format,
78		SecItemImportExportFlags			flags,
79		const SecKeyImportExportParameters	*keyParams,		// optional
80		CFMutableDataRef					outData,		// data appended here
81		const char							**pemHeader);	// e.g., "X509 CERTIFICATE"
82
83	/* member variables are read-only to the public */
84	SecKeychainItemRef	kcItem()		{ return mKcItem; }
85	SecExternalItemType	externType()	{ return mExternType; }
86	CFArrayRef pemParamLines()			{ return mPemParamLines; }
87
88protected:
89	SecKeychainItemRef		mKcItem;
90	SecExternalItemType		mExternType;		// inferred in vend()
91	CFArrayRef				mPemParamLines;		// optional PEM header strings
92
93};
94
95/*
96 * Class representing one item we're importing from external representation.
97 * Normally represents the one "thing" the app has provided to
98 * SecKeychainItemImport(), but when importing in kSecFormatPEMSequence
99 * format, the inpus is parsed into separate components, each of which
100 * gets one instance of this class.
101 */
102class SecImportRep
103{
104private:
105	/* no default constructor */
106	SecImportRep() { }
107
108public:
109	/*
110	 * Between constructor and the importRep() call, we're a placeholder to
111	 * allow our owner to keep track of what is in an incoming pile of bits.
112	 * We keep a reference to the incoming CFDataRef for our lifetime.
113	 */
114	SecImportRep(
115		CFDataRef						external,
116		SecExternalItemType				externType,		// may be unknown
117		SecExternalFormat				externFormat,   // may be unknown
118		CSSM_ALGORITHMS					keyAlg,		// may be unknown, CSSM_ALGID_NONE
119		CFArrayRef						pemParamLines = NULL);
120
121	~SecImportRep();
122
123	/*
124	 * Convert to one or more SecKeychainItemRefs and/or import to keychain.
125	 * Both mExternType and mExternFormat must be valid at this point.
126	 * Any conversion requiring unwrapping rerquires either a keychain
127	 * into which the unwrapped items will be imported) or a CSPDL handle (in
128	 * which case the resulting items are floating and ephemeral).
129	 * If we create a SecKeychainItemRefs, the only ref count held on
130	 * return will be that held by outArray.
131	 *
132	 * Incoming CSP handle is required; by convention it must be derived from
133	 * importKeychain if importKeychain is present.
134	 */
135	OSStatus importRep(
136		SecKeychainRef						importKeychain,		// optional
137		CSSM_CSP_HANDLE						cspHand,			// required
138		SecItemImportExportFlags			flags,
139		const SecKeyImportExportParameters	*keyParams,			// optional
140		ImpPrivKeyImportState				&keyImportState,	// IN/OUT
141		CFMutableArrayRef					outArray);			// optional, append here
142
143private:
144	/* implemented in SecWrappedKeys.cpp */
145	OSStatus importWrappedKeyOpenssl(
146		SecKeychainRef						importKeychain, // optional
147		CSSM_CSP_HANDLE						cspHand,		// required
148		SecItemImportExportFlags			flags,
149		const SecKeyImportExportParameters	*keyParams,		// optional
150		CFMutableArrayRef					outArray);		// optional, append here
151
152	/* optional inferred PrintName attribute */
153	char *mPrintName;
154
155public:
156	/* Just keep these public, it simplifies things */
157	CFDataRef				mExternal;
158	SecExternalItemType		mExternType;
159	SecExternalFormat		mExternFormat;
160	CSSM_ALGORITHMS			mKeyAlg;
161	CFArrayRef				mPemParamLines;		// optional PEM header strings
162};
163
164} // end namespace KeychainCore
165
166} // end namespace Security
167
168extern "C" {
169
170/* implemented in SecWrappedKeys.cpp */
171OSStatus impExpWrappedKeyOpenSslExport(
172	SecKeyRef							secKey,
173	SecItemImportExportFlags			flags,
174	const SecKeyImportExportParameters	*keyParams,		// optional
175	CFMutableDataRef					outData,		// output appended here
176	const char							**pemHeader,	// RETURNED
177	CFArrayRef							*pemParamLines);// RETURNED
178
179}
180
181#endif	/* _SECURITY_SEC_IMPORT_EXPORT_H_ */
182