keychain/headers/SecImportExport.h

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