SecItemAdd(_:_:)

Declaration

func SecItemAdd(_ attributes: CFDictionary, _ result: UnsafeMutablePointer<CFTypeRef?>?) -> OSStatus

Parameters

• attributes:

  A dictionary that describes the item to add. A typical attributes dictionary consists of:

  • The item’s class. Different attributes and behaviors apply to different classes of items. You use the Ksecclass key with a suitable value to tell keychain services whether the data you want to store represents a password, a certificate, a cryptographic key, or something else. See Item Class Keys And Values.

  • The data. Use the Ksecvaluedata key to indicate the data you want to store. Keychain services takes care of encrypting this data if the item is secret, namely when it’s one of the password types or involves a private key.

  • Optional attributes. Include attribute keys that help you find the item later, indicate how your app uses the data, and how the system shares the data. You can add any number of attributes, although many are specific to a particular class of item. For the attributes applicable to the keychain item you add, see the entry for the item’s class in Item Class Keys And Values.

  • Optional return types. Include return type keys to indicate what data, if any, you want returned upon successful completion. You often ignore the return data from a Secitemadd(_:_:) call, in which case you don’t need to include any return result key. See Item Return Result Keys for more information.

• result:

  On return, a reference to the newly added items. The exact type of the result is based on the values supplied in attributes, as discussed in Item Return Result Keys. Pass nil if you don’t need the result. Otherwise, your app becomes responsible for releasing the referenced object.

Mentioned in

• Adding a password to the keychain
• Sharing access to keychain items among a collection of apps
• Storing a Certificate in the Keychain
• Storing Keys in the Keychain
• Updating and deleting keychain items

Return Value

A result code. See Security Framework Result Codes.

Discussion

To add multiple items to a keychain at once use the kSecUseItemList key in the attributes dictionary with an array of dictionaries (each corresponding to one of the items) as its value. This is only supported for non-password items.

When you use Xcode to create an application, Xcode adds an application-identifier entitlement to the application bundle. Keychain Services uses this entitlement to grant the application access to its own keychain items. To share the new keychain item to among multiple apps, include the kSecAttrAccessGroup key in the attributes dictionary. The value of this key must be the name of a keychain access group to which all the programs that share this item belong.

Performance considerations

SecItemAdd blocks the calling thread, so it can cause your app’s UI to hang if called from the main thread. Instead, call SecItemAdd from a background dispatch queue or async function: