Good morning, I'm Craig Keithley, I'm Apple's USB security cryptography evangelist. Today we're going to talk about CDSA and Secure Transport. One of the challenges faced with moving to a new operating system is what sort of security infrastructure we provide. And in the case of Mac OS X, we looked around and we found that CDSA suited our needs best of all. It's an open standard. It's open source.

It provides the services we need. It will even interface down to smart cards. So it was really the right solution for us. So to talk about CDSA, we want to bring out John Hurley and later for Secure Transport, Murph. So, John? Thanks, Craig. Good morning, everyone. Thanks for getting here so early.

So I'm going to start off with kind of a brief introduction to CDSA. One of the things that we wanted to particularly do today was really dive down into some code, because you guys are all developers and

So we're going to talk mainly today in this session about CDSA and using it for cryptography, and then also about the SecureTransport APIs, which are being made public for JAGUAR.

I'm going to do a quick overview of the architecture itself so you have some idea of where the pieces fit in. Then we're going to go into just using it directly, the APIs for doing crypto, and also talk about using CDSA for SSL. So CDSA itself is Common Data Security Architecture. Originally it came from Intel and we shipped a version based on the 1.2 standard in OS 9.

Moving to OS X, we are now shipping the 2.1 version. Based on our experiences with the 1.2 version, we provided a lot of input to the open group and the other members that were working on that standard. The 2.1 spec is much easier to use and much more standard. There were a lot of pass-throughs and things like that in the 1.2 spec. This is the foundation of all the PKI, public key infrastructure, and cryptography, SSL, all those things that we do in OS X.

So here's kind of the big block diagram of CDSA. And the CDSA APIs themselves, it's kind of that blue bar down at the bottom labeled CSSM. Those are the actual CDSA APIs. And the Having that kind of go across the screen indicates one of the main goals of CDSA, which is we're trying to isolate applications up above so that the applications that you see at the top in blue, we really want those to not have to know about all the details of the crypto and other things down below. Most developers are not 100% interested in security.

They have one or two needs in their application, and they kind of want to just use things and get on with it without knowing all these details. And I think we've really seen some good results with achieving that insulation in the apps that we do internally at Apple, and now we're seeing developer applications really making use of that as well. So the... The red...

Down below, we have the add-in modules for CDSA. And so CDSA is a pluggable architecture. You can extend it by writing modules and plugging these in. The cryptographic service provider implements various crypto algorithms.

I couldn't even tell you how many we implement in the default plugin, but it's quite a lot. All the standard ones and a bunch of weird ones, too. But anyway, those are all in the CSP. If you wanted to put in different, you know, some kind of different crypto or like a hardware accelerator box or whatever, that would be the place to put that in. On the far right there, the Datastore library is, roughly speaking, it's a database for storing security-related items. And in fact, it doesn't actually have to have any security associated with it at all.

Those could be, it could be an LDAP database, for example. The keychain is actually a combination CSP and Datastore library. And the... The modules in the middle, Certificate Library Module and Trust Policy Module, are for handling X5-09 certificates. And I'll talk more about those in just a minute.

Data Library modules is the database portion of CDSA. I suppose you could put an Oracle backend on it or something like that, but that's probably overkill for the kind of things that you're doing in security. As I mentioned, the Apple file CSP DL, that's the basis for the keychain, and it is a combination of CSP and DL. So as you're storing information into the keychain or retrieving it, it's encrypting it as it puts it into the datastore module.

and Keychains themselves are just flat files. Another example, which A very interesting example is an LDAP DL. Putting, for example, certificates in an LDAP DL really would make a lot of sense because by their very nature, the public key part of that is, well, it's public, so LDAP directory would be a perfect spot for that.

Certificate Library modules. The whole goal of a Certificate Library Module is just to be able to parse a certificate. So going up into CDSA, clients that are using certificates are going to need to know things like the issuer and the expiration and subject and various things like that.

And the CL basically knows how to find that stuff in a particular type of certificate. So the standard CL that we ship with Mac OS X knows how to interpret X.509V3 certificates. Other examples that would be possible, although they don't exist right now, would be a CL that knows how to interpret PGP certificates or attribute certificates. Those would be a standard. both be really good examples of things.

Trust Policy Modules, on the other hand, that's sort of the other part of the certificate equation, If you have a particular certificate, one of the main questions that you want to ask with that is, "Do I trust this certificate?" And so the idea of a trust policy module is that you take the certificate that you're trying to decide whether you trust or not, and you take some additional evidence, which is, in the X.509 case, it's usually the rest of the certificates in the certificate chain, pass that all into the trust policy module, and then let it churn away and return the answer whether it's trusted or not. And if not, which certificates might not be right or whatever.

So there's actually, the Trust Policy Module has a lot of potential for doing interesting things. You could do different corporate-based Trust Policy Modules. There are a lot of interesting things there. For example, in the PGP case, that would also be-- to integrate PGP into OS X would pretty much be writing a CL and a TP module that knew how to interpret PGP.

Okay, so one of the main things that we wanted to talk about is contrasting CDSA with OpenSSL. And at Apple, we've made a conscious decision to try and evangelize CDSA because we've worked with these things and We have seen the solutions that we can arrive at with CDSA. We really think that it's a more secure setup. It's actually easier to use.

I think one of the main reasons that OpenSSL has sort of gained some currency is just that there's sample code available. We're really doing our best to get more and more CDSA sample code out there. So you can kind of go and grab sample code and either do some quick encryption or do some certificate stuff. We're really trying to make those things available.

Of course, we'll have a lot better integration with other applications and services that we provide at the higher levels because internally at Apple, we are going through CDSA. So that's the direction that we're encouraging people to go in. To explain a little bit more about the more secure bullet point, for example, in the SecureTransport case, SecureTransport knows how to deal with reference keys, so it's not actually dealing with the key bits itself.

In the OpenSSL APIs, you're actually required to pass key bits in through the interfaces. So that means that you actually have to have the key bits available. Well, in the case of something like a smart card, that's not going to be the case. You will not be able to even have those key bits. So that's one example where we just feel like it's a better setup. up. Now I'd like to introduce and bring on Richard Murphy. He's the manager of Data Security Group.

Thanks. Hi, everybody. Thanks, John. So, I wasn't originally supposed to be doing this lecture. My engineer up in Seattle, Doug Mitchell, is going to be doing it. He's really kind of the group's crypto head. He knows all about these algorithms. He maintains the CSP in the CDSA stack. He also did the SecureTransport layer as well. So, Doug had something come up, and I said, "That's okay." I said, "Ship me some sample code, and I'll walk through it, and everything will be cool." So he shipped me a sample code of CDSA doing encryption of a blob.

and he shipped me a sample code of SecureTransport doing a GET operation. and it was really, really interesting going through this. First of all, I looked at the CDSA code and I kind of went, "Oh, my God, there's a lot of code there." And then I looked at the SecureTransport code and I went, "This is a lot easier. This is a lot more sane." So I'd like to back up just a little bit first.

It really brings home this whole layering thing here. We did base our security strategy, our crypto strategy, on using the CDSA stacks. The Common Security Services Manager here , along with its attendant CSP, or Cryptographic Service Provider, the cert library, the trust policy manager, and the data store library.

CDSA is extremely powerful. It has a whole bunch of options. It has a whole bunch of different ways to configure it. Furthermore, you can expand it by plugging in different CSPs, different CLs, and that sort of stuff. As John says, said, we can work with PGP certificates if we replace the CL and the TP, rather than the X509 certificates that Apple's currently supporting.

We could write an interface to plug in a hardware crypto box where the CSP is, or work with smart cards. We could work with an LDAP data store, or something like that, rather than a file data store like we currently use in the data store library. But, one of the things that does is it means that that layer, that common security services manager layer, has to do a lot of stuff to make things look common. You have to generate context.

The example, um, encryption code using just CDSA.

What this thing has to do is initialize some local variables. It ends up creating a CSSM key, which is the way that keys are actually passed around through the crypto algorithms in CDSA. It copies in the caller's key material. So this is a standard encryption call where you're passing in a password or passphrase or something like that.

So the header for our function looks like this. It's a do_encrypt. It's going to take a CSP handle. We'll talk about that in a second.

CSP Handle, I was talking to Doug earlier this week, and I said, "So, what's the CSP Handle thing? How much does it take to do that?" He said, "Well, you have to initialize CSSM, you have to load the CSP module, you have to attach it." So, this all kind of pointed me at, boy, this has got to get a little bit simpler.

So, more on that a little bit later. We have some local variables. We have a CSSM key, which is actually gonna be used to hold the generated key itself. We're going to have a handle for doing the context operations. A UN32 variable key length to actually do all the type conversions for us for the actual key length to get it in the right order.

A label for the actual key itself. An initial vector. We're going to be using AES as our encryption algorithm. This is a block mode cipher. We have to have an initial vector for it. We'll have bytes encrypted for a return variable, total number of bytes that have actually been done, and then the remaining data structure.

So the first thing we actually have to do is create the CSSM key. This is actually going to be used a little bit later on when we perform the encryption algorithm. We're just going to create a context for the first call.

There are approximately, let me see, what did he say, 30 algorithms? Something like that that you can actually use for encryption in our CSP.

Key size and bits, 128. We're passing in no seed or salt. We're going to let those get generated by the library itself. You can have a start date and end date for encryption keys. We aren't using that feature in this one, since we're passing in the key itself. Then there's a place for additional parameters, and finally the actual handle to the context itself.

Here's the call to actually generate the key using the information available. We actually want to be able to get this key out of the CSP. A lot of times when we generate keys, we want to generate it and store it in the DL so that nobody can get it back out.

One of the things that we do in our scheme is that key material is normally protected from the user address space, so that you can't simply go out and interrogate it. We do this by using a Unix process architecture, and actually then when we want to do the encryption, we use IPCs in order to actually be able to encrypt the data. We're going to pass, get everything back in the AES key variable.

Once we've actually done that, we actually take all of this stuff and we put it back into the AES key data structure that we'd allocated previously. This is basically getting set up then for the encryption operation that comes next.

We use the AES key that we just set up Passing the initialization vector, we specify how it's supposed to be padded and pass in the handle.

So here we go with the actual Encrypt the Data operation. Pass in the handle. We've got a plain text buffer coming in. There is only one of them. That's what the 1s stand for. There's a ciphertext buffer ready to handle it coming out. So, I'm going to tell you how many bytes are encrypted and how much remaining data there actually is. That actually will perform the operation given all the specifications that we've set up.

At the end of all this, we might have some remaining data that needs to be appended to the actual output buffer, the ciphertext buffer that we had set up at the opening of the function. So we'll go through and actually start moving that stuff out. We have to reallocate some more space. And then we do a memmove to actually move the data out.

We free the old remdata.data portion, delete the cryptographic context, and we return that everything is okay. Now obviously we didn't do much error checking in there, and you could add all of that. There are a lot more options that we could have done along the way as well.

Okay, so it's a whole lot of operations. One of the things that we end up doing at Apple quite a bit is we're kind of the crypto guys for the entire organization. And we try not to tell people, "Well, just do, you know, use CDSA and send them on their way and make them all happy." So we've started to make a lot of sample code.

We're going to start trying to make a lot more of that available if you go to our open source site. So that an encrypt operation should end up taking about two lines of code at most. So keep looking at the open source site for a little bit more of that. Here's an example of an upper layer piece of code using SecureTransport.

Secure Transport is layered on top of the CDSA infrastructure. We designed it explicitly to be able to do all SSL operations on the system. It'll do server-side and client-side support. supports a whole bunch of different protocols: V2, V3, and TLS. You can actually write server-side or client-side code using an identical API. You don't need to have your actual application do any of the crypto operations. Secure Transport will actually set all of that up for you.

The other thing is we actually made this so that there's a transport layer independence to it. We can use this actually with Unix sockets if you want. If you want to use OpenTransport, you can use it that way. You can use it in asynchronous mode or non-blocking mode, or synchronous mode and non-blocking mode. And it has a pretty straightforward API.

One of the real benefits of this is that you actually end up with the cert handling being done by the CDSA stack. One of the things we're trying to do in Mac OS X is have a common handling of all certificates, so that you actually have a common cert data store. Things are actually all accessed the same way. The user can set up their trust of various certs exactly the same way. And so this actually all just ties in automatically. CERTs are actually used by reference.

On the server side, you actually have the actual identities being handled by Keychain and the secure server. The benefit of this is that the private key is never actually exposed to the user process, so that all operations are being done through the security server. And this actually gives you quite a bit of protection of your key material.

The other part of this is that down the road, should we ever develop a hardware CSP to interface to any vendor's hardware encryption box, we can actually use those functions as well. In general, most of those types of devices will also hide the key material. So you have to have programmed at the very beginning with a paradigm of using essentially hidden private keys. So this actually helps out quite a bit in that regard.

It allows the calling code to specify a whole bunch of protocol parameters or not, or take the defaults. And it can examine the protocol parameters on the basis of the successful negotiation of the beginning of the session. The other benefit of this is that it actually gets to springboard or use all the algorithms that are contained in our CSP.

So that basically just about anything that the transaction hits along the way can be handled with the combination of all of our algorithms. Internally, CF Network and URL Access are APIs that actually use Secure Transport. There are other applications at the higher levels that actually then benefit as well automatically from that. Mail is actually using this for the SSL connection as well.

The Secure Transport functions themselves actually break down into kind of a set of common series of functions. There's functions to actually set up your session.

You can specify, you can either get or set any series of attributes, the domain name actually in use for the transaction, you can get the negotiated protocol version, supported ciphers, etc.

There are some options. One of the problems we had with URL access in 9 was that as root certificates started to become expired, we started to get a lot of negative 96, 96, 96, 96, 69 errors coming back, which essentially mapped into the remote server was mapping back to an expired root cert. So Secure Transport can actually be set up to ignore the fact that the remote cert has been expired and continue the session anyway. Then there are the protocol functions.

And finally, there's the I/O functions that actually do the reads and writes and then close and actually do the callbacks and that sort of stuff. So the sample code... One of the first things you have to do when setting up use of the SecureTransport function is to define two functions: your read callback and a write callback.

These have three parameters each. They have an SSL connection ref, which can be any of a socket, file descriptor, or an open transport interface. Basically anything you want to do. This essentially maps to a void star in the actual interface. So essentially anything you can read or write from, we're happy to provide you with. We're just going to pass it back. When you read, you're going to pass it back as data, and you're going to pass back the length. On the right side, you're going to get the data in, and the length of the data itself.

So here's our function to actually do a GET using SSL. We're going to call it PerformSSL. It takes in a socket as its input. It has the data to send to the server, the actual get string, the data length, and then it actually has a buffer for passing back the data and the length of that data coming back.

As local variables, we set up a cont- have a context reference variable. It's actually used to hold onto the SecureTransport object itself, status return, the actual length, and how much data is remaining. In order to set up, we pass in-- we pass to SSL new context the SSL context pointer. That essentially returns your context pointer. We can set the I/O functions to my read callback and my write callback so that we're ready to do I/O.

And then finally we set up the connection to be used in this particular case with the passed in socket. For this particular transfer, we're asking for SSL version 3 protocol only. You could also specify any of the other options that you would want to do at this particular point.

Then you actually start the session. You do the SSL handshake with the context raff.

Once we do that, we actually send the get string itself with an SSL write. Basically, this will ultimately end up calling your write callback along with the appropriate SSL wrapping. Once we've done that, we go into a read loop. As long as there's buffer space remaining, we do an SSL read that calls your callback. We check for errors and continue on through the loop.

Finally, we close the context and dispose of it. So, the SSL protocol is a lot more complex operation than simply doing a block encryption. And yet, this is a fair bit less code than you would have to do if you were doing this directly with CDSA. Some of the other examples of code we're hoping to provide as an example in the first round is just a simple encrypt function based on CDSA. So that you can make these calls with only one or two calls themselves.

For some of you, however, you're going to want to actually work at the CDSA level, and so that's all available. So there's a lot of documentation on that. There's the open group documentation. If you need that level of control, you can use that. If you want to do more, or if you want to do things a little bit easier, we're providing more and more functions. The next session itself has to do with the Sec APIs.

There are a lot of APIs that we've created to deal with handling access control lists on certificates and that sort of stuff. And also dealing with certificates themselves. So we're trying to make things a little bit easier, but the whole reason for using CDSA itself is to allow us the flexibility to move to different crypto service providers, different data libraries, etc.

For more information, contact Craig, and I think we're up to... Oh, yes, can't forget this. This next session coming up is the Sec APIs. This afternoon we have the feedback forum. Later on this afternoon, we also have the Directory Services discussion, and then also Kerberos is this afternoon. So it's kind of a full day of security. Make sure you hit all the sessions.

For more information, there's a couple URLs. All of CDSA is open source. Please go check it out. We have the Developer Security webpage, which includes some example code. There's the CDSA link to the open group pages on CDSA itself and the documentation. We also have PCSC code available in Mac OS X.

There's a product security web page dealing with real security problems, that sort of stuff, not so much from the developer side, but also from security problems having to do with Mac OS X. And finally, there's the Secure Trusted OS Consortium. One of the projects we're actually working on is trying to create an SE version of Mac OS X, and they're doing most of the work with that. I'd like to move on to the next question.