snej@0: //
snej@0: //  MYKey.h
snej@0: //  MYCrypto
snej@0: //
snej@0: //  Created by Jens Alfke on 3/30/09.
snej@0: //  Copyright 2009 Jens Alfke. All rights reserved.
snej@0: //
snej@0: 
snej@0: #import "MYKeychainItem.h"
snej@0: 
snej@0: 
snej@1: @protocol MYEncryption <NSObject>
snej@0: 
snej@1: /** Encrypts data using this key, returning the raw encrypted result. */
snej@1: - (NSData*) encryptData: (NSData*)data;
snej@1: 
snej@1: @end
snej@1: 
snej@1: @protocol MYDecryption <NSObject>
snej@1: 
snej@1: /** Decrypts data using this key, returning the original data. */
snej@1: - (NSData*) decryptData: (NSData*)data;
snej@1: 
snej@1: @end
snej@1: 
snej@1: 
snej@1: 
snej@1: /** Abstract superclass for keys.
snej@1:     Concrete subclasses are MYSymmetricKey and MYPublicKey. */
snej@0: @interface MYKey : MYKeychainItem
snej@2: { }
snej@0: 
snej@1: /** The key's raw data. */
snej@0: @property (readonly) NSData *keyData;
snej@0: 
snej@0: /** The user-visible name (kSecKeyPrintName) associated with this key in the Keychain.
snej@0:     The user can edit this, so don't expect it to be immutable. */
snej@0: @property (copy) NSString *name;
snej@0: 
snej@0: /** An application-specific string (kSecKeyAlias) associated with this key in the Keychain.
snej@0:     Not visible to or editable by the user.
snej@0:     If you own this key, you can store any associated metadata you like here, although be aware
snej@0:     that it can be read and modified by any other app that can access this key. */
snej@0: @property (copy) NSString *alias;
snej@0: 
snej@2: 
snej@2: /** @name Mac-Only
snej@2:  *  Functionality not available on iPhone. 
snej@2:  */
snej@2: //@{
snej@0: #if !TARGET_OS_IPHONE
snej@2: 
snej@0: /** The user-visible comment (kSecKeyApplicationTag) associated with this key in the Keychain.
snej@2:  The user can edit this, so don't expect it to be immutable. */
snej@0: @property (copy) NSString *comment;
snej@2: 
snej@2: /** Converts the key into a data blob in one of several standard formats, suitable for storing in
snej@2:     a file or sending over the network.
snej@2:     @param format  The data format: kSecFormatOpenSSL, kSecFormatSSH, kSecFormatBSAFE or kSecFormatSSHv2.
snej@2:     @param withPEM  YES if the data should be encoded in PEM format, which converts into short lines
snej@2:         of printable ASCII characters, suitable for sending in email. */
snej@2: - (NSData*) exportKeyInFormat: (SecExternalFormat)format withPEM: (BOOL)withPEM;
snej@2: 
snej@0: #endif
snej@2: //@}
snej@0: 
snej@0: 
snej@2: /** @name Expert
snej@2:  *  Advanced methods. 
snej@2:  */
snej@2: //@{
snej@0: 
snej@1: /** Creates a MYKey object for an existing Keychain key reference.
snej@1:     This is abstract -- must be called on a MYSymmetricKey or MYPublicKey, as appropriate. */
snej@1: - (id) initWithKeyRef: (SecKeyRef)keyRef;
snej@1: 
snej@1: /** The Keychain object reference for this key. */
snej@1: @property (readonly) SecKeyRef keyRef;
snej@1: 
snej@1: #if !TARGET_OS_IPHONE
snej@1: /** The underlying CSSM_KEY structure; used with low-level crypto APIs. */
snej@1: @property (readonly) const struct cssm_key* cssmKey;
snej@1: 
snej@2: /** The underlying CSSM_CSP_HANDLE structure; used with low-level crypto APIs. */
snej@2: @property (readonly) intptr_t /*CSSM_CSP_HANDLE*/ cssmCSPHandle;
snej@2: 
snej@2: /** Gets CSSM authorization credentials for a specified operation, such as
snej@2:     CSSM_ACL_AUTHORIZATION_ENCRYPT. This pointer is necessary for creating some CSSM operation
snej@2:     contexts.
snej@2:     @param operation  The type of operation you are going to perform (see the enum values in
snej@2:             cssmType.h.)
snej@2:     @param type  Specifies whether the operation should be allowed to present a UI. You'll usually
snej@2:             want to pass kSecCredentialTypeDefault.
snej@2:     @param outError  Will be set to point to an NSError on failure, or nil on success.
snej@2:             Pass nil if you don't care about the specific error.
snej@2:     @return  The access credentials, or NULL on failure. 
snej@2:             This pointer is valid for as long as you have a reference
snej@2:             to the key object. Do not free or delete it. */
snej@2: - (const CSSM_ACCESS_CREDENTIALS*) cssmCredentialsForOperation: (CSSM_ACL_AUTHORIZATION_TAG)operation
snej@2:                                                           type: (SecCredentialType)type
snej@2:                                                          error: (NSError**)outError;
snej@2: 
snej@1: #endif
snej@2: //@}
snej@0: 
snej@0: @end