OSX/libsecurity_keychain/lib/SecImportExportUtils.h

   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 "SecImportExport.h"
  30 #include "SecKeychainPriv.h"
  31 #include "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...)   secdebug("SecImpExp", ## args)
  73 #define SecImpInferDbg(args...) secdebug("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 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