README.textile
author snej@snej.local
Sun Apr 12 22:16:14 2009 -0700 (2009-04-12)
changeset 9 aa5eb3fd6ebf
parent 8 4c0eafa7b233
child 11 3568d5fd4b6a
permissions -rw-r--r--
Doc touch-up
     1 h1=. MYCrypto
     2 
     3 p=. Version 0.2 -- 12 April 2009
     4 
     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.
     8 
     9 h2. Introduction
    10 
    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.
    14 
    15 MYCrypto gives you easy object-oriented interfaces to:
    16 
    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
    23 
    24 It's open source, released under a friendly BSD license.
    25 
    26 h3. Requirements
    27 
    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.
    33 
    34 h3. How To Get It
    35 
    36 * "Download the current source code":http://mooseyard.com/hg/hgwebdir.cgi/MYCrypto/archive/tip.zip
    37 * 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 * Or if you're just looking:
    41 ** "Browse the source code":http://mooseyard.com/hg/hgwebdir.cgi/MYCrypto/file/tip
    42 ** "Browse the class documentation":Documentation/html/hierarchy.html
    43 
    44 h2. Overview
    45 
    46 The class hierarchy of MYCrypto looks like this:
    47 
    48 * "_MYKeychain_":Documentation/html/interfaceMYKeychain.html
    49 * "_MYKeychainItem_":Documentation/html/interfaceMYKeychainItem.html
    50 ** "_MYKey_":Documentation/html/interfaceMYKey.html
    51 *** "MYSymmetricKey":Documentation/html/interfaceMYSymmetricKey.html
    52 *** "MYPublicKey":Documentation/html/interfaceMYPublicKey.html
    53 *** "MYPrivateKey":Documentation/html/interfaceMYPrivateKey.html
    54 *** "MYCertificate":Documentation/html/interfaceMYCertificate.html
    55 **** "MYIdentity":Documentation/html/interfaceMYIdentity.html
    56 * "_MYDigest_":Documentation/html/interfaceMYDigest.html
    57 ** "MYSHA1Digest":Documentation/html/interfaceMYSHA1Digest.html
    58 ** "MYSHA256Digest":Documentation/html/interfaceMYSHA256Digest.html
    59 * "MYCryptor":Documentation/html/interfaceMYCryptor.html
    60 * "MYEncoder":Documentation/html/interfaceMYEncoder.html
    61 * "MYDecoder":Documentation/html/interfaceMYDecoder.html
    62 * "MYSigner":Documentation/html/interfaceMYSigner.html
    63 
    64 (_Italicized_ classes are abstract.)
    65 
    66 h2. Current Limitations
    67 
    68 h3. First off, the biggest caveat of all:
    69 
    70 * *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.)
    71 
    72 h3. Further issues with the 0.2 release:
    73 
    74 * *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.
    75 * Exporting symmetric keys in wrapped (encrypted) form will fail. Currently they can be exported only as raw key data.
    76 * Importing symmetric keys, in any form, will fail ... kind of a deal-breaker for using them across two computers, unfortunately.
    77 
    78 h3. Current API limitations, to be remedied in the future:
    79 
    80 * 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.
    81 * No evaluation of trust in certificates (i.e. SecTrust and related APIs.)
    82 * 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.
    83 
    84 h2. References
    85 
    86 * "??Security Overview??":http://developer.apple.com/documentation/Security/Conceptual/Security_Overview/Introduction/Introduction.html (Apple)
    87 * "??Secure Coding Guide??":http://developer.apple.com/documentation/Security/Conceptual/SecureCodingGuide/Introduction.html (Apple)
    88 
    89 * "??Common Security: CDSA and CSSM, Version 2??":http://www.opengroup.org/publications/catalog/c914.htm (The Open Group)
    90 
    91 * "??Practical Cryptography??":http://www.schneier.com/book-practical.html (Ferguson and Schneier)
    92 * "??Handbook of Applied Cryptography??":http://www.cacr.math.uwaterloo.ca/hac/ (Menezes, van Oorschot, Vanstone) -- free download!
    93 * "??The Devil's InfoSec Dictionary??":http://www.csoonline.com/article/220527/The_Devil_s_Infosec_Dictionary (CSO Online)