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