libsecurity_keychain/lib/SecImportExport.h

   1 /*
   2  * Copyright (c) 2000-2010,2013 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         @header SecImportExport
  26         contains import/export functionality for keys and certificates.
  27 */
  28 #ifndef _SECURITY_SEC_IMPORT_EXPORT_H_
  29 #define _SECURITY_SEC_IMPORT_EXPORT_H_
  30
  31 #include <Security/cssmtype.h>
  32 #include <Security/SecAccess.h>
  33 #include <Security/SecKeychain.h>
  34 #include <CoreFoundation/CoreFoundation.h>
  35 #include <stdint.h>
  36
  37 #ifdef  __cplusplus
  38 extern "C" {
  39 #endif
  40
  41 /*
  42  * Supported import/export Formats
  43  */
  44 enum
  45 {
  46         /*
  47          * When importing: unknown format
  48          * When exporting: default format for item
  49          */
  50         kSecFormatUnknown = 0,
  51
  52         /*
  53          * Public and Private Key formats.
  54          * Default for export is kSecFormatOpenSSL.
  55          */
  56         kSecFormatOpenSSL,                              /* a.k.a. X509 for public keys */
  57         kSecFormatSSH,                                  /* OpenSSH v.1 */
  58         kSecFormatBSAFE,
  59
  60         /* Symmetric Key Formats */
  61         kSecFormatRawKey,                               /* raw unformatted key bits; default */
  62
  63         /* Formats for wrapped symmetric and private keys */
  64         kSecFormatWrappedPKCS8,
  65         kSecFormatWrappedOpenSSL,               /* traditional openssl */
  66         kSecFormatWrappedSSH,                   /* OpenSSH v.1 */
  67         kSecFormatWrappedLSH,
  68
  69         /* Formats for certificates */
  70         kSecFormatX509Cert,                             /* DER encoded; default */
  71
  72         /* Aggregate Types */
  73         kSecFormatPEMSequence,                  /* sequence of certs and/or keys, implies PEM
  74                                                                          *    armour. Default format for multiple items */
  75         kSecFormatPKCS7,                                /* sequence of certs */
  76         kSecFormatPKCS12,                               /* set of certs and private keys */
  77         kSecFormatNetscapeCertSequence, /* sequence of certs, form netscape-cert-sequence */
  78
  79         /* Added in Mac OS X 10.5 */
  80         kSecFormatSSHv2                                 /* OpenSSH v.2. Note that OpenSSH v2 private keys
  81                                                                          * are in format kSecFormatOpenSSL or
  82                                                                          * kSecFormatWrappedOpenSSL. */
  83 };
  84 typedef uint32_t SecExternalFormat;
  85
  86 /*
  87  * Indication of basic item type when importing.
  88  */
  89 enum {
  90         kSecItemTypeUnknown,                    /* caller doesn't know what this is */
  91         kSecItemTypePrivateKey,
  92         kSecItemTypePublicKey,
  93         kSecItemTypeSessionKey,
  94         kSecItemTypeCertificate,
  95         kSecItemTypeAggregate                   /* PKCS7, PKCS12, kSecFormatPEMSequence, etc. */
  96 };
  97 typedef uint32_t SecExternalItemType;
  98
  99 /*
 100  * Flags passed to SecKeychainItemExport() and SecKeychainItemImport().
 101  */
 102 enum
 103 {
 104         kSecItemPemArmour                       = 0x00000001,   /* exported blob is PEM formatted */
 105 };
 106 typedef uint32_t SecItemImportExportFlags;
 107
 108 /*
 109  * SecKeyRef-specific flags, specified in SecKeyImportExportParameters.flags
 110  */
 111 enum
 112 {
 113         /*
 114          * When true, prevents the importing of more than one private key
 115          * in a given SecKeychainItemImport().
 116          */
 117         kSecKeyImportOnlyOne            = 0x00000001,
 118
 119         /*
 120          * When true, passphrase for import/export is obtained by user prompt
 121          * instead of by caller-supplied data (SecKeyImportExportParameters.passphrase).
 122          * This is the preferred method for obtaining a user-supplied passphrase
 123          * as it avoids having the cleartext passphrase appear in the app's
 124          * address space at any time.
 125          */
 126         kSecKeySecurePassphrase         = 0x00000002,
 127
 128         /*
 129          * When true, imported private keys will have no Access Control List
 130          * (ACL) attached to them. In the absence of both this bit and the accessRef
 131          * field in SecKeyImportExportParameters (see below), imported private
 132          * keys are given a default ACL.
 133          */
 134         kSecKeyNoAccessControl          = 0x00000004
 135 };
 136 typedef uint32_t SecKeyImportExportFlags;
 137
 138 /*
 139  * Version of a SecKeyImportExportParameters.
 140  */
 141 #define SEC_KEY_IMPORT_EXPORT_PARAMS_VERSION            0
 142
 143 /*
 144  * Parameters specific to SecKeyRefs.
 145  */
 146 typedef struct
 147 {
 148         /* for import and export */
 149         uint32_t                                version;                /* SEC_KEY_IMPORT_EXPORT_PARAMS_VERSION */
 150         SecKeyImportExportFlags flags;                  /* SecKeyImportExportFlags bits */
 151         CFTypeRef                               passphrase;             /* kSecFormatPKCS12, kSecFormatWrapped*
 152                                                                                          *    formats only. Legal types are
 153                                                                                          *    CFStringRef and CFDataRef. */
 154         CFStringRef                             alertTitle;             /* title of secure passphrase alert panel */
 155         CFStringRef                             alertPrompt;    /* prompt in secure passphrase alert panel */
 156
 157         /* for import only */
 158         SecAccessRef                    accessRef;              /* specifies the initial ACL of imported
 159                                                                                          *    key(s) */
 160         CSSM_KEYUSE                             keyUsage;               /* CSSM_KEYUSE_DECRYPT, CSSM_KEYUSE_SIGN,
 161                                                                                          *    etc. */
 162         CSSM_KEYATTR_FLAGS              keyAttributes;  /* CSSM_KEYATTR_PERMANENT, etc. */
 163 } SecKeyImportExportParameters;
 164
 165
 166 typedef struct
 167 {
 168         /* for import and export */
 169         uint32_t                                version;                /* SEC_KEY_IMPORT_EXPORT_PARAMS_VERSION */
 170         SecKeyImportExportFlags flags;                  /* SecKeyImportExportFlags bits */
 171         CFTypeRef                               passphrase;             /* kSecFormatPKCS12, kSecFormatWrapped*
 172                                                                                          *    formats only. Legal types are
 173                                                                                          *    CFStringRef and CFDataRef. */
 174         CFStringRef                             alertTitle;             /* title of secure passphrase alert panel */
 175         CFStringRef                             alertPrompt;    /* prompt in secure passphrase alert panel */
 176
 177         /* for import only */
 178         SecAccessRef                    accessRef;              /* specifies the initial ACL of imported
 179                                                                                          *    key(s) */
 180         CFArrayRef                              keyUsage;               /* An Array containing usage attributes from SecItem.h, e.g.
 181                                                                                            kSecAttrCanEncrypt;, kSecAttrCanDecrypt, kSecAttrCanDerive, etc.
 182                                                                                          */
 183
 184         CFArrayRef                              keyAttributes;  /* An array containing zero or more key attributes
 185                                                                                            for an imported key. Possible values (from SecItem.h):
 186                                                                                            kSecAttrIsPermanent, kSecAttrIsSensitive, kSecAttrIsExtractable
 187                                                                                            Pass NULL in this field to use default attributes:
 188                                                                                            - kSecAttrIsPermanent if a keychain is specified
 189                                                                                            - kSecAttrIsSensitive for private keys
 190                                                                                            - kSecAttrIsExtractable by default
 191                                                                                          */
 192 } SecItemImportExportKeyParameters;
 193
 194 /*
 195  * SecKeychainItemExport()
 196  *
 197  * This function takes one or more SecKeychainItemRefs and creates an
 198  * external representation of the item(s) in the form of a CFDataRef.
 199  * Caller specifies the format of the external representation via a
 200  * SecExternalFormat enum. Caller may specify kSecFormatUnknown for
 201  * the format, in which case a the default format for the item
 202  * being exported is used (as described in the SecExternalFormat enums).
 203  * PEM armouring is optional and is specified by the kSecItemPemArmour
 204  * flag in importFlags.
 205  *
 206  * If exactly one item is to be exported, the keychainItemOrArray argument
 207  * can be a SecKeychainItem. Otherwise this argument is a CFArrayRef
 208  * containing a number of SecKeychainItems.
 209  *
 210  * The following SecKeychainItems may be exported:
 211  *
 212  *   SecCertificateRef
 213  *   SecKeyRef
 214  *   SecIdentityRef
 215  *
 216  *
 217  * Key-related SecKeyImportExportParameters fields
 218  * -----------------------------------------------
 219  *
 220  * When exporting SecKeyRefs in one of the wrapped formats
 221  * (kSecFormatWrappedOpenSSL, kSecFormatWrappedSSH,
 222  * kSecFormatWrappedPKCS8), or in PKCS12 format, caller must
 223  * either explicitly specify the passphrase field or set
 224  * the kSecKeySecurePassphrase bit in SecKeyImportExportFlags.
 225  *
 226  * If kSecKeySecurePassphrase is selected, caller can optionally
 227  * specify strings for the passphrase panel's title bar and for
 228  * the prompt which appears in the panel via the alertTitle and
 229  * alertPrompt fields in SecKeyImportExportParameters.
 230  *
 231  * If an explicit passphrase is specified, note that PKCS12
 232  * explicitly requires that passphrases are in Unicode format;
 233  * passing in a CFStringRef as the passphrase is the safest way
 234  * to ensure that this requirement is met (and that the result
 235  * will be compatible with other implementations). If a CFDataRef
 236  * is supplied as the passphrase for a PKCS12 export operation,
 237  * the referent data is assumed to be in UTF8 form and will be
 238  * converted as appropriate.
 239  *
 240  * If no key items are being exported, the keyParams argument may be NULL.
 241  * @discussion This API has been deprecated. Please us the SecItemExport API instead.
 242  */
 243 OSStatus SecKeychainItemExport(
 244         CFTypeRef                                                       keychainItemOrArray,
 245         SecExternalFormat                                       outputFormat,
 246         SecItemImportExportFlags                        flags,                          /* kSecItemPemArmor, etc. */
 247         const SecKeyImportExportParameters  *keyParams,                 /* optional */
 248         CFDataRef                                                       *exportedData)          /* external representation returned here */
 249                 DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 250
 251 /*
 252  * SecItemExport()
 253  *
 254  * This function takes one or more SecItemRefs and creates an
 255  * external representation of the item(s) in the form of a CFDataRef.
 256  * Caller specifies the format of the external representation via a
 257  * SecExternalFormat enum. Caller may specify kSecFormatUnknown for
 258  * the format, in which case a the default format for the item
 259  * being exported is used (as described in the SecExternalFormat enums).
 260  * PEM armouring is optional and is specified by the kSecItemPemArmour
 261  * flag in importFlags.
 262  *
 263  * If exactly one item is to be exported, the keychainItemOrArray argument
 264  * can be a SecKeychainItem. Otherwise this argument is a CFArrayRef
 265  * containing a number of SecKeychainItems.
 266  *
 267  * The following SecKeychainItems may be exported:
 268  *
 269  *   SecCertificateRef
 270  *   SecKeyRef
 271  *   SecIdentityRef
 272  *
 273  *
 274  * Key-related SecItemExport fields
 275  * -----------------------------------------------
 276  *
 277  * When exporting SecKeyRefs in one of the wrapped formats
 278  * (kSecFormatWrappedOpenSSL, kSecFormatWrappedSSH,
 279  * kSecFormatWrappedPKCS8), or in PKCS12 format, caller must
 280  * either explicitly specify the passphrase field or set
 281  * the kSecKeySecurePassphrase bit in SecKeyImportExportFlags.
 282  *
 283  * If kSecKeySecurePassphrase is selected, caller can optionally
 284  * specify strings for the passphrase panel's title bar and for
 285  * the prompt which appears in the panel via the alertTitle and
 286  * alertPrompt fields in SecItemImportExportKeyParameters.
 287  *
 288  * If an explicit passphrase is specified, note that PKCS12
 289  * explicitly requires that passphrases are in Unicode format;
 290  * passing in a CFStringRef as the passphrase is the safest way
 291  * to ensure that this requirement is met (and that the result
 292  * will be compatible with other implementations). If a CFDataRef
 293  * is supplied as the passphrase for a PKCS12 export operation,
 294  * the referent data is assumed to be in UTF8 form and will be
 295  * converted as appropriate.
 296  *
 297  * If no key items are being exported, the keyParams argument may be NULL.
 298  *
 299  */
 300 OSStatus SecItemExport(
 301         CFTypeRef                                                       secItemOrArray,
 302         SecExternalFormat                                       outputFormat,
 303         SecItemImportExportFlags                        flags,                          /* kSecItemPemArmor, etc. */
 304         const SecItemImportExportKeyParameters  *keyParams,                     /* optional */
 305         CFDataRef                                                       *exportedData)          /* external representation returned here */
 306                 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 307 /*
 308  * SecKeychainItemImport()
 309  *
 310  * This function takes a CFDataRef containing the external representation
 311  * of one or more objects and creates SecKeychainItems corresponding to
 312  * those objects and optionally imports those SecKeychainItems into a
 313  * specified keychain. The format of the incoming representation is
 314  * specified by one or more of the following:
 315  *
 316  * -- A SecExternalFormat. This optional in/out argument is used when
 317  *    the caller knows exactly what format the external representation
 318  *    is in. It's also used to return to the caller the format which the
 319  *    function actually determines the external representation to be in.
 320  *    A value of kSecFormatUnknown is specified on entry when the caller
 321  *    wishes to know the inferred format on return.
 322  *
 323  * -- A SecExternalItemType - optional, in/out. Used to specify what kind
 324  *    of item is in the incoming representation, if known by the caller.
 325  *    It's also used to return to the caller the item type which the
 326  *    function actually determines the external representation to contain.
 327  *    A value of kSecItemTypeUnknown is specified on entry when the caller
 328  *    wishes to know the inferred item type on return.
 329  *
 330  * -- fileNameOrExtension, a CFStringRef. This optional argument contains
 331  *    the name of the file from which the external representation was
 332  *    obtained; it can also be simply an extension like CFSTR(".p7r").
 333  *    This is a convenience for apps like KeychainAccess which can import a
 334  *    number of different formats.
 335  *
 336  * The SecKeychainItemImport() call does its best to figure out what is
 337  * in an incoming external item given the info provided by the above three
 338  * arguments. In most cases, SecKeychainItemImport() can even figure out
 339  * what's in an external item if none of these are specified, but it would
 340  * be unwise for an application to count on that ability.
 341  *
 342  * PEM formatting is determined internally via inspection of the incoming
 343  * data, so the kSecItemPemArmuor in the flags field is ignored.
 344  *
 345  * Zero, one, or both of the following occurs upon successful completion
 346  * of this function:
 347  *
 348  * -- The imported item(s) is (are) imported to the specified importKeychain.
 349  *    If importKeychain is NULL, this step does not occur.
 350  *
 351  * -- The imported item(s) is (are) returned to the caller via the
 352  *    CRArrayRef *outItems argument. If outItems is NULL, this step
 353  *    does not occur. If outItems is NON-NULL, then *outItems will be
 354  *    a CFArrayRef containing a number of SecKeychainItems upon return.
 355  *    Caller must CFRelease the result.
 356  *
 357  * The possible types of returned SecKeychainItems are:
 358  *
 359  *   SecCertificateRef
 360  *   SecKeyRef
 361  *   SecIdentityRef
 362  *
 363  * Note that when importing a PKCS12 blob, typically one SecIdentityRef
 364  * and zero or more additional SecCertificateRefs are returned in
 365  * outItems. No SecKeyRefs will appear there unless a key
 366  * is found in the incoming blob with does not have a matching
 367  * certificate.
 368  *
 369  * A typical case in which an app specifies the outItems
 370  * argument and a NULL for importKeychain is when the app wishes to
 371  * perform some user interaction, perhaps on a per-item basis, before
 372  * committing to actually import the item(s). In this case, if the app
 373  * does wish to proceed with the import, the standard import calls
 374  * (SecCertificateAddToKeychain(), SecKeyAddToKeychain (implementation
 375  * TBD)) would be used.
 376  *
 377  * Passing in NULL for both outItems and importKeychain
 378  * is a perfectly acceptable way of using this function to determine,
 379  * in a non-intrusive way, what is inside a given data blob. No effect
 380  * other than returning inputFormat and/or itemType occurs in this
 381  * case.
 382
 383  *
 384  * Key-related SecKeyImportExportParameters fields
 385  * -----------------------------------------------
 386  *
 387  * If importKeychain is NULL, the kSecKeyImportOnlyOne bit in the flags
 388  * argument is ignored. Otherwise, if the kSecKeyImportOnlyOne bit is set, and
 389  * there is more than one key in the incoming external representation, no
 390  * items will be imported to the specified keychain and errSecMultipleKeys will
 391  * be returned.
 392  *
 393  * The accessRef field allows the caller to specify the initial SecAccessRef
 394  * for imported private keys. If more than one private key is being imported,
 395  * all private keys get the same initial SecAccessRef. If this field is NULL
 396  * when private keys are being imported, then the ACL attached to imported
 397  * private keys depends on the kSecKeyNoAccessControl bit in the specified
 398  * keyParams->flags. If this bit is 0, or keyParams is NULL, the default ACL
 399  * will be used. If this bit is 1, no ACL will be attached to imported
 400  * private keys.
 401  *
 402  * keyUsage and keyAttributes specify the low-level usage and attribute flags
 403  * of imported keys. Each is a word of bits. The default value for keyUsage
 404  * (used when keyParams is NULL or if keyParams->keyUsage is zero) is
 405  * CSSM_KEYUSE_ANY. The default value for keyAttributes defaults is
 406  * CSSM_KEYATTR_SENSITIVE | CSSM_KEYATTR_EXTRACTABLE; the CSSM_KEYATTR_PERMANENT
 407  * bit is also added to the default if a non-NULL importKeychain is provided.
 408  *
 409  * The following are valid bits in keyAttributes:
 410  *
 411  *   CSSM_KEYATTR_PERMANENT
 412  *   CSSM_KEYATTR_SENSITIVE
 413  *   CSSM_KEYATTR_EXTRACTABLE
 414  *
 415  * If the CSSM_KEYATTR_PERMANENT is set then the importKeychain argument must
 416  * be valid or errSecInvalidKeychain will be returned if in fact any keys are found
 417  * in the external representation.
 418  *
 419  * Note that if the caller does not set the CSSM_KEYATTR_EXTRACTABLE, this key
 420  * will never be able to be extracted from the keychain in any form, not even
 421  * in wrapped form. The CSSM_KEYATTR_SENSITIVE indicates that the key can only
 422  * be extracted in wrapped form.
 423  *
 424  * The CSSM_KEYATTR_RETURN_xxx bits are always forced to
 425  * CSSM_KEYATTR_RETURN_REF regardless of the specified keyAttributes
 426  * field.
 427  *
 428  * When importing SecKeyRefs in one of the wrapped formats
 429  * (kSecFormatWrappedOpenSSL, kSecFormatWrappedSSH,
 430  * kSecFormatWrappedPKCS8), or in PKCS12 format, caller must
 431  * either explicitly specify the passphrase field or set
 432  * the kSecKeySecurePassphrase bit in SecKeyImportExportFlags.
 433  *
 434  * If kSecKeySecurePassphrase is selected, caller can optionally
 435  * specify strings for the passphrase panel's title bar and for
 436  * the prompt which appears in the panel via the alertTitle and
 437  * alertPrompt fields in SecKeyImportExportParameters.
 438  *
 439  * If an explicit passphrase is specified, note that PKCS12
 440  * explicitly requires that passphrases are in Unicode format;
 441  * passing in a CFStringRef as the passphrase is the safest way
 442  * to ensure that this requirement is met (and that the result
 443  * will be compatible with other implementations). If a CFDataRef
 444  * is supplied as the passphrase for a PKCS12 export operation,
 445  * the referent data is assumed to be in UTF8 form and will be
 446  * converted as appropriate.
 447
 448  * If no key items are being imported, the keyParams argument may be NULL.
 449  *
 450  * The SecItemImportExportFlags argument is currently unused; caller should pass
 451  * in 0.
 452  *
 453  * @discussion  This API has been deprecated.  Please use the SecItemImport API instead.
 454  */
 455 OSStatus SecKeychainItemImport(
 456         CFDataRef                                                       importedData,
 457         CFStringRef                                                     fileNameOrExtension,    /* optional */
 458         SecExternalFormat                                       *inputFormat,                   /* optional, IN/OUT */
 459         SecExternalItemType                                     *itemType,                              /* optional, IN/OUT */
 460         SecItemImportExportFlags                        flags,
 461         const SecKeyImportExportParameters  *keyParams,                         /* optional */
 462         SecKeychainRef                                          importKeychain,                 /* optional */
 463         CFArrayRef                                                      *outItems)                                                      /* optional */
 464                 DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
 465
 466 /*
 467  * SecItemImport()
 468  *
 469  * This function takes a CFDataRef containing the external representation
 470  * of one or more objects and creates SecKeychainItems corresponding to
 471  * those objects and optionally imports those SecKeychainItems into a
 472  * specified keychain. The format of the incoming representation is
 473  * specified by one or more of the following:
 474  *
 475  * -- A SecExternalFormat. This optional in/out argument is used when
 476  *    the caller knows exactly what format the external representation
 477  *    is in. It's also used to return to the caller the format which the
 478  *    function actually determines the external representation to be in.
 479  *    A value of kSecFormatUnknown is specified on entry when the caller
 480  *    wishes to know the inferred format on return.
 481  *
 482  * -- A SecExternalItemType - optional, in/out. Used to specify what kind
 483  *    of item is in the incoming representation, if known by the caller.
 484  *    It's also used to return to the caller the item type which the
 485  *    function actually determines the external representation to contain.
 486  *    A value of kSecItemTypeUnknown is specified on entry when the caller
 487  *    wishes to know the inferred item type on return.
 488  *
 489  * -- fileNameOrExtension, a CFStringRef. This optional argument contains
 490  *    the name of the file from which the external representation was
 491  *    obtained; it can also be simply an extension like CFSTR(".p7r").
 492  *    This is a convenience for apps like KeychainAccess which can import a
 493  *    number of different formats.
 494  *
 495  * The SecItemImport() call does its best to figure out what is
 496  * in an incoming external item given the info provided by the above three
 497  * arguments. In most cases, SecItemImport() can even figure out
 498  * what's in an external item if none of these are specified, but it would
 499  * be unwise for an application to count on that ability.
 500  *
 501  * PEM formatting is determined internally via inspection of the incoming
 502  * data, so the kSecItemPemArmuor in the flags field is ignored.
 503  *
 504  * Zero, one, or both of the following occurs upon successful completion
 505  * of this function:
 506  *
 507  * -- The imported item(s) is (are) imported to the specified importKeychain.
 508  *    If importKeychain is NULL, this step does not occur.
 509  *
 510  * -- The imported item(s) is (are) returned to the caller via the
 511  *    CRArrayRef *outItems argument. If outItems is NULL, this step
 512  *    does not occur. If outItems is NON-NULL, then *outItems will be
 513  *    a CFArrayRef containing a number of SecKeychainItems upon return.
 514  *    Caller must CFRelease the result.
 515  *
 516  * The possible types of returned SecKeychainItems are:
 517  *
 518  *   SecCertificateRef
 519  *   SecKeyRef
 520  *   SecIdentityRef
 521  *
 522  * Note that when importing a PKCS12 blob, typically one SecIdentityRef
 523  * and zero or more additional SecCertificateRefs are returned in
 524  * outItems. No SecKeyRefs will appear there unless a key
 525  * is found in the incoming blob with does not have a matching
 526  * certificate.
 527  *
 528  * A typical case in which an app specifies the outItems
 529  * argument and a NULL for importKeychain is when the app wishes to
 530  * perform some user interaction, perhaps on a per-item basis, before
 531  * committing to actually import the item(s). In this case, if the app
 532  * does wish to proceed with the import, the standard import calls
 533  * (SecCertificateAddToKeychain(), SecKeyAddToKeychain (implementation
 534  * TBD)) would be used.
 535  *
 536  * Passing in NULL for both outItems and importKeychain
 537  * is a perfectly acceptable way of using this function to determine,
 538  * in a non-intrusive way, what is inside a given data blob. No effect
 539  * other than returning inputFormat and/or itemType occurs in this
 540  * case.
 541
 542  *
 543  * Key-related SecItemImportExportKeyParameters fields
 544  * -----------------------------------------------
 545  *
 546  * If importKeychain is NULL, the kSecKeyImportOnlyOne bit in the flags
 547  * argument is ignored. Otherwise, if the kSecKeyImportOnlyOne bit is set, and
 548  * there is more than one key in the incoming external representation, no
 549  * items will be imported to the specified keychain and errSecMultipleKeys will
 550  * be returned.
 551  *
 552  * The accessRef field allows the caller to specify the initial SecAccessRef
 553  * for imported private keys. If more than one private key is being imported,
 554  * all private keys get the same initial SecAccessRef. If this field is NULL
 555  * when private keys are being imported, then the ACL attached to imported
 556  * private keys depends on the kSecKeyNoAccessControl bit in the specified
 557  * keyParams->flags. If this bit is 0, or keyParams is NULL, the default ACL
 558  * will be used. If this bit is 1, no ACL will be attached to imported
 559  * private keys.
 560  *
 561  * keyUsage and keyAttributes specify the low-level usage and attribute flags
 562  * of imported keys. These fields contain a CFArray whose values are constants
 563  * from SecItem.h.
 564  *
 565  * Possible values in the keyUsage array:
 566  *
 567  *   kSecAttrCanEncrypt
 568  *   kSecAttrCanDecrypt
 569  *   kSecAttrCanDerive
 570  *   kSecAttrCanSign
 571  *   kSecAttrCanVerify
 572  *   kSecAttrCanWrap
 573  *   kSecAttrCanUnwrap
 574  *
 575  * If keyUsage is set to NULL, then any key usage is permitted.
 576  *
 577  * Possible values in the keyAttributes array:
 578  *
 579  *   kSecAttrIsPermanent
 580  *   kSecAttrIsSensitive
 581  *   kSecAttrIsExtractable
 582  *
 583  * If keyAttributes is set to NULL, then default values are used:
 584  *   kSecAttrIsPermanent if an import keychain is specified
 585  *   kSecAttrIsSensitive for non-public keys
 586  *   kSecAttrIsExtractable
 587  *
 588  * If the kSecAttrIsPermanent attribute is set, then the
 589  * importKeychain argument must be valid or errSecInvalidKeychain
 590  * will be returned even if keys were able to be imported.
 591  *
 592  * Note that if the caller provides a keyAttributes array but
 593  * does not set kSecAttrIsExtractable, this key will never be
 594  * able to be extracted from the keychain in any form, not even
 595  * in wrapped form. kSecAttrIsSensitive indicates that the key
 596  * can only be extracted in wrapped form.
 597  *
 598  * When importing SecKeyRefs in one of the wrapped formats
 599  * (kSecFormatWrappedOpenSSL, kSecFormatWrappedSSH,
 600  * kSecFormatWrappedPKCS8), or in PKCS12 format, caller must
 601  * either explicitly specify the passphrase field or set
 602  * the kSecKeySecurePassphrase bit in SecKeyImportExportFlags.
 603  *
 604  * If kSecKeySecurePassphrase is selected, caller can optionally
 605  * specify strings for the passphrase panel's title bar and for
 606  * the prompt which appears in the panel via the alertTitle and
 607  * alertPrompt fields in SecItemImportExportKeyParameters.
 608  *
 609  * If an explicit passphrase is specified, note that PKCS12
 610  * explicitly requires that passphrases are in Unicode format;
 611  * passing in a CFStringRef as the passphrase is the safest way
 612  * to ensure that this requirement is met (and that the result
 613  * will be compatible with other implementations). If a CFDataRef
 614  * is supplied as the passphrase for a PKCS12 export operation,
 615  * the referent data is assumed to be in UTF8 form and will be
 616  * converted as appropriate.
 617
 618  * If no key items are being imported, the keyParams argument may be NULL.
 619  *
 620  * The SecItemImportExportFlags argument is currently unused; caller should pass
 621  * in 0.
 622  */
 623
 624 OSStatus SecItemImport(
 625         CFDataRef                                                       importedData,
 626         CFStringRef                                                     fileNameOrExtension,    /* optional */
 627         SecExternalFormat                                       *inputFormat,                   /* optional, IN/OUT */
 628         SecExternalItemType                                     *itemType,                              /* optional, IN/OUT */
 629         SecItemImportExportFlags                        flags,
 630         const SecItemImportExportKeyParameters  *keyParams,                             /* optional */
 631         SecKeychainRef                                          importKeychain,                 /* optional */
 632         CFArrayRef                                                      *outItems)                              /* optional */
 633                 __OSX_AVAILABLE_STARTING(__MAC_10_7, __IPHONE_NA);
 634 /*!
 635     @enum Import/Export options
 636     @discussion Predefined key constants used when passing dictionary-based arguments to import/export functions.
 637     @constant kSecImportExportPassphrase Specifies a passphrase represented by a CFStringRef to be used when exporting to (or importing from) PKCS#12 format.
 638         @constant kSecImportExportKeychain Specifies a keychain represented by a SecKeychainRef to be used as the target when importing from PKCS#12 format.
 639         @constant kSecImportExportAccess Specifies an access represented by a SecAccessRef for the initial access (ACL) of a key imported from PKCS#12 format.
 640 */
 641 extern CFStringRef kSecImportExportPassphrase;
 642 extern CFStringRef kSecImportExportKeychain;
 643 extern CFStringRef kSecImportExportAccess;
 644
 645 /*!
 646     @enum Import/Export item description
 647     @discussion Predefined key constants used by functions which return a CFArray with a CFDictionary per item.
 648     @constant kSecImportItemLabel A CFStringRef representing the item label. This implementation specific identifier cannot be expected to have any format.
 649     @constant kSecImportItemKeyID A CFDataRef representing the key id. Typically this is the SHA-1 digest of the public key.
 650     @constant kSecImportItemIdentity A SecIdentityRef representing the identity.
 651     @constant kSecImportItemTrust A SecTrustRef set up with all relevant certificates. Not guaranteed to succesfully evaluate.
 652     @constant kSecImportItemCertChain A CFArrayRef holding all relevant certificates for this item's identity.
 653 */
 654 extern CFStringRef kSecImportItemLabel;
 655 extern CFStringRef kSecImportItemKeyID;
 656 extern CFStringRef kSecImportItemTrust;
 657 extern CFStringRef kSecImportItemCertChain;
 658 extern CFStringRef kSecImportItemIdentity;
 659
 660 /*!
 661         @function SecPKCS12Import
 662         @abstract Imports the contents of a PKCS12 formatted blob.
 663     @param pkcs12_data The PKCS12 data to be imported.
 664     @param options A dictionary containing import options. A kSecImportExportPassphrase entry is required at minimum. Only password-based PKCS12 blobs are currently supported.
 665     @param items On return, an array containing a dictionary for every item extracted. Use kSecImportItem constants to access specific elements of these dictionaries. Your code must CFRelease the array when it is no longer needed.
 666         @result errSecSuccess in case of success. errSecDecode means either the blob can't be read or it is malformed.
 667                 errSecAuthFailed means an incorrect password was supplied, or data in the container is damaged.
 668 */
 669 OSStatus SecPKCS12Import(CFDataRef pkcs12_data, CFDictionaryRef options, CFArrayRef *items);
 670
 671 #ifdef  __cplusplus
 672 }
 673 #endif
 674
 675 #endif  /* _SECURITY_SEC_IMPORT_EXPORT_H_ */