5 // Created by Jens Alfke on 4/2/09.
6 // Copyright 2009 Jens Alfke. All rights reserved.
10 #import <CommonCrypto/CommonCryptor.h>
13 @interface MYSymmetricKey : MYKey <MYEncryption, MYDecryption>
15 #if !MYCRYPTO_USE_IPHONE_API
16 CSSM_KEY *_ownedCSSMKey;
20 /** Initializes a symmetric key from the given key data and algorithm. */
21 - (id) initWithKeyData: (NSData*)keyData
22 algorithm: (CCAlgorithm)algorithm;
24 /** Randomly generates a new symmetric key, using the given algorithm and key-size in bits.
25 The key is not added to any keychain; if you want to keep the key persistently, use
26 the method of the same name in the MYKeychain class. */
27 + (MYSymmetricKey*) generateSymmetricKeyOfSize: (unsigned)keySizeInBits
28 algorithm: (CCAlgorithm)algorithm;
30 /** The key's algorithm. */
31 @property (readonly) CCAlgorithm algorithm;
33 /** The key's size/length, in bits. */
34 @property (readonly) unsigned keySizeInBits;
39 - (NSData*) exportWrappedKeyWithPassphrasePrompt: (NSString*)prompt;
41 /** Converts a passphrase into a symmetric key.
42 The same passphrase (and salt) will always return the same key, so you can use this method
43 to encrypt and decrypt data using a user-entered passphrase, without having to store the key
44 itself in the keychain.
45 @param alertTitle A title for the alert (this seems to be ignored by the OS).
46 @param prompt A prompt string displayed in the alert.
47 @param creating Is a new passphrase being created? If YES, the user will have to enter the
48 passphrase twice, to check for errors, and the nifty passphrase-strength meter will be
49 displayed. If NO, there's only one text-field, and an option to display its contents in
51 @param salt An arbitrary value whose data will be mixed in with the passphrase before
52 hashing, to perturb the resulting bits. The purpose of this is to make it harder for
53 an attacker to brute-force the key using a precompiled list of digests of common
54 passwords. Changing the salt changes the key, so you need to pass the same value when
55 re-deriving the key as you did when first generating it. */
56 + (MYSymmetricKey*) generateFromUserPassphraseWithAlertTitle: (NSString*)alertTitle
57 alertPrompt: (NSString*)prompt
58 creating: (BOOL)creating
61 /** A utility that prompts for a passphrase, using the Security agent's nice modal panel,
62 and returns the raw passphrase as a string.
63 @param alertTitle A title for the alert (this seems to be ignored by the OS).
64 @param prompt A prompt string displayed in the alert.
65 @param creating Is a new passphrase being created?
66 (See description in +generateFromUserPassphrase... method.) */
67 + (NSString*) promptForPassphraseWithAlertTitle: (NSString*)alertTitle
68 alertPrompt: (NSString*)prompt
69 creating: (BOOL)creating;
70 #endif TARGET_OS_IPHONE