SecItemImport(_:_:_:_:_:_:_:_:)

Declaration

func SecItemImport(_ importedData: CFData, _ fileNameOrExtension: CFString?, _ inputFormat: UnsafeMutablePointer<SecExternalFormat>?, _ itemType: UnsafeMutablePointer<SecExternalItemType>?, _ flags: SecItemImportExportFlags, _ keyParams: UnsafePointer<SecItemImportExportKeyParameters>?, _ importKeychain: SecKeychain?, _ outItems: UnsafeMutablePointer<CFArray?>?) -> OSStatus

Parameters

• importedData:

  A Cfdata object containing the data to import.

• fileNameOrExtension:

  Optional. The name of the file from which the external representation was previously read, or if that is unknown, then the file extension (.p7r, for example). This serves as a hint for the key format and key type detection code.

• inputFormat:

  Optional. The address of a Secexternalformat variable.

  If you know what format the external representation is in, set the initial value of this variable to an appropriate format constant to eliminate the need to detect the format. If not, set it to Formatunknown.

  On return, the variable referenced by this argument is set to the format that the function actually detected.

  Pass NULL if you don’t know or don’t care what format the external representation is in.

• itemType:

  Optional. The address of a Secexternalitemtype variable.

  Before calling this function, if you know what type of key the external representation contains, set the variable to an appropriate type constant to eliminate the need to detect the key type. If not, set it to Itemtypeunknown.

  On return, the variable referenced by this argument is set to the type of key that the function actually detected.

  Pass NULL if you don’t know or don’t care what key type the external representation contains.

• flags:

  A set of import flags. See Secitemimportexportflags for valid values.

  Note that PEM formatting is determined internally via inspection of the incoming data, so the Pemarmour flag is ignored.

• keyParams:

  A pointer to a structure containing a set of input parameters for the function. See Secitemimportexportkeyparameters.

• importKeychain:

  Optional. The keychain into which the item should be imported. Pass NULL if you do not want to import the item into a keychain.

• outItems:

  Optional. The address of a Cfarray variable that, upon return, will contain a list of keychain items. Pass NULL if you do not want a copy of these items.

  Upon return, the referenced variable is overwritten by a new Cfarray array that contains Seckeychainitem objects, each of which may be a Seccertificate, Seckey, or Secidentity object. The caller is responsible for releasing this Cfarray object.

Return Value

A result code. See Security Framework Result Codes.

Discussion

This function uses the fileNameOrExtension, inputFormat, and itemType parameters to help it interpret the incoming data. In most cases, SecItemImport(_:_:_:_:_:_:_:_:) can correctly interpret an external item if none of these are specified, but it is safer for you not to count on that ability.

When the output item type is SecExternalItemType.itemTypeAggregate, you can use the CFGetTypeID(_:) function to determine the Core Foundation type of each item and the functions in Getting Information About Keychain Services and Types to determine the keychain item type of each item. For example, the following code determines whether the item is a certificate:

CFTypeID theID = CFGetTypeID(theItem);
if (SecCertificateGetTypeID() == theID)

You can pass in NULL for both outItems and importKeychain to determine what is inside a given external data representation. When you do, the function returns the input format and the item type without modifying the data in any way.