1.1 --- a/MYCryptor.h	Sat Apr 04 22:56:13 2009 -0700
     1.2 +++ b/MYCryptor.h	Tue Apr 07 10:56:58 2009 -0700
     1.3 @@ -10,9 +10,9 @@
     1.4  #import <CommonCrypto/CommonCryptor.h>
     1.5  
     1.6  
     1.7 -/** Symmetric encryption: a simple Cocoa wrapper for CommonCrypto/commonCryptor.h.
     1.8 -    Provides a streaming interface for encrypting/decrypting data.
     1.9 -    This class will probably be merged into or integrated with MYSymmetricKey. */
    1.10 +/** Symmetric encryption: a streaming interface for encrypting/decrypting data.
    1.11 +    This is a simple Cocoa wrapper for CommonCrypto/commonCryptor.h. It will probably be
    1.12 +    merged into, or integrated with, MYSymmetricKey. */
    1.13  @interface MYCryptor : NSObject
    1.14  {
    1.15      @private
    1.16 @@ -27,12 +27,26 @@
    1.17      size_t _outputExtraBytes;
    1.18  }
    1.19  
    1.20 -/** Returns a block of cryptographically-random data, suitable for use as a symmetric key.
    1.21 -    (CommonCryptor.h defines constants for key sizes and size-ranges, like kCCKeySizeAES128.) */
    1.22 -+ (NSData*) randomKeyOfLength: (size_t)length;
    1.23 +/** Returns a randomly-generated symmetric key of the desired length (in bits).
    1.24 + *  @param lengthInBits  The length of the desired key, in bits (not bytes).
    1.25 + */
    1.26 ++ (NSData*) randomKeyOfLength: (size_t)lengthInBits;
    1.27  
    1.28 -/** Converts a passphrase into a block of data of the given size, suitable for use as a symmetric key. */
    1.29 -+ (NSData*) keyOfLength: (size_t)lengthInBits fromPassphrase: (NSString*)passphrase;
    1.30 +/** Converts a passphrase into a symmetric key of the desired length (in bits).
    1.31 + *  The same passphrase (and salt) will always return the same key, so you can use this method
    1.32 + *  to encrypt and decrypt data using a user-entered passphrase, without having to store the key
    1.33 + *  itself in the keychain.
    1.34 + *  @param lengthInBits  The length of the desired key, in bits (not bytes).
    1.35 + *  @param passphrase  The user-entered passphrase.
    1.36 + *  @param salt  An arbitrary value whose description will be appended to the passphrase before
    1.37 + *          hashing, to perturb the resulting bits. The purpose of this is to make it harder for
    1.38 + *          an attacker to brute-force the key using a precompiled list of digests of common
    1.39 + *          passwords. Changing the salt changes the key, so you need to pass the same value when
    1.40 + *          re-deriving the key as you did when first generating it.
    1.41 + */
    1.42 ++ (NSData*) keyOfLength: (size_t)lengthInBits
    1.43 +         fromPassphrase: (NSString*)passphrase
    1.44 +                   salt: (id)salt;
    1.45  
    1.46  /** Creates a MYCryptor configured to encrypt data. */
    1.47  - (id) initEncryptorWithKey: (NSData*)key