//

//  KeyPair.h

//  MYCrypto

//

//  Created by Jens Alfke on 3/21/09.

//  Copyright 2009 Jens Alfke. All rights reserved.

//

#import "MYPublicKey.h"

/** A key-pair consisting of a public and a private key.

    Can be used for signing and decrypting, as well as the inherited encrypting/verifying.

    Instances are generated by MYKeychain objects. */

@interface MYKeyPair : MYPublicKey <MYDecryption>

{

    @private

    SecKeyRef _privateKey;

}

/** Decrypts data that was encrypted using the public key.

    See the description of -[MYPublicKey encryptData:] for warnings and caveats.

    This method is usually used only to decrypt a symmetric session key, which then decrypts the

    rest of the data. */

- (NSData*) decryptData: (NSData*)data;

/** Generates a signature of data, using the private key.

    (What's actually signed using RSA is the SHA-256 digest of the data.)

    The resulting signature can be verified using the matching MYPublicKey's

    verifySignature:ofData: method. */

- (NSData*) signData: (NSData*)data;

#if !TARGET_OS_IPHONE

/** Exports the private key as a data blob, so that it can be stored as a backup, or transferred

    to another computer. Since the key is sensitive, it must be exported in encrypted form

    using a user-chosen passphrase. This method will display a standard alert panel, run by

    the Security agent, that prompts the user to enter a new passphrase for encrypting the key.

    The same passphrase must be re-entered when importing the key from the data blob.

    (This is a convenient shorthand for the full exportPrivateKeyInFormat... method.

    It uses OpenSSL format, wrapped with PEM, and a default title and prompt for the alert.) */

- (NSData*) exportPrivateKey;

#endif

@end

@interface MYKeyPair (Expert)

/** Creates a MYKeyPair object from existing Keychain key references. */

- (id) initWithPublicKeyRef: (SecKeyRef)publicKey privateKeyRef: (SecKeyRef)privateKey;

/** The underlying Keychain key reference for the private key. */

@property (readonly) SecKeyRef privateKeyRef;

#if !TARGET_OS_IPHONE

/** Exports the private key as a data blob, so that it can be stored as a backup, or transferred

    to another computer. Since the key is sensitive, it must be exported in encrypted form

    using a user-chosen passphrase. This method will display a standard alert panel, run by

    the Security agent, that prompts the user to enter a new passphrase for encrypting the key.

    The same passphrase must be re-entered when importing the key from the data blob.

    @param format  The data format: kSecFormatOpenSSL, kSecFormatSSH, kSecFormatBSAFE or kSecFormatSSHv2.

    @param withPEM  YES if the data should be encoded in PEM format, which converts into short lines

        of printable ASCII characters, suitable for sending in email.

    @param alertTitle  An optional title for the alert panel. (Currently ignored by the OS?)

    @param prompt  An optional prompt message to display in the alert panel. */

- (NSData*) exportPrivateKeyInFormat: (SecExternalFormat)format

                             withPEM: (BOOL)withPEM

                          alertTitle: (NSString*)title

                         alertPrompt: (NSString*)prompt;

#endif

@end