# HG changeset patch
# User snej@snej-mbp.mtv.corp.google.com
# Date 1239127018 25200
# Node ID 8982b8fada63acb8ae5a693df54a8a96a468349f
# Parent  60e4cbbb51287c7a2322c327a2e42429f8a0100f
More work, mostly on documentation.

diff -r 60e4cbbb5128 -r 8982b8fada63 MYCertificate-iPhone.m
--- a/MYCertificate-iPhone.m	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYCertificate-iPhone.m	Tue Apr 07 10:56:58 2009 -0700
@@ -9,7 +9,7 @@
 #import "MYCertificate.h"
 #import "MYCrypto_Private.h"
 
-#if USE_IPHONE_API
+#if MYCRYPTO_USE_IPHONE_API
 
 
 @implementation MYCertificate
@@ -70,4 +70,4 @@
 
 @end
 
-#endif USE_IPHONE_API
+#endif MYCRYPTO_USE_IPHONE_API
diff -r 60e4cbbb5128 -r 8982b8fada63 MYCertificate.h
--- a/MYCertificate.h	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYCertificate.h	Tue Apr 07 10:56:58 2009 -0700
@@ -27,13 +27,6 @@
 /** Creates a MYCertificate object from exported key data, but does not add it to any keychain. */
 - (id) initWithCertificateData: (NSData*)data;
 
-#if !TARGET_OS_IPHONE
-/** Creates a MYCertificate object from exported key data, but does not add it to any keychain. */
-- (id) initWithCertificateData: (NSData*)data
-                          type: (CSSM_CERT_TYPE) type
-                      encoding: (CSSM_CERT_ENCODING) encoding;
-#endif
-
 /** The Keychain object reference for this certificate. */
 @property (readonly) SecCertificateRef certificateRef;
 
@@ -46,7 +39,18 @@
 /** The name of the subject (owner) of the certificate. */
 @property (readonly) NSString *commonName;
 
+
+/** @name Mac-Only
+ *  Functionality not available on iPhone. 
+ */
+//@{
 #if !TARGET_OS_IPHONE
+
+/** Creates a MYCertificate object from exported key data, but does not add it to any keychain. */
+- (id) initWithCertificateData: (NSData*)data
+                          type: (CSSM_CERT_TYPE) type
+                      encoding: (CSSM_CERT_ENCODING) encoding;
+
 /** The list (if any) of the subject's email addresses. */
 @property (readonly) NSArray *emailAddresses;
 
@@ -55,6 +59,8 @@
 
 /** Associates the receiver as the preferred certificate for the given name string. */
 - (BOOL) setPreferredCertificateForName: (NSString*)name;
+
 #endif
+//@}
 
 @end
diff -r 60e4cbbb5128 -r 8982b8fada63 MYCertificate.m
--- a/MYCertificate.m	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYCertificate.m	Tue Apr 07 10:56:58 2009 -0700
@@ -9,7 +9,7 @@
 #import "MYCertificate.h"
 #import "MYCrypto_Private.h"
 
-#if !USE_IPHONE_API
+#if !MYCRYPTO_USE_IPHONE_API
 
 
 @implementation MYCertificate
@@ -101,4 +101,4 @@
 @end
 
 
-#endif !USE_IPHONE_API
+#endif !MYCRYPTO_USE_IPHONE_API
diff -r 60e4cbbb5128 -r 8982b8fada63 MYCrypto-iPhone.xcodeproj/project.pbxproj
--- a/MYCrypto-iPhone.xcodeproj/project.pbxproj	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYCrypto-iPhone.xcodeproj/project.pbxproj	Tue Apr 07 10:56:58 2009 -0700
@@ -57,6 +57,7 @@
 		276FB34A0F856CA400CB326E /* MYCertificate.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = MYCertificate.m; sourceTree = "<group>"; };
 		27A430130F87C6D50063D362 /* MYSymmetricKey.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = MYSymmetricKey.m; sourceTree = "<group>"; };
 		27A430150F87C6DB0063D362 /* MYSymmetricKey.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MYSymmetricKey.h; sourceTree = "<group>"; };
+		27AAD9710F8927DB0064DD7C /* MYCryptoConfig.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MYCryptoConfig.h; sourceTree = "<group>"; };
 		27E8230C0F81D56E0019BE60 /* MYCertificate.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MYCertificate.h; sourceTree = "<group>"; };
 		27E8230E0F81D56E0019BE60 /* MYCryptor.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MYCryptor.h; sourceTree = "<group>"; };
 		27E8230F0F81D56E0019BE60 /* MYCryptor.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = MYCryptor.m; sourceTree = "<group>"; };
@@ -128,6 +129,7 @@
 		27E8230B0F81D56E0019BE60 /* Source */ = {
 			isa = PBXGroup;
 			children = (
+				27AAD9710F8927DB0064DD7C /* MYCryptoConfig.h */,
 				27E8230C0F81D56E0019BE60 /* MYCertificate.h */,
 				276FB34A0F856CA400CB326E /* MYCertificate.m */,
 				273391CC0F81EC70009414D9 /* MYCertificate-iPhone.m */,
diff -r 60e4cbbb5128 -r 8982b8fada63 MYCrypto.xcodeproj/project.pbxproj
--- a/MYCrypto.xcodeproj/project.pbxproj	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYCrypto.xcodeproj/project.pbxproj	Tue Apr 07 10:56:58 2009 -0700
@@ -47,6 +47,7 @@
 		27A42D410F858ED80063D362 /* MYSymmetricKey.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = MYSymmetricKey.m; sourceTree = "<group>"; };
 		27A42ECC0F8689D30063D362 /* MYCertGen.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MYCertGen.h; sourceTree = "<group>"; };
 		27A42ECD0F8689D30063D362 /* MYCertGen.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = MYCertGen.m; sourceTree = "<group>"; };
+		27AAD97B0F892A0D0064DD7C /* MYCryptoConfig.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MYCryptoConfig.h; sourceTree = "<group>"; };
 		27CFF4B10F7E8535000B418E /* MYCertificate.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MYCertificate.h; sourceTree = "<group>"; };
 		27CFF4B20F7E8535000B418E /* MYCertificate.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = MYCertificate.m; sourceTree = "<group>"; };
 		27CFF4B30F7E8535000B418E /* MYCryptor.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MYCryptor.h; sourceTree = "<group>"; };
@@ -80,6 +81,7 @@
 		27E820710F7EA6260019BE60 /* CoreServices.framework */ = {isa = PBXFileReference; lastKnownFileType = wrapper.framework; name = CoreServices.framework; path = System/Library/Frameworks/CoreServices.framework; sourceTree = SDKROOT; };
 		27E822A00F81C5660019BE60 /* MYKey.h */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.h; path = MYKey.h; sourceTree = "<group>"; };
 		27E822A10F81C5660019BE60 /* MYKey.m */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = sourcecode.c.objc; path = MYKey.m; sourceTree = "<group>"; };
+		27EAF0390F8B2D700091AF95 /* README.textile */ = {isa = PBXFileReference; fileEncoding = 4; lastKnownFileType = text; path = README.textile; sourceTree = "<group>"; };
 		8DD76FA10486AA7600D96B5E /* MYCrypto */ = {isa = PBXFileReference; explicitFileType = "compiled.mach-o.executable"; includeInIndex = 0; path = MYCrypto; sourceTree = BUILT_PRODUCTS_DIR; };
 /* End PBXFileReference section */
 
@@ -118,6 +120,8 @@
 				27CFF4B20F7E8535000B418E /* MYCertificate.m */,
 				27CFF4B30F7E8535000B418E /* MYCryptor.h */,
 				27CFF4B40F7E8535000B418E /* MYCryptor.m */,
+				27CFF4BF0F7E8535000B418E /* MYDigest.h */,
+				27CFF4C00F7E8535000B418E /* MYDigest.m */,
 				27E822A00F81C5660019BE60 /* MYKey.h */,
 				27E822A10F81C5660019BE60 /* MYKey.m */,
 				27CFF4B50F7E8535000B418E /* MYKeychain.h */,
@@ -130,8 +134,7 @@
 				27CFF4BD0F7E8535000B418E /* MYPublicKey.m */,
 				27A42D400F858ED80063D362 /* MYSymmetricKey.h */,
 				27A42D410F858ED80063D362 /* MYSymmetricKey.m */,
-				27CFF4BF0F7E8535000B418E /* MYDigest.h */,
-				27CFF4C00F7E8535000B418E /* MYDigest.m */,
+				27AAD97B0F892A0D0064DD7C /* MYCryptoConfig.h */,
 				27CFF4BE0F7E8535000B418E /* MYCrypto_Private.h */,
 				27A42CBE0F8578B40063D362 /* MYCryptoTest.m */,
 				27CFF5210F7E94DF000B418E /* MYCrypto_main.m */,
@@ -139,6 +142,7 @@
 				27A42ECD0F8689D30063D362 /* MYCertGen.m */,
 				27CFF5120F7E9212000B418E /* MYCrypto.xcconfig */,
 				27CFF5400F7E9653000B418E /* MYCrypto_Debug.xcconfig */,
+				27EAF0390F8B2D700091AF95 /* README.textile */,
 			);
 			name = Source;
 			sourceTree = "<group>";
diff -r 60e4cbbb5128 -r 8982b8fada63 MYCryptoConfig.h
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/MYCryptoConfig.h	Tue Apr 07 10:56:58 2009 -0700
@@ -0,0 +1,23 @@
+//
+//  MYCryptoConfig.h
+//  MYCrypto
+//
+//  Created by Jens Alfke on 4/5/09.
+//  Copyright 2009 Jens Alfke. All rights reserved.
+//
+
+#import <Security/SecBase.h>
+
+/*  The iPhone simulator actually has the Mac OS X security API, not the iPhone one.
+    So check which API is installed by looking for a preprocessor symbol that's defined
+    only in the OS X version of SecBase.h. */
+
+#ifndef MYCRYPTO_USE_IPHONE_API
+
+#if TARGET_OS_IPHONE && !defined(__SEC_TYPES__)
+#define MYCRYPTO_USE_IPHONE_API 1
+#else
+#define MYCRYPTO_USE_IPHONE_API 0
+#endif
+
+#endif
\ No newline at end of file
diff -r 60e4cbbb5128 -r 8982b8fada63 MYCryptoTest.m
--- a/MYCryptoTest.m	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYCryptoTest.m	Tue Apr 07 10:56:58 2009 -0700
@@ -22,14 +22,14 @@
     MYKeychain *kc = [MYKeychain defaultKeychain];
     Log(@"Default keychain = %@", kc);
     CAssert(kc);
-#if !USE_IPHONE_API
+#if !MYCRYPTO_USE_IPHONE_API
     CAssert(kc.path);
 #endif
     
     kc = [MYKeychain allKeychains];
     Log(@"All-keychains = %@", kc);
     CAssert(kc);
-#if !USE_IPHONE_API
+#if !MYCRYPTO_USE_IPHONE_API
     CAssertEq(kc.path,nil);
 #endif
 }
@@ -75,6 +75,61 @@
 #pragma mark SYMMETRIC KEYS:
 
 
+static void testSymmetricKey( CCAlgorithm algorithm, unsigned sizeInBits ) {
+    NSAutoreleasePool *pool = [NSAutoreleasePool new];
+    Log(@"--- Testing %3u-bit #%i", sizeInBits, (int)algorithm);
+    // Generate key:
+    MYSymmetricKey *key = [MYSymmetricKey generateSymmetricKeyOfSize: sizeInBits
+                                                           algorithm: algorithm];
+    Log(@"Created %@", key);
+    CAssert(key);
+    CAssertEq(key.algorithm, algorithm);
+    CAssertEq(key.keySizeInBits, sizeInBits);
+#if !TARGET_OS_IPHONE
+    CAssert(key.cssmKey != NULL);
+#endif
+    
+    NSData *keyData = key.keyData;
+    Log(@"Key data = %@", keyData);
+    CAssertEq(keyData.length, sizeInBits/8);
+    
+    // Encrypt a small amount of text:
+    NSData *cleartext = [@"This is a test. This is only a test." dataUsingEncoding: NSUTF8StringEncoding];
+    NSData *encrypted = [key encryptData: cleartext];
+    Log(@"Encrypted = %u bytes: %@", encrypted.length, encrypted);
+    CAssert(encrypted.length >= cleartext.length);
+    NSData *decrypted = [key decryptData: encrypted];
+    CAssertEqual(decrypted, cleartext);
+    
+    // Encrypt large binary data:
+    cleartext = [NSData dataWithContentsOfFile: @"/Library/Desktop Pictures/Nature/Zen Garden.jpg"];
+    CAssert(cleartext);
+    encrypted = [key encryptData: cleartext];
+    Log(@"Encrypted = %u bytes", encrypted.length);
+    CAssert(encrypted.length >= cleartext.length);
+    decrypted = [key decryptData: encrypted];
+    CAssertEqual(decrypted, cleartext);
+    
+#if !TARGET_OS_IPHONE
+    // Try reconstituting the key from its data:
+    NSData *exported = [key exportKeyInFormat: kSecFormatWrappedPKCS8 withPEM: NO];
+    Log(@"Exported key: %@", exported);
+    // CAssert(exported);
+    //FIX: Exporting symmetric keys isn't working. Temporarily making this optional.
+    if (exported) {
+        CAssert(exported);
+        MYSymmetricKey *key2 = [[MYSymmetricKey alloc] initWithKeyData: exported algorithm: algorithm];
+        Log(@"Reconstituted as %@", key2);
+        CAssertEqual(key2,key);
+        decrypted = [key2 decryptData: encrypted];
+        CAssertEqual(decrypted, cleartext);
+    } else
+        Warn(@"Unable to export key in PKCS8");
+#endif
+    [pool drain];
+}
+
+
 TestCase(MYSymmetricKey) {
     #define kNTests 11
     static const CCAlgorithm kTestAlgorithms[kNTests] = {
@@ -89,38 +144,8 @@
         40, 80, 128,
         32, 200, 512*8};
 
-    for (int i=0; i<kNTests; i++) {
-        NSAutoreleasePool *pool = [NSAutoreleasePool new];
-        Log(@"Test #%2i: algorithm = %3u-bit #%i", i+1, kTestBitSizes[i], (int)kTestAlgorithms[i]);
-        // Generate key:
-        MYSymmetricKey *key = [MYSymmetricKey generateSymmetricKeyOfSize: kTestBitSizes[i]
-                                                               algorithm: kTestAlgorithms[i]];
-        CAssert(key);
-#if !TARGET_OS_IPHONE
-        CAssert(key.cssmKey != NULL);
-#endif
-        Log(@"Key data = %@", key.keyData);
-        CAssertEq(key.keyData.length, kTestBitSizes[i]/8);
-
-        // Encrypt a small amount of text:
-        NSData *cleartext = [@"This is a test. This is only a test." dataUsingEncoding: NSUTF8StringEncoding];
-        NSData *encrypted = [key encryptData: cleartext];
-        Log(@"Encrypted = %u bytes: %@", encrypted.length, encrypted);
-        CAssert(encrypted.length >= cleartext.length);
-        NSData *decrypted = [key decryptData: encrypted];
-        CAssertEqual(decrypted, cleartext);
-        
-        // Encrypt large binary data:
-        cleartext = [NSData dataWithContentsOfFile: @"/Library/Desktop Pictures/Nature/Zen Garden.jpg"];
-        CAssert(cleartext);
-        encrypted = [key encryptData: cleartext];
-        Log(@"Encrypted = %u bytes", encrypted.length);
-        CAssert(encrypted.length >= cleartext.length);
-        decrypted = [key decryptData: encrypted];
-        CAssertEqual(decrypted, cleartext);
-        
-        [pool drain];
-    }
+    for (int i=0; i<kNTests; i++) 
+        testSymmetricKey(kTestAlgorithms[i], kTestBitSizes[i]);
 }
 
 
diff -r 60e4cbbb5128 -r 8982b8fada63 MYCrypto_Private.h
--- a/MYCrypto_Private.h	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYCrypto_Private.h	Tue Apr 07 10:56:58 2009 -0700
@@ -6,6 +6,7 @@
 //  Copyright 2009 Jens Alfke. All rights reserved.
 //
 
+#import "MYCryptoConfig.h"
 #import "MYKeychain.h"
 #import "MYKey.h"
 #import "MYSymmetricKey.h"
@@ -14,15 +15,8 @@
 #import "Test.h"
 #import <Security/Security.h>
 
-/*  The iPhone simulator actually has the Mac OS X security API, not the iPhone one.
-    So don't use the iPhone API when configured to run in the simulator. */
-#if TARGET_OS_IPHONE && !TARGET_IPHONE_SIMULATOR
-#define USE_IPHONE_API 1
-#else
-#define USE_IPHONE_API 0
-#endif
 
-#if USE_IPHONE_API
+#if MYCRYPTO_USE_IPHONE_API
 typedef CFTypeRef SecKeychainAttrType;
 typedef CFTypeRef SecKeychainItemRef;
 typedef CFTypeRef SecKeychainRef;
@@ -30,7 +24,7 @@
 #endif
 
 
-#if TARGET_IPHONE_SIMULATOR
+#if TARGET_OS_IPHONE && !MYCRYPTO_USE_IPHONE_API
 @interface MYKeychain (Private)
 - (id) initWithKeychainRef: (SecKeychainRef)keychainRef;
 @property (readonly) SecKeychainRef keychainRef, keychainRefOrDefault;
@@ -58,7 +52,7 @@
 - (id) _initWithKeyData: (NSData*)data
             forKeychain: (SecKeychainRef)keychain;
 @property (readonly) SecExternalItemType keyType;
-#if !USE_IPHONE_API
+#if !MYCRYPTO_USE_IPHONE_API
 @property (readonly) const CSSM_KEY* cssmKey;
 - (NSData*) exportKeyInFormat: (SecExternalFormat)format withPEM: (BOOL)withPEM;
 #endif
@@ -81,7 +75,7 @@
 
 @interface MYKeyPair (Private)
 + (MYKeyPair*) _generateRSAKeyPairOfSize: (unsigned)keySize
-                            inKeychain: (SecKeychainRef)keychain;
+                            inKeychain: (MYKeychain*)keychain;
 - (id) _initWithPublicKeyData: (NSData*)pubKeyData 
                privateKeyData: (NSData*)privKeyData
                   forKeychain: (SecKeychainRef)keychain
@@ -99,7 +93,7 @@
 @end
 
 
-#if TARGET_IPHONE_SIMULATOR
+#if TARGET_OS_IPHONE && !MYCRYPTO_USE_IPHONE_API
 @interface MYCertificate (Private)
 - (id) initWithCertificateData: (NSData*)data
                           type: (CSSM_CERT_TYPE) type
@@ -113,7 +107,7 @@
 #undef check
 BOOL check(OSStatus err, NSString *what);
 
-#if !USE_IPHONE_API
+#if !MYCRYPTO_USE_IPHONE_API
 BOOL checkcssm(CSSM_RETURN err, NSString *what);
 
 SecKeyRef importKey(NSData *data, 
diff -r 60e4cbbb5128 -r 8982b8fada63 MYCryptor.h
--- a/MYCryptor.h	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYCryptor.h	Tue Apr 07 10:56:58 2009 -0700
@@ -10,9 +10,9 @@
 #import <CommonCrypto/CommonCryptor.h>
 
 
-/** Symmetric encryption: a simple Cocoa wrapper for CommonCrypto/commonCryptor.h.
-    Provides a streaming interface for encrypting/decrypting data.
-    This class will probably be merged into or integrated with MYSymmetricKey. */
+/** Symmetric encryption: a streaming interface for encrypting/decrypting data.
+    This is a simple Cocoa wrapper for CommonCrypto/commonCryptor.h. It will probably be
+    merged into, or integrated with, MYSymmetricKey. */
 @interface MYCryptor : NSObject
 {
     @private
@@ -27,12 +27,26 @@
     size_t _outputExtraBytes;
 }
 
-/** Returns a block of cryptographically-random data, suitable for use as a symmetric key.
-    (CommonCryptor.h defines constants for key sizes and size-ranges, like kCCKeySizeAES128.) */
-+ (NSData*) randomKeyOfLength: (size_t)length;
+/** Returns a randomly-generated symmetric key of the desired length (in bits).
+ *  @param lengthInBits  The length of the desired key, in bits (not bytes).
+ */
++ (NSData*) randomKeyOfLength: (size_t)lengthInBits;
 
-/** Converts a passphrase into a block of data of the given size, suitable for use as a symmetric key. */
-+ (NSData*) keyOfLength: (size_t)lengthInBits fromPassphrase: (NSString*)passphrase;
+/** Converts a passphrase into a symmetric key of the desired length (in bits).
+ *  The same passphrase (and salt) will always return the same key, so you can use this method
+ *  to encrypt and decrypt data using a user-entered passphrase, without having to store the key
+ *  itself in the keychain.
+ *  @param lengthInBits  The length of the desired key, in bits (not bytes).
+ *  @param passphrase  The user-entered passphrase.
+ *  @param salt  An arbitrary value whose description will be appended to the passphrase before
+ *          hashing, to perturb the resulting bits. The purpose of this is to make it harder for
+ *          an attacker to brute-force the key using a precompiled list of digests of common
+ *          passwords. Changing the salt changes the key, so you need to pass the same value when
+ *          re-deriving the key as you did when first generating it.
+ */
++ (NSData*) keyOfLength: (size_t)lengthInBits
+         fromPassphrase: (NSString*)passphrase
+                   salt: (id)salt;
 
 /** Creates a MYCryptor configured to encrypt data. */
 - (id) initEncryptorWithKey: (NSData*)key
diff -r 60e4cbbb5128 -r 8982b8fada63 MYCryptor.m
--- a/MYCryptor.m	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYCryptor.m	Tue Apr 07 10:56:58 2009 -0700
@@ -10,7 +10,7 @@
 #import "MYDigest.h"
 #import "Test.h"
 
-#if USE_IPHONE_API
+#if MYCRYPTO_USE_IPHONE_API
 #import <Security/SecRandom.h>
 #else
 #import "MYCrypto_Private.h"
@@ -21,7 +21,7 @@
 
 NSString* const CryptorErrorDomain = @"CCCryptor";
 
-#if !USE_IPHONE_API
+#if !MYCRYPTO_USE_IPHONE_API
 static BOOL generateRandomBytes(CSSM_CSP_HANDLE module, uint32_t lengthInBytes, void *dstBytes);
 #endif
 
@@ -35,25 +35,31 @@
 @implementation MYCryptor
 
 
-+ (NSData*) randomKeyOfLength: (size_t)length {
-    NSParameterAssert(length<100000);
-    uint8_t *bytes = malloc(length);
++ (NSData*) randomKeyOfLength: (size_t)lengthInBits {
+    size_t lengthInBytes = (lengthInBits + 7)/8;
+    NSParameterAssert(lengthInBytes<100000);
+    uint8_t *bytes = malloc(lengthInBytes);
     if (!bytes) return nil;
-#if USE_IPHONE_API
-    BOOL ok = SecRandomCopyBytes(kSecRandomDefault, length,bytes) >= 0;
+#if MYCRYPTO_USE_IPHONE_API
+    BOOL ok = SecRandomCopyBytes(kSecRandomDefault, lengthInBytes,bytes) >= 0;
 #else
-    BOOL ok = generateRandomBytes([[MYKeychain defaultKeychain] CSPHandle], length, bytes);
+    BOOL ok = generateRandomBytes([[MYKeychain defaultKeychain] CSPHandle], lengthInBytes, bytes);
 #endif
     if (ok)
-        return [NSData dataWithBytesNoCopy: bytes length: length freeWhenDone: YES];
+        return [NSData dataWithBytesNoCopy: bytes length: lengthInBytes freeWhenDone: YES];
     else {
         free(bytes);
         return nil;
     }
 }
 
-+ (NSData*) keyOfLength: (size_t)lengthInBits fromPassphrase: (NSString*)passphrase
++ (NSData*) keyOfLength: (size_t)lengthInBits
+         fromPassphrase: (NSString*)passphrase
+                   salt: (id)salt
 {
+    Assert(passphrase);
+    Assert(salt);
+    passphrase = $sprintf(@"MYCrypto|%@|%@", passphrase, salt);
     size_t lengthInBytes = (lengthInBits + 7)/8;
     MYDigest *digest = [[passphrase dataUsingEncoding: NSUTF8StringEncoding] my_SHA256Digest];
     if (lengthInBytes <= digest.length)
@@ -95,6 +101,13 @@
     [super dealloc];
 }
 
+- (void) finalize
+{
+    if (_cryptor)
+        CCCryptorRelease(_cryptor);
+    [super finalize];
+}
+
 
 @synthesize key=_key, algorithm=_algorithm, options=_options,
     outputStream=_outputStream, error=_error;
@@ -248,7 +261,7 @@
 
 
 
-#if !USE_IPHONE_API
+#if !MYCRYPTO_USE_IPHONE_API
 static BOOL generateRandomBytes(CSSM_CSP_HANDLE module, uint32_t lengthInBytes, void *dstBytes) {
     // Adapted from code in Keychain.framework's KeychainUtils.m by Wade Tregaskis.
     CSSM_CC_HANDLE ccHandle;
@@ -268,7 +281,7 @@
 
 TestCase(MYCryptor) {
     // Encryption:
-    NSData *key = [MYCryptor randomKeyOfLength: kCCKeySizeAES256];
+    NSData *key = [MYCryptor randomKeyOfLength: 256];
     Log(@"Key = %@",key);
     MYCryptor *enc = [[MYCryptor alloc] initEncryptorWithKey: key algorithm: kCCAlgorithmAES128];
     CAssert(enc);
@@ -292,7 +305,7 @@
     CAssertEqual(decrypted, @"This is a test. This is only a test.");
     
     // Encryption to stream:
-    key = [MYCryptor randomKeyOfLength: kCCKeySizeAES256];
+    key = [MYCryptor randomKeyOfLength: 256];
     Log(@"Key = %@",key);
     enc = [[MYCryptor alloc] initEncryptorWithKey: key algorithm: kCCAlgorithmAES128];
     CAssert(enc);
diff -r 60e4cbbb5128 -r 8982b8fada63 MYDigest.h
--- a/MYDigest.h	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYDigest.h	Tue Apr 07 10:56:58 2009 -0700
@@ -10,7 +10,9 @@
 
 
 /** Abstract superclass for cryptographic digests (aka hashes).
-    Each specific type of digest has its own concrete subclass. */
+    Each specific type of digest has its own concrete subclass.
+    Digests are full-fledged value objects, and can be compared, used as dictionary keys,
+    copied, and archived. */
 @interface MYDigest : NSObject <NSCoding, NSCopying>
 {
     @private
@@ -39,13 +41,15 @@
 /** Returns the digest as a hex string. */
 @property (readonly) NSString *hexString;
 
-/** Returns the first 8 digits (32 bits) of the digest's hex string, followed by "..."
+/** Returns the first 8 digits (32 bits) of the digest's hex string, followed by "...".
     This is intended only for use in log messages or object descriptions, since
     32 bits isn't nearly enough to provide any useful uniqueness. */
 @property (readonly) NSString *abbreviatedHexString;
 
-/** The algorithm that created this digest. */
-@property (readonly) uint32_t /*CSSM_ALGORITHMS*/ algorithm;
+/** The algorithm that created this digest. 
+    Values are defined in the CSSM_ALGORITHMS enum in cssmtype.h.
+    (Abstract method.) */
+@property (readonly) uint32_t algorithm;
 
 /** The length (in bytes, not bits!) of this digest. */
 @property (readonly) size_t length;
@@ -54,7 +58,7 @@
 @property (readonly) const void* bytes;
 
 /** The algorithm used by this subclass. (Abstract method.) */
-+ (uint32_t /*CSSM_ALGORITHMS*/) algorithm;
++ (uint32_t) algorithm;
 
 /** The length of digests created by this subclass. (Abstract method.) */
 + (size_t) length;
@@ -65,15 +69,19 @@
 @end
 
 
-/** A simple C struct containing a 160-bit SHA-1 digest. */
+// A simple C struct containing a 160-bit SHA-1 digest. Used by the MYSHA1Digest class.
 typedef struct {
     UInt8 bytes[20];
 } RawSHA1Digest;
     
 /** A 160-bit SHA-1 digest encapsulated in an object. */
 @interface MYSHA1Digest : MYDigest
+{ }
 
+/** Initialize a MYSHA1Digest object given an existing raw SHA-1 digest. */
 - (MYSHA1Digest*) initWithRawSHA1Digest: (const RawSHA1Digest*)rawDigest;
+
+/** Create a MYSHA1Digest object given an existing raw SHA-1 digest. */
 + (MYSHA1Digest*) digestFromRawSHA1Digest: (const RawSHA1Digest*)rawDigest;
 
 @property (readonly) const RawSHA1Digest* rawSHA1Digest;
@@ -81,15 +89,19 @@
 @end
 
 
-/** A simple C struct containing a 256-bit SHA-256 digest. */
+// A simple C struct containing a 256-bit SHA-256 digest.
 typedef struct {
     UInt8 bytes[32];
 } RawSHA256Digest;
 
-/** A 256-bit SHA-256 digest encapsulated in an object. */
+/** A 256-bit SHA-256 digest encapsulated in an object. Used by the MYSHA256Digest class. */
 @interface MYSHA256Digest : MYDigest
+{ }
 
+/** Initialize a MYSHA256Digest object given an existing raw SHA-1 digest. */
 - (MYSHA256Digest*) initWithRawSHA256Digest: (const RawSHA256Digest*)rawDigest;
+
+/** Create a MYSHA256Digest object given an existing raw SHA-1 digest. */
 + (MYSHA256Digest*) digestFromRawSHA256Digest: (const RawSHA256Digest*)rawDigest;
 
 @property (readonly) const RawSHA256Digest* rawSHA256Digest;
@@ -97,8 +109,13 @@
 @end
 
 
-/** Convenience methods for NSData objects */
+/** Convenience methods for computing digests of NSData objects. */
 @interface NSData (MYDigest)
+
+/** The SHA-1 digest of the receiver's data. */
 @property (readonly) MYSHA1Digest* my_SHA1Digest;
+
+/** The SHA-256 digest of the receiver's data. */
 @property (readonly) MYSHA256Digest* my_SHA256Digest;
+
 @end
diff -r 60e4cbbb5128 -r 8982b8fada63 MYDigest.m
--- a/MYDigest.m	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYDigest.m	Tue Apr 07 10:56:58 2009 -0700
@@ -11,7 +11,7 @@
 #import "MYCrypto_Private.h"
 
 
-#if USE_IPHONE_API
+#if MYCRYPTO_USE_IPHONE_API
 enum {
     CSSM_ALGID_SHA1 = 8,
     CSSM_ALGID_SHA256 = 0x80000000 + 14
@@ -53,6 +53,12 @@
     [super dealloc];
 }
 
+- (void) finalize
+{
+    if(_rawDigest) free(_rawDigest);
+    [super finalize];
+}
+
 
 - (id) copyWithZone: (NSZone*)zone
 {
diff -r 60e4cbbb5128 -r 8982b8fada63 MYKey-iPhone.m
--- a/MYKey-iPhone.m	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYKey-iPhone.m	Tue Apr 07 10:56:58 2009 -0700
@@ -9,7 +9,7 @@
 
 #import "MYCrypto_Private.h"
 
-#if USE_IPHONE_API
+#if MYCRYPTO_USE_IPHONE_API
 
 #import "MYDigest.h"
 #import "MYErrorUtils.h"
@@ -72,7 +72,7 @@
                                 {(id)kSecAttrKeyClass, (id)self.keyType},
                                 {(id)kSecMatchItemList, $array((id)self.keyRef)},
                                 {(id)kSecReturnAttributes, $true} );
-    CFDictionaryRef attrs;
+    CFDictionaryRef attrs = NULL;
     if (!check(SecItemCopyMatching((CFDictionaryRef)info, (CFTypeRef*)&attrs), @"SecItemCopyMatching"))
         return nil;
     CFTypeRef rawValue = CFDictionaryGetValue(attrs,attribute);
@@ -112,7 +112,7 @@
 @end
 
 
-#endif USE_IPHONE_API
+#endif MYCRYPTO_USE_IPHONE_API
 
 
 
diff -r 60e4cbbb5128 -r 8982b8fada63 MYKey.h
--- a/MYKey.h	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYKey.h	Tue Apr 07 10:56:58 2009 -0700
@@ -28,6 +28,7 @@
 /** Abstract superclass for keys.
     Concrete subclasses are MYSymmetricKey and MYPublicKey. */
 @interface MYKey : MYKeychainItem
+{ }
 
 /** The key's raw data. */
 @property (readonly) NSData *keyData;
@@ -42,17 +43,32 @@
     that it can be read and modified by any other app that can access this key. */
 @property (copy) NSString *alias;
 
+
+/** @name Mac-Only
+ *  Functionality not available on iPhone. 
+ */
+//@{
 #if !TARGET_OS_IPHONE
+
 /** The user-visible comment (kSecKeyApplicationTag) associated with this key in the Keychain.
-    The user can edit this, so don't expect it to be immutable. */
+ The user can edit this, so don't expect it to be immutable. */
 @property (copy) NSString *comment;
+
+/** Converts the key into a data blob in one of several standard formats, suitable for storing in
+    a file or sending over the network.
+    @param format  The data format: kSecFormatOpenSSL, kSecFormatSSH, kSecFormatBSAFE or kSecFormatSSHv2.
+    @param withPEM  YES if the data should be encoded in PEM format, which converts into short lines
+        of printable ASCII characters, suitable for sending in email. */
+- (NSData*) exportKeyInFormat: (SecExternalFormat)format withPEM: (BOOL)withPEM;
+
 #endif
+//@}
 
-@end
 
-
-
-@interface MYKey (Expert)
+/** @name Expert
+ *  Advanced methods. 
+ */
+//@{
 
 /** Creates a MYKey object for an existing Keychain key reference.
     This is abstract -- must be called on a MYSymmetricKey or MYPublicKey, as appropriate. */
@@ -65,12 +81,26 @@
 /** The underlying CSSM_KEY structure; used with low-level crypto APIs. */
 @property (readonly) const struct cssm_key* cssmKey;
 
-/** Converts the key into a data blob in one of several standard formats, suitable for storing in
-    a file or sending over the network.
-    @param format  The data format: kSecFormatOpenSSL, kSecFormatSSH, kSecFormatBSAFE or kSecFormatSSHv2.
-    @param withPEM  YES if the data should be encoded in PEM format, which converts into short lines
-        of printable ASCII characters, suitable for sending in email. */
-- (NSData*) exportKeyInFormat: (SecExternalFormat)format withPEM: (BOOL)withPEM;
+/** The underlying CSSM_CSP_HANDLE structure; used with low-level crypto APIs. */
+@property (readonly) intptr_t /*CSSM_CSP_HANDLE*/ cssmCSPHandle;
+
+/** Gets CSSM authorization credentials for a specified operation, such as
+    CSSM_ACL_AUTHORIZATION_ENCRYPT. This pointer is necessary for creating some CSSM operation
+    contexts.
+    @param operation  The type of operation you are going to perform (see the enum values in
+            cssmType.h.)
+    @param type  Specifies whether the operation should be allowed to present a UI. You'll usually
+            want to pass kSecCredentialTypeDefault.
+    @param outError  Will be set to point to an NSError on failure, or nil on success.
+            Pass nil if you don't care about the specific error.
+    @return  The access credentials, or NULL on failure. 
+            This pointer is valid for as long as you have a reference
+            to the key object. Do not free or delete it. */
+- (const CSSM_ACCESS_CREDENTIALS*) cssmCredentialsForOperation: (CSSM_ACL_AUTHORIZATION_TAG)operation
+                                                          type: (SecCredentialType)type
+                                                         error: (NSError**)outError;
+
 #endif
+//@}
 
 @end
diff -r 60e4cbbb5128 -r 8982b8fada63 MYKey.m
--- a/MYKey.m	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYKey.m	Tue Apr 07 10:56:58 2009 -0700
@@ -11,7 +11,7 @@
 #import "MYDigest.h"
 #import "MYErrorUtils.h"
 
-#if !USE_IPHONE_API
+#if !MYCRYPTO_USE_IPHONE_API
 
 
 #pragma mark -
@@ -51,10 +51,32 @@
 
 - (const CSSM_KEY*) cssmKey {
     const CSSM_KEY *cssmKey = NULL;
-    Assert(check(SecKeyGetCSSMKey(self.keyRef, &cssmKey), @"SecKeyGetCSSMKey"), @"Failed to get CSSM_KEY");
+    Assert(check(SecKeyGetCSSMKey(self.keyRef, &cssmKey), @"SecKeyGetCSSMKey"), 
+           @"Failed to get CSSM_KEY");
     return cssmKey;
 }
 
+- (const CSSM_CSP_HANDLE) cssmCSPHandle {
+    CSSM_CSP_HANDLE cspHandle = 0;
+    Assert(check(SecKeyGetCSPHandle(self.keyRef, &cspHandle), @"SecKeyGetCSPHandle"),
+           @"Failed to get CSSM_CSP_HANDLE");
+    return cspHandle;
+}
+
+- (const CSSM_ACCESS_CREDENTIALS*) cssmCredentialsForOperation: (CSSM_ACL_AUTHORIZATION_TAG)operation
+                                                          type: (SecCredentialType)type
+                                                         error: (NSError**)outError
+{
+    const CSSM_ACCESS_CREDENTIALS *credentials = NULL;
+    OSStatus err = SecKeyGetCredentials(self.keyRef,
+                                        operation,
+                                        type,
+                                        &credentials);
+    if (!MYReturnError(outError, err,NSOSStatusErrorDomain, @"Couldn't get credentials for key"))
+        return NULL;
+    return credentials;
+}
+
 - (NSData*) exportKeyInFormat: (SecExternalFormat)format withPEM: (BOOL)withPEM {
     CFDataRef data = NULL;
     if (check(SecKeychainItemExport(self.keyRef, format, (withPEM ?kSecItemPemArmour :0), NULL, &data),
@@ -111,8 +133,9 @@
     
     params->version = SEC_KEY_IMPORT_EXPORT_PARAMS_VERSION;
     params->flags |= kSecKeyImportOnlyOne;
+    params->keyAttributes |= CSSM_KEYATTR_EXTRACTABLE;
     if (keychain) {
-        params->keyAttributes = CSSM_KEYATTR_EXTRACTABLE | CSSM_KEYATTR_PERMANENT;
+        params->keyAttributes |= CSSM_KEYATTR_PERMANENT;
         if (type==kSecItemTypeSessionKey)
             params->keyUsage = CSSM_KEYUSE_ENCRYPT | CSSM_KEYUSE_DECRYPT;
         else if (type==kSecItemTypePublicKey)
@@ -132,7 +155,7 @@
 }    
 
 
-#endif USE_IPHONE_API
+#endif MYCRYPTO_USE_IPHONE_API
 
 
 
diff -r 60e4cbbb5128 -r 8982b8fada63 MYKeyPair-iPhone.m
--- a/MYKeyPair-iPhone.m	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYKeyPair-iPhone.m	Tue Apr 07 10:56:58 2009 -0700
@@ -12,13 +12,13 @@
 #import <CommonCrypto/CommonDigest.h>
 
 
-#if USE_IPHONE_API
+#if MYCRYPTO_USE_IPHONE_API
 
 
 @implementation MYKeyPair
 
 
-+ (MYKeyPair*) _generateKeyPairOfSize: (unsigned)keySize inKeychain: (MYKeychain*)keychain {
++ (MYKeyPair*) _generateRSAKeyPairOfSize: (unsigned)keySize inKeychain: (MYKeychain*)keychain {
     Assert( keySize == 512 || keySize == 1024 || keySize == 2048, @"Unsupported key size %u", keySize );
     SecKeyRef pubKey=NULL, privKey=NULL;
     OSStatus err;
@@ -82,4 +82,4 @@
 @end
 
 
-#endif USE_IPHONE_API
+#endif MYCRYPTO_USE_IPHONE_API
diff -r 60e4cbbb5128 -r 8982b8fada63 MYKeyPair.h
--- a/MYKeyPair.h	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYKeyPair.h	Tue Apr 07 10:56:58 2009 -0700
@@ -30,7 +30,13 @@
     verifySignature:ofData: method. */
 - (NSData*) signData: (NSData*)data;
 
+
+/** @name Mac-Only
+ *  Functionality not available on iPhone. 
+ */
+//@{
 #if !TARGET_OS_IPHONE
+
 /** Exports the private key as a data blob, so that it can be stored as a backup, or transferred
     to another computer. Since the key is sensitive, it must be exported in encrypted form
     using a user-chosen passphrase. This method will display a standard alert panel, run by
@@ -39,21 +45,7 @@
     (This is a convenient shorthand for the full exportPrivateKeyInFormat... method.
     It uses OpenSSL format, wrapped with PEM, and a default title and prompt for the alert.) */
 - (NSData*) exportPrivateKey;
-#endif
 
-@end
-
-
-
-@interface MYKeyPair (Expert)
-
-/** Creates a MYKeyPair object from existing Keychain key references. */
-- (id) initWithPublicKeyRef: (SecKeyRef)publicKey privateKeyRef: (SecKeyRef)privateKey;
-
-/** The underlying Keychain key reference for the private key. */
-@property (readonly) SecKeyRef privateKeyRef;
-
-#if !TARGET_OS_IPHONE
 /** Exports the private key as a data blob, so that it can be stored as a backup, or transferred
     to another computer. Since the key is sensitive, it must be exported in encrypted form
     using a user-chosen passphrase. This method will display a standard alert panel, run by
@@ -66,8 +58,24 @@
     @param prompt  An optional prompt message to display in the alert panel. */
 - (NSData*) exportPrivateKeyInFormat: (SecExternalFormat)format
                              withPEM: (BOOL)withPEM
-                          alertTitle: (NSString*)title
+                          alertTitle: (NSString*)alertTitle
                          alertPrompt: (NSString*)prompt;
+
 #endif
+//@}
+
+
+/** @name Expert
+ *  Advanced functionality.
+ */
+//@{
+
+/** Creates a MYKeyPair object from existing Keychain key references. */
+- (id) initWithPublicKeyRef: (SecKeyRef)publicKey privateKeyRef: (SecKeyRef)privateKey;
+
+/** The underlying Keychain key reference for the private key. */
+@property (readonly) SecKeyRef privateKeyRef;
+
+//@}
 
 @end
diff -r 60e4cbbb5128 -r 8982b8fada63 MYKeyPair.m
--- a/MYKeyPair.m	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYKeyPair.m	Tue Apr 07 10:56:58 2009 -0700
@@ -10,7 +10,7 @@
 #import "MYCrypto_Private.h"
 #import <CommonCrypto/CommonDigest.h>
 
-#if !USE_IPHONE_API
+#if !MYCRYPTO_USE_IPHONE_API
 
 
 #pragma mark -
@@ -19,11 +19,14 @@
 
 
 + (MYKeyPair*) _generateRSAKeyPairOfSize: (unsigned)keySize
-                            inKeychain: (SecKeychainRef)keychain {
+                            inKeychain: (MYKeychain*)keychain {
     Assert( keySize == 512 || keySize == 1024 || keySize == 2048, @"Unsupported key size %u", keySize );
     SecKeyRef pubKey=NULL, privKey=NULL;
     OSStatus err;
-    err = SecKeyCreatePair(keychain, CSSM_ALGID_RSA, keySize, 0LL,
+    err = SecKeyCreatePair(keychain.keychainRefOrDefault,
+                           CSSM_ALGID_RSA, 
+                           keySize,
+                           0LL,
                            CSSM_KEYUSE_ENCRYPT | CSSM_KEYUSE_VERIFY,        // public key
                            CSSM_KEYATTR_EXTRACTABLE | CSSM_KEYATTR_PERMANENT,
                            CSSM_KEYUSE_DECRYPT | CSSM_KEYUSE_SIGN,          // private key
@@ -103,6 +106,12 @@
     [super dealloc];
 }
 
+- (void) finalize
+{
+    if (_privateKey) CFRelease(_privateKey);
+    [super finalize];
+}
+
 
 - (NSUInteger)hash {
     // Ensure that a KeyPair doesn't hash the same as its corresponding PublicKey:
@@ -209,7 +218,7 @@
 @end
 
 
-#endif !USE_IPHONE_API
+#endif !MYCRYPTO_USE_IPHONE_API
 
 
 
diff -r 60e4cbbb5128 -r 8982b8fada63 MYKeychain-iPhone.m
--- a/MYKeychain-iPhone.m	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYKeychain-iPhone.m	Tue Apr 07 10:56:58 2009 -0700
@@ -9,7 +9,7 @@
 #import "MYCrypto_Private.h"
 #import "MYDigest.h"
 
-#if USE_IPHONE_API
+#if MYCRYPTO_USE_IPHONE_API
 
 
 @interface MYKeyEnumerator : NSEnumerator
@@ -208,8 +208,8 @@
     if (!_results)
         return nil;
     MYKeychainItem *next = nil;
-    for (; next==nil && _index < CFArrayGetCount(_results); _index++) {
-        CFTypeRef found = CFArrayGetValueAtIndex(_results, _index); 
+    while (next==nil && _index < CFArrayGetCount(_results)) {
+        CFTypeRef found = CFArrayGetValueAtIndex(_results, _index++); 
         if (_itemClass == kSecAttrKeyClassPrivate) {
             MYSHA1Digest *digest = [MYPublicKey _digestOfKey: (SecKeyRef)found];
             if (digest) {
@@ -224,16 +224,12 @@
                     //Warn(@"Couldn't find matching public key for private key!");
                 }
             }
-            break;
         } else if (_itemClass == kSecAttrKeyClassPublic) {
             next = [[[MYPublicKey alloc] initWithKeyRef: (SecKeyRef)found] autorelease];
-            break;
         } else if (_itemClass == kSecAttrKeyClassSymmetric) {
             next = [[[MYSymmetricKey alloc] initWithKeyRef: (SecKeyRef)found] autorelease];
-            break;
         } else if (_itemClass == kSecClassCertificate) {
             next = [[[MYCertificate alloc] initWithCertificateRef: (SecCertificateRef)found] autorelease];
-            break;
         }
         CFRelease(found);
     }
@@ -243,7 +239,7 @@
 
 @end
 
-#endif USE_IPHONE_API
+#endif MYCRYPTO_USE_IPHONE_API
 
 
 /*
diff -r 60e4cbbb5128 -r 8982b8fada63 MYKeychain.h
--- a/MYKeychain.h	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYKeychain.h	Tue Apr 07 10:56:58 2009 -0700
@@ -7,6 +7,7 @@
 //
 
 #import <Foundation/Foundation.h>
+#import "MYCryptoConfig.h"
 @class MYSymmetricKey, MYPublicKey, MYKeyPair, MYCertificate, MYSHA1Digest;
 
 
@@ -15,7 +16,7 @@
 @interface MYKeychain : NSObject 
 {
     @private
-#if !TARGET_OS_IPHONE || TARGET_IPHONE_SIMULATOR
+#if !MYCRYPTO_USE_IPHONE_API
     SecKeychainRef _keychain;
 #endif
 }
@@ -40,6 +41,10 @@
 
 #pragma mark PUBLIC KEYS:
 
+/** Imports a public key into the keychain, given its external representation
+    (as generated by -[MYPublicKey keyData].) */
+- (MYPublicKey*) importPublicKey: (NSData*)keyData;
+
 /** Looks up an existing public key with the given digest.
     Returns nil if there is no such key in the keychain.
     (This method does not look for keys embedded in certificates, only 'bare' keys.) */
@@ -49,11 +54,10 @@
     (This method does not find keys embedded in certificates, only 'bare' keys.) */
 - (NSEnumerator*) enumeratePublicKeys;
 
-/** Imports a public key into the keychain, given its external representation
-    (as generated by -[MYPublicKey keyData].) */
-- (MYPublicKey*) importPublicKey: (NSData*)keyData;
+#pragma mark CERTIFICATES:
 
-#pragma mark CERTIFICATES:
+/** Imports a certificate into the keychain, given its external representation. */
+- (MYCertificate*) importCertificate: (NSData*)data;
 
 /** Looks up an existing certificate with the given public-key digest.
     Returns nil if there is no such certificate in the keychain.
@@ -63,20 +67,8 @@
 /** Enumerates all certificates in the keychain. */
 - (NSEnumerator*) enumerateCertificates;
 
-/** Imports a certificate into the keychain, given its external representation. */
-- (MYCertificate*) importCertificate: (NSData*)data;
-
 #pragma mark KEY-PAIRS:
 
-/** Looks up an existing key-pair whose public key has the given digest.
-    Returns nil if there is no such key-pair in the keychain.
-    (This method does not look for public keys embedded in certificates, only 'bare' keys.) */
-- (MYKeyPair*) keyPairWithDigest: (MYSHA1Digest*)pubKeyDigest;
-
-/** Enumerates all key-pairs in the keychain.
-    (This method does not find keys embedded in certificates, only 'bare' keys.) */
-- (NSEnumerator*) enumerateKeyPairs;
-
 /** Generates a new RSA key-pair and adds both keys to the keychain.
     This is very slow -- it may take seconds, depending on the key size, CPU speed,
     and other random factors. You may want to start some kind of progress indicator before
@@ -87,19 +79,63 @@
         to stay secure for years; or you could use 4096 if you're extremely paranoid. */
 - (MYKeyPair*) generateRSAKeyPairOfSize: (unsigned)keySize;
 
-@end
+/** Looks up an existing key-pair whose public key has the given digest.
+    Returns nil if there is no such key-pair in the keychain.
+    (This method does not look for public keys embedded in certificates, only 'bare' keys.) */
+- (MYKeyPair*) keyPairWithDigest: (MYSHA1Digest*)pubKeyDigest;
 
-
+/** Enumerates all key-pairs in the keychain.
+    (This method does not find keys embedded in certificates, only 'bare' keys.) */
+- (NSEnumerator*) enumerateKeyPairs;
 
 
 #pragma mark -
 #pragma mark METHODS NOT SUPPORTED ON IPHONE:
 
 
+/** @name Mac-Only
+ *  Functionality not available on iPhone. 
+ */
+//@{
 #if !TARGET_OS_IPHONE
 
-/** Keychain functionality that's not supported on iPhone. */
-@interface MYKeychain (MacOnly)
+/** Enumerates all public keys in the keychain that have the given alias string. */
+- (NSEnumerator*) symmetricKeysWithAlias: (NSString*)alias;
+
+/** Enumerates all public keys in the keychain that have the given alias string. */
+- (NSEnumerator*) publicKeysWithAlias: (NSString*)alias;
+
+/** Imports a key-pair into the keychain, given the external representations
+    of both the public and private keys.
+    Since the private key data is wrapped (encrypted), the Security agent will prompt the user to enter
+    the passphrase. */
+- (MYKeyPair*) importPublicKey: (NSData*)pubKeyData 
+                    privateKey: (NSData*)privKeyData;
+
+/** Imports a key-pair into the keychain, given the external representations
+    of both the public and private keys.
+    Since the private key data is wrapped (encrypted), the Security agent will prompt the user to enter
+    the passphrase. You can specify the title and prompt message for this alert panel. */
+- (MYKeyPair*) importPublicKey: (NSData*)pubKeyData 
+                    privateKey: (NSData*)privKeyData
+                    alertTitle: (NSString*)title
+                   alertPrompt: (NSString*)prompt;
+
+/** Imports a certificate into the keychain, given its external representation. */
+- (MYCertificate*) importCertificate: (NSData*)data
+                                type: (CSSM_CERT_TYPE) type
+                            encoding: (CSSM_CERT_ENCODING) encoding;
+
+//@}
+#endif
+
+
+
+/** @name Expert (Mac-Only)
+ *  Advanced functionality, not available on iPhone. 
+ */
+//@{
+#if !TARGET_OS_IPHONE
 
 /** Creates a MYKeychain for an existing SecKeychainRef. */
 - (id) initWithKeychainRef: (SecKeychainRef)keychainRef;
@@ -131,35 +167,8 @@
 /** The underlying CSSM storage handle; used when calling CSSM APIs. */
 @property (readonly) CSSM_CSP_HANDLE CSPHandle;
 
-
-/** Enumerates all public keys in the keychain that have the given alias string. */
-- (NSEnumerator*) symmetricKeysWithAlias: (NSString*)alias;
-
-/** Enumerates all public keys in the keychain that have the given alias string. */
-- (NSEnumerator*) publicKeysWithAlias: (NSString*)alias;
-
-
-/** Imports a certificate into the keychain, given its external representation. */
-- (MYCertificate*) importCertificate: (NSData*)data
-                                type: (CSSM_CERT_TYPE) type
-                            encoding: (CSSM_CERT_ENCODING) encoding;
-
-/** Imports a key-pair into the keychain, given the external representations
-    of both the public and private keys.
-    Since the private key data is wrapped (encrypted), the Security agent will prompt the user to enter
-    the passphrase. */
-- (MYKeyPair*) importPublicKey: (NSData*)pubKeyData 
-                    privateKey: (NSData*)privKeyData;
-
-/** Imports a key-pair into the keychain, given the external representations
-    of both the public and private keys.
-    Since the private key data is wrapped (encrypted), the Security agent will prompt the user to enter
-    the passphrase. You can specify the title and prompt message for this alert panel. */
-- (MYKeyPair*) importPublicKey: (NSData*)pubKeyData 
-                    privateKey: (NSData*)privKeyData
-                    alertTitle: (NSString*)title
-                   alertPrompt: (NSString*)prompt;
+#endif
+//@}
 
 @end
 
-#endif
diff -r 60e4cbbb5128 -r 8982b8fada63 MYKeychain.m
--- a/MYKeychain.m	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYKeychain.m	Tue Apr 07 10:56:58 2009 -0700
@@ -10,7 +10,7 @@
 #import "MYCrypto_Private.h"
 #import "MYDigest.h"
 
-#if !USE_IPHONE_API
+#if !MYCRYPTO_USE_IPHONE_API
 
 
 @interface MYKeyEnumerator : NSEnumerator
@@ -97,6 +97,12 @@
     [super dealloc];
 }
 
+- (void) finalize
+{
+    if (_keychain) CFRelease(_keychain);
+    [super finalize];
+}
+
 
 + (MYKeychain*) allKeychains
 {
@@ -321,7 +327,7 @@
 }
 
 - (MYKeyPair*) generateRSAKeyPairOfSize: (unsigned)keySize {
-    return [MYKeyPair _generateRSAKeyPairOfSize: keySize inKeychain: self.keychainRefOrDefault];
+    return [MYKeyPair _generateRSAKeyPairOfSize: keySize inKeychain: self];
 }
 
 
@@ -367,6 +373,13 @@
     [super dealloc];
 }
 
+- (void) finalize
+{
+    [_keychain release];
+    if (_search) CFRelease(_search);
+    [super finalize];
+}
+
 
 - (id) nextObject {
     if (!_search)
@@ -416,7 +429,7 @@
 @end
 
 
-#endif !USE_IPHONE_API
+#endif !MYCRYPTO_USE_IPHONE_API
 
 
 
diff -r 60e4cbbb5128 -r 8982b8fada63 MYKeychainItem.h
--- a/MYKeychainItem.h	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYKeychainItem.h	Tue Apr 07 10:56:58 2009 -0700
@@ -8,6 +8,7 @@
 
 #import <Foundation/Foundation.h>
 #import <Security/Security.h>
+#import "MYCryptoConfig.h"
 @class MYKeychain;
 
 
@@ -15,7 +16,7 @@
 extern NSString* const MYCSSMErrorDomain;
 
 
-#if TARGET_OS_IPHONE && !TARGET_IPHONE_SIMULATOR
+#if MYCRYPTO_USE_IPHONE_API
 typedef CFTypeRef MYKeychainItemRef;
 #else
 typedef SecKeychainItemRef MYKeychainItemRef;
diff -r 60e4cbbb5128 -r 8982b8fada63 MYKeychainItem.m
--- a/MYKeychainItem.m	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYKeychainItem.m	Tue Apr 07 10:56:58 2009 -0700
@@ -37,6 +37,12 @@
     [super dealloc];
 }
 
+- (void) finalize
+{
+    if (_itemRef) CFRelease(_itemRef);
+    [super finalize];
+}
+
 - (id) copyWithZone: (NSZone*)zone {
     // As keys are immutable, it's not necessary to make copies of them. This makes it more efficient
     // to use instances as NSDictionary keys or store them in NSSets.
@@ -63,7 +69,7 @@
     return $array((id)_itemRef);
 }
 
-#if USE_IPHONE_API
+#if MYCRYPTO_USE_IPHONE_API
 - (CFDictionaryRef) asQuery {
     return (CFDictionaryRef) $dict( {(id)kSecClass, (id)kSecClassKey},//FIX
                                     {(id)kSecMatchItemList, self._itemList} );
@@ -72,7 +78,7 @@
 
 
 - (MYKeychain*) keychain {
-#if USE_IPHONE_API
+#if MYCRYPTO_USE_IPHONE_API
     return [MYKeychain defaultKeychain];
 #else
     MYKeychain *keychain = nil;
@@ -88,7 +94,7 @@
 }
 
 - (BOOL) removeFromKeychain {
-#if USE_IPHONE_API
+#if MYCRYPTO_USE_IPHONE_API
     return check(SecItemDelete(self.asQuery), @"SecItemDelete");
 #else
     return check(SecKeychainItemDelete((SecKeychainItemRef)_itemRef), @"SecKeychainItemDelete");
@@ -102,7 +108,7 @@
 
 - (NSData*) _getContents: (OSStatus*)outError {
     NSData *contents = nil;
-#if USE_IPHONE_API
+#if MYCRYPTO_USE_IPHONE_API
 #else
 	UInt32 length = 0;
     void *bytes = NULL;
@@ -117,7 +123,7 @@
 
 + (NSData*) _getAttribute: (SecKeychainAttrType)attr ofItem: (MYKeychainItemRef)item {
     NSData *value = nil;
-#if USE_IPHONE_API
+#if MYCRYPTO_USE_IPHONE_API
     NSDictionary *info = $dict( {(id)kSecClass, (id)kSecClassKey},
                                 {(id)kSecMatchItemList, $array((id)item)},
                                 {(id)kSecReturnAttributes, $true} );
@@ -171,7 +177,7 @@
 + (BOOL) _setAttribute: (SecKeychainAttrType)attr ofItem: (MYKeychainItemRef)item
            stringValue: (NSString*)stringValue
 {
-#if USE_IPHONE_API
+#if MYCRYPTO_USE_IPHONE_API
     id value = stringValue ?(id)stringValue :(id)[NSNull null];
     NSDictionary *query = $dict({(id)kSecClass, (id)kSecClassKey},
                                 {(id)kSecAttrKeyType, (id)attr},
@@ -200,7 +206,7 @@
 
 BOOL check(OSStatus err, NSString *what) {
     if (err) {
-#if !USE_IPHONE_API
+#if !MYCRYPTO_USE_IPHONE_API
         if (err < -2000000000)
             return checkcssm(err,what);
 #endif
@@ -210,7 +216,7 @@
         return YES;
 }
 
-#if !USE_IPHONE_API
+#if !MYCRYPTO_USE_IPHONE_API
 BOOL checkcssm(CSSM_RETURN err, NSString *what) {
     if (err != CSSM_OK) {
         Warn(@"MYCrypto error, %@: %@", what, MYErrorName(MYCSSMErrorDomain,err));
diff -r 60e4cbbb5128 -r 8982b8fada63 MYPublicKey-iPhone.m
--- a/MYPublicKey-iPhone.m	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYPublicKey-iPhone.m	Tue Apr 07 10:56:58 2009 -0700
@@ -9,7 +9,7 @@
 #import "MYPublicKey.h"
 #import "MYCrypto_Private.h"
 
-#if USE_IPHONE_API
+#if MYCRYPTO_USE_IPHONE_API
 
 #import "MYDigest.h"
 #import "MYErrorUtils.h"
@@ -36,18 +36,22 @@
 }
 
 
-
-- (MYSHA1Digest*) publicKeyDigest {
-    NSData *digestData = [self _attribute: kSecAttrApplicationLabel];
++ (MYSHA1Digest*) _digestOfKey: (SecKeyRef)key {
+    NSData *digestData = [MYKeychainItem _getAttribute: kSecAttrApplicationLabel ofItem: key];
     if (digestData)
         return (MYSHA1Digest*) [MYSHA1Digest digestFromDigestData: digestData];
     else {
-        Warn(@"MYKeyPair: public key didn't have digest attribute");
+        Warn(@"MYKeyPair: public keyref %p didn't have digest attribute", key);
         return nil;
     }
 }
 
 
+- (MYSHA1Digest*) publicKeyDigest {
+    return [[self class] _digestOfKey: self.keyRef];
+}
+
+
 - (NSData*) encryptData: (NSData*)data {
     return _crypt(self.keyRef,data,kCCEncrypt);
 }
@@ -94,4 +98,4 @@
         return [NSData dataWithBytesNoCopy: outputBuf length: outputLength freeWhenDone: YES];
 }
 
-#endif USE_IPHONE_API
+#endif MYCRYPTO_USE_IPHONE_API
diff -r 60e4cbbb5128 -r 8982b8fada63 MYPublicKey.m
--- a/MYPublicKey.m	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYPublicKey.m	Tue Apr 07 10:56:58 2009 -0700
@@ -9,7 +9,7 @@
 #import "MYPublicKey.h"
 #import "MYCrypto_Private.h"
 
-#if !USE_IPHONE_API
+#if !MYCRYPTO_USE_IPHONE_API
 
 #import "MYDigest.h"
 #import "MYErrorUtils.h"
@@ -185,7 +185,7 @@
         return 0;
 }
 
-#endif !USE_IPHONE_API
+#endif !MYCRYPTO_USE_IPHONE_API
 
 
 
diff -r 60e4cbbb5128 -r 8982b8fada63 MYSymmetricKey.h
--- a/MYSymmetricKey.h	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYSymmetricKey.h	Tue Apr 07 10:56:58 2009 -0700
@@ -25,4 +25,7 @@
 /** The key's algorithm. */
 @property (readonly) CCAlgorithm algorithm;
 
+/** The key's size/length, in bits. */
+@property (readonly) unsigned keySizeInBits;
+
 @end
diff -r 60e4cbbb5128 -r 8982b8fada63 MYSymmetricKey.m
--- a/MYSymmetricKey.m	Sat Apr 04 22:56:13 2009 -0700
+++ b/MYSymmetricKey.m	Tue Apr 07 10:56:58 2009 -0700
@@ -11,7 +11,7 @@
 #import "MYCrypto_Private.h"
 
 
-#if USE_IPHONE_API
+#if MYCRYPTO_USE_IPHONE_API
 typedef uint32_t CSSM_ALGORITHMS;
 enum {
 // Taken from cssmtype.h in OS X 10.5 SDK:
@@ -32,6 +32,8 @@
     CSSM_ALGID_AES, CSSM_ALGID_DES, CSSM_ALGID_3DES_3KEY, CSSM_ALGID_CAST, CSSM_ALGID_RC4
 };
 
+static const char *kCCAlgorithmNames[] = {"AES", "DES", "DES^3", "CAST", "RC4"};
+
 
 #pragma mark -
 @implementation MYSymmetricKey
@@ -44,21 +46,41 @@
     Assert(algorithm <= kCCAlgorithmRC4);
     Assert(keyData);
     SecKeyRef keyRef = NULL;
-#if USE_IPHONE_API
-    unsigned keySizeInBits = keyData.length / 8;
+#if MYCRYPTO_USE_IPHONE_API
+    NSNumber *keySizeInBits = [NSNumber numberWithUnsignedInt: keyData.length * 8];
     NSDictionary *keyAttrs = $dict( {(id)kSecClass, (id)kSecClassKey},
-                                    {(id)kSecAttrKeyClass, (id)kSecAttrKeyClassSymmetric},
-                                    {(id)kSecAttrKeyType, $object(kCSSMAlgorithms[algorithm])},
-                                    {(id)kSecAttrKeySizeInBits, $object(keySizeInBits)},
-                                    {(id)kSecAttrEffectiveKeySize, $object(keySizeInBits)},
+                                    //{(id)kSecAttrKeyClass, (id)kSecAttrKeyClassSymmetric},
+                                    {(id)kSecAttrKeyType, [NSNumber numberWithUnsignedInt: kCSSMAlgorithms[algorithm]]},
+                                    {(id)kSecAttrKeySizeInBits, keySizeInBits},
+                                    {(id)kSecAttrEffectiveKeySize, keySizeInBits},
                                     {(id)kSecAttrIsPermanent, keychain ?$true :$false},
-                                    {(id)kSecValueData, keyData} );
+                                    {(id)kSecAttrCanEncrypt, $true},
+                                    {(id)kSecAttrCanDecrypt, $true},
+                                    {(id)kSecAttrCanWrap, $false},
+                                    {(id)kSecAttrCanUnwrap, $false},
+                                    {(id)kSecAttrCanDerive, $false},
+                                    {(id)kSecAttrCanSign, $false},
+                                    {(id)kSecAttrCanVerify, $false},
+                                    {(id)kSecValueData, keyData},
+    //{(id)kSecAttrApplicationTag, [@"foo" dataUsingEncoding: NSUTF8StringEncoding]}, //TEMP
+                                    {(id)kSecReturnPersistentRef, $true});
     if (!check(SecItemAdd((CFDictionaryRef)keyAttrs, (CFTypeRef*)&keyRef), @"SecItemAdd")) {
         [self release];
         return nil;
     }
+    Log(@"SecItemAdd returned %@", keyRef);//TEMP
+    Assert(keyRef, @"SecItemAdd didn't return anything");
 #else
     Assert(NO,@"Unimplemented"); //FIX
+    /* The technique below doesn't work, because there's no way to tell SecKeychainItemImport
+       what algorithm to use when importing a raw key. Still looking for a solution... --jpa 4/2009
+    SecKeyImportExportParameters params = {};
+    keyRef = importKey(keyData, kSecItemTypeSessionKey, keychain.keychainRefOrDefault, &params);
+    if (!keyRef) {
+        [self release];
+        return nil;
+    }
+     */
 #endif
     self = [self initWithKeyRef: keyRef];
     CFRelease(keyRef);
@@ -75,8 +97,8 @@
                                       algorithm: (CCAlgorithm)algorithm
                                      inKeychain: (MYKeychain*)keychain
 {
-#if USE_IPHONE_API
-    return [[[self alloc] _initWithKeyData: [MYCryptor randomKeyOfLength: (keySizeInBits+7)/8]
+#if MYCRYPTO_USE_IPHONE_API
+    return [[[self alloc] _initWithKeyData: [MYCryptor randomKeyOfLength: keySizeInBits]
                                  algorithm: algorithm
                                 inKeychain: keychain]
                     autorelease];
@@ -106,9 +128,28 @@
 }
 
 
+#if !TARGET_OS_IPHONE
+- (NSData*) exportKeyInFormat: (SecExternalFormat)format
+                      withPEM: (BOOL)withPEM
+{
+    SecKeyImportExportParameters params = {
+        .version = SEC_KEY_IMPORT_EXPORT_PARAMS_VERSION,
+        .flags = kSecKeySecurePassphrase,
+    };
+    CFDataRef data = NULL;
+    if (check(SecKeychainItemExport(self.keyRef,
+                                    format, (withPEM ?kSecItemPemArmour :0), 
+                                    &params, &data),
+              @"SecKeychainItemExport"))
+        return [(id)CFMakeCollectable(data) autorelease];
+    else
+        return nil;
+}
+#endif
+
 
 - (SecExternalItemType) keyType {
-#if USE_IPHONE_API
+#if MYCRYPTO_USE_IPHONE_API
     return kSecAttrKeyClassSymmetric;
 #else
     return kSecItemTypeSessionKey;
@@ -117,7 +158,7 @@
 
 - (CCAlgorithm) algorithm {
     CSSM_ALGORITHMS cssmAlg;
-#if USE_IPHONE_API
+#if MYCRYPTO_USE_IPHONE_API
     id keyType = [self _attribute: kSecAttrKeyType];
     Assert(keyType!=nil, @"Key has no kSecAttrKeyType");
     cssmAlg = [keyType unsignedIntValue];
@@ -141,6 +182,31 @@
     }
 }
 
+- (const char*) algorithmName {
+    CCAlgorithm a = self.algorithm;
+    if (a >= 0 && a <= kCCAlgorithmRC4)
+        return kCCAlgorithmNames[a];
+    else
+        return "???";
+}
+
+- (unsigned) keySizeInBits {
+#if MYCRYPTO_USE_IPHONE_API
+    id keySize = [self _attribute: kSecAttrKeySizeInBits];
+    Assert(keySize!=nil, @"Key has no kSecAttrKeySizeInBits");
+    return [keySize unsignedIntValue];
+#else
+    const CSSM_KEY *key = self.cssmKey;
+    Assert(key);
+    return key->KeyHeader.LogicalKeySizeInBits;
+#endif
+}
+
+
+- (NSString*) description {
+    return $sprintf(@"%@[%u-bit %s]", [self class], self.keySizeInBits, self.algorithmName);
+}
+
 
 - (NSData*) _cryptData: (NSData*)data operation: (CCOperation)op options: (CCOptions)options
 {
diff -r 60e4cbbb5128 -r 8982b8fada63 README.textile
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.textile	Tue Apr 07 10:56:58 2009 -0700
@@ -0,0 +1,75 @@
+h1=. MYCrypto
+
+p=. Version 0.1 -- 6 April 2009
+
+p=. By "Jens Alfke":mailto:jens@mooseyard.com <br>
+Based in part on code by Wade Tregaskis, <br>
+and sample code by Apple Computer.
+
+h2. Introduction
+
+*MYCrypto* is a high-level cryptography API for Mac OS X and iPhone. It's an Objective-C wrapper around the system
+"*Keychain*":http://developer.apple.com/documentation/Security/Conceptual/keychainServConcepts/02concepts/concepts.html#//apple_ref/doc/uid/TP30000897-CH204-TP9
+and *CSSM* APIs, which are notoriously hard to use, as well as *CommonCrypto*, which is easier but quite limited.
+
+MYCrypto gives you easy object-oriented interfaces to
+
+* Symmmetric cryptography (session keys and password-based encryption)
+* Asymmetric cryptography (public and private keys; digital signatures)
+* Cryptographic digests/hashes (effectively-unique IDs for data)
+* The Keychain (a secure, encrypted storage system for keys and passwords)
+
+h3. Requirements
+
+* Mac OS X 10.5 or later _[has been tested on 10.5.6]_
+* iPhone OS 2.0 or later _[not yet tested; see Limitations section below]_
+* iPhone Simulator, for iPhone OS 2.0 or later
+* The MYUtilities library, which is used by MYCrypto.
+* _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.
+
+h3. Current Limitations
+
+h4. First off, the biggest caveat of all:
+
+* *MYCrypto 0.1 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.)
+
+h4. Further issues with the 0.1 release:
+
+* *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.
+* Exporting symmetric keys in wrapped (encrypted) form will fail. Currently they can be exported only as raw key data.
+* Importing symmetric keys, in any form, will fail ... kind of a deal-breaker for using them across two computers, unfortunately.
+
+h4. Current API limitations, to be remedied in the future:
+
+* 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.
+* No bulk data encryption/decryption using public/private keys. MYKeyPair only does raw RSA crypto, which is slow and limited to small chunks of data.
+* No creating or signing certificate-requests, or creating self-signed certificates.
+* No evaluation of trust in certificates (i.e. SecTrust and related APIs.)
+* 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.
+
+h2. Overview
+
+The class hierarchy of MYCrypto looks like this:
+
+* "MYKeychainItem":Documentation/html/interfaceMYKeychainItem.html
+** "MYKey":Documentation/html/interfaceMYKey.html
+*** "*MYSymmetricKey*":Documentation/html/interfaceMYSymmetricKey.html
+*** "*MYPublicKey*":Documentation/html/interfaceMYPublicKey.html
+**** "*MYKeyPair*":Documentation/html/interfaceMYKeyPair.html
+*** "*MYCertificate*":Documentation/html/interfaceMYCertificate.html
+* "MYDigest":Documentation/html/interfaceMYDigest.html
+** "*MYSHA1Digest*":Documentation/html/interfaceMYSHA1Digest.html
+** "*MYSHA256Digest*":Documentation/html/interfaceMYSHA256Digest.html
+* "MYCryptor":Documentation/html/interfaceMYCryptor.html
+
+(*Boldface* classes are concrete, others are abstract.)
+
+h2. References
+
+* "??Security Overview??":http://developer.apple.com/documentation/Security/Conceptual/Security_Overview/Introduction/Introduction.html (Apple)
+* "??Secure Coding Guide??":http://developer.apple.com/documentation/Security/Conceptual/SecureCodingGuide/Introduction.html (Apple)
+
+* "??Common Security: CDSA and CSSM, Version 2??":http://www.opengroup.org/publications/catalog/c914.htm (The Open Group)
+
+* "??Practical Cryptography??":http://www.schneier.com/book-practical.html (Ferguson and Schneier)
+* "??The Devil's InfoSec Dictionary??":http://www.csoonline.com/article/220527/The_Devil_s_Infosec_Dictionary (CSO Online)
\ No newline at end of file
diff -r 60e4cbbb5128 -r 8982b8fada63 iPhone/MYCrypto_iPhoneAppDelegate.m
--- a/iPhone/MYCrypto_iPhoneAppDelegate.m	Sat Apr 04 22:56:13 2009 -0700
+++ b/iPhone/MYCrypto_iPhoneAppDelegate.m	Tue Apr 07 10:56:58 2009 -0700
@@ -19,11 +19,12 @@
 
     // Override point for customization after application launch
     [window makeKeyAndVisible];
-    
+    /*
     static const char *testArgs[] = {"MYCrypto", "Test_All"};
     int argc = 2;
     const char **argv = testArgs;
     RunTestCases(argc,argv);
+     */
 }
 
 
diff -r 60e4cbbb5128 -r 8982b8fada63 iPhone/MYCrypto_iPhone_main.m
--- a/iPhone/MYCrypto_iPhone_main.m	Sat Apr 04 22:56:13 2009 -0700
+++ b/iPhone/MYCrypto_iPhone_main.m	Tue Apr 07 10:56:58 2009 -0700
@@ -9,14 +9,12 @@
 #import <UIKit/UIKit.h>
 
 int main(int argc, char *argv[]) {
-    /*
     if (argc<2) {
         static char *testArgs[] = {"MYCrypto", "Test_All"};
         argc = 2;
         argv = testArgs;
     }
     RunTestCases(argc,(const char**)argv);
-     */
     
     NSAutoreleasePool * pool = [[NSAutoreleasePool alloc] init];
     int retVal = UIApplicationMain(argc, argv, nil, nil);
diff -r 60e4cbbb5128 -r 8982b8fada63 maindocs.h
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/maindocs.h	Tue Apr 07 10:56:58 2009 -0700
@@ -0,0 +1,53 @@
+//
+//  maindocs.h
+//  MYCrypto
+//
+//  Created by Jens Alfke on 4/06/09.
+//  Copyright 2009 Jens Alfke. All rights reserved.
+//
+// This file just contains the Doxygen comments that generate the main (index.html) page content.
+
+
+/*! \mainpage MYCrypto: Mooseyard Cryptography Library
+ 
+    <center><b>By <a href="/Jens/">Jens Alfke</a></b></center>
+
+\section intro_sec Introduction
+ 
+    MYCrypto is a set of Objective-C cryptography classes for Cocoa applications on Mac OS X and iPhone.
+    
+    <a href="annotated.html">Browse the class documentation.</a>
+ 
+\section license License
+ 
+ MYCrypto is released under a BSD license, which means you can freely use it in open-source
+ or commercial projects, provided you give credit in your documentation or About box.
+   
+\section config Configuration
+ 
+    MYCrypto requires Mac OS X 10.5 or later, since it uses Objective-C 2 features like
+    properties and for...in loops.
+ 
+    MYCrypto uses my <a href="/hg/hgwebdir.cgi/MYUtilities">MYUtilities</a> library. You'll need to have downloaded that library, and added
+    the necessary source files and headers to your project. See the MYCrypto Xcode project,
+    which contains the minimal set of MYUtilities files needed to build MYUtilities. (That project
+    has its search paths set up to assume that MYUtilities is in a directory next to MYCrypto.)
+
+\section download How To Get It
+
+    <ul>
+    <li><a href="/hg/hgwebdir.cgi/MYCrypto/archive/tip.zip">Download the current source code</a>
+    <li>To check out the source code using <a href="http://selenic.com/mercurial">Mercurial</a>:
+    \verbatim hg clone /hg/hgwebdir.cgi/MYCrypto/ MYCrypto \endverbatim
+    <li>As described above, you'll also need to download or check out <a href="/hg/hgwebdir.cgi/MYUtilities">MYUtilities</a> and put it in 
+    a directory next to MYCrypto.
+    </ul>
+
+    Or if you're just looking:
+
+    <ul>
+    <li><a href="/hg/hgwebdir.cgi/MYCrypto/file/tip">Browse the source code</a>
+    <li><a href="annotated.html">Browse the class documentation</a>
+    </ul>
+    
+ */