5 // Created by Jens Alfke on 4/7/09.
6 // Copyright 2009 Jens Alfke. All rights reserved.
10 @class MYPublicKey, MYSHA1Digest, MYIdentity;
13 /** A private key, used for signing and decrypting data.
14 Always paired with a matching public key in a "key-pair".
15 MYPublicKeys are instantiated by MYKeychain: either by generating a new key-pair, by
16 looking up a key-pair by its attributes, or by importing a key-pair from data. */
17 @interface MYPrivateKey : MYKey <MYDecryption>
20 MYPublicKey *_publicKey;
23 /** The matching public key. Always non-nil. */
24 @property (readonly) MYPublicKey *publicKey;
26 /** The public key's SHA-1 digest.
27 This is a convenient short (20-byte) identifier for the key pair. You can store it in your
28 application data, and then later look up either key using MYKeychain methods. */
29 @property (readonly) MYSHA1Digest *publicKeyDigest;
32 /** Decrypts data that was encrypted using the public key.
33 See the description of -[MYPublicKey encryptData:] for warnings and caveats.
34 This method is usually used only to decrypt a symmetric session key, which then decrypts the
36 - (NSData*) decryptData: (NSData*)data;
38 /** Generates a signature of data.
39 (What's actually signed using RSA is the SHA-256 digest of the data.)
40 The resulting signature can be verified using the matching MYPublicKey's
41 verifySignature:ofData: method. */
42 - (NSData*) signData: (NSData*)data;
46 * Functionality not available on iPhone.
51 /** Creates a self-signed identity certificate using this key-pair.
52 The attributes describe the certificate's metadata, including its expiration date and the
53 subject's name. Keys for the dictionary are given below; the only mandatory one is
54 kMYIdentityCommonNameKey.
55 The resulting identity certificate includes X.509 extended attributes allowing it to be
56 used for SSL connections. (Plug: See my MYNetwork library for an easy way to run SSL
57 servers and clients.) */
58 - (MYIdentity*) createSelfSignedIdentityWithAttributes: (NSDictionary*)attributes;
60 /** Exports the private key as a data blob, so that it can be stored as a backup, or transferred
61 to another computer. Since the key is sensitive, it must be exported in encrypted form
62 using a user-chosen passphrase. This method will display a standard alert panel, run by
63 the Security agent, that prompts the user to enter a new passphrase for encrypting the key.
64 The same passphrase must be re-entered when importing the key from the data blob.
65 (This is a convenient shorthand for the full exportPrivateKeyInFormat... method.
66 It uses OpenSSL format, wrapped with PEM, and a default title and prompt for the alert.) */
67 - (NSData*) exportKey;
69 /** Exports the private key as a data blob, so that it can be stored as a backup, or transferred
70 to another computer. Since the key is sensitive, it must be exported in encrypted form
71 using a user-chosen passphrase. This method will display a standard alert panel, run by
72 the Security agent, that prompts the user to enter a new passphrase for encrypting the key.
73 The same passphrase must be re-entered when importing the key from the data blob.
74 @param format The data format: kSecFormatOpenSSL, kSecFormatSSH, kSecFormatBSAFE or kSecFormatSSHv2.
75 @param withPEM YES if the data should be encoded in PEM format, which converts into short lines
76 of printable ASCII characters, suitable for sending in email.
77 @param alertTitle An optional title for the alert panel. (Currently ignored by the OS?)
78 @param prompt An optional prompt message to display in the alert panel. */
79 - (NSData*) exportKeyInFormat: (SecExternalFormat)format
80 withPEM: (BOOL)withPEM
81 alertTitle: (NSString*)alertTitle
82 alertPrompt: (NSString*)prompt;
89 /* Attribute keys for creating identities: */
91 #define kMYIdentityCommonNameKey @"Common Name" // NSString. Required!
92 #define kMYIdentityGivenNameKey @"Given Name"
93 #define kMYIdentitySurnameKey @"Surname"
94 #define kMYIdentityDescriptionKey @"Description"
95 #define kMYIdentityEmailAddressKey @"Email Address"
96 #define kMYIdentityValidFromKey @"Valid From" // NSDate. Defaults to the current date/time
97 #define kMYIdentityValidToKey @"Valid To" // NSDate. Defaults to one year from ValidFrom
98 #define kMYIdentitySerialNumberKey @"Serial Number" // NSNumber. Defaults to 1