So as Bill said, I'm Ken McLeod and I work on this thing called Keychain, which we're going to go through today. So hopefully we have some exciting stuff to tell you about, much more exciting than what's going on next door. We'll give you a quick overview of what the keychain is, and then we'll update you since we talked to you last year about what's been going on with the keychain.

will tell you about the Keychain Manager APIs and answer your questions about where they fit with Carbon and where they are on OS X. And then at the end, we'll tell you where we're going with the APIs. And finally, we'll have a demo, of course, and Q&A. Hopefully what you'll take away from the session is a knowledge of what the keychain provides for you and especially what APIs will be in Carbon so you can go out and add keychain support to your applications.

So what is the keychain? The keychain is a repository that's secure. An analogy I use is a bank vault. The bank vault door closes and the things that you put in there are secure. The things that you put in there are passwords, cryptographic keys, digital certificates, the bits of information that sort of authenticate you or private bits of data that unlock other things or decrypt pieces of data. The keychain is built on top of this framework called CDSA, which is the common data security architecture that originated at Intel, and that's an open group standard. I believe they've announced plans to open source their implementation.

The keychain has a really neat feature in that it enables its clients to provide something called transparent authentication. That's the ability to log in once and then any servers and things that you have passwords stored in your keychain for, you'll just be able to connect to them transparently through clients that use the keychain.

The keychain is first introduced and shipped with Mac OS 9 and it's available there and going forward, of course, on 10 and later. So let's define some terms that are important when talking about keychains. Keychain is always in one of two states. It's either locked or it's unlocked. And when it's locked, you can't retrieve data from the keychain. You need to unlock it in order to do that.

Every stored password or key or certificate, things that are in the keychain, we call keychain items. And we'll go into it in a little bit, the things that all keychain items have in common. Then we have this notion of the default keychain. That's the one, if you have multiple keychains, that's the one where new items are added.

So a system can have more than one keychain. You can have some locked, some unlocked, put some types of keys or server passwords in one and copy one to a server and use it over the network if you want. Typically we see that there's one keychain per user, but certainly the ability to have more than one is there.

Keychains can be set to lock automatically, so you don't have to go off, for example, leave your desk and worry about whether or not someone can come up and access things that are in your keychain. And the keychain is scriptable. So everything that you can access through the keychain API, you can get out through Apple Script.

Keychain files can be moved around from one machine to the other, which makes them very useful. You can take your keychain from work to home and have it available there. You can have it on the network. At this point, I have to tell you that keychains will not be portable between 9 and 10.

Now, that was a decision that we did not make lightly, and part of the reason is that the keychains on OS 9 use encryption algorithm which is patented and we're trying to move away from. We're trying to get rid of any things that would prevent us from open sourcing this at some point in the future.

But when you go from 9-based keychains to 10-based keychains, we hope to provide some kind of updater that will just convert them so you can go easily. But if that's going to be a problem, please let us know about it. Like I said, keychain files can be on servers. You can use them over the network and you can use them on locked media. So you can open a keychain read-only.

Most important for where we're going in the future, the CDSA architecture on which the keychain is built allows you to have keychains on smart cards and removable tokens. These things just appear as keychains to clients of the keychain API. And when there are modules to plug into the underlying CDSA architecture to support these types of things, we actually have one working, but as there are other ones that are provided, these things just show up and you can use them in the keychain.

So, lots actually happened since last year. We're in OS 9 and not just shipping, but we're actually an integral part of it. There are a lot of system components that use the keychain and are tied to it. If you used the Apple share client, you'll know that it can store passwords in the keychain. And other components like network browser and even airport and Apple file security, AFS, all use the keychain for password storage.

We shipped a security SDK which includes the keychain and URL access and Macintosh file signing and the CMS technology, Cryptographic Message Syntax. And all those things are available now. Hopefully some of you have had a chance to look at and use them, play with it. Copy that URL down because a lot of good stuff there. The keychain is now in DP4. If you've had a chance to install that, the APIs are in there.

is still kind of a development release, still working on it, and it requires you to link to the security HI framework in order to actually get at the Keychain API. That won't stay the case. We're very close to actually having this fully in Carbon on both 9 and 10. We just missed the DP4 train, but you can still use DP4 again if you link with security HI framework.

So this is a map of where the APIs are and where you can call them from. It's actually a pretty important slide. On the left-hand side are legacy apps, which are your pre-Carbon Mac OS 9 applications. And the APIs that are there are those that we ship with Mac OS 9, the keychain, URL access, iSign, which is Macintosh file signing, and the CMS APIs. All those are still there in Classic. And they're built on top of CDSA 1.2.

So those apps will just work in Classic on OS X, and they'll continue to work on Mac OS 9, of course. The middle box, Carbon applications, sort of straddle this line between Mac OS 9 and Mac OS X. The APIs that are in Carbon will be keychain and URL access. So a Carbonized application that can run on 9 or on 10 can make use of those APIs.

One thing that we did after Mac OS 9 when we sort of looked toward the future and integrating with OS X is how to factor the pieces, the functionality that we had in the Keychain API and make it available for, you know, not just Carbon applications but, you know, BSD Unix applications, Cocoa apps across the board. And when we re-architected this, we realized that a number of things had to be separated out, especially key and certificate management.

will be talking about the things that required keys and certificates. Mac OS X apps as a category are those applications that will only run on Mac OS X. That could include your Cocoa apps, your BSD Unix apps, and also Carbon applications that make use of those APIs such as file signing. And the piece there that we're calling Security Core, which includes keychain APIs and some newer versions of those APIs that you can use from lower levels that don't require UI, which I'll get into in a little bit.

Again, those applications, 10 applications and Carbon applications that you're running on 10, sit on top of the CDSA 2.0 API. And that's a big step forward from 1.2 in the amount of things that it lets us do. It lets us have, for example, something called access control lists so that each individual item in your keychain can be protected separately. And you can allow certain applications to access certain items and not access other items. And all those things are sort of enabled by CDSA 2.0.

So you're an application, you want to use the Keychain API, what can you store in the Keychain? There are three basic classes of items that go into the Keychain: keys, passwords, and certificates. And each of those classes has subclasses of items that we support. The middle column there, passwords, is what the Keychain API is primarily focused on in this release and in Carbon.

Every keychain item has two components. They have attributes and they have data. The data, in this case, in this example, is just a password. But there are additional attributes that sort of hang on to that password and allow you to find it again. In this example, for example, I have my account name, Ken, and a server and a path on that server. These are all just bits of data that you can attach to the password and that help you find it.

So all these items that are in the keychain have these common attributes, the class of the item, the date created, the date modified. Every item has a label, the thing that shows up when you view it in keychain access. It has a description and a comment, which is all optional. Within those subclasses, of course, every item has additional attributes that you can look at.

Internet password items, for example, have a server name associated with them and things like the protocol that's used for that particular password. attributes, as I said, are used just to find the item. The actual thing that you're storing in the keychain and what you're keeping secure is the data.

Now, the item data can't be searched. You can't look for all items that have a particular password, because that wouldn't be too secure. You can't get the data out unless the keychain is unlocked. And you can't retrieve the data of an item without the user's explicit permission. Now, what that's meant in the past, if you've had a chance to play with a keychain on OS9, is that every time you go to get something out of the keychain, a dialog pops up and asks you, do you want to allow access to this item? That's been a problem.

If for no other reason, then users just get conditioned to hit the Enter key every time. So we're moving away from that dialog. It would come up no more than once. And we're going toward the ability to let you preconfigure access for your items. In particular, very important, cryptographic keys, private keys, and symmetric keys, the data of those items can never be retrieved from a keychain.

So how secure is the keychain? Well, for one, and I think this is pretty important, it doesn't actually depend on the machine's physical security. It's stored in an encrypted format, so you don't have to write down your passwords or store them in a preferences file or store them in a sticky note somewhere on your disk.

The keychain file itself is encrypted. And the password that unlocks your keychain is never stored anywhere on disk. What we do is run it through an algorithm called PBKDF2, which is specified in RSA's PKCS5 standard. And what that does is it derives a key every time from your keychain password.

A little bit about the encryption that's used. And again, I said that we were trying to move away from what we were using on Mac OS 9. to something a little better on OS X that did not prevent us from, at some point in the future, doing what Darwin has done. The current plan is to use triple DES, although I've talked to some of you and some of you brought this up in another session, that there are perhaps other algorithms that we can use. So we were certainly looking forward to any feedback that you have about that.

Now normally, the keychain is unlocked with a password. A dialog box comes up and it asks you to unlock the keychain. You type in the password and then the keychain is unlocked and items can be retrieved. If you type the wrong password in, every time you do that, the delay grows between the amount of--the time when that dialog can come up again and new passwords are accepted. So this sort of prevents a systematic attack, a sort of virtual user type thing where it just types in the password into the dialog over and over.

We allow programmatic unlock. In OS 9, it was limited. Essentially, if you use the programmatic API to unlock the keychain and you got the password wrong the first time, that was it. You'd have to restart in order to try that again. And, but, you know, effectively shut down that opportunity, but it also prevented a lot of people from

Now, again, data of the items can't be retrieved without some sort of explicit permission that the user has granted. This permission can be given on a per item basis, a per process basis, or an entire keychain, you can say. Always allow everything in this keychain to be accessed without bothering me.

Again, in OS 9, we had a problem identifying processes. It would be nice to say, "Okay, always let my web browser or my mail client access the password and the keychain. You know, don't bother me." The problem was when that client quit, something else could start up and say, "Hey, I'm the mail client. Give me the password." And there was actually no mechanism in 9 to prevent that. So in 10, we can actually do a digest, a cryptographic digest of the process, store that, and... will securely allow in a pre-configured manner access to keychain items.

Now, cryptographic keys in your keychain in 9 optionally required a password in order to use them, not just to unlock the keychain itself to get at them, but every time you went to use them. The CDSA 2.0 API in Mac OS X is going to allow us to provide that sort of per item protection optionally for every item in your keychain.

So what can you do with the keychain? Well, if your application at any point asks the user for a password and needs to store it somewhere, you can store that password in a keychain instead of having to worry about how you're going to encrypt it or where you're going to store it.

And also, you really want to allow the user the opportunity to save off the password that you've asked for so that in the future, they can come back and they don't have to type the password over and over as they access whatever it is that needs the password. And you can also store keys and certificates. This is a piece of the functionality that is moving out of the keychain API in Carbon to that other box that I showed in the previous slide that's going to be a Mac OS X technology.

So let's go over the APIs that are in Carbon. There are high level calls, which are very easy to get started with. Those high level calls actually have some underlying low level routines to do bits and pieces of functionality that you may need. The API allows you to search for items.

That's its primary sort of

So the first thing you need to do is call this routine keychain manager available. The reason for that is that it may not be there. If your application is a Carbon application running on, say, 8.1, the keychain is not going back that far, but your application can still be running as a Carbon app. So you need to test for it to make sure that it's present.

You also don't need to explicitly create a keychain to get started with unless your application needs to for some reason, but the preferred way is to let the user be in charge of that. If you need to store something in a keychain, you can just store it and all of the sort of housekeeping of setting up a keychain will be taken care of for you by the API.

And then finally, you'll just use a high level call to find a password in the keychain. So there are three basic API routines to get a password. Find Apple share password, Internet password, and generic. And all of these take a number of attributes that you're looking for, maybe a server name, an account name, and will return the password to you.

And conversely, we have-- those actually should say add instead of find. But we have the similar routines for adding a single password to the default keychain. So just mentally replace the word find in each of those with add and you have the idea. So those high level calls are actually made up of a number of sort of individual factored pieces.

When you're calling add internet password to put something into the keychain, it's actually doing the work of all of those items that you see there on the right hand side to set up the item, to associate it with a keychain, to associate the attributes you passed in, and finally to update it and write it out to the keychain storage.

So the new item call will create a new keychain item. And when you do that, it's just in memory, and it's not associated with any particular keychain. You want to add it to a keychain, you'll call add item. You'll always access items through a KC item ref. That's sort of the common denominator, the format that all items, whether they're keys, passwords, or certificates, can be manipulated You'll use get attribute to retrieve a particular attribute from an item. and set attribute to change the attribute. And the same thing with the data. Get data will retrieve the data of the item and set data will change it.

When you've changed an item, whether you've added new attributes to it or changed them or changed the data, you'll want to call updateItem, which actually commits the change and writes it to the keychain. And finally, when you're done with an item, you can release the memory that the item occupies by calling kc.releaseItem.

If you need to find more than one item in the keychain, you can use find first item and find next item. Fairly straightforward. They take a list of attributes, things that you're searching for, and they'll return a search reference to you. So you can continue to call find next item as you need to to find items that match your search criteria. And then when you're all done, you'll call release search.

Now, as I said before, most of the time you want to allow the user to create their own keychains. But there are calls when you need to create a keychain yourself. And when you need to sort of iterate through the keychains, perhaps you're looking for a particular keychain with a particular set of attributes, you'll access those through a KC ref.

A KC ref is an opaque structure. Currently, everything on the system is a keychain file, but that's changing. And it's very important not to assume that a KC ref or a keychain is actually an FS spec or a file on the system, because it could be a smart card. It could be any kind of device that's pluggable into the CDSA layer on the bottom.

We have a get status routine. You'll probably actually use that when you need to determine whether a keychain is locked, unlocked, whether it has read-only access before you try to store something in it, for example, and other status flags. Keychain name returns, like it says, the name of the keychain. You'll use count keychains to figure out how many keychains are available and get in the keychain, which is get indexed keychain, will return a particular keychain out of that list given an index.

So this is an interesting part of the API, notification. When anything happens in the keychain, you can be notified and take some sort of action. Maybe you want to write a logging app that logs all accesses to the keychain. You can do it with this. What you do is register a callback procedure with KCAD callback.

You can give it a bit mask that specifies the actual events that you're interested in receiving. You don't have to deal with all of these. But we'll tell you when a keychain unlocks, when it locks, when something's added, when someone does a search and the item is found.

We'll certainly tell you when someone retrieves an item. That's the get data event. We'll tell you when an item is deleted, updated, and we'll tell you when the default keychain has been changed. When you're all done and you don't want these events anymore, you can call Casey Remove Callback and then you won't get them.

So here's a real simplified example of a routine that your application might call. I have a connect to server routine and the two parameters there are the server that I'm connecting to and who I want to connect as, what my account name is. So the first thing I do there, actually the first thing I do would be to call keychain manager available, but that's just sort of assumed.

So I can call Casey find internet password. And the things that I'm interested in when I want to look up this password are of course the server name. So I'll pass that in. I don't actually care about the security domain which is a string so I'll leave that nil. I could specify a particular constant there. I do want to look for a particular account name that matches. I really don't care about associating a particular port so I'll pass any port.

This is an HTTP password so there's a constant that I'll pass in that says I only want an HTTP password. Use the default auth type, authentication type. There may be different authentication types that you can associate with the same server and you can distinguish them with that parameter.

Then I'll pass in a buffer that I've pre-allocated and the length of that buffer. When the call returns, assuming that a password was found, that buffer will be filled out with the password data and then actual length will contain the length of that So then if that all went well and I found a password, the return value status is going to be no error and so I can just connect. If it's not, I need to look at that, do something else, ask the user for a password with my own UI, whatever I need to do there. And then finally at the end, I've got a password and I can connect.

I said that everything you can do from a C API you can also do from Apple Script with the keychain. Here's a real simple example. I have the first internet key of the current keychain. The whose clause at the end there is doing all my searching. So I can add attributes like whose account is Ken and whose server is ftp.apple.com.

I can string a list of those together to sort of specify the item I'm looking for. If the item is in the keychain, it'll be returned in the item. And then I can get particular attributes from the item such as password of the item. And then this sample just displays the password, which is obviously not something that you ever want to do.

So which keychain APIs are actually in Carbon? Well, the good news is the things that were in Universal Interface's 3.3, I believe we're up to 3.3.1 or 2.3 actually, all of those calls with two exceptions are part of Carbon. So those will be there. They'll be there in Carbon lib and they'll be there in Carbon framework on 10. We had a keychain 1.0 API.

I know that some of you in this room actually used it and, you know, it's a little bit of Unfortunately, it didn't actually ship until we were at Keychain 2.0. But, you know, we put in some code that actually kept Keychain 1.0 working and everything was supported on OS 9, with some exceptions which were noted at the time.

: Going forward into 10, that will be removed. There is a document in that security SDK : I think the primary one is not to use a keychain specification, but you always want to use a KC ref, which is that opaque reference. And that allows things like smart cards and other forms of keychain to work.

So we'll be in Carbon Lib 1.1 on OS 9. I think that We may actually be in there even as we speak in the current D build of 1.1. The next sort of build cycle will get that in. So it's imminently there. And on OS X, we will be on the Carbon framework. In DP4, as I said before, you need to currently link against an additional framework, Security HI. But certainly by the time this thing reaches public beta, we will be fully integrated.

So what do you have to do right now to use the keychain? Well, there's a list here. First of all, the current interfaces define this weird symbol, call in keychain but not in Carbon, which is kind of a mouthful. It's a workaround, so if you define it to true, you'll get all of the keychain calls.

The caveat there is that as well as defining that, you need to link to one of two libraries. On 9, you need to link still with keychain lib until that 1.1 build of Carbon lib is done. And on 10, you need to link against security HI framework. So right now, today, there's not the ability to have a CFM binary that you can just build on 9 and take over to 10 and that will run using the keychain. But certainly that will be possible by public beta.

I should also point out that DP4 does mean developer preview, and it is a preview. We are not done. And one of the things we're not done with is the encryption. So you may, you will definitely need to know that encryption has been disabled in DP4. So do not rely on keychains that you create in DP4 to be secure. Just a warning.

Take those APIs that we had in Keychain on OS 9 and move them into a, factor them into a way that they can be called from applications that don't bring up UI. That was sort of a problem that we had with the current release. You were forced in some cases to bring up UI to unlock a keychain if the keychain was locked in order to do anything. If your app couldn't bring up UI, then that was a problem. Another problem was that there was no way to add items to a specific keychain. All items went to the default keychain, whatever that happened to be. So we needed to correct that.

Going forward on 10, these APIs will be part of security core and part of the, The OS X frameworks, they won't necessarily be in Carbon as we move forward. The APIs that we have there in place now are certainly in Carbon. But the new key and certificate management based things that will interoperate with the keychain are OS X only.

So the first part of those new API routines solve that problem of what can happen or what needs to happen if you can't bring up any UI to unlock or authenticate. And we had a routine, and we still have a routine in the SDK called set interaction allowed which lets you turn on or off any user interface coming up. The problem of course is that if you turn that off and the keychain is locked then we just return an error and that's not very useful.

So the new APIs will require credentials to be provided. And this is something that is, again, supported by the underlying framework, the CDSA framework that we're built on top of in OS X. So the APIs will let you provide some sort of credential which can be either a password, it can be a token, it can be as simple as here's the process that I am, did I have a digest that was pre-approved.

There will be a callback where you can provide that information that the keychain needs without popping up a dialogue when it needs it. Ultimately, we want to move towards certificates as a way of authenticating that items can be retrieved and sort of verifying the identity of the process that is trying to retrieve them.

Another problem that we had is how to add an item to a particular keychain. What you had to do previously is to save off the default keychain whenever you were going to add something to your own keychain. You'd have to set it as the default. You'd have to put the item in and then sort of swap it back to save the user's or restore the user's default keychain. That was pretty messy. So the new APIs in OS X will have an optional keychain parameter.

So I mentioned the keys and certificate APIs that were part of Keychain in OS 9. We really only had two API routines and I'm not aware of anyone that actually used them. Please come up afterwards if you use them and heavily depend on these. But to factor out these and be able to, as I said, look forward, is the developer of the new CSA 2.0. We've had to move the certificate handling out of the keychain proper.

So these two routines will not be there going forward in 10. They'll still be available on 9 and they'll still be available on Classic, but we'd like you to get away from using them and use the ones that we'll have going forward. The new routines will be provided as part of that security core piece, which is an OS X technology.

One big reason we want to do this is to avoid dependence on Carbon. So if you are, for example, a BSD Unix app, you don't want to depend on Carbon and have all of this. And I don't know in every case whether it's even possible to have that dependent.

So what this all means is that we're not taking away keys and certificates. They'll still be there and they'll still be visible in your keychain. They'll just be put in from a different sort of vector. You won't call add in the keychain. You'll add from the security core APIs and you'll even add from the lower level CDSA APIs if you want to go down that far and use those.

All of the CDSA headers are available. They're on the Open Group's website, which is opengroup.com/cdsa. And you can find them on opengroup.org, I believe. I have a URL for them later on in this talk. But you can look at those, certainly. And items in a keychain are certainly accessible at that layer.

We are working on higher level interfaces, obviously, to sit on top of those, which will -- or to be available by public beta. I'm sorry. Those are actually the ones that we're working on for the release right after public beta. So this is the part I've been looking forward to, and mostly because I know that there's no way MaxBug can pop up. So it's going to be good. If we could have demo one up on the screen, I can actually go to that. Okay, great.

So the first thing I'll do is look at Keychain Access. This is the new Keychain Access. Maybe some of you have actually already installed DP4 and have had a chance to see this. But it looks a lot like the Keychain Access that's in OS 9, except of course it's carbonized and it has the Aqua look and feel. So I can have columns that resize and all those neat things that you get with Aqua and Carbon.

When we shipped OS 9 we listened to a lot of feedback on this and there was a lot of user feedback. And of course number one was why doesn't my web browser support the keychain? But number two was how do I get something into the keychain? And there was no clear way.

Yes, you could drag mounted servers into the keychain, you know, and you could add passwords there. But it wasn't real apparent how you would, you know, store something, for example, you know, a credit card number or, you know, the password to your E-Trade account. Or, you know, these bits of data that people have been writing down on their palm pilots and on sticky notes. It wasn't real clear how to get that in. So we've added an add button. And that just allows you to put in your account name and a location. Maybe this is the password for my WWC demo. And I'll type it in.

Add it. And then I can get a password in that way. And it becomes a little more useful for people to use. Another feature that we've added to keychain access is the ability to manage your keychains a little better than you could before. So, for example, you may have a list of two or three keychains or you may have a dozen keychains and maybe you don't want all of them to be searched when applications call find and applications are looking for things in your keychain. So you have the ability to turn on or off whether these things are included in the search and you'll have the ability to reorder the search order from a dialog. So these are things we're working on.

What I'd like to do now is run the Carbonized version of Fetch, thanks to Jim Matthews. This is an FTP client for the Mac that's been Carbonized. And I have a shortcut here, actually, that goes to a server that I have an account on. So when I double-click that, Fetch, like most clients, needs a password for this server because it's a password-protected account.

So it pops up a password dialog. But in this password dialog is a checkbox that lets me, as the user, decide whether or not I want to add my password to the keychain. And that's actually very important. You don't want to force people to use the keychain. You always want to give them the option. I'll add that. I'll log into my server. And if I sort of go back to keychain access here, I see that it's added a password for that server to the keychain.

So I can look at it, see that it's in fact an internet password, see the URL, the account. And this looks an awful lot again like OS 9. What's not there and what we are working on is those access control lists that I mentioned. So given that item, I want to be able to allow

And of course, the next time Fetch needs to access it, I can just open it. And it doesn't pop any password dialog because he's called find internet password and it was there in the keychain, so he was able to use it.

And I can close the connection again and I can open it again and still no password. I can do that all day long. But of course, I can also remove this password from the keychain if I don't want it to be used anymore. And then fetch can't use it because it's not there and it has to ask again. So that's just a basic demo of Keychain in OS X. And if we could have the slides back, we can wrap up.

So just to wrap up, the keychain is a repository. It's like a bank vault, like a safe. It's the place that you can put your secure data in. It's provided for you as a system service so your application doesn't have to do all the work associated with making these things secure and hopefully even for asking for the data that you need to authenticate. It's very easy to use.

You really only need two to three calls to get your application using this. And you can get started now. You can get started with DP4. The APIs are there. Again, with the one note that you need to link with security HI framework. And certainly the security SDK is out there for 9, which you can also look at.

Unfortunately, the problem with this slide is that everything's already happened, but you really, if you can, want to take a look at security directions. That gives you more information. And I'm not sure what media the session will be available in afterwards, but if you get a chance to look at a recorded version of that, it's very important to see how CDSA 2.0 fits in. Um.

For more information, we have the SDK available on the website and we have updated documentation. So you should all look at the PDF file that's up on the Carbon, the TechBubz Carbon website. And the documentation is also available in HTML format on the DP4 CD. So if you look in, I think, system documentation, in that path, you'll find all of the keychain manager documentation.

If you're interested in sort of drilling down and getting to the CDSA API layer, CDSA is documented at the Open Groups website. You can go there for more info. And if you're interested in developing smart card plugins or the ability to have these things show up as keychains, that was talked about, of course, in the security direction session. But for more info, take a look at the PCSC workgroup website. So...