This repository has been archived by the owner on Oct 18, 2021. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 12
/
MYKeychain.h
209 lines (156 loc) · 7.86 KB
/
MYKeychain.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
//
// MYKeychain.h
// MYCrypto
//
// Created by Jens Alfke on 3/23/09.
// Copyright 2009 Jens Alfke. All rights reserved.
//
#import <Foundation/Foundation.h>
#import "MYCryptoConfig.h"
@class MYSymmetricKey, MYPublicKey, MYPrivateKey, MYCertificate, MYIdentity, MYSHA1Digest;
/** A Keychain, a secure database of cryptographic keys.
This class wraps the Security framework's SecKeychain API. */
@interface MYKeychain : NSObject
{
@private
#if !MYCRYPTO_USE_IPHONE_API
SecKeychainRef _keychain;
#endif
}
/** Returns a MYKeychain instance representing the user's default keychain.
This is the instance you'll usually want to add keys to. */
+ (MYKeychain*) defaultKeychain;
/** Returns a MYKeychain instance representing the aggregate of all open keychains.
This is the instance you'll usually want to search for keys with. */
+ (MYKeychain*) allKeychains;
#pragma mark SYMMETRIC KEYS:
/** Randomly generates a new symmetric key, using the given algorithm and key-size in bits.
The key is persistently added to this keychain. */
- (MYSymmetricKey*) generateSymmetricKeyOfSize: (unsigned)keySizeInBits
algorithm: (uint32_t/*CCAlgorithm*/)algorithm;
/** Enumerates all of the symmetric keys in the keychain, as MYSymmetricKey objects. */
- (NSEnumerator*) enumerateSymmetricKeys;
#pragma mark PUBLIC KEYS:
/** Imports a public key into the keychain, given its external representation
(as generated by -[MYPublicKey keyData].) */
- (MYPublicKey*) importPublicKey: (NSData*)keyData;
/** Looks up an existing public key with the given digest.
Returns nil if there is no such key in the keychain.
(This method does not look for keys embedded in certificates, only 'bare' keys.) */
- (MYPublicKey*) publicKeyWithDigest: (MYSHA1Digest*)pubKeyDigest;
/** Enumerates all public keys in the keychain.
(This method does not find keys embedded in certificates, only 'bare' keys.) */
- (NSEnumerator*) enumeratePublicKeys;
#pragma mark CERTIFICATES:
/** Imports a certificate into the keychain, given its external representation. */
- (MYCertificate*) importCertificate: (NSData*)data;
/** Looks up an existing certificate with the given public-key digest.
Returns nil if there is no such certificate in the keychain.
(This method only looks for keys embedded in certificates, not 'bare' public keys.) */
- (MYCertificate*) certificateWithDigest: (MYSHA1Digest*)pubKeyDigest;
/** Enumerates all certificates in the keychain whose public keys have the given digest.
(Usually there will be at most one, but in some cases there may be multiple certificates
for the same public key.) */
- (NSEnumerator*) enumerateCertificatesWithDigest: (MYSHA1Digest*)pubKeyDigest;
/** Enumerates all certificates in the keychain. */
- (NSEnumerator*) enumerateCertificates;
/** Enumerates all identities in the keychain. */
- (NSEnumerator*) enumerateIdentities;
#pragma mark KEY-PAIRS:
/** Generates a new RSA key-pair and adds both keys to the keychain.
This is very slow -- it may take seconds, depending on the key size, CPU speed,
and other random factors. You may want to start some kind of progress indicator before
calling this method, so the user doesn't think the app has locked up!
@param keySize The RSA key length in bits. Must be a power of two. Longer keys are harder
to break, but operate more slowly and generate larger signatures.
2048 is a good default choice. You could use 1024 if the data and signatures won't need
to stay secure for years; or you could use 4096 if you're extremely paranoid. */
- (MYPrivateKey*) generateRSAKeyPairOfSize: (unsigned)keySize;
/** Looks up an existing key-pair whose public key has the given digest.
Returns nil if there is no such key-pair in the keychain.
(This method does not look for public keys embedded in certificates, only 'bare' keys.) */
- (MYPrivateKey*) privateKeyWithDigest: (MYSHA1Digest*)pubKeyDigest;
/** Enumerates all key-pairs in the keychain.
(This method does not find keys embedded in certificates, only 'bare' keys.) */
- (NSEnumerator*) enumeratePrivateKeys;
#pragma mark -
#pragma mark METHODS NOT SUPPORTED ON IPHONE:
/** @name Mac-Only
* Functionality not available on iPhone.
*/
//@{
#if !TARGET_OS_IPHONE
/** Sets whether the keychain is allowed to pop up panels to interact with the user,
for example to ask for permission to access keys. If user interaction is not
allowed, all such requests will fail. */
+ (void) setUserInteractionAllowed: (BOOL)allowed;
/** Enumerates all public keys in the keychain that have the given alias string. */
- (NSEnumerator*) symmetricKeysWithAlias: (NSString*)alias;
/** Enumerates all public keys in the keychain that have the given alias string. */
- (NSEnumerator*) publicKeysWithAlias: (NSString*)alias;
- (NSEnumerator*) enumerateIdentitiesWithKeyUsage: (CSSM_KEYUSE)keyUsage;
/** Imports a key-pair into the keychain, given the external representations
of both the public and private keys.
Since the private key data is wrapped (encrypted), the Security agent will prompt the user to enter
the passphrase. */
- (MYPrivateKey*) importPublicKey: (NSData*)pubKeyData
privateKey: (NSData*)privKeyData;
/** Imports a key-pair into the keychain, given the external representations
of both the public and private keys.
Since the private key data is wrapped (encrypted), the Security agent will prompt the user to enter
the passphrase. You can specify the title and prompt message for this alert panel. */
- (MYPrivateKey*) importPublicKey: (NSData*)pubKeyData
privateKey: (NSData*)privKeyData
alertTitle: (NSString*)title
alertPrompt: (NSString*)prompt;
/** Adds a certificate to this keychain. (It must not already belong to a keychain.) */
- (BOOL) addCertificate: (MYCertificate*)certificate;
/** Imports a certificate into the keychain, given its external representation. */
- (MYCertificate*) importCertificate: (NSData*)data
type: (CSSM_CERT_TYPE) type
encoding: (CSSM_CERT_ENCODING) encoding;
/** Imports an identity into the keychain, given its external representation.
The usual format is PKCS12 (a .p12 file). */
- (MYIdentity*) importIdentity: (NSData*)data
inFormat: (SecExternalFormat)format
error: (NSError**)outError;
//@}
#else
/** @name iPhone-Only
* Functionality only available on iPhone.
*/
//@{
- (BOOL) removeAllCertificates;
- (BOOL) removeAllKeys;
//@}
#endif
/** @name Expert (Mac-Only)
* Advanced functionality, not available on iPhone.
*/
//@{
#if !TARGET_OS_IPHONE
/** Creates a MYKeychain for an existing SecKeychainRef. */
- (id) initWithKeychainRef: (SecKeychainRef)keychainRef;
/** Opens a keychain file. */
+ (MYKeychain*) openKeychainAtPath: (NSString*)path;
/** Creates a new keychain file. */
+ (MYKeychain*) createKeychainAtPath: (NSString*)path
withPassword: (NSString*)password;
/** Closes and deletes the keychain's file. You should not use this object any more. */
- (BOOL) deleteKeychainFile;
/** Returns the underlying SecKeychainRef for this keychain.
This will be NULL for the special allKeychains instance, because it doesn't
represent a single specific keychain. To handle that case, use the
keychainRefOrDefault property instead. */
@property (readonly) SecKeychainRef keychainRef;
/** Returns the underlying SecKeychainRef for this keychain.
The special allKeychains instance returns a reference to the default keychain,
as a convenience. */
@property (readonly) SecKeychainRef keychainRefOrDefault;
/** The path of this keychain's file. */
@property (weak, readonly) NSString* path;
/** The underlying CSSM storage handle; used when calling CSSM APIs. */
@property (readonly) CSSM_CSP_HANDLE CSPHandle;
#endif
//@}
@end