Hi, I am trying to implement encryption and decryption with EC signing keys. in the process I am getting the following error while creating a SecKey from the private key. Error in creating a secKey Optional(Swift.Unmanaged<__C.CFErrorRef>(_value: Error Domain=NSOSStatusErrorDomain Code=-50 "EC private key creation from data failed" (paramErr: error in user parameter list) UserInfo={numberOfErrorsDeep=0, NSDescription=EC private key creation from data failed})) Code snippet for decryption func decrypt(data: Data, key: SecureEnclave.P256.Signing.PrivateKey) throws -> Data? {     var error: Unmanaged<CFError>?     let privateKeyData: CFData = key.dataRepresentation as CFData     let privateKeyAttributes = [kSecAttrKeyType: kSecAttrKeyTypeECSECPrimeRandom,                                 kSecAttrKeyClass: kSecAttrKeyClassPrivate] as CFDictionary     guard let SecKey = SecKeyCreateWithData(privateKeyData, privateKeyAttributes as CFDictionary, &error)     else {         print("Error in creating a secKey", error)         return nil     }          guard SecKeyIsAlgorithmSupported(SecKey, .decrypt, EncryptAndDecryptAlogrithm)     else {         print("Decryption algorithm is not supported", error)         return nil     }          guard let decryptedData = SecKeyCreateDecryptedData(SecKey, EncryptAndDecryptAlogrithm, data as CFData, &error) else {         print("Error in decryption", error)         return nil     }     return decryptedData as Data } let data = Data(base64Encoded: "BNtHrb1cZuflSDZz+E3PnIkLtYUQuBDW+ONlzuAypZcQa+5oKv0L0wSIBMMseMr0roloexPwTaVV26ddewTP0+vRt9v6uLOg366cElMo6P5nh2K7xKi1PMcRyBVel+Kq9WQWT/EkRIuUkHdq2KLXy/Q=")! let alice = try SecureEnclave.P256.Signing.PrivateKey() let decryptedData = try decrypt(data: data, key:alice) Thank you in advance.

Hi, I want to implement FIDO based biometric authentication in our app. I don't want to use passkeys because they are only compatible with iOS 16 and higher. Is there a way to use it through the SFSafariViewController, a web view, ASWebAuthenticationSession or any another method?

I am trying to use SecItemUpdate in order to change the kSecAttrAccessControl value on a private key protected by the Secure Enclave as well as an .applicationPassword - which I want to change. I have been unsuccessful getting the query and attributesToUpdate dictionaries right though, with SecItemUpdate returning either errSecParam, errSecNoSuchAttr or errSecAuthFailed. Am I on the right track here or am I trying to do something that is not possible?

I maintain a cross-platform client side network library for persistent TCP connections targeting Win32, Darwin and FreeBSD platforms. I recently upgraded to a Mac Studio w/ M1 Max (Ventura 13.1) from a late 2015 Intel Macbook Pro (Monterey 12.6.2) and I've encountered a discrepancy between the two. For secure TCP connections my lib uses WolfSSL across all platforms but also supports use of system provided Security libraries. On Darwin platforms this is SecureTransport. Yes I am aware SecureTransport is deprecated in favor of Network. I intend to attempt to integrate with Network later but for now my architecture dictates that I use similar C-style callbacks akin to WolfSSL, OpenSSL, MBedTLS etc. On the first call to SSLHandshake the SecureTransport write callback generates 151 bytes for my TLS 1.2 connection to example.com:443 on both platforms. However, while on Intel MBP I am able to continue with the full handshake I immediately receive 0 bytes with EOF. In Wireshark on the Intel MBP the 151 bytes are observed as a TLS 1.2 client hello while on M1 it is observed as an SSL continuation message and that is the last message observed.

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 implementations: the original file-based keychain and the iOS-style data protection keychain. If you’re able to use the data protection keychain, do so. It’ll make your life easier. TN3137 On Mac keychain APIs and implementations explains this distinction in depth. 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 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.

If you’re on macOS and targeting the file-based keychain, kSecMatchLimitAll always defaults to kSecMatchLimitOne 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 who’s 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. 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. 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. 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. 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: Fight!. 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 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.

We are building an Authorization Plugin with a custom GUI where we prompt the user for additional information after they have entered their username/password. Right now, we are doing this using an NSWindowController and an NSWindow. The problem is that the login "spinner" shows up in front of the window as seen here: Is there a way to avoid this? Or do we have to subclass SFAuthorizationPluginView to get this to work? Thanks!

Looking at the certificate chains for various binaries (using Apple's APIs or codesign --vvd) shows several patterns for the common names. I am wondering why some code has the structure Apple Root CA Developer ID Certification Authority Developer ID Application: Google LLC (EQHXZ8M8AV) while others have the pattern Apple Root CA Apple Worldwide Developer Relations Certification Authority Apple Mac OS Application Signing Note, the second pattern does not include an organizational name. Why is there a difference? Is the second pattern an older pattern and the first (with the organization name) the new pattern? (There are other certificate patterns like for Apple's binaries and development code I am testing)

SecCopyErrorMessageString suggests that the return value should be called with CFRelease to release/free the object. Though upon attempting to do so, XCode says "CFRelease is unavailable: Core Foundation objects are automatically memory managed". I have verified with Instruments in XCode that the follow code increases in memory usage without bound, from ~3MB to 20MB+ over 100000 iterations. public func simpleLeak(){ var secReq: SecRequirement? let err = SecRequirementCreateWithString("blah" as CFString, SecCSFlags(rawValue: 0), &amp;secReq) guard err == errSecSuccess else { var errorString = SecCopyErrorMessageString(err, nil) print(errorString) return } } What's the proper usage of SecCopyErrorMessageString that doesn't leak memory in Swift?

open Terminal.app export DYLD_INSERT_LIBRARIES="path_to_dylib" env Result: x86: no DYLD_INSERT_LIBRARIES environment is printed. M1 pro: dyld[1393]: tried: '/usr/local/lib/***.dylib' (fat file, but missing compatible architecture (have 'x86_64,arm64', need '')), '/System/Volumes/Preboot/Cryptexes/OS/usr/local/lib/***.dylib' (no such file), '/usr/local/lib/***.dylib' (fat file, but missing compatible architecture (have 'x86_64,arm64', need ''))

I am trying to convert publicKeyFromDongleData to SecKey, then perform some tasks. After that, I want to convert SecKey to b64 String. I am assuming that publicKeyFromDongleData and b64 string will be the same. But, surprisingly, they are not the same. How can i resolve the issue? Is there any way around? My goal is to retain the public key before and after converting the same. let publicKeyFromDongleData = Data.init(base64Encoded: publicKeyFromDongle) guard let publicKeySecKey = SecKeyCreateWithData(publicKeyFromDongleData! as CFData, keyDict as CFDictionary, &amp;error) else { print("Failed to create public key:", error!.takeRetainedValue()) return nil } //var error:Unmanaged&lt;CFError&gt;? if let cfdata = SecKeyCopyExternalRepresentation(publicKeySecKey, &amp;error) { let data:Data = cfdata as Data let b64Key = data.base64EncodedString() print("after : \n") print(b64Key) }

Hi, I'm getting the error code -34018 in the VisionOS simulator when calling SecItemCopyMatching with this query: let getquery: [String: Any] = [kSecClass as String: kSecClassGenericPassword, kSecAttrAccount as String: name, kSecReturnData as String: kCFBooleanTrue!, kSecMatchLimit as String : kSecMatchLimitOne ] The console says: copy_matching Error Domain=NSOSStatusErrorDomain Code=-34018 "Client has neither application-identifier nor keychain-access-groups entitlements" UserInfo={numberOfErrorsDeep=0, NSDescription=Client has neither application-identifier nor keychain-access-groups entitlements} I'm NOT using groups. I've tried changing the bundle id. Xcode version 15.0 beta 2 (15A5161b) Anyone have any ideas? Anyone using the keychain in their visionOS app? :-)

I have in the past used TN2326 as reference to generate keys for our server that aren't self signed, instead signed by our certificate authority. The method in TN2326 is not working with the latest openssl, and honestly I don't understand these error messages enough to debug. If I add '-legacy' to the openssl command below - I do not get the error. However, clients using TLS are unable to connect to the server. In iOS, it reports a trust issue with the certificate, also pasted below. You can see below that I am using http3 with quic, so TLS 1.3 is important. I am running a python (3.10) script for the server, openssl I appreciate any help on this. % openssl pkcs12 -in server_192_168_0_187.p12 -nokeys -out server.crt Enter Import Password: Error outputting keys and certificates 4076BD4CF87F0000:error:0308010C:digital envelope routines:inner_evp_generic_fetch:unsupported:crypto/evp/evp_fetch.c:341:Global default library context, Algorithm (RC2-40-CBC : 0), Properties () From the iOS client using the '-legacy' option: task will start, url: https://X.X.X.X:4433 Connection 3: default TLS Trust evaluation failed(-9807) Connection 3: TLS Trust encountered error 3:-9807 Connection 3: encountered error(3:-9807) [connection] nw_connection_copy_connected_local_endpoint_block_invoke [C4] Client called nw_connection_copy_connected_local_endpoint on unconnected nw_connection [connection] nw_connection_copy_connected_remote_endpoint_block_invoke [C4] Client called nw_connection_copy_connected_remote_endpoint on unconnected nw_connection [connection] nw_connection_copy_protocol_metadata_internal_block_invoke [C4] Client called nw_connection_copy_protocol_metadata_internal on unconnected nw_connection Task &lt;BA37397D-B6F1-46C0-8D1C-BC112FC82956&gt;.&lt;2&gt; HTTP load failed, 0/0 bytes (error code: -1202 [3:-9807]) protocols: ["h3"] Task &lt;BA37397D-B6F1-46C0-8D1C-BC112FC82956&gt;.&lt;2&gt; finished with error [-1202] Error Domain=NSURLErrorDomain Code=-1202 "The certificate for this server is invalid. You might be connecting to a server that is pretending to be “X.X.X.X” which could put your confidential information at risk." UserInfo={NSLocalizedRecoverySuggestion=Would you like to connect to the server anyway?, _kCFStreamErrorDomainKey=3, NSErrorPeerCertificateChainKey=( "&lt;cert(0x108827800) s: X.X.X.X i: Company CA&gt;" ), NSErrorClientCertificateStateKey=0, NSErrorFailingURLKey=https://X.X.X.X:4433/, NSErrorFailingURLStringKey=https://X.X.X.X:4433/, NSUnderlyingError=0x283385560 {Error Domain=kCFErrorDomainCFNetwork Code=-1202 "(null)" UserInfo={_kCFStreamPropertySSLClientCertificateState=0, kCFStreamPropertySSLPeerTrust=&lt;SecTrustRef: 0x280cec1e0&gt;, _kCFNetworkCFStreamSSLErrorOriginalValue=-9807, _kCFStreamErrorDomainKey=3, _kCFStreamErrorCodeKey=-9807, kCFStreamPropertySSLPeerCertificates=( "&lt;cert(0x108827800) s: X.X.X.X i: Company CA&gt;" )}}, _NSURLErrorRelatedURLSessionTaskErrorKey=( "LocalDataTask &lt;BA37397D-B6F1-46C0-8D1C-BC112FC82956&gt;.&lt;2&gt;" ), _kCFStreamErrorCodeKey=-9807, _NSURLErrorFailingURLSessionTaskErrorKey=LocalDataTask &lt;BA37397D-B6F1-46C0-8D1C-BC112FC82956&gt;.&lt;2&gt;, NSURLErrorFailingURLPeerTrustErrorKey=&lt;SecTrustRef: 0x280cec1e0&gt;, NSLocalizedDescription=The certificate for this server is invalid. You might be connecting to a server that is pretending to be “X.X.X.X” which could put your confidential information at risk.} task transport error NSURLErrorDomain / -1202

Hi, I'd like to understand better the differences between the entitlements "com.apple.security.cs.debugger" and "task_for_pid-allow." According to documentation, both entitlements authorize the application to call "task_for_pid()." Is that correct? What are the limitations that differentiate these entitlements? Will the application be able to call "task_for_pid()" for any third-party and unsigned application? Or are there any other conditions? (such as specific entitlements for the target application). Would it be necessary to run the application as root? And lastly, I wondered if any other entitlements enable using "task_for_pid()"? Thank you for your help!

Hello! I am a newby into Apple ecosystem/swift development so forgive me if it is a trivial question. But I cannot find a good tutorial/article on this topic. I am trying to implement a mutual TLS for my iOS application. To generate key/certificate I use https://github.com/apple/swift-* libraries. Next moving to mTLS logic. I use URLSessionDelegate for this purpose as it seems it is the only way to implement mTLS. The NSURLAuthenticationMethodServerTrust part seems fine. Now I am trying to implement the client side of the authentication. let identity = ??? let urlCredential = URLCredential( identity: identity, certificates: nil, persistence: .none) completionHandler(.useCredential, urlCredential) And here is my question. What is the correct/idiomatic way to create SecIdentityRef object out of a private key/certificate? Certificate can be serialized into DER form if needed. I googled for a whole day and did not find a clear information on how to create the identity I need. If anyone has some information on this topic, could you please help me?

I have made my own public key infrastructure that my app uses and I want to support certificate revocation on it. From what I have gather through documentation and forum posts, there is not too much support for that. I have seen mentions of using OCSP stapling, which is probably the direction I want to take. However, I did not see anything showing how to use it. Is it even possible to do so with a custom OCSP authority? If so, how would it be enabled/configured? Thanks

Is it possible to get permission to make an app unremovable? perhaps not permanently, but so the user e.g. can only remove the app after a month from it being requested? It might sound a bit obscure, but it is in relation to helping people with gambling addiction.

Hello, I have a problem with SecItemDelete when trying to delete a private key stored using the data protection keychain on macOS 13.5 (testing on MB Pro 2023). Everything else works: adding the item (using SecKeyCreateRandomKey) getting a reference to the item using SecItemCopyMatching and reading the data But calling SecItemDelete with kSecValueRef and a reference received from SecItemCopyMatching fails with errSecItemNotFound. What's even more interesting, the call to SecItemDelete fails with that error even if passed the exact same search dictionary (omitting the kSecReturnRef key) that results in successfully getting an item reference when passed to SecItemCopyMatching (the documentation of SecItemDelete refers to the SecItemCopyMatching documentation on construction a search dictionary, so, in theory, it should accept the same parameters). I am at a dead end here honestly, and, despite knowing better, I'm starting to suspect this might be a bug in the API implementation. Any help is appreciated. SecItemCopyMatching call: auto params = cf::create_dict({{kSecClass, kSecClassKey}, {kSecAttrKeyClass, kSecAttrKeyClassPrivate}, {kSecAttrLabel, cf::from_string(create_key_name(name))}, {kSecReturnRef, kCFBooleanTrue}}); SecKeyRef key_ref{nullptr}; auto status = ::SecItemCopyMatching(params.get(), (CFTypeRef*)&key_ref); SecItemDeleteCall with ref from SecItemCopyMatching: auto query = cf::create_dict({{kSecValueRef, key}}); sec::throw_if_fail(::SecItemDelete(query)); SecItemDeleteCall with search by key label: auto query = cf::create_dict({{kSecClass, kSecClassKey}, {kSecAttrKeyClass, kSecAttrKeyClassPrivate}, {kSecAttrLabel, cf::from_string(create_key_name(name))} }); sec::throw_if_fail(::SecItemDelete(query)); Private key creation params for SecKeyCreateRandomKey: {kSecClass, kSecClassKey}, {kSecAttrKeyType, kSecAttrKeyTypeECSECPrimeRandom}, {kSecAttrKeySizeInBits, cf::make_guarded(::CFNumberCreate(kCFAllocatorDefault, kCFNumberIntType, &bit_length.at(key_spec.curve)))}, {kSecAttrIsPermanent, kCFBooleanTrue}, {kSecUseDataProtectionKeychain, kCFBooleanTrue}, {kSecAttrLabel, cf::from_string(create_key_name(name))}, {kSecAttrIsExtractable, storage_spec.exportable ? kCFBooleanTrue : kCFBooleanFalse}

I regularly see folks confused by this issue, both here on DevForums and in DTS incidents, so I thought I’d write it up publicly. If you have questions or comments, start new thread here on DevForums. Tag it with Foundation, CFNetwork, and Security so that I see it. Share and Enjoy — Quinn “The Eskimo!” @ Developer Technical Support @ Apple let myEmail = "eskimo" + "1" + "@" + "apple.com" Debugging HTTP Proxies and Certificate Transparency Some developers think that Certificate Transparency (CT) will prevent the user from using a debugging HTTP proxy to inspect the requests issued by their app. That’s not the case. This post explains why, and offers advice as to what you might do about that. About debugging HTTP proxies A debugging HTTP proxy works using a process known as TLS inspection [1]. In rough terms: The user sets up their debugging HTTP proxy. The proxy creates its own, internal certificate authority (CA). The user installs that CA’s root certificate on their Apple device. And configures their device to use their proxy. When the device makes an outgoing HTTPS request, it makes a TLS connection through the proxy. A normal proxy would pass the connection through to the origin server. A debugging proxy does not. Rather, it uses the CA it set up in step 2 to create its own certificate for the origin server. It has the private key for that certificate, and thus can recover the plaintext from the TLS connection. The proxy then makes its own TLS connection to the origin server and forwards the plaintext down that. Debugging HTTP proxies are a great tool for app developers. For references to some of the more popular ones, see Taking Advantage of Third-Party Network Debugging Tools. Note Historically such proxies were a critical implement in any app developer’s debugging toolkit. These days, however, it’s often easier to use Instruments to inspect HTTP requests. See Analyzing HTTP Traffic with Instruments. [1] Well, different folks use different names, but TLS inspection is the name that I prefer. And it seems that I’m good company (-: https://www.schneier.com/blog/archives/2019/11/the\_nsa\_warns\_o.html That post’s link to the original NSA article is broken, but you can view it on the Wayback Machine: https://web.archive.org/web/20191119195359/https://media.defense.gov/2019/Nov/18/2002212783/-1/-1/0/MANAGING%20RISK%20FROM%20TLS%20INSPECTION\_20191106.PDF About Certificate Transparency Certificate Transparency is a technology designed to protect the user from misissued certificates. Apple platforms support CT out of the box. For more on that, see the links in Networking Resources. Historically CT was not enabled by default. However, an app using URLSession could opt in to it by adding the NSRequiresCertificateTransparency property to their App Transport Security (ATS) configuration. This is no longer necessary. Starting with iOS 16 and its aligned releases, CT is always on, and thus the NSRequiresCertificateTransparency property is no longer useful. Crossing the streams Some developers think that Certificate Transparency will prevent the user from using a debugging HTTP proxy to inspect the requests issued by their app. That’s not the case. Apple’s CT support is focused on protecting the user from certificates misissued by the built-in trusted CAs [1]. It’s not relevant for certificates issued by a custom CA, and thus it doesn’t block the operation of a debugging HTTP proxy. If you want block the operation of a debugging HTTP proxy, the easiest path forward is the NSPinnedDomains property. For the details, see its documentation. IMPORTANT Some enterprise environments rely on TLS inspection, and it’s likely that this will prevent your app from working in such environments. If your app supports older systems, or the rules of your pinning policy can’t be expressed by the NSPinnedDomains property, you can implement your own policy by overriding HTTPS server trust evaluation. For advice on how to do this with URLSession, see Performing Manual Server Trust Authentication. [1] That is, a CA whose root certificate is trusted by the system by default. For a link to the Apple Support article that lists the built-in trusted root certificates, see Networking Resources.

We have our own root CA that is installed with our application. For non-MDM installs, the system asks if the user wants to do that, which is all well and good. It also used to ask us when removing that certificate. It doesn't now. So now I am wondering if I dreamed it, except other people say they also got prompted and don't now. It's being installed and removed using the security command, in scripts.