SecItemAdd函数

1 SecItemAdd函数

Adds one or more items to a keychain.
增加一个或者多个项目到KeyChain.

2 Declaration 声明

OSStatus SecItemAdd(CFDictionaryRef attributes, CFTypeRef  _Nullable *result);

3 Parameters 参数

3.1 attributes参数

A dictionary that describes the item to add. A typical attributes dictionary consists of:
一个描述要增加项目item的字典.一个经典的attributes字典由以下几部分构成:

• 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.
  不同类型的钥匙链项目会应用不同的属性和行为.为键kSecClass设置一个合适的值,来告诉钥匙链服务你要存储的数据是代表一个密码,还是证书,还是加密密钥,或者其他数据.参考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.
  键kSecValueData所对应的值为你需要保存的数据.钥匙链服务负责对该数据进行加密,如果该钥匙链项目的类型为密码或者私钥.

• Optional attributes可选属性.
  Include attribute keys that allow you to find the item later and that indicate how the data should be used or shared. You may add any number of attributes, although many are specific to a particular class of item. See Item Attribute Keys and Values for the complete list.
  包含了允许你之后访问的属性和声明该数据如何使用和共享的属性.你可添加任意数量的属性,尽管某些属性只对特定类别的项目有效.要了解完整列表,请参考Item Attribute Keys and Values钥匙链项目的属性的键与值

• Optional return types可选返回类型.
  Include one or more 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 no return value key is needed. See Item Return Result Keys for more information.
  包含了一个或者多个返回类型键来声明成功完成操作后,如果有返回值的话,需要返回什么值.通常我们会忽略SecItemAdd函数的返回值,在这种情况下,我们不需要指定返回类型键.要了解更新信息,请参考Item Return Result Keys钥匙链项目返回结果键

3.2 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.
返回成功后,新增加的钥匙链项目的引用.结果的类型基于attributes中提供的键.如果你不需要直接使用该项目,传入nil.否则,你需要在应用中负责释放引用的对象.

4 Return Value返回值

A result code. See Security Framework Result Codes.
一个结果代码.参考Security Framework Result Codes安全框架结果代码

5 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.
如果需要一次添加多个钥匙链项目,在attributes字典中使用kSecUseItemList键,并用一个字典数组作为值(每个字典代表一个钥匙链项目).这支持非密码的项目.

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. If you want the new keychain item to be shared among multiple applications, 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 of the programs that will share this item belong.
如果使用Xcode来创建应用,Xcode会在应用包中添加一个application-identifier entitlement应用标识说明.钥匙链服务使用该说明来保证应用访问它自己的钥匙链项目.如果你想让这个钥匙链项目在多个应用中共享,在attributes字典中加上kSecAttrAccessGroup键.该键的值,必须是一个钥匙链访问组,所有共享该项目的应用都属于该组.

6 See Also参考

6.1 Adding Keychain Items 添加钥匙链项目

6.1.1 Adding a Password to the Keychain添加一个密码到钥匙链.

Add network credentials to the keychain on behalf of the user.
为用户添加网络证书到钥匙链.

6.1.2 Item Class Keys And Values 钥匙链项目的类型的键与值

Specify the class of a keychain item.
指定钥匙链项目的类型.

6.1.3 Item Attribute Keys and Values 钥匙链项目的属性的键与值

Specify the attributes of keychain items.
指定钥匙链项目的属性.