1  /*
  2   * Copyright (c) 2004,2011,2013-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   * SecImportExportUtils.h - misc. utilities for import/export module
 24   */
 25  
 26  #ifndef	_SECURITY_SEC_IMPORT_EXPORT_UTILS_H_
 27  #define _SECURITY_SEC_IMPORT_EXPORT_UTILS_H_
 28  
 29  #include <Security/SecImportExport.h>
 30  #include "SecKeychainPriv.h"
 31  #include <Security/SecBasePriv.h>
 32  #include <security_utilities/debugging.h>
 33  #include <security_utilities/errors.h>
 34  
 35  #ifdef	__cplusplus
 36  extern "C" {
 37  #endif
 38  
 39  /*
 40   * Macros for begin/end of public functions. Although the import/export
 41   * module does not intentionally throw C++ exceptions which are intended to 
 42   * be caught like this, we catch possible exceptions which can conceivably
 43   * be thrown here or below. 
 44   */
 45   
 46  #define BEGIN_IMP_EXP_SECAPI \
 47  	try {
 48  
 49  #define END_IMP_EXP_SECAPI \
 50  	} \
 51  	catch (const MacOSError &err) { return err.osStatus(); } \
 52  	catch (const CommonError &err) { return SecKeychainErrFromOSStatus(err.osStatus()); } \
 53  	catch (const std::bad_alloc &) { return errSecAllocate; }\
 54  	catch (...) { return errSecInternalComponent; }
 55  
 56  /* 
 57   * Debug support.
 58   */
 59   
 60  #ifdef  NDEBUG
 61  
 62  #define impExpExtFormatStr(f)
 63  #define impExpExtItemTypeStr(t)
 64  
 65  #else
 66  
 67  extern const char *impExpExtFormatStr(SecExternalFormat format);
 68  extern const char *impExpExtItemTypeStr(SecExternalItemType itemType);
 69  
 70  #endif  /* NDEBUG */
 71  
 72  #define SecImpExpDbg(args...)	secinfo("SecImpExp", ## args)
 73  #define SecImpInferDbg(args...)	secinfo("SecImpInfer", ## args)
 74  
 75  /* 
 76   * Parse file extension and attempt to map it to format and type. Returns true 
 77   * on success. 
 78   */
 79  bool impExpImportParseFileExten(
 80  	CFStringRef			fstr,
 81  	SecExternalFormat   *inputFormat,   // RETURNED
 82  	SecExternalItemType	*itemType);		// RETURNED
 83  
 84  /* do a [NSString stringByDeletingPathExtension] equivalent */
 85  CFStringRef CF_RETURNS_RETAINED impExpImportDeleteExtension(
 86  	CFStringRef			fileStr);
 87  
 88  /*
 89   * map {algorithm, class, SecExternalFormat} to a CSSM_KEYBLOB_FORMAT.
 90   * Returns errSecUnsupportedFormat in the rare appropriate case.
 91   */
 92  OSStatus impExpKeyForm(
 93  	SecExternalFormat		externForm,
 94  	SecExternalItemType		itemType,
 95  	CSSM_ALGORITHMS			alg,
 96  	CSSM_KEYBLOB_FORMAT		*cssmForm,		// RETURNED
 97  	CSSM_KEYCLASS			*cssmClass);	// RETRUNED
 98  
 99  /*
100   * Guess an incoming blob's type, format and (for keys only) algorithm
101   * by examining its contents. Returns true on success, in which case 
102   * *inputFormat and *itemType, and *keyAlg are valid. Caller optionally 
103   * passes in valid values any number of these as a clue.
104   */
105  bool impExpImportGuessByExamination(
106  	CFDataRef			inData,
107  	SecExternalFormat   *inputFormat,	// may be kSecFormatUnknown on entry 
108  	SecExternalItemType	*itemType,		// may be kSecItemTypeUnknown on entry 
109  	CSSM_ALGORITHMS		*keyAlg);		// CSSM_ALGID_NONE - unknown
110  
111  /*
112   * Obtain the CDSA-layer CSSM_RESOURCE_CONTROL_CONTEXT given a SecAccessRef.
113   */
114  extern OSStatus impExpAccessToRcc(
115  	SecAccessRef	accessRef,
116  	const CSSM_RESOURCE_CONTROL_CONTEXT **rcc);
117  
118  
119  
120  /* low-level crypto/CSP support */
121  
122  /*
123   * Given a context specified via a CSSM_CC_HANDLE, add a new
124   * CSSM_CONTEXT_ATTRIBUTE to the context as specified by AttributeType,
125   * AttributeLength, and an untyped pointer.
126   */
127  CSSM_RETURN impExpAddContextAttribute(CSSM_CC_HANDLE CCHandle,
128  	uint32 AttributeType,
129  	uint32 AttributeLength,
130  	const void *AttributePtr);
131  
132  /*
133   * Free memory via specified plugin's app-level allocator
134   */
135  void impExpFreeCssmMemory(
136  	CSSM_HANDLE		hand,
137  	void 			*p);
138  
139  /* 
140   * Calculate digest of any CSSM_KEY. Unlike older implementations
141   * of this logic, you can actually calculate the public key hash 
142   * on any class of key, any format, raw CSP or CSPDL.
143   *
144   * Caller must free keyDigest->Data using impExpFreeCssmMemory() since 
145   * this is allocated by the CSP's app-specified allocator.
146   */
147  CSSM_RETURN impExpKeyDigest(
148  	CSSM_CSP_HANDLE cspHand,
149  	CSSM_KEY_PTR	key,
150  	CSSM_DATA_PTR   keyDigest);		// contents allocd and RETURNED
151  
152  /*
153   * Given a CFTypeRef passphrase which may be a CFDataRef or a CFStringRef,
154   * return a refcounted CFStringRef suitable for use with the PKCS12 library.
155   * PKCS12 passphrases in CFData format must be UTF8 encoded. 
156   */
157  OSStatus impExpPassphraseToCFString(
158  	CFTypeRef   passin,
159  	CFStringRef *passout);	// may be the same as passin, but refcounted
160  
161  /*
162   * Given a CFTypeRef passphrase which may be a CFDataRef or a CFStringRef,
163   * return a refcounted CFDataRef whose bytes are suitable for use with 
164   * PKCS5 (v1.5 and v2.0) key derivation.
165   */
166  OSStatus impExpPassphraseToCFData(
167  	CFTypeRef   passin,
168  	CFDataRef   *passout);	// may be the same as passin, but refcounted
169  
170  /*
171   * Obtain passphrase, given a SecKeyImportExportParameters. 
172   *
173   * Passphrase comes from one of two places: app-specified, in 
174   * SecKeyImportExportParameters.passphrase (either as CFStringRef
175   * or CFDataRef); or via the secure passphrase mechanism.
176   *
177   * Passphrase is returned in one of two forms:
178   *
179   * -- Secure passphrase is returned as a CSSM_KEY_PTR, which the 
180   *    caller must CSSM_FreeKey later. THe CSSM_KEY_PTR must also 
181   *    be free()d. 
182   *
183   * -- CFTypeRef for app-supplied passphrases. This can be one of 
184   *    two types:
185   *
186   *    -- CFStringRef, for use with P12
187   *    -- CFDataRef, for more general use (e.g. for PKCS5). 
188   *   
189   *    In either case the caller must CFRelease the result.    
190   */
191  typedef enum {
192  	SPF_String,			// CFStringRef, P12
193  	SPF_Data			// CFDataRef, PKCS5
194  } impExpPassphraseForm;
195  
196  typedef enum {
197  	VP_Export,			// verify passphrase
198  	VP_Import			// no verify
199  } impExpVerifyPhrase;
200  
201  OSStatus impExpPassphraseCommon(
202  	const SecKeyImportExportParameters *keyParams,
203  	CSSM_CSP_HANDLE			cspHand,		// MUST be CSPDL, for passKey generation
204  	impExpPassphraseForm	phraseForm,
205  	impExpVerifyPhrase		verifyPhrase,   // for secure passphrase
206  	CFTypeRef				*phrase,		// RETURNED, or
207  	CSSM_KEY_PTR			*passKey);		// mallocd and RETURNED
208  	
209  CSSM_KEYATTR_FLAGS ConvertArrayToKeyAttributes(SecKeyRef aKey, CFArrayRef usage);
210  
211  Boolean ConvertSecKeyImportExportParametersToSecImportExportKeyParameters(SecKeyRef aKey,
212  	const SecItemImportExportKeyParameters* newPtr, SecKeyImportExportParameters* oldPtr);
213  
214  #ifdef	__cplusplus
215  }
216  #endif
217  
218  #endif  /* _SECURITY_SEC_IMPORT_EXPORT_UTILS_H_ */
219