Whew, lots and lots of changes accumulated over the past few weeks. Mostly fixes for bugs I discovered while retrofitting Cloudy to use MYCrypto.
5 // Created by Jens Alfke on 4/2/09.
6 // Copyright 2009 Jens Alfke. All rights reserved.
10 #import <CommonCrypto/CommonCryptor.h>
13 /** An old-fashioned symmetric key, so named because it both encrypts and decrypts.
14 A key can be generated at random, stored in the keychain, or derived from a user-entered
17 These days, symmetric encryption is used mostly on local data such as files, with
18 passphrases; or as a transient "session key" for data sent between users, with the
19 session key itself encrypted in the message using public-key encryption. (The
20 MYEncoder/MYDecoder classes manage this second usage, whose details are tricky.) */
21 @interface MYSymmetricKey : MYKey <MYEncryption, MYDecryption>
24 #if MYCRYPTO_USE_IPHONE_API
25 CCAlgorithm _algorithm;
26 unsigned _keySizeInBits;
28 CSSM_KEY *_ownedCSSMKey;
32 /** Initializes a symmetric key from the given key data and algorithm. */
33 - (id) initWithKeyData: (NSData*)keyData
34 algorithm: (CCAlgorithm)algorithm;
36 /** Randomly generates a new symmetric key, using the given algorithm and key-size in bits.
37 The key is not added to any keychain; if you want to keep the key persistently, use
38 the method of the same name in the MYKeychain class. */
39 + (MYSymmetricKey*) generateSymmetricKeyOfSize: (unsigned)keySizeInBits
40 algorithm: (CCAlgorithm)algorithm;
42 /** The key's algorithm. */
43 @property (readonly) CCAlgorithm algorithm;
48 /** Exports the key as a data blob, so that it can be stored as a backup, or transferred
49 to another computer. Since the key is sensitive, it must be exported in encrypted form
50 using a user-chosen passphrase. This method will display a standard alert panel, run by
51 the Security agent, that prompts the user to enter a new passphrase for encrypting the key.
52 The same passphrase must be re-entered when importing the key from the data blob. */
53 - (NSData*) exportWrappedKeyWithPassphrasePrompt: (NSString*)prompt;
55 /** Recreates a symmetric key from its wrapped (encrypted) form. The user will be prompted for
56 the passphrase to decrypt the key; this must be the same passphrase that was entered when
57 wrapping the key, e.g. when -exportWrappedKeyWithPassphrasePrompt: was called. */
58 - (id) initWithWrappedKeyData: (NSData*)wrappedKeyData;
60 /** Converts a passphrase into a symmetric key.
61 The same passphrase (and salt) will always return the same key, so you can use this method
62 to encrypt and decrypt data using a user-entered passphrase, without having to store the key
63 itself in the keychain.
64 @param alertTitle A title for the alert (this seems to be ignored by the OS).
65 @param prompt A prompt string displayed in the alert.
66 @param creating Is a new passphrase being created? If YES, the user will have to enter the
67 passphrase twice, to check for errors, and the nifty passphrase-strength meter will be
68 displayed. If NO, there's only one text-field, and an option to display its contents in
70 @param saltObj An arbitrary value whose data will be mixed in with the passphrase before
71 hashing, to perturb the resulting bits. The purpose of this is to make it harder for
72 an attacker to brute-force the key using a precompiled list of digests of common
73 passwords. Changing the salt changes the key, so you need to pass the same value when
74 re-deriving the key as you did when first generating it. */
75 + (MYSymmetricKey*) generateFromUserPassphraseWithAlertTitle: (NSString*)alertTitle
76 alertPrompt: (NSString*)prompt
77 creating: (BOOL)creating
80 /** A utility that prompts for a passphrase, using the Security agent's nice modal panel,
81 and returns the raw passphrase as a string.
82 @param alertTitle A title for the alert (this seems to be ignored by the OS).
83 @param prompt A prompt string displayed in the alert.
84 @param creating Is a new passphrase being created?
85 (See description in +generateFromUserPassphrase... method.) */
86 + (NSString*) promptForPassphraseWithAlertTitle: (NSString*)alertTitle
87 alertPrompt: (NSString*)prompt
88 creating: (BOOL)creating;
89 #endif TARGET_OS_IPHONE