1.1 --- a/README.textile	Sun Apr 12 22:16:14 2009 -0700
     1.2 +++ b/README.textile	Tue Apr 14 18:34:52 2009 -0700
     1.3 @@ -34,13 +34,27 @@
     1.4  h3. How To Get It
     1.5  
     1.6  * "Download the current source code":http://mooseyard.com/hg/hgwebdir.cgi/MYCrypto/archive/tip.zip
     1.7 -* To check out the source code using "Mercurial":http://selenic.com/mercurial/:<br>
     1.8 +* or to check out the source code using "Mercurial":http://selenic.com/mercurial/:<br>
     1.9  @hg clone http://mooseyard.com/hg/hgwebdir.cgi/MYCrypto/ MYCrypto@
    1.10  * As described above, you'll also need to download or check out MYUtilities and put it in a directory next to MYCrypto.
    1.11 +* To file or view bug reports, visit "the project tracker page":http://mooseyard.lighthouseapp.com/projects/29227/home.
    1.12  * Or if you're just looking:
    1.13  ** "Browse the source code":http://mooseyard.com/hg/hgwebdir.cgi/MYCrypto/file/tip
    1.14  ** "Browse the class documentation":Documentation/html/hierarchy.html
    1.15  
    1.16 +h3. How To Build It
    1.17 +
    1.18 +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':
    1.19 +
    1.20 +# Open Xcode's Preferences panel
    1.21 +# Click the "Source Trees" icon at the top
    1.22 +# Click the "+" button to add a new item to the list
    1.23 +# 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.
    1.24 +
    1.25 +Now you're golden. From now on you can just open MYCrypto.xcode and press the Build button.
    1.26 +
    1.27 +(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.)
    1.28 +
    1.29  h2. Overview
    1.30  
    1.31  The class hierarchy of MYCrypto looks like this:
    1.32 @@ -63,6 +77,65 @@
    1.33  
    1.34  (_Italicized_ classes are abstract.)
    1.35  
    1.36 +h2. Examples
    1.37 +
    1.38 +h3. Creating an RSA key-pair
    1.39 +
    1.40 +<pre>
    1.41 +MYPrivateKey *keyPair = [[MYKeychain defaultKeychain] generateRSAKeyPairOfSize: 2048];
    1.42 +</pre>
    1.43 +
    1.44 +h3. Creating a self-signed identity certificate:
    1.45 +
    1.46 +<pre>
    1.47 +NSDictionary *attrs = [NSDictionary dictionaryWithObjectsAndKeys:
    1.48 +		@"alice", @"Common Name",
    1.49 +		@"Alice", @"Given Name",
    1.50 +		@"Lidell", @"Surname",
    1.51 +		nil];
    1.52 +MYIdentity *ident = [keyPair createSelfSignedIdentityWithAttributes: attrs];
    1.53 +
    1.54 +NSData *certData = ident.certificateData;
    1.55 +</pre>
    1.56 +
    1.57 +h3. Signing and encrypting a message:
    1.58 +
    1.59 +<pre>
    1.60 +NSData *cleartext = [@"Attack at dawn" dataUsingEncoding: NSUTF8StringEncoding];
    1.61 +MYEncoder *encoder = [[MYEncoder alloc] init];
    1.62 +[encoder addSigner: ident];
    1.63 +[encoder addRecipient: bob];
    1.64 +[encoder addRecipient: carla];
    1.65 +[encoder addData: cleartext];
    1.66 +[encoder finish];
    1.67 +NSData *ciphertext = encoder.encodedData;
    1.68 +
    1.69 +sendMessage(ciphertext);
    1.70 +</pre>
    1.71 +
    1.72 +h3. Verifying and decoding a message:
    1.73 +
    1.74 +<pre>
    1.75 +NSData *ciphertext = receiveMessage();
    1.76 +NSError *error;
    1.77 +MYDecoder *decoder = [[MYDecoder alloc] initWithData: ciphertext error: &error];
    1.78 +if (!decoder)
    1.79 +    return NO;
    1.80 +
    1.81 +if (!decoder.isSigned)
    1.82 +    return NO;
    1.83 +decoder.policy = [MYCertificate X509Policy];
    1.84 +NSMutableArray *signerCerts = [NSMutableArray array];
    1.85 +for (MYSigner *signer in decoder.signers) {
    1.86 +    if (signer.status != kCMSSignerValid) {
    1.87 +        return NO;
    1.88 +    [signerCerts addObject: signer.certificate];
    1.89 +}
    1.90 +
    1.91 +NSData *plaintext = decoder.content;
    1.92 +processMessage(plaintext, signerCerts);
    1.93 +</pre>
    1.94 +
    1.95  h2. Current Limitations
    1.96  
    1.97  h3. First off, the biggest caveat of all: