snej@0: //
snej@0: //  Cryptor.h
snej@0: //  MYCrypto
snej@0: //
snej@0: //  Created by Jens Alfke on 3/21/09.
snej@0: //  Copyright 2009 Jens Alfke. All rights reserved.
snej@0: //
snej@0: 
snej@0: #import <Foundation/Foundation.h>
snej@0: #import <CommonCrypto/CommonCryptor.h>
snej@0: 
snej@0: 
snej@2: /** Symmetric encryption: a streaming interface for encrypting/decrypting data.
snej@2:     This is a simple Cocoa wrapper for CommonCrypto/commonCryptor.h. It will probably be
snej@2:     merged into, or integrated with, MYSymmetricKey. */
snej@0: @interface MYCryptor : NSObject
snej@0: {
snej@1:     @private
snej@0:     NSData *_key;
snej@0:     CCOperation _operation;
snej@0:     CCAlgorithm _algorithm;
snej@0:     CCOptions _options;
snej@0:     CCCryptorRef _cryptor;
snej@0:     NSError *_error;
snej@0:     NSOutputStream *_outputStream;
snej@0:     NSMutableData *_output;
snej@0:     size_t _outputExtraBytes;
snej@0: }
snej@0: 
snej@2: /** Returns a randomly-generated symmetric key of the desired length (in bits).
snej@2:  *  @param lengthInBits  The length of the desired key, in bits (not bytes).
snej@2:  */
snej@2: + (NSData*) randomKeyOfLength: (size_t)lengthInBits;
snej@0: 
snej@2: /** Converts a passphrase into a symmetric key of the desired length (in bits).
snej@2:  *  The same passphrase (and salt) will always return the same key, so you can use this method
snej@2:  *  to encrypt and decrypt data using a user-entered passphrase, without having to store the key
snej@2:  *  itself in the keychain.
snej@2:  *  @param lengthInBits  The length of the desired key, in bits (not bytes).
snej@2:  *  @param passphrase  The user-entered passphrase.
snej@2:  *  @param salt  An arbitrary value whose description will be appended to the passphrase before
snej@2:  *          hashing, to perturb the resulting bits. The purpose of this is to make it harder for
snej@2:  *          an attacker to brute-force the key using a precompiled list of digests of common
snej@2:  *          passwords. Changing the salt changes the key, so you need to pass the same value when
snej@2:  *          re-deriving the key as you did when first generating it.
snej@2:  */
snej@2: + (NSData*) keyOfLength: (size_t)lengthInBits
snej@2:          fromPassphrase: (NSString*)passphrase
snej@2:                    salt: (id)salt;
snej@0: 
snej@0: /** Creates a MYCryptor configured to encrypt data. */
snej@0: - (id) initEncryptorWithKey: (NSData*)key
snej@0:                   algorithm: (CCAlgorithm)algorithm;
snej@0: 
snej@0: /** Creates a MYCryptor configured to decrypt data. */
snej@0: - (id) initDecryptorWithKey: (NSData*)key
snej@0:                   algorithm: (CCAlgorithm)algorithm;
snej@0: 
snej@0: /** The encryption/decryption key; same as the 'key' parameter to the initializer. */
snej@0: @property (readonly) NSData *key;
snej@0: 
snej@0: /** The cipher to use; initial value is the 'algorithm' parameter to the initializer.
snej@1:     You can change this <i>before</i> the first call to -addData:, but not after. */
snej@0: @property CCAlgorithm algorithm;
snej@0: 
snej@0: /** Block-mode cipher options; you can set flags to enable PKCS7 padding or ECB mode
snej@0:     (default is CBC.)
snej@1:     You can change this <i>before</i> the first call to -addData:, but not after. */
snej@0: @property CCOptions options;
snej@0: 
snej@1: /** Setting this property tells the cryptor to send its output to the stream,
snej@1:     instead of accumulating it in the outputData property.
snej@1:     You can change this <i>before</i> the first call to -addData:, but not after. */
snej@1: @property (retain) NSOutputStream *outputStream;
snej@1: 
snej@0: /** The error state, if any, of this cryptor.
snej@0:     After -addData: or -finish: returns NO, check this property. */
snej@0: @property (readonly, retain) NSError *error;
snej@0: 
snej@0: /** Adds input data.
snej@0:     @return  YES if the operation succeeded, NO if it failed. */
snej@0: - (BOOL) addData: (NSData*)data;
snej@0: 
snej@0: /** Finishes up the encryption/decryption and flushes the remaining bytes of output.
snej@0:     After this is called, you cannot add any more bytes of data.
snej@0:     @return  YES if the operation succeeded, NO if it failed. */
snej@0: - (BOOL) finish;
snej@0: 
snej@0: /** The output of the cryptor. Accessing this property implicitly calls -finish, so don't
snej@0:     do it until you've added all of the input. (And don't add any more input afterwards.)
snej@0:     This property will be nil if the outputStream property has been set. */
snej@0: @property (readonly) NSData *outputData;
snej@0: 
snej@0: @end
snej@0: 
snej@0: 
snej@0: 
snej@0: /** NSError domain for MYCryptor operations. Error code is interpreted as a CCCryptorStatus,
snej@0:     with additional error code(s) defined below. */
snej@0: extern NSString* const CryptorErrorDomain;
snej@0: 
snej@0: enum {
snej@0:     /** Indicates that the outputStream couldn't write all the bytes given to it (this is legal
snej@0:         behavior for an NSOutputStream, but MYCryptor can't handle this yet.) */
snej@0:     kMYCryptorErrorOutputStreamChoked = -777000
snej@0: };