snej@3: //
snej@3: //  MYPrivateKey.h
snej@3: //  MYCrypto
snej@3: //
snej@3: //  Created by Jens Alfke on 4/7/09.
snej@3: //  Copyright 2009 Jens Alfke. All rights reserved.
snej@3: //
snej@3: 
snej@3: #import "MYKey.h"
snej@4: @class MYPublicKey, MYSHA1Digest, MYIdentity;
snej@3: 
snej@3: 
snej@3: /** A private key, used for signing and decrypting data.
snej@3:     Always paired with a matching public key in a "key-pair".
snej@3:     MYPublicKeys are instantiated by MYKeychain: either by generating a new key-pair, by
snej@3:     looking up a key-pair by its attributes, or by importing a key-pair from data. */
snej@3: @interface MYPrivateKey : MYKey <MYDecryption>
snej@3: {
snej@3:     @private
snej@3:     MYPublicKey *_publicKey;
snej@3: }
snej@3: 
snej@3: /** The matching public key. Always non-nil. */
snej@3: @property (readonly) MYPublicKey *publicKey;
snej@3: 
snej@3: /** The public key's SHA-1 digest. 
snej@3:     This is a convenient short (20-byte) identifier for the key pair. You can store it in your
snej@3:     application data, and then later look up either key using MYKeychain methods. */
snej@3: @property (readonly) MYSHA1Digest *publicKeyDigest;
snej@3: 
snej@3: 
snej@3: /** Decrypts data that was encrypted using the public key.
snej@3:     See the description of -[MYPublicKey encryptData:] for warnings and caveats.
snej@3:     This method is usually used only to decrypt a symmetric session key, which then decrypts the
snej@3:     rest of the data. */
snej@3: - (NSData*) decryptData: (NSData*)data;
snej@3: 
snej@3: /** Generates a signature of data.
snej@3:     (What's actually signed using RSA is the SHA-256 digest of the data.)
snej@3:     The resulting signature can be verified using the matching MYPublicKey's
snej@3:     verifySignature:ofData: method. */
snej@3: - (NSData*) signData: (NSData*)data;
snej@3: 
snej@3: 
snej@3: /** @name Mac-Only
snej@3:  *  Functionality not available on iPhone. 
snej@3:  */
snej@3: //@{
snej@3: #if !TARGET_OS_IPHONE
snej@3: 
snej@4: /** Creates a self-signed identity certificate using this key-pair.
snej@4:     The attributes describe the certificate's metadata, including its expiration date and the
snej@4:     subject's name. Keys for the dictionary are given below; the only mandatory one is
snej@4:     kMYIdentityCommonNameKey. */
snej@4: - (MYIdentity*) createSelfSignedIdentityWithAttributes: (NSDictionary*)attributes;
snej@4: 
snej@3: /** Exports the private key as a data blob, so that it can be stored as a backup, or transferred
snej@3:     to another computer. Since the key is sensitive, it must be exported in encrypted form
snej@3:     using a user-chosen passphrase. This method will display a standard alert panel, run by
snej@3:     the Security agent, that prompts the user to enter a new passphrase for encrypting the key.
snej@3:     The same passphrase must be re-entered when importing the key from the data blob.
snej@3:     (This is a convenient shorthand for the full exportPrivateKeyInFormat... method.
snej@3:     It uses OpenSSL format, wrapped with PEM, and a default title and prompt for the alert.) */
snej@3: - (NSData*) exportKey;
snej@3: 
snej@3: /** Exports the private key as a data blob, so that it can be stored as a backup, or transferred
snej@3:     to another computer. Since the key is sensitive, it must be exported in encrypted form
snej@3:     using a user-chosen passphrase. This method will display a standard alert panel, run by
snej@3:     the Security agent, that prompts the user to enter a new passphrase for encrypting the key.
snej@3:     The same passphrase must be re-entered when importing the key from the data blob.
snej@3:     @param format  The data format: kSecFormatOpenSSL, kSecFormatSSH, kSecFormatBSAFE or kSecFormatSSHv2.
snej@3:     @param withPEM  YES if the data should be encoded in PEM format, which converts into short lines
snej@3:         of printable ASCII characters, suitable for sending in email.
snej@3:     @param alertTitle  An optional title for the alert panel. (Currently ignored by the OS?)
snej@3:     @param prompt  An optional prompt message to display in the alert panel. */
snej@3: - (NSData*) exportKeyInFormat: (SecExternalFormat)format
snej@3:                       withPEM: (BOOL)withPEM
snej@3:                    alertTitle: (NSString*)alertTitle
snej@3:                   alertPrompt: (NSString*)prompt;
snej@3: #endif
snej@3: //@}
snej@3: 
snej@3: @end
snej@4: 
snej@4: 
snej@4: /* Attribute keys for creating identities: */
snej@4: #define kMYIdentityCommonNameKey    @"Common Name"      // NSString. Required!
snej@4: #define kMYIdentityGivenNameKey     @"Given Name"
snej@4: #define kMYIdentitySurnameKey       @"Surname"
snej@4: #define kMYIdentityDescriptionKey   @"Description"
snej@4: #define kMYIdentityEmailAddressKey  @"Email Address"
snej@4: #define kMYIdentityValidFromKey     @"Valid From"       // NSDate. Defaults to the current date/time
snej@4: #define kMYIdentityValidToKey       @"Valid To"         // NSDate. Defaults to one year from ValidFrom
snej@4: #define kMYIdentitySerialNumberKey  @"Serial Number"    // NSNumber. Defaults to 1