1.1 --- a/MYSymmetricKey.h	Sun Apr 19 21:19:35 2009 -0700
     1.2 +++ b/MYSymmetricKey.h	Sat Jun 06 15:01:28 2009 -0700
     1.3 @@ -10,8 +10,17 @@
     1.4  #import <CommonCrypto/CommonCryptor.h>
     1.5  
     1.6  
     1.7 +/** An old-fashioned symmetric key, so named because it both encrypts and decrypts.
     1.8 +    A key can be generated at random, stored in the keychain, or derived from a user-entered
     1.9 +    passphrase.
    1.10 + 
    1.11 +    These days, symmetric encryption is used mostly on local data such as files, with
    1.12 +    passphrases; or as a transient "session key" for data sent between users, with the
    1.13 +    session key itself encrypted in the message using public-key encryption. (The
    1.14 +    MYEncoder/MYDecoder classes manage this second usage, whose details are tricky.) */
    1.15  @interface MYSymmetricKey : MYKey <MYEncryption, MYDecryption>
    1.16  {
    1.17 +    @private
    1.18  #if !MYCRYPTO_USE_IPHONE_API
    1.19      CSSM_KEY *_ownedCSSMKey;
    1.20  #endif
    1.21 @@ -36,7 +45,17 @@
    1.22  
    1.23  #if !TARGET_OS_IPHONE
    1.24  
    1.25 -- (NSData*) exportWrappedKeyWithPassphrasePrompt: (NSString*)prompt;
    1.26 +/** Exports the key as a data blob, so that it can be stored as a backup, or transferred
    1.27 +    to another computer. Since the key is sensitive, it must be exported in encrypted form
    1.28 +    using a user-chosen passphrase. This method will display a standard alert panel, run by
    1.29 +    the Security agent, that prompts the user to enter a new passphrase for encrypting the key.
    1.30 +    The same passphrase must be re-entered when importing the key from the data blob. */
    1.31 + - (NSData*) exportWrappedKeyWithPassphrasePrompt: (NSString*)prompt;
    1.32 +
    1.33 +/** Recreates a symmetric key from its wrapped (encrypted) form. The user will be prompted for
    1.34 +    the passphrase to decrypt the key; this must be the same passphrase that was entered when
    1.35 +    wrapping the key, e.g. when -exportWrappedKeyWithPassphrasePrompt: was called. */
    1.36 +- (id) initWithWrappedKeyData: (NSData*)wrappedKeyData;
    1.37  
    1.38  /** Converts a passphrase into a symmetric key.
    1.39      The same passphrase (and salt) will always return the same key, so you can use this method
    1.40 @@ -48,12 +67,12 @@
    1.41          passphrase twice, to check for errors, and the nifty passphrase-strength meter will be
    1.42          displayed. If NO, there's only one text-field, and an option to display its contents in
    1.43          the clear.
    1.44 -    @param salt  An arbitrary value whose data will be mixed in with the passphrase before
    1.45 +    @param saltObj  An arbitrary value whose data will be mixed in with the passphrase before
    1.46          hashing, to perturb the resulting bits. The purpose of this is to make it harder for
    1.47          an attacker to brute-force the key using a precompiled list of digests of common
    1.48          passwords. Changing the salt changes the key, so you need to pass the same value when
    1.49          re-deriving the key as you did when first generating it. */
    1.50 - + (MYSymmetricKey*) generateFromUserPassphraseWithAlertTitle: (NSString*)alertTitle
    1.51 ++ (MYSymmetricKey*) generateFromUserPassphraseWithAlertTitle: (NSString*)alertTitle
    1.52                                                   alertPrompt: (NSString*)prompt
    1.53                                                      creating: (BOOL)creating
    1.54                                                          salt: (id)saltObj;