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