5 // Created by Jens Alfke on 3/21/09.
6 // Copyright 2009 Jens Alfke. All rights reserved.
9 #import <Foundation/Foundation.h>
10 #import <CommonCrypto/CommonCryptor.h>
13 /** Symmetric encryption: a streaming interface for encrypting/decrypting data.
14 This is a simple Cocoa wrapper for CommonCrypto/commonCryptor.h. It will probably be
15 merged into, or integrated with, MYSymmetricKey. */
16 @interface MYCryptor : NSObject
20 CCOperation _operation;
21 CCAlgorithm _algorithm;
23 CCCryptorRef _cryptor;
25 NSOutputStream *_outputStream;
26 NSMutableData *_output;
27 size_t _outputExtraBytes;
30 /** Returns a randomly-generated symmetric key of the desired length (in bits).
31 * @param lengthInBits The length of the desired key, in bits (not bytes).
33 + (NSData*) randomKeyOfLength: (size_t)lengthInBits;
35 /** Converts a passphrase into a symmetric key of the desired length (in bits).
36 * The same passphrase (and salt) will always return the same key, so you can use this method
37 * to encrypt and decrypt data using a user-entered passphrase, without having to store the key
38 * itself in the keychain.
39 * @param lengthInBits The length of the desired key, in bits (not bytes).
40 * @param passphrase The user-entered passphrase.
41 * @param salt An arbitrary value whose description will be appended to the passphrase before
42 * hashing, to perturb the resulting bits. The purpose of this is to make it harder for
43 * an attacker to brute-force the key using a precompiled list of digests of common
44 * passwords. Changing the salt changes the key, so you need to pass the same value when
45 * re-deriving the key as you did when first generating it.
47 + (NSData*) keyOfLength: (size_t)lengthInBits
48 fromPassphrase: (NSString*)passphrase
51 /** Creates a MYCryptor configured to encrypt data. */
52 - (id) initEncryptorWithKey: (NSData*)key
53 algorithm: (CCAlgorithm)algorithm;
55 /** Creates a MYCryptor configured to decrypt data. */
56 - (id) initDecryptorWithKey: (NSData*)key
57 algorithm: (CCAlgorithm)algorithm;
59 /** The encryption/decryption key; same as the 'key' parameter to the initializer. */
60 @property (readonly) NSData *key;
62 /** The cipher to use; initial value is the 'algorithm' parameter to the initializer.
63 You can change this <i>before</i> the first call to -addData:, but not after. */
64 @property CCAlgorithm algorithm;
66 /** Block-mode cipher options; you can set flags to enable PKCS7 padding or ECB mode
68 You can change this <i>before</i> the first call to -addData:, but not after. */
69 @property CCOptions options;
71 /** Setting this property tells the cryptor to send its output to the stream,
72 instead of accumulating it in the outputData property.
73 You can change this <i>before</i> the first call to -addData:, but not after. */
74 @property (retain) NSOutputStream *outputStream;
76 /** The error state, if any, of this cryptor.
77 After -addData: or -finish: returns NO, check this property. */
78 @property (readonly, retain) NSError *error;
81 @return YES if the operation succeeded, NO if it failed. */
82 - (BOOL) addData: (NSData*)data;
84 /** Finishes up the encryption/decryption and flushes the remaining bytes of output.
85 After this is called, you cannot add any more bytes of data.
86 @return YES if the operation succeeded, NO if it failed. */
89 /** The output of the cryptor. Accessing this property implicitly calls -finish, so don't
90 do it until you've added all of the input. (And don't add any more input afterwards.)
91 This property will be nil if the outputStream property has been set. */
92 @property (readonly) NSData *outputData;
98 /** NSError domain for MYCryptor operations. Error code is interpreted as a CCCryptorStatus,
99 with additional error code(s) defined below. */
100 extern NSString* const CryptorErrorDomain;
103 /** Indicates that the outputStream couldn't write all the bytes given to it (this is legal
104 behavior for an NSOutputStream, but MYCryptor can't handle this yet.) */
105 kMYCryptorErrorOutputStreamChoked = -777000