OSX/libsecurity_keychain/lib/SecImportExport.h

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