5 // Created by Jens Alfke on 3/21/09.
6 // Copyright 2009 Jens Alfke. All rights reserved.
9 #import "MYPublicKey.h"
12 /** A key-pair consisting of a public and a private key.
13 Can be used for signing and decrypting, as well as the inherited encrypting/verifying.
14 Instances are generated by MYKeychain objects. */
15 @interface MYKeyPair : MYPublicKey <MYDecryption>
18 SecKeyRef _privateKey;
21 /** Decrypts data that was encrypted using the public key.
22 See the description of -[MYPublicKey encryptData:] for warnings and caveats.
23 This method is usually used only to decrypt a symmetric session key, which then decrypts the
25 - (NSData*) decryptData: (NSData*)data;
27 /** Generates a signature of data, using the private key.
28 (What's actually signed using RSA is the SHA-256 digest of the data.)
29 The resulting signature can be verified using the matching MYPublicKey's
30 verifySignature:ofData: method. */
31 - (NSData*) signData: (NSData*)data;
34 /** Exports the private key as a data blob, so that it can be stored as a backup, or transferred
35 to another computer. Since the key is sensitive, it must be exported in encrypted form
36 using a user-chosen passphrase. This method will display a standard alert panel, run by
37 the Security agent, that prompts the user to enter a new passphrase for encrypting the key.
38 The same passphrase must be re-entered when importing the key from the data blob.
39 (This is a convenient shorthand for the full exportPrivateKeyInFormat... method.
40 It uses OpenSSL format, wrapped with PEM, and a default title and prompt for the alert.) */
41 - (NSData*) exportPrivateKey;
48 @interface MYKeyPair (Expert)
50 /** Creates a MYKeyPair object from existing Keychain key references. */
51 - (id) initWithPublicKeyRef: (SecKeyRef)publicKey privateKeyRef: (SecKeyRef)privateKey;
53 /** The underlying Keychain key reference for the private key. */
54 @property (readonly) SecKeyRef privateKeyRef;
57 /** Exports the private key as a data blob, so that it can be stored as a backup, or transferred
58 to another computer. Since the key is sensitive, it must be exported in encrypted form
59 using a user-chosen passphrase. This method will display a standard alert panel, run by
60 the Security agent, that prompts the user to enter a new passphrase for encrypting the key.
61 The same passphrase must be re-entered when importing the key from the data blob.
62 @param format The data format: kSecFormatOpenSSL, kSecFormatSSH, kSecFormatBSAFE or kSecFormatSSHv2.
63 @param withPEM YES if the data should be encoded in PEM format, which converts into short lines
64 of printable ASCII characters, suitable for sending in email.
65 @param alertTitle An optional title for the alert panel. (Currently ignored by the OS?)
66 @param prompt An optional prompt message to display in the alert panel. */
67 - (NSData*) exportPrivateKeyInFormat: (SecExternalFormat)format
68 withPEM: (BOOL)withPEM
69 alertTitle: (NSString*)title
70 alertPrompt: (NSString*)prompt;