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