OSX/libsecurity_keychain/lib/SecExternalRep.h

   1 /*
   2  * Copyright (c) 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  * SecExternalRep.h - private classes representing external representations of
  24  *                                        SecKeychainItemRefs, used by SecImportExport.h
  25  */
  26
  27 #ifndef _SECURITY_SEC_EXTERNAL_REP_H_
  28 #define _SECURITY_SEC_EXTERNAL_REP_H_
  29
  30 #include <Security/SecImportExport.h>
  31
  32 /*
  33  * mechanism to limit private key import
  34  */
  35 typedef enum {
  36         PIS_NoLimit,                    // no limit
  37         PIS_AllowOne,                   // allow import of at most one
  38         PIS_NoMore                              // found one, no more allowed
  39 } ImpPrivKeyImportState;
  40
  41 namespace Security
  42 {
  43
  44 namespace KeychainCore
  45 {
  46
  47 /*
  48  * When exporting, each instance of this represents one keychain item we're
  49  * exporting. Note that SecIdentityRefs are represented by two of these - one
  50  * for the cert, one for the key.
  51  */
  52 class SecExportRep
  53 {
  54 protected:
  55         SecExportRep(
  56                 CFTypeRef                                               kcItemRef);
  57
  58 public:
  59         /* default constructor throws */
  60         SecExportRep();
  61
  62         /*
  63          * Gleans SecExternalItemType from incoming type, throws MacOSError if
  64          * incoming type is bogus, and vends an instance of a suitable subclass.
  65          * Vended object holds a reference to kcItem for its lifetime.
  66          */
  67         static SecExportRep *vend(
  68                 CFTypeRef                                               kcItemRef);
  69
  70         virtual ~SecExportRep();
  71
  72         /*
  73          * Append external representation to CFData.
  74          * Implemented in subclass.
  75          */
  76         virtual OSStatus exportRep(
  77                 SecExternalFormat                                       format,
  78                 SecItemImportExportFlags                        flags,
  79                 const SecKeyImportExportParameters      *keyParams,             // optional
  80                 CFMutableDataRef                                        outData,                // data appended here
  81                 const char                                                      **pemHeader);   // e.g., "X509 CERTIFICATE"
  82
  83         /* member variables are read-only to the public */
  84         SecKeychainItemRef      kcItem()                { return mKcItem; }
  85         SecExternalItemType     externType()    { return mExternType; }
  86         CFArrayRef pemParamLines()                      { return mPemParamLines; }
  87
  88 protected:
  89         SecKeychainItemRef              mKcItem;
  90         SecExternalItemType             mExternType;            // inferred in vend()
  91         CFArrayRef                              mPemParamLines;         // optional PEM header strings
  92
  93 };
  94
  95 /*
  96  * Class representing one item we're importing from external representation.
  97  * Normally represents the one "thing" the app has provided to
  98  * SecKeychainItemImport(), but when importing in kSecFormatPEMSequence
  99  * format, the inpus is parsed into separate components, each of which
 100  * gets one instance of this class.
 101  */
 102 class SecImportRep
 103 {
 104 private:
 105         /* no default constructor */
 106         SecImportRep() { }
 107
 108 public:
 109         /*
 110          * Between constructor and the importRep() call, we're a placeholder to
 111          * allow our owner to keep track of what is in an incoming pile of bits.
 112          * We keep a reference to the incoming CFDataRef for our lifetime.
 113          */
 114         SecImportRep(
 115                 CFDataRef                                               external,
 116                 SecExternalItemType                             externType,             // may be unknown
 117                 SecExternalFormat                               externFormat,   // may be unknown
 118                 CSSM_ALGORITHMS                                 keyAlg,         // may be unknown, CSSM_ALGID_NONE
 119                 CFArrayRef                                              pemParamLines = NULL);
 120
 121         ~SecImportRep();
 122
 123         /*
 124          * Convert to one or more SecKeychainItemRefs and/or import to keychain.
 125          * Both mExternType and mExternFormat must be valid at this point.
 126          * Any conversion requiring unwrapping rerquires either a keychain
 127          * into which the unwrapped items will be imported) or a CSPDL handle (in
 128          * which case the resulting items are floating and ephemeral).
 129          * If we create a SecKeychainItemRefs, the only ref count held on
 130          * return will be that held by outArray.
 131          *
 132          * Incoming CSP handle is required; by convention it must be derived from
 133          * importKeychain if importKeychain is present.
 134          */
 135         OSStatus importRep(
 136                 SecKeychainRef                                          importKeychain,         // optional
 137                 CSSM_CSP_HANDLE                                         cspHand,                        // required
 138                 SecItemImportExportFlags                        flags,
 139                 const SecKeyImportExportParameters      *keyParams,                     // optional
 140                 ImpPrivKeyImportState                           &keyImportState,        // IN/OUT
 141                 CFMutableArrayRef                                       outArray);                      // optional, append here
 142
 143 private:
 144         /* implemented in SecWrappedKeys.cpp */
 145         OSStatus importWrappedKeyOpenssl(
 146                 SecKeychainRef                                          importKeychain, // optional
 147                 CSSM_CSP_HANDLE                                         cspHand,                // required
 148                 SecItemImportExportFlags                        flags,
 149                 const SecKeyImportExportParameters      *keyParams,             // optional
 150                 CFMutableArrayRef                                       outArray);              // optional, append here
 151
 152         /* optional inferred PrintName attribute */
 153         char *mPrintName;
 154
 155 public:
 156         /* Just keep these public, it simplifies things */
 157         CFDataRef                               mExternal;
 158         SecExternalItemType             mExternType;
 159         SecExternalFormat               mExternFormat;
 160         CSSM_ALGORITHMS                 mKeyAlg;
 161         CFArrayRef                              mPemParamLines;         // optional PEM header strings
 162 };
 163
 164 } // end namespace KeychainCore
 165
 166 } // end namespace Security
 167
 168 extern "C" {
 169
 170 /* implemented in SecWrappedKeys.cpp */
 171 OSStatus impExpWrappedKeyOpenSslExport(
 172         SecKeyRef                                                       secKey,
 173         SecItemImportExportFlags                        flags,
 174         const SecKeyImportExportParameters      *keyParams,             // optional
 175         CFMutableDataRef                                        outData,                // output appended here
 176         const char                                                      **pemHeader,    // RETURNED
 177         CFArrayRef                                                      *pemParamLines);// RETURNED
 178
 179 }
 180
 181 #endif  /* _SECURITY_SEC_IMPORT_EXPORT_H_ */