[apple/security.git] / OSX / libsecurity_pkcs12 / lib / pkcs12Crypto.h

/*
 * Copyright (c) 2003-2004,2011,2014 Apple Inc. All Rights Reserved.
 * 
 * @APPLE_LICENSE_HEADER_START@
 * 
 * This file contains Original Code and/or Modifications of Original Code
 * as defined in and that are subject to the Apple Public Source License
 * Version 2.0 (the 'License'). You may not use this file except in
 * compliance with the License. Please obtain a copy of the License at
 * http://www.opensource.apple.com/apsl/ and read it before using this
 * file.
 * 
 * The Original Code and all software distributed under the License are
 * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
 * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
 * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
 * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
 * Please see the License for the specific language governing rights and
 * limitations under the License.
 * 
 * @APPLE_LICENSE_HEADER_END@
 */
 
/*
 * p12Crypto.h - PKCS12 Crypto routines.
 */
 
#ifndef	_PKCS12_CRYPTO_H_
#define _PKCS12_CRYPTO_H_

#include <Security/Security.h>
#include <security_asn1/SecNssCoder.h>

#ifdef __cplusplus
extern "C" {
#endif

/*
 * Given appropriate P12-style parameters, cook up a CSSM_KEY.
 */
CSSM_RETURN p12KeyGen(
	CSSM_CSP_HANDLE		cspHand,
	CSSM_KEY			&key,
	bool				isForEncr,	// true: en/decrypt   false: MAC
	CSSM_ALGORITHMS		keyAlg,
	CSSM_ALGORITHMS		pbeHashAlg,	// SHA1, MD5 only
	uint32				keySizeInBits,
	uint32				iterCount,
	const CSSM_DATA		&salt,
	
	/* exactly one of the following two must be valid */
	const CSSM_DATA		*pwd,		// unicode, double null terminated
	const CSSM_KEY		*passKey,
	CSSM_DATA			&iv);		// referent is optional
	
/*
 * Decrypt (typically, an encrypted P7 ContentInfo contents or
 * a P12 ShroudedKeyBag).
 */
CSSM_RETURN p12Decrypt(
	CSSM_CSP_HANDLE		cspHand,
	const CSSM_DATA		&cipherText,
	CSSM_ALGORITHMS		keyAlg,				
	CSSM_ALGORITHMS		encrAlg,
	CSSM_ALGORITHMS		pbeHashAlg,			// SHA1, MD5 only
	uint32				keySizeInBits,
	uint32				blockSizeInBytes,	// for IV
	CSSM_PADDING		padding,			// CSSM_PADDING_PKCS7, etc.
	CSSM_ENCRYPT_MODE	mode,				// CSSM_ALGMODE_CBCPadIV8, etc.
	uint32				iterCount,
	const CSSM_DATA		&salt,
	/* exactly one of the following two must be valid */
	const CSSM_DATA		*pwd,		// unicode, double null terminated
	const CSSM_KEY		*passKey,
	SecNssCoder			&coder,		// for mallocing KeyData and plainText
	CSSM_DATA			&plainText);

/*
 * Decrypt (typically, an encrypted P7 ContentInfo contents)
 */
CSSM_RETURN p12Encrypt(
	CSSM_CSP_HANDLE		cspHand,
	const CSSM_DATA		&plainText,
	CSSM_ALGORITHMS		keyAlg,				
	CSSM_ALGORITHMS		encrAlg,
	CSSM_ALGORITHMS		pbeHashAlg,			// SHA1, MD5 only
	uint32				keySizeInBits,
	uint32				blockSizeInBytes,	// for IV
	CSSM_PADDING		padding,			// CSSM_PADDING_PKCS7, etc.
	CSSM_ENCRYPT_MODE	mode,				// CSSM_ALGMODE_CBCPadIV8, etc.
	uint32				iterCount,
	const CSSM_DATA		&salt,
	const CSSM_DATA		*pwd,		// unicode, double null terminated
	const CSSM_KEY		*passKey,
	SecNssCoder			&coder,		// for mallocing cipherText
	CSSM_DATA			&cipherText);

/*
 * Calculate the MAC for a PFX. Caller is either going compare
 * the result against an existing PFX's MAC or drop the result into 
 * a newly created PFX.
 */
CSSM_RETURN p12GenMac(
	CSSM_CSP_HANDLE		cspHand,
	const CSSM_DATA		&ptext,	// e.g., NSS_P12_DecodedPFX.derAuthSaafe
	CSSM_ALGORITHMS		alg,	// better be SHA1!
	unsigned			iterCount,
	const CSSM_DATA		&salt,
	/* exactly one of the following two must be valid */
	const CSSM_DATA		*pwd,		// unicode, double null terminated
	const CSSM_KEY		*passKey,
	SecNssCoder			&coder,		// for mallocing macData
	CSSM_DATA			&macData);	// RETURNED 

/*
 * Unwrap a shrouded key.
 */
CSSM_RETURN p12UnwrapKey(
	CSSM_CSP_HANDLE		cspHand,
	CSSM_DL_DB_HANDLE_PTR	dlDbHand,		// optional
	int					keyIsPermanent,		// nonzero - store in DB
	const CSSM_DATA		&shroudedKeyBits,
	CSSM_ALGORITHMS		keyAlg,				// of the unwrapping key
	CSSM_ALGORITHMS		encrAlg,
	CSSM_ALGORITHMS		pbeHashAlg,			// SHA1, MD5 only
	uint32				keySizeInBits,
	uint32				blockSizeInBytes,	// for IV
	CSSM_PADDING		padding,			// CSSM_PADDING_PKCS7, etc.
	CSSM_ENCRYPT_MODE	mode,				// CSSM_ALGMODE_CBCPadIV8, etc.
	uint32				iterCount,
	const CSSM_DATA		&salt,
	/* exactly one of the following two must be valid */
	const CSSM_DATA		*pwd,		// unicode, double null terminated
	const CSSM_KEY		*passKey,
	SecNssCoder			&coder,		// for mallocing privKey
	const CSSM_DATA		&labelData,
	SecAccessRef		access,		// optional; use default ACL if NULL and !noAcl
	bool				noAcl,		// true ==> no ACL
	CSSM_KEYUSE			keyUsage,
	CSSM_KEYATTR_FLAGS	keyAttrs,

	/*
	 * Result: a private key, reference format, optionaly stored
	 * in dlDbHand
	 */
	CSSM_KEY_PTR		&privKey);

CSSM_RETURN p12WrapKey(
	CSSM_CSP_HANDLE		cspHand,
	CSSM_KEY_PTR		privKey,
	const CSSM_ACCESS_CREDENTIALS *privKeyCreds,
	CSSM_ALGORITHMS		keyAlg,				// of the unwrapping key
	CSSM_ALGORITHMS		encrAlg,
	CSSM_ALGORITHMS		pbeHashAlg,			// SHA1, MD5 only
	uint32				keySizeInBits,
	uint32				blockSizeInBytes,	// for IV
	CSSM_PADDING		padding,			// CSSM_PADDING_PKCS7, etc.
	CSSM_ENCRYPT_MODE	mode,				// CSSM_ALGMODE_CBCPadIV8, etc.
	uint32				iterCount,
	const CSSM_DATA		&salt,
	/* exactly one of the following two must be valid */
	const CSSM_DATA		*pwd,		// unicode, double null terminated
	const CSSM_KEY		*passKey,
	SecNssCoder			&coder,		// for mallocing keyBits
	CSSM_DATA			&shroudedKeyBits);	// RETURNED

#ifdef __cplusplus
}
#endif

#endif	/* _PKCS12_CRYPTO_H_ */
Commit	Line	Data
b1ab9ed8	1	/*
d8f41ccd	2	* Copyright (c) 2003-2004,2011,2014 Apple Inc. All Rights Reserved.
b1ab9ed8 A	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
	35	extern "C" {
	36	#endif
	37
	38	/*
	39	* Given appropriate P12-style parameters, cook up a CSSM_KEY.
	40	*/
	41	CSSM_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	*/
	60	CSSM_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	*/
81	CSSM_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	*/
103	CSSM_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	*/
118	CSSM_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
148	CSSM_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