SecItemCopyMatching, types and uniques

To address your question about types, I’m going to have to start with some background. There are two implementations of the SecItem API:

• the iOS implementation, which is also used for iCloud Keychain on OS X

• the OS X implementation, which is a compatibility shim that bridges over to the traditional keychain

Note Both are available in Darwin. Search the Security project for

SecItemUpdate_ios

and

SecItemUpdate_osx

to see how this works under the covers.

The iOS implementation is based on SQLite. If you’re familiar with SQLite you’ll know that it is, at its core, untyped, and thus the iOS implementation has to do its own type conversion. This is why that implementation is somewhat forgiving on the types front. However…

IMPORTANT I strongly recommend that you use the types specified in the header. Other types do work but that’s an accident of the implementation rather than a designed in feature. Moreover, as there are two implementations, it’s not always the case that these accidents line up.

I realise that this rule is broken by various bits of Apple sample code. I’d be more than happy if you filed a bug about any cases where you notice that.

With regards the uniqueness constraints of various keychain items, the only definitive doc I know of for this is my post on the old DevForums. I took a quick look at the current state of affairs for

kSecClassGenericPassword

and it has not change substantially since then. this is officially documented in the reference docs for errSecDuplicateItem.

Uniqueness is only relevant for calls that update the database (

SecItemAdd

and

SecItemUpdate

). The database enforces that each update maintain the uniqueness constraints. For example, if the database contains the following generic passwords:

svce        acct
----        ----
door        gumby
door        pokey

here’s what you should expect:

• add

  {"svce": "door", "acct": "gumby"}

  ?

  errSecDuplicateItem

• add

  {"svce": "door", "acct": "minga"}

  ?

  errSecSuccess

• add

  {"svce": "window", "acct": "gumby"}

  ?

  errSecSuccess

• update

  {"svce": "door", "acct": "gumby"}

  to

  {"svce": "door", "acct": "pokey"}

  ?

  errSecDuplicateItem

• update

  {"svce": "door", "acct": "gumby"}

  to

  {"svce": "door", "acct": "minga"}

  ?

  errSecSuccess

• update

  {"svce": "door", "acct": "gumby"}

  to

  {"svce": "window", "acct": "gumby"}

  ?

  errSecSuccess

In contrast, uniqueness criteria are irrelevant to database queries. Database queries a very simple:

• if you specify an attribute, you only get items where that attribute matches

• if you leave out an attribute, you get all items

The most common cause of problems with this design is a mismatch between your query and the uniqueness criteria. For example, assuming the same database shown above, consider this sequence:

1. copy

   {"svce": "door", "acct": "gumby", "gena": "foo"}

   ?

   errSecItemNotFound

2. add

   {"svce": "door", "acct": "gumby", "gena": "foo"}

   ?

   errSecDuplicateItem

Argh!

However, if you understand the uniqueness criteria the reason for this is obvious: the query fails because you’ve included the

kSecAttrGeneric

attribute and that doesn’t match what’s in the database, while the add fails because that combination of

kSecAttrAccount

and

kSecAttrService

already exists in the database.

So, to come back to your specific questions:

Question 1: Is for kSecClassGenericPassword the attributes kSecClass, kSecAttrService, kSecAttrGeneric enough? Or does it require kSecAttrAccount?

That depends. The

kSecAttrAccount

attribute is not required, in that if you don’t supply it when you create the item, you effectively get an empty value. However, that empty value can cause confusion later on, so…

IMPORTANT I strongly recommend that you include values for all of the attributes included in the uniqueness constraint. That makes things simpler later on. If you don’t have a meaningful value, use a fixed value that’s not going to collide with anything (like a reverse DNS name).

Question 2: How is the query behaviour for attributes that are not required to make the item unique. Right now the code searchs for kSecClass, kSecAttrService, kSecAttrGeneric and kSecAttrAccount. See here. But in the store we only have kSecClass, kSecAttrService, kSecAttrGeneric. Yet the search works most of the times.

I believe I’ve addressed this point via the discussion above.

Share and Enjoy
—
Quinn “The Eskimo!”
Apple Developer Relations, Developer Technical Support, Core OS/Hardware

let myEmail = "eskimo" + "1" + "@apple.com"

Hi Quinn,

Thank you for your detailed answer.

A bug for the wrong type on GenericKeychain is filled under 26167065.

My test code shows that setting the wrong type on kSecAttrAccount results in the iCloud Keychain on OS X ignoring this attribute. I assume in the background it will create empty value like you suggest.

Running some test code, on a customer system which is effected with the issue, showed that the kSecAttrGeneric attribute was missing in the keychain item. Which explains why SecItemCopyMatching returns errSecItemNotFound.

So the question now is, how got this attribute missing? I don't see any code in RMStore that could be responsible for this. One idea is if a migration from traditional keychain to iCloud Keychain could be responible. Or the otherway around.

Cheers,

Christopher

So the question now is, how got this attribute missing?

I don’t have any good theories on that one, alas.

Share and Enjoy
—
Quinn “The Eskimo!”
Apple Developer Relations, Developer Technical Support, Core OS/Hardware

let myEmail = "eskimo" + "1" + "@apple.com"