I regularly help developers with keychain problems, both here on DevForums and for my Day Job™ in DTS. Over the years I’ve learnt a lot about the API, including many pitfalls and best practices. This post is my attempt to collect that experience in one place. If you have questions or comments about any of this, put them in a new thread and apply the Security tag so that I see it. Share and Enjoy — Quinn “The Eskimo!” @ Developer Technical Support @ Apple let myEmail = "eskimo" + "1" + "@" + "apple.com" SecItem: Pitfalls and Best Practices It’s just four functions, how hard can it be? The SecItem API seems very simple. After all, it only has four function calls, how hard can it be? In reality, things are not that easy. Various factors contribute to making this API much trickier than it might seem at first glance. This post explains some of the keychain’s pitfalls and then goes on to explain various best practices. Before reading this, make sure you understand the fundamentals by reading its companion post, SecItem: Fundamentals. Pitfalls Lets start with some common pitfalls. Queries and Uniqueness Constraints The relationship between query dictionaries and uniqueness constraints is a major source of problems with the keychain API. Consider code like this: var copyResult: CFTypeRef? = nil let query = [ kSecClass: kSecClassGenericPassword, kSecAttrService: "AYS", kSecAttrAccount: "mrgumby", kSecAttrGeneric: Data("SecItemHints".utf8), ] as NSMutableDictionary let err = SecItemCopyMatching(query, &copyResult) if err == errSecItemNotFound { query[kSecValueData] = Data("opendoor".utf8) let err2 = SecItemAdd(query, nil) if err2 == errSecDuplicateItem { fatalError("… can you get here? …") } } Can you get to the fatal error? At first glance this might not seem possible because you’ve run your query and it’s returned errSecItemNotFound. However, the fatal error is possible because the query contains an attribute, kSecAttrGeneric, that does not contribute to the uniqueness. If the keychain contains a generic password whose service (kSecAttrService) and account (kSecAttrAccount) attributes match those supplied but whose generic (kSecAttrGeneric) attribute does not, the SecItemCopyMatching calls will return errSecItemNotFound. However, for a generic password item, of the attributes shown here, only the service and account attributes are included in the uniqueness constraint. If you try to add an item where those attributes match an existing item, the add will fail with errSecDuplicateItem even though the value of the generic attribute is different. The take-home point is that that you should study the attributes that contribute to uniqueness and use them in a way that’s aligned with your view of uniqueness. See the Uniqueness section of SecItem: Fundamentals for a link to the relevant documentation. Erroneous Attributes Each keychain item class supports its own specific set of attributes. For information about the attributes supported by a given class, see SecItem: Fundamentals. I regularly see folks use attributes that aren’t supported by the class they’re working with. For example, the kSecAttrApplicationTag attribute is only supported for key items (kSecClassKey). Using it with a certificate item (kSecClassCertificate) will cause, at best, a runtime error and, at worst, mysterious bugs. This is an easy mistake to make because: The ‘parameter block’ nature of the SecItem API means that the compiler won’t complain if you use an erroneous attribute. On macOS, the shim that connects to the file-based keychain ignores unsupported attributes. Imagine you want to store a certificate for a particular user. You might write code like this: let err = SecItemAdd([ kSecClass: kSecClassCertificate, kSecAttrApplicationTag: Data(name.utf8), kSecValueRef: cert, ] as NSDictionary, nil) The goal is to store the user’s name in the kSecAttrApplicationTag attribute so that you can get back their certificate with code like this: let err = SecItemCopyMatching([ kSecClass: kSecClassCertificate, kSecAttrApplicationTag: Data(name.utf8), kSecReturnRef: true, ] as NSDictionary, &copyResult) On iOS, and with the data protection keychain on macOS, both calls will fail with errSecNoSuchAttr. That makes sense, because the kSecAttrApplicationTag attribute is not supported for certificate items. Unfortunately, the macOS shim that connects the SecItem API to the file-based keychain ignores extraneous attributes. This results in some very bad behaviour: SecItemAdd works, ignoring kSecAttrApplicationTag. SecItemCopyMatching ignores kSecAttrApplicationTag, returning the first certificate that it finds. If you only test with a single user, everything seems to work. But, later on, when you try your code with multiple users, you might get back the wrong result depending on the which certificate the SecItemCopyMatching call happens to discover first. Ouch! Context Matters Some properties change behaviour based on the context. The value type properties are the biggest offender here, as discussed in the Value Type Subtleties section of SecItem: Fundamentals. However, there are others. The one that’s bitten me is kSecMatchLimit: In a query and return dictionary its default value is kSecMatchLimitOne. If you don’t supply a value for kSecMatchLimit, SecItemCopyMatching returns at most one item that matches your query. In a pure query dictionary its default value is kSecMatchLimitAll. For example, if you don’t supply a value for kSecMatchLimit, SecItemDelete will delete all items that match your query. This is a lesson that, once learnt, is never forgotten! Note Although this only applies to the data protection keychain. If you’re on macOS and targeting the file-based keychain, kSecMatchLimit always defaults to kSecMatchLimitOne (r. 105800863). Fun times! Digital Identities Aren’t Real A digital identity is the combination of a certificate and the private key that matches the public key within that certificate. The SecItem API has a digital identity keychain item class, namely kSecClassIdentity. However, the keychain does not store digital identities. When you add a digital identity to the keychain, the system stores its components, the certificate and the private key, separately, using kSecClassCertificate and kSecClassKey respectively. This has a number of non-obvious effects: Adding a certificate can ‘add’ a digital identity. If the new certificate happens to match a private key that’s already in the keychain, the keychain treats that pair as a digital identity. Likewise when you add a private key. Similarly, removing a certificate or private key can ‘remove’ a digital identity. Adding a digital identity will either add a private key, or a certificate, or both, depending on what’s already in the keychain. Removing a digital identity removes its certificate. It might also remove the private key, depending on whether that private key is used by a different digital identity. The system forms a digital identity by matching the kSecAttrApplicationLabel (klbl) attribute of the private key with the kSecAttrPublicKeyHash (pkhh) attribute of the certificate. If you add both items to the keychain and the system doesn’t form an identity, check the value of these attributes. For more information the key attributes, see SecItem attributes for keys. Keys Aren’t Stored in the Secure Enclave Apple platforms let you protect a key with the Secure Enclave (SE). The key is then hardware bound. It can only be used by that specific SE [1]. Earlier versions of the Protecting keys with the Secure Enclave article implied that SE-protected keys were stored in the SE itself. This is not true, and it’s caused a lot of confusion. For example, I once asked the keychain team “How much space does the SE have available to store keys?”, a question that’s complete nonsense once you understand how this works. In reality, SE-protected keys are stored in the standard keychain database alongside all your other keychain items. The difference is that the key is wrapped in such a way that only the SE can use it. So, the key is protected by the SE, not stored in the SE. A while back we updated the docs to clarify this point but the confusion persists. [1] Technically it’s that specific iteration of that specific SE. If you erase the device then the key material needed to use the key is erased and so the key becomes permanently useless. This is the sort of thing you’ll find explained in Apple Platform Security. Careful With that Shim, Mac Developer As explained in TN3137 On Mac keychain APIs and implementations, macOS has a shim that connects the SecItem API to either the data protection keychain or the file-based keychain depending on the nature of the request. That shim has limitations. Some of those are architectural but others are simply bugs in the shim. For some great examples, see the Investigating Complex Attributes section below. The best way to avoid problems like this is to target the data protection keychain. If you can’t do that, try to avoid exploring the outer reaches of the SecItem API. If you encounter a case that doesn’t make sense, try that same case with the data protection keychain. If it works there but fails with the file-based keychain, please do file a bug against the shim. It’ll be in good company. Here’s some known issues with the shim: It ignores unsupported attributes. See Erroneous Attributes, above, for more background on that. The shim can fan out to both the data protection and the file-based keychain. In that case it has to make a policy decision about how to handle errors. This results in some unexpected behaviour (r. 143405965). For example, if you call SecItemCopyMatching while the keychain is locked, the data protection keychain will fail with errSecInteractionNotAllowed (-25308). OTOH, it’s possible to query for the presence of items in the file-based keychain even when it’s locked. If you do that and there’s no matching item, the file-based keychain fails with errSecItemNotFound (-25300). When the shim gets these conflicting errors, it chooses to return the latter. Whether this is right or wrong depends on your perspective, but it’s certainly confusing, especially if you’re coming at this from the iOS side. If you call SecItemDelete without specifying a match limit (kSecMatchLimit), the data protection keychain deletes all matching items, whereas the file-based keychain just deletes a single match (r. 105800863). While these issue have all have bug numbers, there’s no guarantee that any of them will be fixed. Fixing bugs like this is tricky because of binary compatibility concerns. Add-only Attributes Some attributes can only be set when you add an item. These attributes are usually associated with the scope of the item. For example, to protect an item with the Secure Enclave, supply the kSecAttrAccessControl attribute to the SecItemAdd call. Once you do that, however, you can’t change the attribute. Calling SecItemUpdate with a new kSecAttrAccessControl won’t work. Lost Keychain Items A common complaint from developers is that a seemingly minor update to their app has caused it to lose all of its keychain items. Usually this is caused by one of two problems: Entitlement changes Query dictionary confusion Access to keychain items is mediated by various entitlements, as described in Sharing access to keychain items among a collection of apps. If the two versions of your app have different entitlements, one version may not be able to ‘see’ items created by the other. Imagine you have an app with an App ID of SKMME9E2Y8.com.example.waffle-varnisher. Version 1 of your app is signed with the keychain-access-groups entitlement set to [ SKMME9E2Y8.groupA, SKMME9E2Y8.groupB ]. That makes its keychain access group list [ SKMME9E2Y8.groupA, SKMME9E2Y8.groupB, SKMME9E2Y8.com.example.waffle-varnisher ]. If this app creates a new keychain item without specifying kSecAttrAccessGroup, the system places the item into SKMME9E2Y8.groupA. If version 2 of your app removes SKMME9E2Y8.groupA from the keychain-access-groups, it’ll no longer be able to see the keychain items created by version 1. You’ll also see this problem if you change your App ID prefix, as described in App ID Prefix Change and Keychain Access. IMPORTANT When checking for this problem, don’t rely on your .entitlements file. There are many steps between it and your app’s actual entitlements. Rather, run codesign to dump the entitlements of your built app: % codesign -d --entitlements - /path/to/your.app Lost Keychain Items, Redux Another common cause of lost keychain items is confusion about query dictionaries, something discussed in detail in this post and SecItem: Fundamentals. If SecItemCopyMatching isn’t returning the expected item, add some test code to get all the items and their attributes. For example, to dump all the generic password items, run code like this: func dumpGenericPasswords() throws { let itemDicts = try secCall { SecItemCopyMatching([ kSecClass: kSecClassGenericPassword, kSecMatchLimit: kSecMatchLimitAll, kSecReturnAttributes: true, ] as NSDictionary, $0) } as! [[String: Any]] print(itemDicts) } Then compare each item’s attributes against the attributes you’re looking for to see why there was no match. Data Protection and Background Execution Keychain items are subject to data protection. Specifically, an item may or may not be accessible depending on whether specific key material is available. For an in-depth discussion of how this works, see Apple Platform Security. Note This section focuses on iOS but you’ll see similar effects on all Apple platforms. On macOS specifically, the contents of this section only apply to the data protection keychain. The keychain supports three data protection levels: kSecAttrAccessibleWhenUnlocked kSecAttrAccessibleAfterFirstUnlock kSecAttrAccessibleAlways Note There are additional data protection levels, all with the ThisDeviceOnly suffix. Understanding those is not necessary to understanding this pitfall. Each data protection level describes the lifetime of the key material needed to work with items protected in that way. Specifically: The key material needed to work with a kSecAttrAccessibleWhenUnlocked item comes and goes as the user locks and unlocks their device. The key material needed to work with a kSecAttrAccessibleAfterFirstUnlock item becomes available when the device is first unlocked and remains available until the device restarts. The default data protection level is kSecAttrAccessibleWhenUnlocked. If you add an item to the keychain and don’t specify a data protection level, this is what you get [1]. To specify a data protection level when you add an item to the keychain, apply the kSecAttrAccessible attribute. Alternatively, embed the access level within a SecAccessControl object and apply that using the kSecAttrAccessControl attribute. IMPORTANT It’s best practice to set these attributes when you add the item and then never update them. See Add-only Attributes, above, for more on that. If you perform an operation whose data protection is incompatible with the currently available key material, that operation fails with errSecInteractionNotAllowed [2]. There are four fundamental keychain operations, discussed in the SecItem: Fundamentals, and each interacts with data protection in a different way: Copy — If you attempt to access a keychain item whose key material is unavailable, SecItemCopyMatching fails with errSecInteractionNotAllowed. This is an obvious result; the whole point of data protection is to enforce this security policy. Add — If you attempt to add a keychain item whose key material is unavailable, SecItemAdd fails with errSecInteractionNotAllowed. This is less obvious. The reason why this fails is that the system needs the key material to protect (by encryption) the keychain item, and it can’t do that if if that key material isn’t available. Update — If you attempt to update a keychain item whose key material is unavailable, SecItemUpdate fails with errSecInteractionNotAllowed. This result is an obvious consequence of the previous result. Delete — Deleting a keychain item, using SecItemDelete, doesn’t require its key material, and thus a delete will succeed when the item is otherwise unavailable. That last point is a significant pitfall. I regularly see keychain code like this: Read an item holding a critical user credential. If that works, use that credential. If it fails, delete the item and start from a ‘factory reset’ state. The problem is that, if your code ends up running in the background unexpectedly, step 1 fails with errSecInteractionNotAllowed and you turn around and delete the user’s credential. Ouch! Note Even if you didn’t write this code, you might have inherited it from a keychain wrapper library. See *Think Before Wrapping, below. There are two paths forward here: If you don’t expect this code to work in the background, check for the errSecInteractionNotAllowed error and non-destructively cancel the operation in that case. If you expect this code to be running in the background, switch to a different data protection level. WARNING For the second path, the most obvious fix is to move from kSecAttrAccessibleWhenUnlocked to kSecAttrAccessibleAfterFirstUnlock. However, this is not a panacea. It’s possible that your app might end up running before first unlock [3]. So, if you choose the second path, you must also make sure to follow the advice for the first path. You can determine whether the device is unlocked using the isProtectedDataAvailable property and its associated notifications. However, it’s best not to use this property as part of your core code, because such preflighting is fundamentally racy. Rather, perform the operation and handle the error gracefully. It might make sense to use isProtectedDataAvailable property as part of debugging, logging, and diagnostic code. [1] For file data protection there’s an entitlement (com.apple.developer.default-data-protection) that controls the default data protection level. There’s no such entitlement for the keychain. That’s actually a good thing! In my experience the file data protection entitlement is an ongoing source of grief. See this thread if you’re curious. [2] This might seem like an odd error but it’s actually pretty reasonable: The operation needs some key material that’s currently unavailable. Only a user action can provide that key material. But the data protection keychain will never prompt the user to unlock their device. Thus you get an error instead. [3] iOS generally avoids running third-party code before first unlock, but there are circumstances where that can happen. The obvious legitimate example of this is a VoIP app, where the user expects their phone to ring even if they haven’t unlocked it since the last restart. There are also other less legitimate examples of this, including historical bugs that caused apps to launch in the background before first unlock. Best Practices With the pitfalls out of the way, let’s talk about best practices. Less Painful Dictionaries I look at a lot of keychain code and it’s amazing how much of it is way more painful than it needs to be. The biggest offender here is the dictionaries. Here are two tips to minimise the pain. First, don’t use CFDictionary. It’s seriously ugly. While the SecItem API is defined in terms of CFDictionary, you don’t have to work with CFDictionary directly. Rather, use NSDictionary and take advantage of the toll-free bridge. For example, consider this CFDictionary code: CFTypeRef keys[4] = { kSecClass, kSecAttrService, kSecMatchLimit, kSecReturnAttributes, }; static const int kTen = 10; CFNumberRef ten = CFNumberCreate(NULL, kCFNumberIntType, &kTen); CFAutorelease(ten); CFTypeRef values[4] = { kSecClassGenericPassword, CFSTR("AYS"), ten, kCFBooleanTrue, }; CFDictionaryRef query = CFDictionaryCreate( NULL, keys, values, 4, &kCFTypeDictionaryKeyCallBacks, &kCFTypeDictionaryValueCallBacks ); Note This might seem rather extreme but I’ve literally seen code like this, and worse, while helping developers. Contrast this to the equivalent NSDictionary code: NSDictionary * query = @{ (__bridge NSString *) kSecClass: (__bridge NSString *) kSecClassGenericPassword, (__bridge NSString *) kSecAttrService: @"AYS", (__bridge NSString *) kSecMatchLimit: @10, (__bridge NSString *) kSecReturnAttributes: @YES, }; Wow, that’s so much better. Second, if you’re working in Swift, take advantage of its awesome ability to create NSDictionary values from Swift dictionary literals. Here’s the equivalent code in Swift: let query = [ kSecClass: kSecClassGenericPassword, kSecAttrService: "AYS", kSecMatchLimit: 10, kSecReturnAttributes: true, ] as NSDictionary Nice! Avoid Reusing Dictionaries I regularly see folks reuse dictionaries for different SecItem calls. For example, they might have code like this: var copyResult: CFTypeRef? = nil let dict = [ kSecClass: kSecClassGenericPassword, kSecAttrService: "AYS", kSecAttrAccount: "mrgumby", kSecReturnData: true, ] as NSMutableDictionary var err = SecItemCopyMatching(dict, &copyResult) if err == errSecItemNotFound { dict[kSecValueData] = Data("opendoor".utf8) err = SecItemAdd(dict, nil) } This specific example will work, but it’s easy to spot the logic error. kSecReturnData is a return type property and it makes no sense to pass it to a SecItemAdd call whose second parameter is nil. I’m not sure why folks do this. I think it’s because they think that constructing dictionaries is expensive. Regardless, this pattern can lead to all sorts of weird problems. For example, it’s the leading cause of the issue described in the Queries and the Uniqueness Constraints section, above. My advice is that you use a new dictionary for each call. That prevents state from one call accidentally leaking into a subsequent call. For example, I’d rewrite the above as: var copyResult: CFTypeRef? = nil let query = [ kSecClass: kSecClassGenericPassword, kSecAttrService: "AYS", kSecAttrAccount: "mrgumby", kSecReturnData: true, ] as NSMutableDictionary var err = SecItemCopyMatching(query, &copyResult) if err == errSecItemNotFound { let add = [ kSecClass: kSecClassGenericPassword, kSecAttrService: "AYS", kSecAttrAccount: "mrgumby", kSecValueData: Data("opendoor".utf8), ] as NSMutableDictionary err = SecItemAdd(add, nil) } It’s a bit longer, but it’s much easier to track the flow. And if you want to eliminate the repetition, use a helper function: func makeDict() -> NSMutableDictionary { [ kSecClass: kSecClassGenericPassword, kSecAttrService: "AYS", kSecAttrAccount: "mrgumby", ] as NSMutableDictionary } var copyResult: CFTypeRef? = nil let query = makeDict() query[kSecReturnData] = true var err = SecItemCopyMatching(query, &copyResult) if err == errSecItemNotFound { let add = makeDict() query[kSecValueData] = Data("opendoor".utf8) err = SecItemAdd(add, nil) } Think Before Wrapping A lot of folks look at the SecItem API and immediately reach for a wrapper library. A keychain wrapper library might seem like a good idea but there are some serious downsides: It adds another dependency to your project. Different subsystems within your project may use different wrappers. The wrapper can obscure the underlying API. Indeed, its entire raison d’être is to obscure the underlying API. This is problematic if things go wrong. I regularly talk to folks with hard-to-debug keychain problems and the conversation goes something like this: Quinn: What attributes do you use in the query dictionary? J R Developer: What’s a query dictionary? Quinn: OK, so what error are you getting back? J R Developer: It throws WrapperKeychainFailedError. That’s not helpful )-: If you do use a wrapper, make sure it has diagnostic support that includes the values passed to and from the SecItem API. Also make sure that, when it fails, it returns an error that includes the underlying keychain error code. These benefits will be particularly useful if you encounter a keychain problem that only shows up in the field. Wrappers must choose whether to be general or specific. A general wrapper may be harder to understand than the equivalent SecItem calls, and it’ll certainly contain a lot of complex code. On the other hand, a specific wrapper may have a model of the keychain that doesn’t align with your requirements. I recommend that you think twice before using a keychain wrapper. Personally I find the SecItem API relatively easy to call, assuming that: I use the techniques shown in Less Painful Dictionaries, above, to avoid having to deal with CFDictionary. I use my secCall(…) helpers to simplify error handling. For the code, see Calling Security Framework from Swift. If you’re not prepared to take the SecItem API neat, consider writing your own wrapper, one that’s tightly focused on the requirements of your project. For example, in my VPN apps I use the wrapper from this post, which does exactly what I need in about 100 lines of code. Prefer to Update Of the four SecItem functions, SecItemUpdate is the most neglected. Rather than calling SecItemUpdate I regularly see folks delete and then re-add the item. This is a shame because SecItemUpdate has some important benefits: It preserves persistent references. If you delete and then re-add the item, you get a new item with a new persistent reference. It’s well aligned with the fundamental database nature of the keychain. It forces you to think about which attributes uniquely identify your item and which items can be updated without changing the item’s identity. Understand These Key Attributes Key items have a number of attributes that are similarly named, and it’s important to keep them straight. I created a cheat sheet for this, namely, SecItem attributes for keys. You wouldn’t believe how often I consult this! Investigating Complex Attributes Some attributes have values where the format is not obvious. For example, the kSecAttrIssuer attributed is documented as: The corresponding value is of type CFData and contains the X.500 issuer name of a certificate. What exactly does that mean? If I want to search the keychain for all certificates issued by a specific certificate authority, what value should I supply? One way to figure this out is to add a certificate to the keychain, read the attributes back, and then dump the kSecAttrIssuer value. For example: let cert: SecCertificate = … let attrs = try secCall { SecItemAdd([ kSecValueRef: cert, kSecReturnAttributes: true, ] as NSDictionary, $0) } as! [String: Any] let issuer = attrs[kSecAttrIssuer as String] as! NSData print((issuer as NSData).debugDescription) // prints: <3110300e 06035504 030c074d 6f757365 4341310b 30090603 55040613 024742> Those bytes represent the contents of a X.509 Name ASN.1 structure with DER encoding. This is without the outer SEQUENCE element, so if you dump it as ASN.1 you’ll get a nice dump of the first SET and then a warning about extra stuff at the end of the file: % xxd issuer.asn1 00000000: 3110 300e 0603 5504 030c 074d 6f75 7365 1.0...U....Mouse 00000010: 4341 310b 3009 0603 5504 0613 0247 42 CA1.0...U....GB % dumpasn1 -p issuer.asn1 SET { SEQUENCE { OBJECT IDENTIFIER commonName (2 5 4 3) UTF8String 'MouseCA' } } Warning: Further data follows ASN.1 data at position 18. Note For details on the Name structure, see section 4.1.2.4 of RFC 5280. Amusingly, if you run the same test against the file-based keychain you’ll… crash. OK, that’s not amusing. It turns out that the code above doesn’t work when targeting the file-based keychain because SecItemAdd doesn’t return a dictionary but rather an array of dictionaries (r. 21111543). Once you get past that, however, you’ll see it print: <301f3110 300e0603 5504030c 074d6f75 73654341 310b3009 06035504 06130247 42> Which is different! Dumping it as ASN.1 shows that it’s the full Name structure, including the outer SEQUENCE element: % xxd issuer-file-based.asn1 00000000: 301f 3110 300e 0603 5504 030c 074d 6f75 0.1.0...U....Mou 00000010: 7365 4341 310b 3009 0603 5504 0613 0247 seCA1.0...U....G 00000020: 42 B % dumpasn1 -p issuer-file-based.asn1 SEQUENCE { SET { SEQUENCE { OBJECT IDENTIFIER commonName (2 5 4 3) UTF8String 'MouseCA' } } SET { SEQUENCE { OBJECT IDENTIFIER countryName (2 5 4 6) PrintableString 'GB' } } } This difference in behaviour between the data protection and file-based keychains is a known bug (r. 26391756) but in this case it’s handy because the file-based keychain behaviour makes it easier to understand the data protection keychain behaviour. Import, Then Add It’s possible to import data directly into the keychain. For example, you might use this code to add a certificate: let certData: Data = … try secCall { SecItemAdd([ kSecClass: kSecClassCertificate, kSecValueData: certData, ] as NSDictionary, nil) } However, it’s better to import the data and then add the resulting credential reference. For example: let certData: Data = … let cert = try secCall { SecCertificateCreateWithData(nil, certData as NSData) } try secCall { SecItemAdd([ kSecValueRef: cert, ] as NSDictionary, nil) } There are two advantages to this: If you get an error, you know whether the problem was with the import step or the add step. It ensures that the resulting keychain item has the correct attributes. This is especially important for keys. These can be packaged in a wide range of formats, so it’s vital to know whether you’re interpreting the key data correctly. I see a lot of code that adds key data directly to the keychain. That’s understandable because, back in the day, this was the only way to import a key on iOS. Fortunately, that’s not been the case since the introduction of SecKeyCreateWithData in iOS 10 and aligned releases. For more information about importing keys, see Importing Cryptographic Keys. App Groups on the Mac Sharing access to keychain items among a collection of apps explains that three entitlements determine your keychain access: keychain-access-groups application-identifier (com.apple.application-identifier on macOS) com.apple.security.application-groups In the discussion of com.apple.security.application-groups it says: Starting in iOS 8, the array of strings given by this entitlement also extends the list of keychain access groups. That’s true, but it’s also potentially misleading. This affordance only works on iOS and its child platforms. It doesn’t work on macOS. That’s because app groups work very differently on macOS than they do on iOS. For all the details, see App Groups: macOS vs iOS: Working Towards Harmony. However, the take-home point is that, when you use the data protection keychain on macOS, your keychain access group list is built from keychain-access-groups and com.apple.application-identifier. Revision History 2025-06-29 Added the Data Protection and Background Execution section. Made other minor editorial changes. 2025-02-03 Added another specific example to the Careful With that Shim, Mac Developer section. 2025-01-29 Added somes specific examples to the Careful With that Shim, Mac Developer section. 2025-01-23 Added the Import, Then Add section. 2024-08-29 Added a discussion of identity formation to the Digital Identities Aren’t Real section. 2024-04-11 Added the App Groups on the Mac section. 2023-10-25 Added the Lost Keychain Items and Lost Keychain Items, Redux sections. 2023-09-22 Made minor editorial changes. 2023-09-12 Fixed various bugs in the revision history. Added the Erroneous Attributes section. 2023-02-22 Fixed the link to the VPNKeychain post. Corrected the name of the Context Matters section. Added the Investigating Complex Attributes section. 2023-01-28 First posted.

Can someone please guide me on the entire process of integrating ads in an IOS application using google's admob sdk? Not related to code but things related to Apple's privacy policy. Which options do need to select or specify in my app profile's privacy policy (identifier) section?

When developing and testing using my phone I got prompted for allowing app tracking. I later uploaded a build to TestFlight, deleted the old testing app and installed the TestFlight build. I am now stuck in an infinite loop of not getting prompted for allowing app tracking for the app. When entering the app settings the toggle for tracking never appears which leaves me not able to enter the app's content. My guess is that the prompt can only be shown once for the app bundle, but there has to be a way for me to get prompted again without changing the app bundle id. Help is appreciated since this app is scheduled to be published in a week.

Hi Apple Developer Team, I am encountering an issue with the “Sign in with Apple” feature. While implementing this functionality in my dotnet application, I noticed that the user’s first name and last name are not being returned, even though I have explicitly requested the name scope. However, the email and other requested information are returned successfully. Here are the details of my implementation: 1. Scope Requested: name, email 2. Response Received: Email and other data are present, but fullName is missing or null. 3. Expected Behavior: I expected to receive the user’s first and last name as per the fullName scope. I have verified the implementation and ensured that the correct scopes are being passed in the request. Could you please help clarify the following? 1. Are there specific conditions under which Apple may not return the user’s fullName despite the scope being requested? 2. Is there a recommended approach or fallback mechanism to handle this scenario? 3. Could this behavior be related to a limitation or change in the API, or might it be an issue on my end? I also came to know that for initial sign in the user details will be displayed in the signin-apple payload as Form data but how do I fetch those form-data from the signin-apple request, please suggest I would greatly appreciate any guidance or solutions to resolve this issue. Thank you for your support!

I keep getting the following error when trying to run Passkey sign in on macOS. Told not to present authorization sheet: Error Domain=com.apple.AuthenticationServicesCore.AuthorizationError Code=1 "(null)" ASAuthorizationController credential request failed with error: Error Domain=com.apple.AuthenticationServices.AuthorizationError Code=1004 "(null)" This is the specific error. Application with identifier a is not associated with domain b I have config the apple-app-site-association link and use ?mode=developer Could there be any reason for this?

I'm experiencing a strange issue where ASWebAuthenticationSession works perfectly when running from Xcode (both Debug and Release), but fails on TestFlight builds. The setup: iOS app using ASWebAuthenticationSession for OIDC login (Keycloak) Custom URL scheme callback (myapp://) prefersEphemeralWebBrowserSession = false The issue: When using iOS Keychain autofill (with Face ID/Touch ID or normal iphone pw, that auto-submits the form) -> works perfectly When manually typing credentials and clicking the login button -> fails with white screen When it fails, the form POST from Keycloak back to my server (/signin-oidc) never reaches the server at all. The authentication session just shows a white screen. Reproduced on: Multiple devices (iPhone 15 Pro, etc.) iOS 18.x Xcode 16.x Multiple TestFlight testers confirmed same behavior What I've tried: Clearing Safari cookies/data prefersEphemeralWebBrowserSession = true and false Different SameSite cookie policies on server Verified custom URL scheme is registered and works (testing myapp://test in Safari opens the app) Why custom URL scheme instead of Universal Links: We couldn't get Universal Links to trigger from a js redirect (window.location.href) within ASWebAuthenticationSession. Only custom URL schemes seemed to be intercepted. If there's a way to make Universal Links work in this context, without a manual user-interaction we'd be happy to try. iOS Keychain autofill works The only working path is iOS Keychain autofill that requires iphone-authentication and auto-submits the form. Any manual form submission fails, but only on TestFlight - not Xcode builds. Has anyone encountered this or know a workaround?

Hello I'm using Auth0 for handling auth in my app When the user wants to sign in, it will show the auth system pop-up And when the user wants to log out it shows the same pop-up My issue is how to replace the Sign In text in this pop-up to show Sign Out instead of Sign In when the user wants to sign out?

Hello, I'm receiving an unknown error instead of the excluded credentials error when using the "Save on another device" option for Passkey creation. When creating the ASAuthorizationPlatformPublicKeyCredentialProvider request to pass to the ASAuthorizationController. The excludedCredentials property is used to add a list of credentials to exclude in the registration process. This is to prevent duplicate passkeys from being created if one already exists for the user. When trying to create a duplicate passkey using the same device, the ASAuthorizationControllerDelegate method authorizationController(controller, didCompleteWithError:) is called. The error received has localized description “At least one credential matches an entry of the excludeCredentials list in the platform attached authenticator." When trying to create a duplicate passkey using the “Save on another device” option. The delegate method is called, but the error received has code 1000 ("com.apple.AuthenticationServices.AuthorizationError" - code: 1000). Which maps to the unknown error case in ASAuthorization error type.

We're experiencing crashes in our production iOS app related to Apple's DeviceCheck framework. The crash occurs in DCAnalytics internal performance tracking, affecting some specific versions of iOS 18 (18.4.1, 18.5.0). Crash Signature CoreFoundation: -[__NSDictionaryM setObject:forKeyedSubscript:] + 460 DeviceCheck: -[DCAnalytics sendPerformanceForCategory:eventType:] + 236 Observed Patterns Scenario 1 - Token Generation: Crashed: com.appQueue EXC_BAD_ACCESS KERN_INVALID_ADDRESS 0x0000000000000010 DeviceCheck: -[DCDevice generateTokenWithCompletionHandler:] Thread: Background dispatch queue Scenario 2 - Support Check: Crashed: com.apple.main-thread EXC_BAD_ACCESS KERN_INVALID_ADDRESS 0x0000000000000008 DeviceCheck: -[DCDevice _isSupportedReturningError:] DeviceCheck: -[DCDevice isSupported] Thread: Main thread Root Cause Analysis The DCAnalytics component within DeviceCheck attempts to insert a nil value into an NSMutableDictionary when recording performance metrics, indicating missing nil validation before dictionary operations. Reproduction Context Crashes occur during standard DeviceCheck API usage: Calling DCDevice.isSupported property Calling DCDevice.generateToken(completionHandler:) (triggered by Firebase App Check SDK) Both operations invoke internal analytics that fail with nil insertion attempts. Concurrency Considerations We've implemented sequential access guards around DeviceCheck token generation to prevent race conditions, yet crashes persist. This suggests the issue likely originates within the DeviceCheck framework's internal implementation rather than concurrent access from our application code. Note: Scenario 2 occurs through Firebase SDK's App Check integration, which internally uses DeviceCheck for attestation. Request Can Apple engineering confirm if this is a known issue with DeviceCheck's analytics subsystem? Is there a recommended workaround to disable DCAnalytics or ensure thread-safe DeviceCheck API usage? Any guidance on preventing these crashes would be appreciated.

Hi Apple Devs, For our app, we utilize passkeys for account creation (not MFA). This is mainly for user privacy, as there is 0 PII associated with passkey account creation, but it additionally also satisfies the 4.8: Login Services requirement for the App Store. However, we're getting blocked in Apple Review. Because the AASA does not get fetched immediately upon app install, the reviewers are not able to create an account immediately via passkeys, and then they reject the build. I'm optimistic I can mitigate the above. But even if we pass Apple Review, this is a pretty catastrophic issue for user security and experience. There are reports that 5% of users cannot create passkeys immediately (https://developer.apple.com/forums/thread/756740). That is a nontrivial amount of users, and this large of an amount distorts how app developers design onboarding and authentication flows towards less secure experiences: App developers are incentivized to not require MFA setup on account creation because requiring it causes significant churn, which is bad for user security. If they continue with it anyways, for mitigation, developers are essentially forced to add in copy into their app saying something along the lines of "We have no ability to force Apple to fetch the config required to continue sign up, so try again in a few minutes, you'll just have to wait." You can't even implement a fallback method. There's no way to check if the AASA is available before launching the ASAuthorizationController so you can't mitigate a portion of users encountering an error!! Any app that wants to use the PRF extension to encrypt core functionality (again, good for user privacy) simply cannot exist because the app simply does not work for an unspecified amount of time for a nontrivial portion of users. It feels like a. Apple should provide a syscall API that we can call to force SWCD to verify the AASA or b. implement a config based on package name for the app store such that the installation will immediately include a verified AASA from Apple's CDN. Flicking the config on would require talking with Apple. If this existed, this entire class of error would go away. It feels pretty shocking that there isn't a mitigation in place for this already given that it incentivizes app developers to pursue strictly less secure and less private authentication practices.

Hi, I am developing a Platform SSO in order to have integrated with our IdP, which I am also adapting to provide the right endpoints for Platform SSO. I have a few questions about the implementation: does the client-request-id need to be present on all requests? Is it unique per request, or requests that are bound together like those requesting a nonce and those who will use that nonce should use the same client-request-id? I am not sure how the loginManager.presentRegistrationViewController works. I'd like to get the user to authenticate to my IdP before device registration. So I am not sure if I should provide my own Webview or something similar or if this method should do something for me; My idea is to request user authentication once, save the state when performing device registration, so that I avoid asking for user authentication twice when performing user registration. Is this the right way to do it? How does platform SSO handles tokens? If one application of my IdP requests the authentication on a common OIDC/OAuth2 flow, should I perform some sort of token exchange? How about SAML? Platform SSO seems to be token-centric, but how does one handle SAML flows? Is it by using WebView as well?

Context We are experiencing inconsistent behaviour with "Sign in with Apple" across different environments (we have an app for "A" and "B" regions) on our web client in browsers. Specifically, we have observed two key issues: Missing email and email_verified Claims in ID Token In some cases, the ID token received after successful authentication does not contain the email and email_verified claims. Here the docs state that "Alternatively, if the managed Apple ID is in Apple School Manager, the email claim may be empty. Students, for example, often don’t have an email that the school issues.", but this was experienced with a non-student Apple ID. This issue was observed for certain users in the "A" environment, while the same users had no issues in the "B" environment. For one affected user, removing and re-enabling the "Sign in with Apple" integration resolved the issue (https://account.apple.com/account/manage/section/security). However, for another user, the integration could not be removed, preventing this workaround (button was active, but did nothing). In contrast, for some users, authentication works correctly in both environments without missing claims. Inconsistent Display of App Icon and App Name The app icon and app name do not always appear on the Apple login interface. One user observed that the app icon and name were displayed in "A" but not in "B". Another user had the opposite experience, with the app icon and name appearing in "B" but not in "A". A third user did not see the app icon or name in either environment. Questions Why does the app icon and name not always appear on the "Sign in with Apple" login screen? How is it possible that the ID token sometimes lacks email and email_verified claims when using the same Apple ID in different environments?

Without developer mode, I was able to get Password AutoFill to work in my SwiftUI app with my local Vapor server using ngrok and adding the Associated Domains capability with the value webcredentials:....ngrok-free.app and the respective apple-app-site-association file on my local server in /.well-known/. (works on device, but not in the simulator). However, if I use the developer mode (webcredentials:....ngrok-free.app?mode=developer) it only works halfway when running from Xcode: I get asked to save the password, but the saved passwords are not picked up, when I try to login again. Neither on device, nor in the simulator. If I remove the ?mode=developer it seems to work as expected. Is this by design, or am I missing something? var body: some View { ... Section(header: Text("Email")) { TextField("Email", text: $viewModel.credentials.username) .textContentType(.username) .autocapitalization(.none) .keyboardType(.emailAddress) } Section(header: Text("Passwort")) { SecureField("Passwort", text: $viewModel.credentials.password) .textContentType(.password) } ... }

During SmartCard pairing the PIN prompt enables the OK button only on user provides a PIN of 6 digits. Is there a way to submit the empty PIN in this flow, where the custom CTK is used here (the custom CTK would take care of the PIN from the custom ctk code). I was able to do an empty PIN submit once the I've paired the user successfully at login, unlock and other cli tools. Is there a way to do the same during the pairing? Once the user has successfully paired with the SmartCard authentication with PIN, I was able to see most of the authentication flows was prompting for the PIN authentication like login, unlock, CLI tools like ssh, su etc., perhaps at few apps where it is still prompted with the Password instead of PIN examples, when I tried to launch Keychain Access app or Add a user from users&amp;groups system setting. Is this expected behaviour?

Hi Apple Developer Support, I’m building a macOS app that acts as a default browser. I can confirm that I can set it correctly through System Settings → Default Web Browser. The app implements ASWebAuthenticationSessionWebBrowserSessionHandling to intercept Single Sign-On (SSO) flows. To handle requests, it presents SSO pages in a WKWebView embedded in a window that this app creates and owns - this works perfectly for the initial login flow. However, after I close my WebView window and then launch Safari or Chrome, any subsequent SSO requests open in the newly-launched browser instead of my custom browser, even though it remains selected as the default in System Settings. I’d appreciate any insight on why the system “hands off” to Safari/Chrome in this scenario, and how I can keep my app consistently intercepting all ASWebAuthenticationSession requests. Here are the steps that break down the issue: Launch & confirm that the custom default browser app is the default browser in System Settings → Default Web Browser. Trigger SSO (e.g., try to log in to Slack). App’s WKWebView appears, and the SSO UI works end-to-end. Close the WebView window (I have windowShouldClose callback where I cancel the pending session). Manually launch Safari or Chrome. Trigger SSO again. Observed behaviour: the login URL opens in Safari/Chrome. I am using macOS 15.3.2

Current Setup: Using Secure Enclave with userPresence access control Foreground keychain accessibility: whenPasscodeSetThisDeviceOnly Security Requirement: Our security group wants us to invalidate biometrics and require a username/password if a biometric item is added (potentially by a hostile 3rd party) Need to upgrade from userPresence to biometricCurrentSet to ensure re-authentication when biometric credentials change. Issue: After implementing biometricCurrentSet, authentication cancels after two failed biometric attempts instead of falling back to passcode. Current Detection Method: User completes initial biometric authentication Biometric changes occur (undetectable by app) App attempts Secure Enclave access Access denial triggers re-authentication requirement Cannot revoke refresh token after access is denied Security Concern: Current implementation allows new biometric enrollments to access existing authenticated sessions without re-verification. Question: What's the recommended approach to: Implement biometricCurrentSet while maintaining passcode fallback Properly handle refresh token invalidation when biometric credentials change Looking for guidance on best practices for implementing these security requirements while maintaining good UX.

I am experiencing an issue with Apple Sign-In on Vision Pro. When I build and run the app from Xcode, everything works fine—after signing in, the app returns to the foreground as expected. However, when I launch the app directly on Vision Pro (not from Xcode), after completing the sign-in process, the app does not reopen from the background automatically. Instead, it closes, and I have to manually tap the app icon to reopen it. Has anyone else encountered this issue? Is there a way to ensure the app properly resumes after sign-in without requiring manual intervention?

Feedback ticket ID: FB21797397 Summary When using posix_spawn() with posix_spawnattr_set_uid_np() to spawn a child process with a different UID, the eslogger incorrectly reports a setuid event as an event originating from the parent process instead of the child process. Steps to Reproduce Create a binary that do the following: Configure posix_spawnattr_t that set the process UIDs to some other user ID (I'll use 501 in this example). Uses posix_spawn() to spawn a child process Run eslogger with the event types setuid, fork, exec Execute the binary as root process using sudo or from root owned shell Terminate the launched eslogger Observe the process field in the setuid event Expected behavior The eslogger will report events indicating a process launch and uid changes so the child process is set to 501. i.e.: fork setuid - Done by child process exec Actual behavior The process field in the setuid event is reported as the parent process (that called posix_spawn) - indicating UID change to the parent process. Attachments I'm attaching source code for a small project with a 2 binaries: I'll add the source code for the project at the end of the file + attach filtered eslogger JSONs One that runs the descirbed posix_spawn flow One that produces the exact same sequence of events by doing different operation and reaching a different process state: Parent calls fork() Parent process calls setuid(501) Child process calls exec() Why this is problematic Both binaries in my attachment do different operations, achieving different process state (1 is parent with UID=0 and child with UID=501 while the other is parent UID=501 and child UID=0), but report the same sequence of events. Code #include <cstdio> #include <spawn.h> #include <stdio.h> #include <stdlib.h> #include <unistd.h> #include <sys/wait.h> #include <string.h> // environ contains the current environment variables extern char **environ; extern "C" { int posix_spawnattr_set_uid_np(posix_spawnattr_t *attr, uid_t uid); int posix_spawnattr_set_gid_np(posix_spawnattr_t *attr, gid_t gid); } int main() { pid_t pid; int status; posix_spawnattr_t attr; // 1. Define the executable path and arguments const char *path = "/bin/sleep"; char *const argv[] = {(char *)"sleep", (char *)"1", NULL}; // 2. Initialize spawn attributes if ((status = posix_spawnattr_init(&attr)) != 0) { fprintf(stderr, "posix_spawnattr_init: %s\n", strerror(status)); return EXIT_FAILURE; } // 3. Set the UID for the child process (e.g., UID 501) // Note: Parent must be root to change to a different user uid_t target_uid = 501; if ((status = posix_spawnattr_set_uid_np(&attr, target_uid)) != 0) { fprintf(stderr, "posix_spawnattr_set_uid_np: %s\n", strerror(status)); posix_spawnattr_destroy(&attr); return EXIT_FAILURE; } // 4. Spawn the process printf("Spawning /bin/sleep 1 as UID %d...\n", target_uid); status = posix_spawn(&pid, path, NULL, &attr, argv, environ); if (status == 0) { printf("Successfully spawned child with PID: %d\n", pid); // Wait for the child to finish (will take 63 seconds) if (waitpid(pid, &status, 0) != -1) { printf("Child process exited with status %d\n", WEXITSTATUS(status)); } else { perror("waitpid"); } } else { fprintf(stderr, "posix_spawn: %s\n", strerror(status)); } // 5. Clean up posix_spawnattr_destroy(&attr); return (status == 0) ? EXIT_SUCCESS : EXIT_FAILURE; } #include <cstdio> #include <cstdlib> #include <unistd.h> #include <sys/wait.h> #include <errno.h> #include <string.h> // This program demonstrates fork + setuid + exec behavior for ES framework bug report // 1. Parent forks // 2. Parent does setuid(501) // 3. Child waits with sleep syscall // 4. Child performs exec int main() { printf("Parent PID: %d, UID: %d, EUID: %d\n", getpid(), getuid(), geteuid()); pid_t pid = fork(); if (pid < 0) { // Fork failed perror("fork"); return EXIT_FAILURE; } if (pid == 0) { // Child process printf("Child PID: %d, UID: %d, EUID: %d\n", getpid(), getuid(), geteuid()); // Child waits for a bit with sleep syscall printf("Child sleeping for 2 seconds...\n"); sleep(2); // Child performs exec printf("Child executing child_exec...\n"); // Get the path to child_exec (same directory as this executable) char *const argv[] = {(char *)"/bin/sleep", (char *)"2", NULL}; // Try to exec child_exec from current directory first execv("/bin/sleep", argv); // If exec fails perror("execv"); return EXIT_FAILURE; } else { // Parent process printf("Parent forked child with PID: %d\n", pid); // Parent does setuid(501) printf("Parent calling setuid(501)...\n"); if (setuid(501) != 0) { perror("setuid"); // Continue anyway to observe behavior } printf("Parent after setuid - UID: %d, EUID: %d\n", getuid(), geteuid()); // Wait for child to finish int status; if (waitpid(pid, &status, 0) != -1) { if (WIFEXITED(status)) { printf("Child exited with status %d\n", WEXITSTATUS(status)); } else if (WIFSIGNALED(status)) { printf("Child killed by signal %d\n", WTERMSIG(status)); } } else { perror("waitpid"); } } return EXIT_SUCCESS; } posix_spawn.json fork_exec.json

The One-time codes documentation details how to enable autofill for SMS based codes. However, there is no details about how to correctly implement autofill for email based codes. I am observing the email based autofill works inconsistently when using email based OTC. In my application: There is latency of 10-15 seconds from when the email arrives to when it is available for autofill. After the autofill feature is used, the OTC email is not being deleted from the inbox automatically. Without documentation, it's unclear to me what I might be doing wrong that is causing these side effects. I found an ietf proposal for how autofill with email based codes might work, but it’s unclear if this is how Apple has implemented the feature: https://www.ietf.org/archive/id/draft-wells-origin-bound-one-time-codes-00.html#name-email Existing docs for Autofill using SMS: https://developer.apple.com/documentation/security/enabling-autofill-for-domain-bound-sms-codes

When presenting a cookie banner for GDPR purposes, should ATT precede the cookie banner? It seems that showing a Cookie Banner and then showing the ATT permission prompt afterwards (if a user elects to allow cookies/tracking) would be more appropriate. Related question: Should the “Allow Tracking” toggle for an app in system settings serve as a master switch for any granular tracking that might be managed by a 3rd party Consent Management Platform? If ATT is intended to serve as a master switch for tracking consent, if the ATT prompt is presented before a cookie banner, should the banner even appear if a user declines tracking consent? I’m not finding any good resources that describe this flow in detail and I’m seeing implementations all over the place on this. Help! Thanks!!!