snej@0: //
snej@0: //  MYSymmetricKey.h
snej@0: //  MYCrypto
snej@0: //
snej@0: //  Created by Jens Alfke on 4/2/09.
snej@0: //  Copyright 2009 Jens Alfke. All rights reserved.
snej@0: //
snej@0: 
snej@0: #import "MYKey.h"
snej@0: #import <CommonCrypto/CommonCryptor.h>
snej@0: 
snej@0: 
snej@0: @interface MYSymmetricKey : MYKey <MYEncryption, MYDecryption>
snej@12: {
snej@12: #if !MYCRYPTO_USE_IPHONE_API
snej@12:     CSSM_KEY *_ownedCSSMKey;
snej@12: #endif
snej@12: }
snej@0: 
snej@1: /** Initializes a symmetric key from the given key data and algorithm. */
snej@1: - (id) initWithKeyData: (NSData*)keyData
snej@1:              algorithm: (CCAlgorithm)algorithm;
snej@1: 
snej@1: /** Randomly generates a new symmetric key, using the given algorithm and key-size in bits.
snej@1:     The key is not added to any keychain; if you want to keep the key persistently, use
snej@1:     the method of the same name in the MYKeychain class. */
snej@0: + (MYSymmetricKey*) generateSymmetricKeyOfSize: (unsigned)keySizeInBits
snej@0:                                      algorithm: (CCAlgorithm)algorithm;
snej@0: 
snej@14: /** The key's algorithm. */
snej@14: @property (readonly) CCAlgorithm algorithm;
snej@14: 
snej@14: /** The key's size/length, in bits. */
snej@14: @property (readonly) unsigned keySizeInBits;
snej@14: 
snej@14: 
snej@14: #if !TARGET_OS_IPHONE
snej@14: 
snej@14: - (NSData*) exportWrappedKeyWithPassphrasePrompt: (NSString*)prompt;
snej@14: 
snej@12: /** Converts a passphrase into a symmetric key.
snej@12:     The same passphrase (and salt) will always return the same key, so you can use this method
snej@12:     to encrypt and decrypt data using a user-entered passphrase, without having to store the key
snej@12:     itself in the keychain.
snej@12:     @param alertTitle  A title for the alert (this seems to be ignored by the OS).
snej@12:     @param prompt  A prompt string displayed in the alert.
snej@12:     @param creating  Is a new passphrase being created? If YES, the user will have to enter the
snej@12:         passphrase twice, to check for errors, and the nifty passphrase-strength meter will be
snej@12:         displayed. If NO, there's only one text-field, and an option to display its contents in
snej@12:         the clear.
snej@12:     @param salt  An arbitrary value whose data will be mixed in with the passphrase before
snej@12:         hashing, to perturb the resulting bits. The purpose of this is to make it harder for
snej@12:         an attacker to brute-force the key using a precompiled list of digests of common
snej@12:         passwords. Changing the salt changes the key, so you need to pass the same value when
snej@12:         re-deriving the key as you did when first generating it. */
snej@12:  + (MYSymmetricKey*) generateFromUserPassphraseWithAlertTitle: (NSString*)alertTitle
snej@12:                                                  alertPrompt: (NSString*)prompt
snej@12:                                                     creating: (BOOL)creating
snej@12:                                                         salt: (id)saltObj;
snej@12: 
snej@12: /** A utility that prompts for a passphrase, using the Security agent's nice modal panel,
snej@12:     and returns the raw passphrase as a string.
snej@12:     @param alertTitle  A title for the alert (this seems to be ignored by the OS).
snej@12:     @param prompt  A prompt string displayed in the alert.
snej@12:     @param creating  Is a new passphrase being created? 
snej@12:         (See description in +generateFromUserPassphrase... method.) */
snej@12: + (NSString*) promptForPassphraseWithAlertTitle: (NSString*)alertTitle
snej@12:                                     alertPrompt: (NSString*)prompt
snej@12:                                        creating: (BOOL)creating;
snej@14: #endif TARGET_OS_IPHONE
snej@12: 
snej@0: @end