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 everyone, I'm encountering a persistent 503 Server Temporarily Not Available error when trying to implement "Sign in with Apple" for my web application. I've already performed a full review of my configuration and I'm confident it's set up correctly, which makes this server-side error particularly confusing. Problem Description: Our web application uses Firebase Authentication to handle the "Sign in with Apple" flow. When a user clicks the sign-in button, they are correctly redirected to the appleid.apple.com authorization page. However, instead of seeing the login prompt, the page immediately displays a 503 Server Temporarily Not Available error. This is the redirect URL being generated (with the state parameter truncated for security): https://appleid.apple.com/auth/authorize?response_type=code&client_id=XXXXXX&redirect_uri=https%3A%2F%2FXXXXXX.firebaseapp.com%2F__%2Fauth%2Fhandler&state=AMbdmDk...&scope=email%20name&response_mode=form_post Troubleshooting Steps Performed: Initially, I was receiving an invalid_client error, which prompted me to meticulously verify every part of my setup. I have confirmed the following: App ID Configuration: The "Sign in with Apple" capability is enabled for our primary App ID. Services ID Configuration: We have a Services ID configured specifically for this. The "Sign in with Apple" feature is enabled on this Services ID. The domain is registered and verified under "Domains and Subdomains". Firebase Settings Match Apple Settings: The Services ID from Apple is used as the Client ID in our Firebase configuration. The Team ID is correct. We have generated a private key, and both the Key ID and the .p8 file have been correctly uploaded to Firebase. The key is not revoked in the Apple Developer portal. Since the redirect to Apple is happening with the correct client_id and redirect_uri, and the error is a 5xx server error (not a 4xx client error like invalid_client), I believe our configuration is correct and the issue might be on Apple's end. This has been happening consistently for some time. My Questions: What could be causing a persistent 503 Server Temporarily Not Available error on the /auth/authorize endpoint when all client-side configurations appear to be correct? What is the formal process for opening a technical support ticket (TSI) directly with Apple Developer Support for an issue like this? Thank you for any insights or help you can provide.

Hi, I know it's been discussed before, but I'm testing the Sign in with Apple feature, and I only get the user info on the first try. Now, I know that you're supposed to go to the account settings, and look for the list of accounts that you used your Apple account to sign in with, and it used to work a few months back. But for the last few weeks I haven't been able to get the user info, even after deleting the entry from my Sign In With Apple app list. Has there been a recent change to Apple security policy that prevents such a move from working ? Or am I doing something wrong ? Thank you

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?

Hi, I am in need of your help with publishing my game. I got the following explanation for the negative review of my app/game. Issue Description One or more purpose strings in the app do not sufficiently explain the use of protected resources. Purpose strings must clearly and completely describe the app's use of data and, in most cases, provide an example of how the data will be used. Next Steps Update the local network information purpose string to explain how the app will use the requested information and provide a specific example of how the data will be used. See the attached screenshot. Resources Purpose strings must clearly describe how an app uses the ability, data, or resource. The following are hypothetical examples of unclear purpose strings that would not pass review: "App would like to access your Contacts" "App needs microphone access" See examples of helpful, informative purpose strings. The problem is that they say my app asks to allow my app to find devices on local networks. And that this needs more explanation in the purpose strings. Totally valid to ask, but the problem is my app doesn't need local access to devices, and there shouldn't be code that asks this?? FYI the game is build with Unity. Would love some help on how to turn this off so that my app can get published.

During internal testing, we observed the following behavior and would appreciate clarification on whether it is expected and supported in production environments. When generating an elliptic-curve cryptographic key pair using "kSecAttrTokenIDSecureEnclave", and explicitly specifying a "kSecAttrAccessGroup", we found that cryptographic operations (specifically encryption and decryption) could be successfully performed using this key pair from two distinct applications. Both applications had the Keychain Sharing capability enabled and were signed with the same provisioning profile identity. Given the documented security properties of Secure Enclave, backed keys, namely that private key material is protected by hardware and access is strictly constrained by design, we would like to confirm whether the ability for multiple applications (sharing the same keychain access group and signing identity) to perform cryptographic operations with the same Secure Enclave–backed key is expected behavior on iOS. Specifically, we are seeking confirmation on: Whether this behavior is intentional and supported in production. Whether the Secure Enclave enforces access control primarily at the application-identifier (App ID) level rather than the individual app bundle level in this scenario. Whether there are any documented limitations or guarantees regarding cross-application usage of Secure Enclave keys when keychain sharing is configured. Any guidance or references to official documentation clarifying this behavior would be greatly appreciated.

I don't know why? 🤷 My uuid and imi as well as ip have been leaked, I don't know what to do? Can someone help me?

Hello, I am developing a macOS menu bar window-management utility (similar in functionality to Magnet / Rectangle) that relies on the Accessibility (AXUIElement) API to move and resize windows and on global hotkeys. I am facing a consistent issue when App Sandbox is enabled. Summary: App Sandbox enabled Hardened Runtime enabled Apple Events entitlement enabled NSAccessibilityDescription present in Info.plist AXIsProcessTrustedWithOptions is called with prompt enabled Observed behavior: When App Sandbox is enabled, the Accessibility permission prompt never appears. The app cannot be manually added in System Settings → Privacy & Security → Accessibility. AXIsProcessTrusted always returns false. As a result, window snapping does not work. When App Sandbox is disabled: The Accessibility prompt appears correctly. The app functions as expected. This behavior occurs both: In local builds In TestFlight builds My questions: Is this expected behavior for sandboxed macOS apps that rely on Accessibility APIs? Are window-management utilities expected to ship without App Sandbox enabled? Is there any supported entitlement or configuration that allows a sandboxed app to request Accessibility permission? Thank you for any clarification.

我配置了 DKIM 和 amazon 的默认 spf。但无法使用 Amazon Send 获取电子邮件，则可以发送配置的单个电子邮件

When I delete an image from my camera roll, my iPhone adds another previously deleted image to my camera roll. This previously deleted image or video is from up to 3 years ago, and isn't in my recently deleted. Therefore, these added images should technically not exist. I am using an iPhone 12 running iOS 26 public beta, but apparently this issue is happening on iOS 18 too. I feel worried that an image/video that I deleted for privacy reasons may appear back in my camera roll. I'll add that I am paying for iCloud+ storage, and I still have 15GB of local storage left on my device.

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!!!

I understand from the recent Apple Developer News that Korean developers are now required to register a URL to receive notifications from the Apple server when creating or modifying a Sign in With Apple Service ID. However, it is not clear whether simply registering the URL is sufficient, or if it is also mandatory to implement the real-time processing of those notifications. I am inquiring whether the processing part is also a mandatory requirement.

We have a crash on DCDevice.current.isSupported We want to try to make a serial queue to generate tokens but the side effect would be the same token would be used on multiple server API requests that are made within a few ms of each other? Is this safe or will the Apple server immediately reject the same token being reused? Can you share how long tokens are safe to use for? Here is the code we want to try final actor DeviceTokenController: NSObject { static var shared: DeviceTokenController = .init() private var tokenGenerationTask: Task<Data?, Never>? var ephemeralDeviceToken: Data? { get async { // Re-using the token for short periods of time if let existingTask = tokenGenerationTask { return await existingTask.value } let task = Task<Data?, Never> { guard DCDevice.current.isSupported else { return nil } do { return try await DCDevice.current.generateToken() } catch { Log("Failed to generate ephemeral device token", error) return nil } } tokenGenerationTask = task let result = await task.value tokenGenerationTask = nil return result } } }

I want to add the "Sign In with Apple" feature to my iPadOS application. I've already done the following: Include com.apple.developer.applesignin in mobileprovision Include com.apple.developer.applesignin in entitlements However, I'm getting the following errors: `Authorization failed: Error Domain=AKAuthenticationError Code=-7026 "(null)" UserInfo={AKClientBundleID=xxxx} LaunchServices: store (null) or url (null) was nil: Error Domain=NSOSStatusErrorDomain Code=-54 "process may not map database" UserInfo={_LSLine=72, _LSFunction=_LSServer_GetServerStoreForConnectionWithCompletionHandler, _LSFile=LSDReadService.mm, NSDebugDescription=process may not map database} Attempt to map database failed: permission was denied. This attempt will not be retried. Failed to initialize client context with error Error Domain=NSOSStatusErrorDomain Code=-54 "process may not map database" UserInfo={_LSLine=72, _LSFunction=_LSServer_GetServerStoreForConnectionWithCompletionHandler, _LSFile=LSDReadService.mm, NSDebugDescription=process may not map database} Failed to get application extension record: Error Domain=NSOSStatusErrorDomain Code=-54 "(null)" ASAuthorizationController credential request failed with error: Error Domain=com.apple.AuthenticationServices.AuthorizationError Code=1000 "(null)" ` What is this problem? How can I solve it? Hoping someone can help, thank you!

I was testing an app with AppleSignIn with a Firebase backend and wanted to test account deletion functionality. I was unaware of needing to revoke the token with Apple before proceeding with account deletion. Now, when I try to create a new account with the same appleId email, the token passed to Firebase is invalid and the login fails. As such, I am blocked from testing my app with authenticated Apple users, so I'm trying to understand what the workaround is. Thanks in advance!

Hello. When a user revokes Apple Login authorization, I am expecting a webhook to be delivered to our configured endpoint, but I currently not receiving any at all. So I have some questions: Should the revoke event webhook be delivered in real-time? If it is not real-time, when is the webhook supposed to be sent? If my server fails to respond to the webhook request, does Apple retry the delivery? (Actually I couldn't find how to response in this scenario, but if I can) Thanks in advance.

https://developer.apple.com/documentation/apptrackingtransparency/attrackingmanager/authorizationstatus/notdetermined Note: Discussion If you call ATTrackingManager.trackingAuthorizationStatus in macOS, the result is always ATTrackingManager.AuthorizationStatus.notDetermined. So, does macOS support getting ATT?

After registe Passkey with webauthn library, i create a passkeyRegistration with follow, let passkeyRegistration = ASPasskeyRegistrationCredential(relyingParty: serviceIdentifier, clientDataHash: clientDataHashSign, credentialID: credentialId, attestationObject: attestationObject) and then completeRegistrationRequest like that, extensionContext.completeRegistrationRequest(using: passkeyRegistration) But a bad outcome occurred from user agent. NotAllowedError:The request is not allowed by the user agent or the platform in the current context. And the return data rawID & credentialPublicKey is empty,

Hi everyone, We are using the App Attest API to securely transition users to our new system. As part of this, we store the Key ID of the attestation key for each user to verify their identity later. However, we’ve noticed that some users are encountering the error “DCErrorInvalidKey 3” when calling generateAssertion. Importantly, the key was previously successfully attested, and generateAssertion has worked before for these users. Our questions: Could this error be caused by an app or iOS update? Is it problematic to link an attestation key's Key ID directly to a user, or are there scenarios where the key might change or become invalid? If there’s a way to mitigate this issue or recover affected users, what best practices would you recommend? Any help or shared experiences would be greatly appreciated! Thanks in advance.

Hi, We are operating a service that uses Sign in with Apple for user registration and login. As part of our security incident response and periodic security improvements, we are planning to rotate the private key used to generate the client secret (JWT) for Sign in with Apple. I have read the Human Interface Guidelines and the AuthenticationServices documentation, but I could not find a clear description of the behavior and user impact when rotating this private key. I would like to ask the following questions: Background: We issue a Sign in with Apple private key (with a Key ID) in our Apple Developer account. Our server uses this private key to generate the client secret (JWT). This is used for Sign in with Apple login on our web / mobile app. We are planning to invalidate the existing private key and switch to a newly issued one. Questions: Impact on existing logged-in sessions Will rotating the private key force already logged-in users (who previously signed in with Apple) to be logged out from our service? Can the user identifier (such as the "sub" claim) for existing Sign in with Apple users change due to key rotation? Recommended frequency and best practices Does Apple recommend rotating this private key only when it is compromised, or on a regular basis? If there are any official documents or examples that describe how to safely perform key rotation in production, we would appreciate a pointer. Impact on marketing / analytics We are using user IDs (linked via Sign in with Apple) for analytics and marketing attribution. Is there any expected impact on such use cases caused by rotating the private key? For example, is there any possibility that user identifiers change as a result of key rotation, or anything we should be careful about from a data linkage perspective? Our goal is to rotate the private key in a secure way without causing service downtime, mass logouts, or loss of account linkage. If there is already an official document that covers this, please let me know the URL. Thank you in advance.