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 * p12Crypto.h - PKCS12 Crypto routines.
26 */
27
28#ifndef	_PKCS12_CRYPTO_H_
29#define _PKCS12_CRYPTO_H_
30
31#include <Security/Security.h>
32#include <security_asn1/SecNssCoder.h>
33
34#ifdef __cplusplus
35extern "C" {
36#endif
37
38/*
39 * Given appropriate P12-style parameters, cook up a CSSM_KEY.
40 */
41CSSM_RETURN p12KeyGen(
42	CSSM_CSP_HANDLE		cspHand,
43	CSSM_KEY			&key,
44	bool				isForEncr,	// true: en/decrypt   false: MAC
45	CSSM_ALGORITHMS		keyAlg,
46	CSSM_ALGORITHMS		pbeHashAlg,	// SHA1, MD5 only
47	uint32				keySizeInBits,
48	uint32				iterCount,
49	const CSSM_DATA		&salt,
50
51	/* exactly one of the following two must be valid */
52	const CSSM_DATA		*pwd,		// unicode, double null terminated
53	const CSSM_KEY		*passKey,
54	CSSM_DATA			&iv);		// referent is optional
55
56/*
57 * Decrypt (typically, an encrypted P7 ContentInfo contents or
58 * a P12 ShroudedKeyBag).
59 */
60CSSM_RETURN p12Decrypt(
61	CSSM_CSP_HANDLE		cspHand,
62	const CSSM_DATA		&cipherText,
63	CSSM_ALGORITHMS		keyAlg,
64	CSSM_ALGORITHMS		encrAlg,
65	CSSM_ALGORITHMS		pbeHashAlg,			// SHA1, MD5 only
66	uint32				keySizeInBits,
67	uint32				blockSizeInBytes,	// for IV
68	CSSM_PADDING		padding,			// CSSM_PADDING_PKCS7, etc.
69	CSSM_ENCRYPT_MODE	mode,				// CSSM_ALGMODE_CBCPadIV8, etc.
70	uint32				iterCount,
71	const CSSM_DATA		&salt,
72	/* exactly one of the following two must be valid */
73	const CSSM_DATA		*pwd,		// unicode, double null terminated
74	const CSSM_KEY		*passKey,
75	SecNssCoder			&coder,		// for mallocing KeyData and plainText
76	CSSM_DATA			&plainText);
77
78/*
79 * Decrypt (typically, an encrypted P7 ContentInfo contents)
80 */
81CSSM_RETURN p12Encrypt(
82	CSSM_CSP_HANDLE		cspHand,
83	const CSSM_DATA		&plainText,
84	CSSM_ALGORITHMS		keyAlg,
85	CSSM_ALGORITHMS		encrAlg,
86	CSSM_ALGORITHMS		pbeHashAlg,			// SHA1, MD5 only
87	uint32				keySizeInBits,
88	uint32				blockSizeInBytes,	// for IV
89	CSSM_PADDING		padding,			// CSSM_PADDING_PKCS7, etc.
90	CSSM_ENCRYPT_MODE	mode,				// CSSM_ALGMODE_CBCPadIV8, etc.
91	uint32				iterCount,
92	const CSSM_DATA		&salt,
93	const CSSM_DATA		*pwd,		// unicode, double null terminated
94	const CSSM_KEY		*passKey,
95	SecNssCoder			&coder,		// for mallocing cipherText
96	CSSM_DATA			&cipherText);
97
98/*
99 * Calculate the MAC for a PFX. Caller is either going compare
100 * the result against an existing PFX's MAC or drop the result into
101 * a newly created PFX.
102 */
103CSSM_RETURN p12GenMac(
104	CSSM_CSP_HANDLE		cspHand,
105	const CSSM_DATA		&ptext,	// e.g., NSS_P12_DecodedPFX.derAuthSaafe
106	CSSM_ALGORITHMS		alg,	// better be SHA1!
107	unsigned			iterCount,
108	const CSSM_DATA		&salt,
109	/* exactly one of the following two must be valid */
110	const CSSM_DATA		*pwd,		// unicode, double null terminated
111	const CSSM_KEY		*passKey,
112	SecNssCoder			&coder,		// for mallocing macData
113	CSSM_DATA			&macData);	// RETURNED
114
115/*
116 * Unwrap a shrouded key.
117 */
118CSSM_RETURN p12UnwrapKey(
119	CSSM_CSP_HANDLE		cspHand,
120	CSSM_DL_DB_HANDLE_PTR	dlDbHand,		// optional
121	int					keyIsPermanent,		// nonzero - store in DB
122	const CSSM_DATA		&shroudedKeyBits,
123	CSSM_ALGORITHMS		keyAlg,				// of the unwrapping key
124	CSSM_ALGORITHMS		encrAlg,
125	CSSM_ALGORITHMS		pbeHashAlg,			// SHA1, MD5 only
126	uint32				keySizeInBits,
127	uint32				blockSizeInBytes,	// for IV
128	CSSM_PADDING		padding,			// CSSM_PADDING_PKCS7, etc.
129	CSSM_ENCRYPT_MODE	mode,				// CSSM_ALGMODE_CBCPadIV8, etc.
130	uint32				iterCount,
131	const CSSM_DATA		&salt,
132	/* exactly one of the following two must be valid */
133	const CSSM_DATA		*pwd,		// unicode, double null terminated
134	const CSSM_KEY		*passKey,
135	SecNssCoder			&coder,		// for mallocing privKey
136	const CSSM_DATA		&labelData,
137	SecAccessRef		access,		// optional; use default ACL if NULL and !noAcl
138	bool				noAcl,		// true ==> no ACL
139	CSSM_KEYUSE			keyUsage,
140	CSSM_KEYATTR_FLAGS	keyAttrs,
141
142	/*
143	 * Result: a private key, reference format, optionaly stored
144	 * in dlDbHand
145	 */
146	CSSM_KEY_PTR		&privKey);
147
148CSSM_RETURN p12WrapKey(
149	CSSM_CSP_HANDLE		cspHand,
150	CSSM_KEY_PTR		privKey,
151	const CSSM_ACCESS_CREDENTIALS *privKeyCreds,
152	CSSM_ALGORITHMS		keyAlg,				// of the unwrapping key
153	CSSM_ALGORITHMS		encrAlg,
154	CSSM_ALGORITHMS		pbeHashAlg,			// SHA1, MD5 only
155	uint32				keySizeInBits,
156	uint32				blockSizeInBytes,	// for IV
157	CSSM_PADDING		padding,			// CSSM_PADDING_PKCS7, etc.
158	CSSM_ENCRYPT_MODE	mode,				// CSSM_ALGMODE_CBCPadIV8, etc.
159	uint32				iterCount,
160	const CSSM_DATA		&salt,
161	/* exactly one of the following two must be valid */
162	const CSSM_DATA		*pwd,		// unicode, double null terminated
163	const CSSM_KEY		*passKey,
164	SecNssCoder			&coder,		// for mallocing keyBits
165	CSSM_DATA			&shroudedKeyBits);	// RETURNED
166
167#ifdef __cplusplus
168}
169#endif
170
171#endif	/* _PKCS12_CRYPTO_H_ */
172
173