I regularly help developers with keychain problems, both here on DevForums and for my Day Job™ in DTS. Many of these problems are caused by a fundamental misunderstanding of how the keychain works. This post is my attempt to explain that. I wrote it primarily so that Future Quinn™ can direct folks here rather than explain everything from scratch (-: 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: Fundamentals or How I Learned to Stop Worrying and Love the SecItem API 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 the fundamental underpinnings of the keychain. For information about specific issues, see its companion post, SecItem: Pitfalls and Best Practices. Keychain Documentation Your basic starting point should be Keychain Items. If your code runs on the Mac, also read TN3137 On Mac keychain APIs and implementations. Read the doc comments in <Security/SecItem.h>. In many cases those doc comments contain critical tidbits. When you read keychain documentation [1] and doc comments, keep in mind that statements specific to iOS typically apply to iPadOS, tvOS, and watchOS as well (r. 102786959). Also, they typically apply to macOS when you target the data protection keychain. Conversely, statements specific to macOS may not apply when you target the data protection keychain. [1] Except TN3137, which is very clear about this (-: Caveat Mac Developer macOS supports two different keychain implementations: the original file-based keychain and the iOS-style data protection keychain. IMPORTANT If you’re able to use the data protection keychain, do so. It’ll make your life easier. See the Careful With that Shim, Mac Developer section of SecItem: Pitfalls and Best Practices for more about this. TN3137 On Mac keychain APIs and implementations explains this distinction. It also says: The file-based keychain is on the road to deprecation. This is talking about the implementation, not any specific API. The SecItem API can’t be deprecated because it works with both the data protection keychain and the file-based keychain. However, Apple has deprecated many APIs that are specific to the file-based keychain, for example, SecKeychainCreate. TN3137 also notes that some programs, like launchd daemons, can’t use the file-based keychain. If you’re working on such a program then you don’t have to worry about the deprecation of these file-based keychain APIs. You’re already stuck with the file-based keychain implementation, so using a deprecated file-based keychain API doesn’t make things worse. The Four Freedoms^H^H^H^H^H^H^H^H Functions The SecItem API contains just four functions: SecItemAdd(_:_:) SecItemCopyMatching(_:_:) SecItemUpdate(_:_:) SecItemDelete(_:) These directly map to standard SQL database operations: SecItemAdd(_:_:) maps to INSERT. SecItemCopyMatching(_:_:) maps to SELECT. SecItemUpdate(_:_:) maps to UPDATE. SecItemDelete(_:) maps to DELETE. You can think of each keychain item class (generic password, certificate, and so on) as a separate SQL table within the database. The rows of that table are the individual keychain items for that class and the columns are the attributes of those items. Note Except for the digital identity class, kSecClassIdentity, where the values are split across the certificate and key tables. See Digital Identities Aren’t Real in SecItem: Pitfalls and Best Practices. This is not an accident. The data protection keychain is actually implemented as an SQLite database. If you’re curious about its structure, examine it on the Mac by pointing your favourite SQLite inspection tool — for example, the sqlite3 command-line tool — at the keychain database in ~/Library/Keychains/UUU/keychain-2.db, where UUU is a UUID. WARNING Do not depend on the location and structure of this file. These have changed in the past and are likely to change again in the future. If you embed knowledge of them into a shipping product, it’s likely that your product will have binary compatibility problems at some point in the future. The only reason I’m mentioning them here is because I find it helpful to poke around in the file to get a better understanding of how the API works. For information about which attributes are supported by each keychain item class — that is, what columns are in each table — see the Note box at the top of Item Attribute Keys and Values. Alternatively, look at the Attribute Key Constants doc comment in <Security/SecItem.h>. Uniqueness A critical part of the keychain model is uniqueness. How does the keychain determine if item A is the same as item B? It turns out that this is class dependent. For each keychain item class there is a set of attributes that form the uniqueness constraint for items of that class. That is, if you try to add item A where all of its attributes are the same as item B, the add fails with errSecDuplicateItem. For more information, see the errSecDuplicateItem page. It has lists of attributes that make up this uniqueness constraint, one for each class. These uniqueness constraints are a major source of confusion, as discussed in the Queries and the Uniqueness Constraints section of SecItem: Pitfalls and Best Practices. Parameter Blocks Understanding The SecItem API is a classic ‘parameter block’ API. All of its inputs are dictionaries, and you have to know which properties to set in each dictionary to achieve your desired result. Likewise for when you read properties in output dictionaries. There are five different property groups: The item class property, kSecClass, determines the class of item you’re operating on: kSecClassGenericPassword, kSecClassCertificate, and so on. The item attribute properties, like kSecAttrAccessGroup, map directly to keychain item attributes. The search properties, like kSecMatchLimit, control how the system runs a query. The return type properties, like kSecReturnAttributes, determine what values the query returns. The value type properties, like kSecValueRef perform multiple duties, as explained below. There are other properties that perform a variety of specific functions. For example, kSecUseDataProtectionKeychain tells macOS to use the data protection keychain instead of the file-based keychain. These properties are hard to describe in general; for the details, see the documentation for each such property. Inputs Each of the four SecItem functions take dictionary input parameters of the same type, CFDictionary, but these dictionaries are not the same. Different dictionaries support different property groups: The first parameter of SecItemAdd(_:_:) is an add dictionary. It supports all property groups except the search properties. The first parameter of SecItemCopyMatching(_:_:) is a query and return dictionary. It supports all property groups. The first parameter of SecItemUpdate(_:_:) is a pure query dictionary. It supports all property groups except the return type properties. Likewise for the only parameter of SecItemDelete(_:). The second parameter of SecItemUpdate(_:_:) is an update dictionary. It supports the item attribute and value type property groups. Outputs Two of the SecItem functions, SecItemAdd(_:_:) and SecItemCopyMatching(_:_:), return values. These output parameters are of type CFTypeRef because the type of value you get back depends on the return type properties you supply in the input dictionary: If you supply a single return type property, except kSecReturnAttributes, you get back a value appropriate for that return type. If you supply multiple return type properties or kSecReturnAttributes, you get back a dictionary. This supports the item attribute and value type property groups. To get a non-attribute value from this dictionary, use the value type property that corresponds to its return type property. For example, if you set kSecReturnPersistentRef in the input dictionary, use kSecValuePersistentRef to get the persistent reference from the output dictionary. In the single item case, the type of value you get back depends on the return type property and the keychain item class: For kSecReturnData you get back the keychain item’s data. This makes most sense for password items, where the data holds the password. It also works for certificate items, where you get back the DER-encoded certificate. Using this for key items is kinda sketchy. If you want to export a key, called SecKeyCopyExternalRepresentation. Using this for digital identity items is nonsensical. For kSecReturnRef you get back an object reference. This only works for keychain item classes that have an object representation, namely certificates, keys, and digital identities. You get back a SecCertificate, a SecKey, or a SecIdentity, respectively. For kSecReturnPersistentRef you get back a data value that holds the persistent reference. Value Type Subtleties There are three properties in the value type property group: kSecValueData kSecValueRef kSecValuePersistentRef Their semantics vary based on the dictionary type. For kSecValueData: In an add dictionary, this is the value of the item to add. For example, when adding a generic password item (kSecClassGenericPassword), the value of this key is a Data value containing the password. This is not supported in a query dictionary. In an update dictionary, this is the new value for the item. For kSecValueRef: In add and query dictionaries, the system infers the class property and attribute properties from the supplied object. For example, if you supply a certificate object (SecCertificate, created using SecCertificateCreateWithData), the system will infer a kSecClass value of kSecClassCertificate and various attribute values, like kSecAttrSerialNumber, from that certificate object. This is not supported in an update dictionary. For kSecValuePersistentRef: For query dictionaries, this uniquely identifies the item to operate on. This is not supported in add and update dictionaries. Revision History 2025-05-28 Expanded the Caveat Mac Developer section to cover some subtleties associated with the deprecation of the file-based keychain. 2023-09-12 Fixed various bugs in the revision history. Added a paragraph explaining how to determine which attributes are supported by each keychain item class. 2023-02-22 Made minor editorial changes. 2023-01-28 First posted.

Hello, We received a rejection on one of our IOS applications because we were doing Microsoft MSAL login through the user's browser. The representative recommended that we use Webview to do in-app logins. However when we tried to handle the custom app uri redirection (looking like myapp://auth/), Webview does not seem to send the user back to the application. Does anyone have a fix for this? Thanks!

Our company has a micro service which sends a notification email to an iCloud account/email and the email is going to the junk folder. As we tested, the email generated from user-field.company.com goes to the Inbox, while the email from user-dev.company.com goes to the Junk folder. Is there a way to avoid sending the emails to client's Junk folder when the email is sent from a specific company domain?

I'm trying to setup device attestation. I believe I have everything setup correctly but the final step of signature validation never succeeds. I've added validation on the client side for debugging and it doesn't validate using CryptoKit. After the assertion is created, I try to validate it: assertion = try await DCAppAttestService.shared.generateAssertion(keyId, clientDataHash: clientDataHash) await validateAssertionLocallyForDebugging(keyId: keyId, assertionObject: assertion, clientDataHash: clientDataHash) In the validateAssertionLocallyForDebugging method, I extract all the data from the CBOR assertionObject and then setup the parameters to validate the signature, using the key that was created from the original attestation flow, but it fails every time. I'm getting the public key from the server using a temporary debugging API. let publicKeyData = Data(base64Encoded: publicKeyB64)! let p256PublicKey = try P256.Signing.PublicKey(derRepresentation: publicKeyData) let ecdsaSignature = try P256.Signing.ECDSASignature(derRepresentation: signature) let digestToVerify = SHA256.hash(data: authenticatorData + clientDataHash) print(" - Recreated Digest to Verify: \(Data(digestToVerify).hexDescription)") if p256PublicKey.isValidSignature(ecdsaSignature, for: digestToVerify) { print("[DEBUG] SUCCESS: Local signature validation passed!") } else { print("[DEBUG] FAILED: Local signature validation failed.") } I have checked my .entitlements file and it is set to development. I have checked the keyId and verified the public key. I have verified the public key X,Y, the RP ID Hash, COSE data, and pretty much anything else I could think of. I've also tried using Gemini and Claude to debug this and that just sends me in circles of trying hashed, unhashed, and double hashed clientData. I'm doing this from Xcode on an M3 macbook air to an iPhone 16 Pro Max. Do you have any ideas on why the signature is not validating with everything else appears to be working? Thanks

override func prepareInterface(forPasskeyRegistration registrationRequest: any ASCredentialRequest) int this function how can i get the "challenge" from user agent, the params "challenge" need to be used in webauthn navigator.credentials.create

We have been having very high response times in device check device validation service (https://developer.apple.com/documentation/devicecheck/accessing-and-modifying-per-device-data#Create-the-payload-for-a-device-validation-request) since 17 July at 19:10hs GMT. The service information page says the service was running in green status but that isn't the case and we currenly have stop consuming it. Is it being looked at? Are you aware of this issue? Can you give us an estimate of when it should be working correctly?

Script attachment enables advanced users to create powerful workflows that start in your app. NSUserScriptTask lets you implement script attachment even if your app is sandboxed. This post explains how to set that up. IMPORTANT Most sandboxed apps are sandboxed because they ship on the Mac App Store [1]. While I don’t work for App Review, and thus can’t make definitive statements on their behalf, I want to be clear that NSUserScriptTask is intended to be used to implement script attachment, not as a general-purpose sandbox bypass mechanism. If you have questions or comments, please put them in a new thread. Place it in the Privacy &amp; Security &gt; General subtopic, and tag it with App Sandbox. Share and Enjoy — Quinn “The Eskimo!” @ Developer Technical Support @ Apple let myEmail = "eskimo" + "1" + "@" + "apple.com" [1] Most but not all. There are good reasons to sandbox your app even if you distribute it directly. See The Case for Sandboxing a Directly Distributed App. Implementing Script Attachment in a Sandboxed App Some apps support script attachment, that is, they allow a user to configure the app to run a script when a particular event occurs. For example: A productivity app might let a user automate repetitive tasks by configuring a toolbar button to run a script. A mail client might let a user add a script that processes incoming mail. When adding script attachment to your app, consider whether your scripting mechanism is internal or external: An internal script is one that only affects the state of the app. A user script is one that operates as the user, that is, it can change the state of other apps or the system as a whole. Supporting user scripts in a sandboxed app is a conundrum. The App Sandbox prevents your app from changing the state of other apps, but that’s exactly what your app needs to do to support user scripts. NSUserScriptTask resolves this conundrum. Use it to run scripts that the user has placed in your app’s Script folder. Because these scripts were specifically installed by the user, their presence indicates user intent and the system runs them outside of your app’s sandbox. Provide easy access to your app’s Script folder Your application’s Scripts folder is hidden within ~/Library. To make it easier for the user to add scripts, add a button or menu item that uses NSWorkspace to show it in the Finder: let scriptsDir = try FileManager.default.url(for: .applicationScriptsDirectory, in: .userDomainMask, appropriateFor: nil, create: true) NSWorkspace.shared.activateFileViewerSelecting([scriptsDir]) Enumerate the available scripts To show a list of scripts to the user, enumerate the Scripts folder: let scriptsDir = try FileManager.default.url(for: .applicationScriptsDirectory, in: .userDomainMask, appropriateFor: nil, create: true) let scriptURLs = try FileManager.default.contentsOfDirectory(at: scriptsDir, includingPropertiesForKeys: [.localizedNameKey]) let scriptNames = try scriptURLs.map { url in return try url.resourceValues(forKeys: [.localizedNameKey]).localizedName! } This uses .localizedNameKey to get the name to display to the user. This takes care of various edge cases, for example, it removes the file name extension if it’s hidden. Run a script To run a script, instantiate an NSUserScriptTask object and call its execute() method: let script = try NSUserScriptTask(url: url) try await script.execute() Run a script with arguments NSUserScriptTask has three subclasses that support additional functionality depending on the type of the script. Use the NSUserUnixTask subsclass to run a Unix script and: Supply command-line arguments. Connect pipes to stdin, stdout, and stderr. Get the termination status. Use the NSUserAppleScriptTask subclass to run an AppleScript, executing either the run handler or a custom Apple event. Use the NSUserAutomatorTask subclass to run an Automator workflow, supplying an optional input. To determine what type of script you have, try casting it to each of the subclasses: let script: NSUserScriptTask = … switch script { case let script as NSUserUnixTask: … use Unix-specific functionality … case let script as NSUserAppleScriptTask: … use AppleScript-specific functionality … case let script as NSUserAutomatorTask: … use Automatic-specific functionality … default: … use generic functionality … }

Hi, A certificate imported on macOS 15 using the security command with the "non-exportable" option was imported in an exportable state. I would like to know how to change this certificate to be non-exportable. Regards, CTJ

On Tahoe and earlier, ScreenCapture permissions can disappear and not return. Customers are having an issue with this disappearing and when our code executes CGRequestScreenCaptureAccess() nothing happens, the prompt does not appear. I can reproduce this by using the "-" button and removing the entry in the settings, then adding it back with the "+" button. CGPreflightScreenCaptureAccess() always returns the correct value but once the entry has been removed, CGRequestScreenCaptureAccess() requires a reboot before it will work again.

Our proposed solution to identify an app user when opening a website operated by app developer is: Apps sends a request to backed with app users auth header Backend fetches a generated authenticated url from website backend, based on users auth header App opens it in browser The browser journey is self contained within domain of the business. Would this interaction require an ATT request given that the users identity cannot be tracked back to the app user ? Thanks

WebAuthn Level 3 § 5.1.3 Step 22 Item 4 states the steps a user agent MUST follow when "conditional" mediation is used in conjunction with required user verification: Let userVerification be the effective user verification requirement for credential creation, a Boolean value, as follows. If pkOptions.authenticatorSelection.userVerification is set to required If options.mediation is set to conditional and user verification cannot be collected during the ceremony, throw a ConstraintError DOMException. Let userVerification be true. On my iPhone 15 Pro Max running iOS 18.5, Safari + Passwords does not exhibit this behavior; instead an error is not reported and user verification is not performed (i.e., the UV bit is 0). Per the spec this results in a registration ceremony failure on the server which is made all the more "annoying" since the credential was created in Passwords forcing a user to then delete the credential. : If the Relying Party requires user verification for this registration, verify that the UV bit of the flags in authData is set. In contrast when I use Google Password Manager + Chrome on a Samsung Galaxy S24 running Android 15, user verification is enforced and the UV bit is 1. Either the UV bit should be 1 after enforcing user verification or an error should be thrown since user verification cannot be performed.

Steps to reproduce: register a passkey on device A authenticate on device A, using the prf extension and a constant salt. Note the prf output go to device B. wait for iCloud sync authenticate on device B using the prf extension and the same constant salt. Note the prf output The prf outputs are different. Note: Repeat the authentication on each device. The prf output is identical for a given device, which seems to point towards the inclusion of a device specific component in the prf derivation. In my scenario, I need the prf output to be the same regardless of the device since I use it as the recovery key for my app data. Could you confirm that this is the expected behavior or not? Thanks,

hello, My organization has an outlook add-in that requires auth into our platform. As Microsoft forces Auth on MacOS to use WKWebView https://learn.microsoft.com/en-us/office/dev/add-ins/concepts/browsers-used-by-office-web-add-ins, we are running into a situation that we cannot use passkeys as an auth method as we are unable to trigger WebAuthN flows. We’ve raised this in Microsoft side but they have deferred to Apple given WKWebView is Safari based. This is a big blocker for us to achieve a full passwordless future. Has anyone come across this situation? Thank you.

I am trying to integrate those into my app, stuck on it would not transfer to view that inside app, can someone help? Scott

When implementing a custom right in macOS authorizationdb, the mechanism array element builtin:authenticate is displaying the message 'Enter the name and password of a user in the "(null)" group to allow this.' on the macOS credential prompt UI popup. I am trying to find a fix to avoid the reference to null group in the message label that is displayed just above the username and password input fields. The current plist uses class as the key and value as the evaluate-mechanisms. The mechanisms array includes mechanism array with elements "builtin:login-begin", "mycustombundle:mycustompreaction", "builtin:authenticate", "mycustombundle:mycustommechanism". I have tried specifying group in the plist, have tried setting hint in the MechanismInvoke for group, username, security, authority, prompt, reason among several other hints into the context duing the execution of mycustombundle:mycustompreaction, but none seem to fix the "(null)" in the message label. Any help is greately appreciated. There is not much of any documentation for developers implementing custom authorization in macOS.

Hi Apple Developer Community, Quick question — is there currently a way to disable the “Save Password” prompt in iOS while keeping AutoFill enabled? From what I can see, the only available setting under General → AutoFill & Passwords controls AutoFill as a whole, with no option to turn off just the save prompt. I’m using a third-party password manager and would prefer to keep AutoFill but avoid the repeated prompts to save credentials. Has anyone found a workaround for this, or is this simply not configurable at the moment? Thanks!

Hi, we were recently approved for the com.apple.developer.web-browser.public-key-credential entitlement and have added it to our app. It initially worked as expected for a couple of days, but then it stopped working. We're now seeing the same error as before adding the entitlement: 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)" Do you have any insights into what might be causing this issue? Thank you!

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 Apple team, For our iPhone app (App Store build), a small subset of devices report DCAppAttestService.isSupported == false, preventing App Attest from being enabled. Approx. impact: 0.23% (352/153,791) iOS observed: Broadly 15.x–18.7 (also saw a few anomalous entries ios/26.0, likely client logging noise) Device models: Multiple generations (iPhone8–iPhone17); a few iPad7 entries present although the app targets iPhone Questions In iPhone main app context, what conditions can make isSupported return false on iOS 14+? Are there known device/iOS cases where temporary false can occur (SEP/TrustChain related)? Any recommended remediation (e.g., DFU restore)? Could you share logging guidance (Console.app subsystem/keywords) to investigate such cases? What fallback policy do you recommend when isSupported == false (e.g., SE-backed signature + DeviceCheck + risk rules), and any limitations? We can provide sysdiagnose/Console logs and more case details upon request. Thank you, —