A snapshot taken during the long, agonizing crawl toward getting everything running on iPhone.
3 p=. Version 0.2 -- 12 April 2009
5 p=. By "Jens Alfke":mailto:jens@mooseyard.com <br>
6 Based in part on code by Wade Tregaskis, <br>
7 and sample code by Apple Computer.
11 *MYCrypto* is a high-level cryptography API for Mac OS X and iPhone. It's an Objective-C wrapper around the system
12 "*Keychain*":http://developer.apple.com/documentation/Security/Conceptual/keychainServConcepts/02concepts/concepts.html#//apple_ref/doc/uid/TP30000897-CH204-TP9
13 and *CSSM* APIs, which are notoriously hard to use, as well as *CommonCrypto*, which is easier but quite limited.
15 MYCrypto gives you easy object-oriented interfaces to:
17 * Symmmetric cryptography (session keys and password-based encryption)
18 * Asymmetric cryptography (public and private keys; digital signatures)
19 * Identity certificates (for use with SSL and CMS)
20 * Cryptographic digests/hashes (effectively-unique IDs for data)
21 * The Keychain (a secure, encrypted storage system for keys and passwords)
22 * Cryptographic Message Syntax [CMS] for signing/encrypting data
24 It's open source, released under a friendly BSD license.
28 * Mac OS X 10.5 or later _[has been tested on 10.5.6]_
29 * or iPhone OS 2.0 or later _[not yet tested; see Limitations section below]_
30 * or iPhone Simulator, for iPhone OS 2.0 or later
31 * The "MYUtilities":http://mooseyard.com/hg/hgwebdir.cgi/MYUtilities library, which is used by MYCrypto.
32 * _Some understanding of security and cryptography on your part!_ Even with convenient APIs, cryptographic operations still require care and knowledge to be used safely. There are already too many "examples":http://en.wikipedia.org/wiki/Wired_Equivalent_Privacy#Flaws of insecure systems that were incorrectly assembled from secure primitives; don't add your app to that list. Please read a good overview like "??Practical Cryptography??":http://www.schneier.com/book-practical.html before attempting anything the least bit fancy.
36 * "Download the current source code":http://mooseyard.com/hg/hgwebdir.cgi/MYCrypto/archive/tip.zip
37 * or to check out the source code using "Mercurial":http://selenic.com/mercurial/:<br>
38 @hg clone http://mooseyard.com/hg/hgwebdir.cgi/MYCrypto/ MYCrypto@
39 * As described above, you'll also need to download or check out MYUtilities and put it in a directory next to MYCrypto.
40 * To file or view bug reports, visit "the project tracker page":http://mooseyard.lighthouseapp.com/projects/29227/home.
41 * Or if you're just looking:
42 ** "Browse the source code":http://mooseyard.com/hg/hgwebdir.cgi/MYCrypto/file/tip
43 ** "Browse the class documentation":Documentation/html/hierarchy.html
47 With Xcode, of course. But before the _first_ time you build MYCrypto.xcode, you'll need to tell Xcode where the MYUtilities sources are. You do this by setting up a named 'Source Tree':
49 # Open Xcode's Preferences panel
50 # Click the "Source Trees" icon at the top
51 # Click the "+" button to add a new item to the list
52 # Fill in the Setting Name as "@MYUtilities@", the Display Name also as "@MYUtilities@", and the Path as the absolute filesystem path to where you downloaded MYUtilities to. _Do not use a "~" in this path!_ The compiler won't understand it and will give you errors.
54 Now you're golden. From now on you can just open MYCrypto.xcode and press the Build button.
56 (So far, the MYCrypto project doesn't build anything that's useful to you, like a framework ... just a tiny program that runs the unit-tests. You can add the source files to your own projects to use them.)
60 The class hierarchy of MYCrypto looks like this:
62 * "_MYKeychain_":Documentation/html/interfaceMYKeychain.html
63 * "_MYKeychainItem_":Documentation/html/interfaceMYKeychainItem.html
64 ** "_MYKey_":Documentation/html/interfaceMYKey.html
65 *** "MYSymmetricKey":Documentation/html/interfaceMYSymmetricKey.html
66 *** "MYPublicKey":Documentation/html/interfaceMYPublicKey.html
67 *** "MYPrivateKey":Documentation/html/interfaceMYPrivateKey.html
68 *** "MYCertificate":Documentation/html/interfaceMYCertificate.html
69 **** "MYIdentity":Documentation/html/interfaceMYIdentity.html
70 * "_MYDigest_":Documentation/html/interfaceMYDigest.html
71 ** "MYSHA1Digest":Documentation/html/interfaceMYSHA1Digest.html
72 ** "MYSHA256Digest":Documentation/html/interfaceMYSHA256Digest.html
73 * "MYCryptor":Documentation/html/interfaceMYCryptor.html
74 * "MYEncoder":Documentation/html/interfaceMYEncoder.html
75 * "MYDecoder":Documentation/html/interfaceMYDecoder.html
76 * "MYSigner":Documentation/html/interfaceMYSigner.html
78 (_Italicized_ classes are abstract.)
82 h3. Creating an RSA key-pair
85 MYPrivateKey *keyPair = [[MYKeychain defaultKeychain] generateRSAKeyPairOfSize: 2048];
88 h3. Creating a self-signed identity certificate:
91 NSDictionary *attrs = [NSDictionary dictionaryWithObjectsAndKeys:
92 @"alice", @"Common Name",
93 @"Alice", @"Given Name",
94 @"Lidell", @"Surname",
96 MYIdentity *ident = [keyPair createSelfSignedIdentityWithAttributes: attrs];
98 NSData *certData = ident.certificateData;
101 h3. Signing and encrypting a message:
104 NSData *cleartext = [@"Attack at dawn" dataUsingEncoding: NSUTF8StringEncoding];
105 MYEncoder *encoder = [[MYEncoder alloc] init];
106 [encoder addSigner: ident];
107 [encoder addRecipient: bob];
108 [encoder addRecipient: carla];
109 [encoder addData: cleartext];
111 NSData *ciphertext = encoder.encodedData;
113 sendMessage(ciphertext);
116 h3. Verifying and decoding a message:
119 NSData *ciphertext = receiveMessage();
121 MYDecoder *decoder = [[MYDecoder alloc] initWithData: ciphertext error: &error];
125 if (!decoder.isSigned)
127 decoder.policy = [MYCertificate X509Policy];
128 NSMutableArray *signerCerts = [NSMutableArray array];
129 for (MYSigner *signer in decoder.signers) {
130 if (signer.status != kCMSSignerValid) {
132 [signerCerts addObject: signer.certificate];
135 NSData *plaintext = decoder.content;
136 processMessage(plaintext, signerCerts);
139 h2. Current Limitations
141 h3. First off, the biggest caveat of all:
143 * *MYCrypto 0.2 is new code and has not yet been used in any real projects. Expect bugs.* (I'm talking about my wrapper/glue code. The underlying cryptographic functionality provided by the OS is robust.)
145 h3. Further issues with the 0.2 release:
147 * *MYCrypto does not yet work on the iPhone.* It currently builds, but runs into problems at runtime. I'm currently trying to figure these out. (The iPhone OS Security APIs are very different from the Mac OS X ones, and I'm much less familiar with them.) However, it does work in the iPhone Simulator, which uses the OS X APIs.
148 * Exporting symmetric keys in wrapped (encrypted) form will fail. Currently they can be exported only as raw key data.
149 * Importing symmetric keys, in any form, will fail ... kind of a deal-breaker for using them across two computers, unfortunately.
151 h3. Current API limitations, to be remedied in the future:
153 * No API for accessing passwords; fortunately there are several other utility libraries that provide this. And if your code is doing cryptographic operations, it probably needs to store the keys themselves, not passwords.
154 * No evaluation of trust in certificates (i.e. SecTrust and related APIs.)
155 * Error reporting is too limited. Most methods indicate an error by returning nil, NULL or NO, but don't provide the standard "out" NSError parameter to provide more information. Expect the API to be refactored in the near future to remedy this.
159 * "??Security Overview??":http://developer.apple.com/documentation/Security/Conceptual/Security_Overview/Introduction/Introduction.html (Apple)
160 * "??Secure Coding Guide??":http://developer.apple.com/documentation/Security/Conceptual/SecureCodingGuide/Introduction.html (Apple)
162 * "??Common Security: CDSA and CSSM, Version 2??":http://www.opengroup.org/publications/catalog/c914.htm (The Open Group)
164 * "??Practical Cryptography??":http://www.schneier.com/book-practical.html (Ferguson and Schneier)
165 * "??Handbook of Applied Cryptography??":http://www.cacr.math.uwaterloo.ca/hac/ (Menezes, van Oorschot, Vanstone) -- free download!
166 * "??The Devil's InfoSec Dictionary??":http://www.csoonline.com/article/220527/The_Devil_s_Infosec_Dictionary (CSO Online)