1/*
2 * Copyright (c) 2003-2004,2011,2014 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/*******************************************************************
25 *
26 * SecPkcs12.h
27 *
28 * This module is an implementation of the logic required to create
29 * and parse PKCS12 "blobs", known as PFXs in PKCS12 lingo. The user
30 * of this module need not know anything about the details of
31 * PKCS12 PFX construction. All one needs to know at this level
32 * is that a PKCS12 PFX is a collection of the following items:
33 *
34 * -- Zero or more certificates
35 * -- Zero or more Certficate Revocation Lists (CRLs)
36 * -- Zero or more private keys. (If this number is zero, using this
37 *    module is probably not what you want to do)
38 * -- Zero or more other opaque types, not understood or parsed
39 *    by this module.
40 *
41 * Each individual component of a PFX contains zero or more
42 * attributes; commonly the only two such attributes used in
43 * the PKCS12 world are "FriendlyName", a Unicode string, and
44 * "LocalKeyId", an opaque data blob which serves solely to tie
45 * a specific cert to a specific key in the context of this specific
46 * PFX.
47 *
48 * Individual components of a PKCS12 PFX are typically encrypted with
49 * a key derived from a user-supplied passphrase. The entire PFX
50 * is protected with a MAC whose key is also derived from a user-
51 * supplied passphrase. Typically these two passphrases are identical
52 * but they don't have to be.
53 *
54 * There are a number of options and modes which, while described in
55 * the PKCS12 spec and provided for in the interface in this file,
56 * are rarely if ever used. The following is a description of the
57 * actual, typical, real-world use of this module.
58 *
59 * Decoding a PKCS12 blob
60 * ----------------------
61 *
62 * 1. App creates a SecPkcs12CoderRef via SecPkcs12CoderCreate().
63 *
64 * 2. App specifies supplies a (small) number of options such as
65 *    passphrase(s) and SecKeychainRefs.
66 *
67 * 3. App calls SecPkcs12Decode(), providing the raw PKCS12 PFX
68 *    blob which is to be decoded. This performs all of the actual
69 *    decoding and decryption.
70 *
71 * 4. At this point the app optionally obtains the resulting
72 *    components by a set of calls which return individual
73 *    certs, CRLS, and keys.
74 *
75 * 5. Also, per the configuration performed in step 2, individual
76 *    components (certs, keys) found in the PFX have been added
77 *    to a specified keychain, rendering step 4 superfluous.
78 *
79 *
80 * Creating a PKCS12 blob
81 * ----------------------
82 *
83 * 1. App creates a SecPkcs12CoderRef via SecPkcs12CoderCreate().
84 *
85 * 2. App specifies supplies a (small) number of options such as
86 *    passphrase(s).
87 *
88 * 3. App makes a set of calls which add individual components such
89 *    as certs, CRLs, and private keys. A high-level call,
90 *    SecPkcs12ExportKeychainItems(), allow the specification of
91 *    all components to be exported at once.
92 *
93 * 4. App calls SecPkcs12Encode(), which does all of the required
94 *    encryption and encoding. The result is an exportable PKCS12
95 *    PFX blob.
96 */
97
98#ifndef	_SEC_PKCS12_H_
99#define _SEC_PKCS12_H_
100
101#include <CoreFoundation/CoreFoundation.h>
102#include <Security/Security.h>
103
104#ifdef __cplusplus
105extern "C" {
106#endif
107
108/*
109 * Opaque handle for a PKCS12 encoder/decoder.
110 */
111typedef void 	*SecPkcs12CoderRef;
112
113#pragma mark --- SecPkcs12CoderRef create/destroy ---
114
115/*
116 * Basic SecPkcs12CoderRef create/destroy.
117 */
118OSStatus SecPkcs12CoderCreate(
119	SecPkcs12CoderRef	*coder);		// RETURNED
120
121/*
122 * Destroy object created in SecPkcs12CoderCreate.
123 */
124OSStatus SecPkcs12CoderRelease(
125	SecPkcs12CoderRef	coder);
126
127#pragma mark --- High-level API ---
128
129/*
130 * Keychain associated with encode/decode.
131 * Client must call exactly one of { SecPkcs12SetKeychain(),
132 * SecPkcs12SetCspHandle() } for both encoding and decoding.
133 * If SecPkcs12SetCspHandle() is used, components which are
134 * obtained during decode are ephemeral (i.e., they are not
135 * stored anywhere and only have a lifetime which is the same as
136 * the lifetime of the SecPkcs12CoderRef).
137 */
138OSStatus SecPkcs12SetKeychain(
139	SecPkcs12CoderRef		coder,
140	SecKeychainRef			keychain);
141
142/*
143 * Required iff SecPkcs12SetKeychain() is not called.
144 */
145OSStatus SecPkcs12SetCspHandle(
146	SecPkcs12CoderRef		coder,
147	CSSM_CSP_HANDLE			cspHandle);
148
149
150/*
151 * PKCS12 allows for separate passphrases for encryption and for
152 * verification (via MAC). Typically, in the real world, one
153 * passphrase is used for both; we provide the means to set them
154 * separately.
155 *
156 * Passphrases can be specified directly as CFStringRefs, or as
157 * CSSM_KEYs which represent secure passphrases obtained by the
158 * SecurityServer. This latter method is preferred since the
159 * plaintext passphrase never appears in the app's address space.
160 * Passphrases expressed in this manner are referred to as
161 * PassKeys.
162 *
163 * If one passphrase is to be used for both encryption and
164 * verification, use one of these two function to set it.
165 */
166OSStatus SecPkcs12SetMACPassphrase(
167	SecPkcs12CoderRef	coder,
168	CFStringRef			passphrase);
169
170OSStatus SecPkcs12SetMACPassKey(
171	SecPkcs12CoderRef	coder,
172	const CSSM_KEY		*passKey);
173
174/*
175 * Specify separate passphrase for encrypt/decrypt.
176 */
177OSStatus SecPkcs12SetCryptPassphrase(
178	SecPkcs12CoderRef	coder,
179	CFStringRef			passphrase);
180
181OSStatus SecPkcs12SetCryptPassKey(
182	SecPkcs12CoderRef	coder,
183	const CSSM_KEY		*passKey);
184
185/*
186 * Prior to decoding a PFX, client can specify whether individual
187 * components (certificates, CRLs, and keys) get stored in the
188 * keychain specified via SecPkcs12SetKeychain().
189 */
190enum {
191	kSecImportCertificates	= 0x0001,
192	kSecImportCRLs			= 0x0002,
193	kSecImportKeys			= 0x0004,
194};
195
196typedef UInt32 SecPkcs12ImportFlags;
197
198OSStatus SecPkcs12SetImportToKeychain(
199	SecPkcs12CoderRef			coder,
200	SecPkcs12ImportFlags		flags);
201
202OSStatus SecPkcs12GetImportToKeychain(
203	SecPkcs12CoderRef			coder,
204	SecPkcs12ImportFlags		*flags);		// RETURNED
205
206/*
207 * Specify individual SecKeychainItemRef to export, prior to encoding.
208 * The items argument is a CFArray containing any number of each
209 * of the following SecKeychainItemRef objects:
210 *
211 *		SecKeyRef
212 *		SecCertificateRef
213 *		...and others, in the future.
214 */
215OSStatus SecPkcs12ExportKeychainItems(
216	SecPkcs12CoderRef			coder,
217	CFArrayRef					items);
218
219/*
220 * Specify additional optional imported private key attributes:
221 * -- a SecAccessRef; default is the default ACL. Passing NULL here
222 *    results in private keys being created with no ACL.
223 * -- CSSM_KEYUSE; default is CSSM_KEYUSE_ANY.
224 * -- CSSM_KEYATTR_FLAGS; default is CSSM_KEYATTR_RETURN_REF |
225 *    CSSM_KEYATTR_EXTRACTABLE | CSSM_KEYATTR_SENSITIVE, plus
226 *    CSSM_KEYATTR_PERMANENT if importing to a keychain
227 */
228OSStatus SecPkcs12SetAccess(
229	SecPkcs12CoderRef		coder,
230	SecAccessRef			access);
231
232OSStatus SecPkcs12SetKeyUsage(
233	SecPkcs12CoderRef		coder,
234	CSSM_KEYUSE				keyUsage);
235
236OSStatus SecPkcs12SetKeyAttrs(
237	SecPkcs12CoderRef		coder,
238	CSSM_KEYATTR_FLAGS		keyAttrs);
239
240/*
241 * Parse and decode.
242 */
243OSStatus SecPkcs12Decode(
244	SecPkcs12CoderRef		coder,
245	CFDataRef				pfx);
246
247/*
248 * This the final step to create an encoded PKCS12 PFX blob.
249 * This called after initial configuration of the SecPkcs12CoderRef,
250 * and either specifying items to export via either
251 * SecPkcs12ExportKeychainItems() or some number of SecPkcs12Add*
252 * function calls, described below.
253 *
254 * The result is a DER-encoded PFX in PKCS12 lingo.
255 */
256OSStatus SecPkcs12Encode(
257	SecPkcs12CoderRef		coder,
258	CFDataRef				*pfx);			// RETURNED
259
260
261/*
262 * Opaque handle for optional attributes associated with any
263 * component of a SecPkcs12CoderRef.
264 *
265 * The use of SecPkcs12AttrsRefs is optional and in fact, in the real
266 * world, rare. Their appearance in this API is just for completeness
267 * and to allow access to all "legal" PKCS12 options.
268 *
269 * We define the type here to allow use elsewhere in this
270 * interface; actual SecPkcs12AttrsRef manipulation functions
271 * are described later in this header.
272 */
273typedef void 	*SecPkcs12AttrsRef;
274
275#pragma mark --- Decoder Functions ---
276
277/*
278 * Subsequent to decoding, obtain the components.
279 * These functions can also be used as "getter" functions while encoding.
280 *
281 * Certificates:
282 */
283OSStatus SecPkcs12CertificateCount(
284	SecPkcs12CoderRef		coder,
285	CFIndex					*numCerts);		// RETURNED
286
287OSStatus SecPkcs12CopyCertificate(
288	SecPkcs12CoderRef		coder,
289	CFIndex					certNum,
290	SecCertificateRef		*cert,			// RETURNED
291	CFStringRef				*friendlyName,	// optional, RETURNED
292	CFDataRef				*localKeyId,	// optional, RETURNED
293	SecPkcs12AttrsRef		*attrs);		// optional, RETURNED
294
295/*
296 * CRLs. The might change if a SecCrl type is defined elsewhere.
297 * We'll typedef it here to preserve the semantics of this function.
298 */
299typedef CFDataRef	SecCrlRef;
300
301OSStatus SecPkcs12CrlCount(
302	SecPkcs12CoderRef		coder,
303	CFIndex					*numCrls);		// RETURNED
304
305OSStatus SecPkcs12CopyCrl(
306	SecPkcs12CoderRef		coder,
307	CFIndex					crlNum,
308	SecCrlRef				*crl,			// RETURNED
309	CFStringRef				*friendlyName,	// optional, RETURNED
310	CFDataRef				*localKeyId,	// optional, RETURNED
311	SecPkcs12AttrsRef		*attrs);		// optional, RETURNED
312
313/*
314 * Private keys.
315 */
316OSStatus SecPkcs12PrivateKeyCount(
317	SecPkcs12CoderRef		coder,
318	CFIndex					*numKeys);		// RETURNED
319
320/* currently not implemented : use SecPkcs12GetCssmPrivateKey() */
321OSStatus SecPkcs12CopyPrivateKey(
322	SecPkcs12CoderRef		coder,
323	CFIndex					keyNum,
324	SecKeyRef				*privateKey,	// RETURNED
325	CFStringRef				*friendlyName,	// optional, RETURNED
326	CFDataRef				*localKeyId,	// optional, RETURNED
327	SecPkcs12AttrsRef		*attrs);		// optional, RETURNED
328
329/*
330 * The CSSM_KEY_PTR returned by this function has a lifetime
331 * which is the same as the SecPkcs12CoderRef which created it.
332 */
333OSStatus SecPkcs12GetCssmPrivateKey(
334	SecPkcs12CoderRef		coder,
335	CFIndex					keyNum,
336	CSSM_KEY_PTR			*privateKey,	// RETURNED
337	CFStringRef				*friendlyName,	// optional, RETURNED
338	CFDataRef				*localKeyId,	// optional, RETURNED
339	SecPkcs12AttrsRef		*attrs);		// optional, RETURNED
340
341/*
342 * Catch-all for other components not currently understood
343 * or supported by this library. An "opaque blob" component
344 * is identified by an OID and is obtained as an opaque data
345 * blob.
346 */
347OSStatus SecPkcs12OpaqueBlobCount(
348	SecPkcs12CoderRef		coder,
349	CFIndex					*numBlobs);		// RETURNED
350
351OSStatus SecPkcs12CopyOpaqueBlob(
352	SecPkcs12CoderRef		coder,
353	CFIndex					blobNum,
354	CFDataRef				*blobOid,		// RETURNED
355	CFDataRef				*opaqueBlob,	// RETURNED
356	CFStringRef				*friendlyName,	// optional, RETURNED
357	CFDataRef				*localKeyId,	// optional, RETURNED
358	SecPkcs12AttrsRef		*attrs);		// optional, RETURNED
359
360#pragma mark --- Encoder Functions ---
361
362/*
363 * Add individual components. "Getter" functions are available
364 * as described above (under "Functions used for decoding").
365 */
366OSStatus SecPkcs12AddCertificate(
367	SecPkcs12CoderRef		coder,
368	SecCertificateRef		cert,
369	CFStringRef				friendlyName,	// optional
370	CFDataRef				localKeyId,		// optional
371	SecPkcs12AttrsRef		attrs);			// optional
372
373OSStatus SecPkcs12AddCrl(
374	SecPkcs12CoderRef		coder,
375	SecCrlRef				crl,
376	CFStringRef				friendlyName,	// optional
377	CFDataRef				localKeyId,		// optional
378	SecPkcs12AttrsRef		attrs);			// optional
379
380OSStatus SecPkcs12AddPrivateKey(
381	SecPkcs12CoderRef		coder,
382	SecKeyRef				privateKey,
383	CFStringRef				friendlyName,	// optional
384	CFDataRef				localKeyId,		// optional
385	SecPkcs12AttrsRef		attrs);			// optional
386
387OSStatus SecPkcs12AddOpaqueBlob(
388	SecPkcs12CoderRef		coder,
389	CFDataRef				blobOid,
390	CFDataRef				opaqueBlob,
391	CFStringRef				friendlyName,	// optional
392	CFDataRef				localKeyId,		// optional
393	SecPkcs12AttrsRef		attrs);			// optional
394
395
396#pragma mark --- Optional Functions ---
397
398/************************************************************
399 *** Optional, rarely used SecPkcs12CoderRef manipulation ***
400 ************************************************************/
401
402/***
403 *** SecPkcs12AttrsRef manipulation. Optional and in fact expected to
404 *** be rarely used, if ever.
405 ***/
406
407/*
408 * A SecPkcs12AttrsRef is an opaque handle referring to an aribtrary
409 * collection of OID/value pairs which can be attached to any
410 * component of a SecPkcs12CoderRef. OIDs and values are expressed
411 * as CFDataRefs. Each OID can have associated with it an arbitrary
412 * number of values.
413 */
414
415/*
416 * Create/destroy.
417 */
418OSStatus SecPkcs12AttrsCreate(
419	SecPkcs12AttrsRef	*attrs);		// RETURNED
420
421OSStatus SecPkcs12AttrsRelease(
422	SecPkcs12AttrsRef	attrs);
423
424/*
425 * Add an OID/value set to an existing SecPkcs12AttrsRef.
426 * Values are a CFArray containing an arbitrary number of
427 * CFDataRefs.
428 */
429OSStatus SecPkcs12AttrsAddAttr(
430	SecPkcs12AttrsRef	attrs,
431	CFDataRef			attrOid,
432	CFArrayRef			attrValues);	// an array of CFDataRefs
433
434OSStatus SecPkcs12AttrCount(
435	SecPkcs12AttrsRef	attrs,
436	CFIndex				*numAttrs);		// RETURNED
437
438/*
439 * Obtain n'th oid/value set from an existing SecPkcs12AttrsRef.
440 */
441OSStatus SecPkcs12AttrsGetAttr(
442	SecPkcs12AttrsRef	attrs,
443	CFIndex				attrNum,
444	CFDataRef			*attrOid,		// RETURNED
445	CFArrayRef			*attrValues);	// RETURNED
446
447/***
448 *** Integrity and Privacy Modes
449 ***/
450
451/*
452 * PKCS12 allows for two different modes for each of {privacy,
453 * integrity}. Each of these can be implemented via password
454 * or public key. Per the PKCS12 spec, all four combinations
455 * of these modes are legal. In the current version of this
456 * library, only password privacy and integrity modes are
457 * implemented. These functions are defined here for the
458 * completeness of the API and need never be called by users of
459 * the current implementation.
460 */
461typedef enum {
462	kSecPkcs12ModeUnknown,		// uninitialized
463	kSecPkcs12ModePassword,
464	kSecPkcs12ModePublicKey
465} SecPkcs12Mode;
466
467OSStatus SecPkcs12SetIntegrityMode(
468	SecPkcs12CoderRef	coder,
469	SecPkcs12Mode		mode);
470
471OSStatus SecPkcs12GetIntegrityMode(
472	SecPkcs12CoderRef	coder,
473	SecPkcs12Mode		*mode);			// RETURNED
474
475OSStatus SecPkcs12SetPrivacyMode(
476	SecPkcs12CoderRef	coder,
477	SecPkcs12Mode		mode);
478
479OSStatus SecPkcs12GetPrivacyMode(
480	SecPkcs12CoderRef	coder,
481	SecPkcs12Mode		*mode);			// RETURNED
482
483/***
484 *** Encryption algorithms
485 ***/
486
487/*
488 * Each individual component of a PKCS12 PFX can be encrypted with
489 * a different encryption algorithm. Typically, Certs and CRLs are
490 * all encrypted with one weak algorithm, and private keys are
491 * encrypted with a stronger algorithm.
492 *
493 * The following functions allow the app to specify, during encoding,
494 * the encryption algorithms to use for the different kinds of
495 * components. These are optional; this library provides appropriate
496 * defaults for these algorithms.
497 */
498OSStatus SecPkcs12SetKeyEncryptionAlg(
499	SecPkcs12CoderRef	coder,
500	CFDataRef			encryptionAlg);
501
502OSStatus SecPkcs12SetCertCrlEncryptionAlg(
503	SecPkcs12CoderRef	coder,
504	CFDataRef			encryptionAlg);
505
506/*
507 * Along with an encryption algorithm is an iteration count used for
508 * deriving keys. All of these are optional; reasonable defaults
509 * are provided.
510 *
511 * NOTE: salt is not visible at this API. During encoding,
512 * random values of salt are generated by this module.
513 */
514OSStatus SecPkcs12SetKeyEncryptionIterCount(
515	SecPkcs12CoderRef	coder,
516	unsigned			iterCount);
517
518OSStatus SecPkcs12SetCertCrlEncryptionIterCount(
519	SecPkcs12CoderRef	coder,
520	unsigned			iterCount);
521
522OSStatus SecPkcs12SetMacIterCount(
523	SecPkcs12CoderRef	coder,
524	unsigned			iterCount);
525
526/*
527 * "Getter" versions of the above. During decryption, the values
528 * returned here refer to the *first* such element found (e.g.,
529 * the encryption algorithm for the first key).
530 */
531OSStatus SecPkcs12CopyKeyEncryptionAlg(
532	SecPkcs12CoderRef	coder,
533	CFDataRef			*encryptionAlg);		// RETURNED
534
535OSStatus SecPkcs12CopyCertCrlEncryptionAlg(
536	SecPkcs12CoderRef	coder,
537	CFDataRef			*encryptionAlg);		// RETURNED
538
539OSStatus SecPkcs12CopyKeyEncryptionIterCount(
540	SecPkcs12CoderRef	coder,
541	unsigned			*iterCount);			// RETURNED
542
543OSStatus SecPkcs12CopyCertCrlEncryptionIterCount(
544	SecPkcs12CoderRef	coder,
545	unsigned			*iterCount);			// RETURNED
546
547OSStatus SecPkcs12CopyMacIterCount(
548	SecPkcs12CoderRef	coder,
549	unsigned			*iterCount);			// RETURNED
550
551/*
552 * Avoid importing multiple private keys. Primarily for use by
553 * SecKeychainItemImport(). Behavior depends on the foundOneKey
554 * argument, which indicates whether the current high-level import
555 * has already imported at least one key. If foundOneKey is true,
556 * SecPkcs12Decode() will return errSecMultiplePrivKeys upon
557 * the detection of *any* private keys in the incoming PFX.
558 * If foundOneKey is false, SecPkcs12Decode() will return
559 * errSecMultiplePrivKeys if more than one private key is
560 * found in the incoming PFX.
561 */
562OSStatus SecPkcs12LimitPrivateKeyImport(
563	SecPkcs12CoderRef	coder,
564	bool				foundOneKey);
565
566#ifdef __cplusplus
567}
568#endif
569
570#endif	/* _SEC_PKCS12_H_ */
571
572