Function

SecItemImport

Imports one or more certificates, keys, or identities and optionally adds them to a keychain.

Declaration

OSStatus SecItemImport(CFDataRef importedData, CFStringRef fileNameOrExtension, SecExternalFormat *inputFormat, SecExternalItemType *itemType, SecItemImportExportFlags flags, const SecItemImportExportKeyParameters *keyParams, SecKeychainRef importKeychain, CFArrayRef  _Nullable *outItems);

Parameters

importedData

A CFDataRef 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 kSecFormatUnknown.

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 kSecItemTypeUnknown.

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 kSecItemPemArmour 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 CFArrayRef 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 CFArrayRef array that contains SecKeychainItemRef objects, each of which may be a SecCertificateRef, SecKeyRef, or SecIdentityRef object. The caller is responsible for releasing this CFArrayRef object.

Return Value

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 kSecItemTypeAggregate, 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.

See Also

Import and Export

SecItemExport

Exports one or more certificates, keys, or identities.

SecExternalFormat

The external format of a keychain item.

SecExternalItemType

The import item type.

SecItemImportExportFlags

The import and export function flags.

SecItemImportExportKeyParameters

The import/export parameter structure.

SecKeyImportExportFlags

The import/export parameter structure flags.

SEC_KEY_IMPORT_EXPORT_PARAMS_VERSION

The import/export parameter structure version.

SecKeychainItemImport

Imports one or more certificates, keys, or identities and adds them to a keychain.

Deprecated
SecKeychainItemExport

Exports one or more certificates, keys, or identities.

Deprecated
SecKeyImportExportParameters

The legacy import/export parameter structure.