MYKeychain Class Reference

A Keychain, a secure database of cryptographic keys. More...

List of all members.

Public Member Functions

(MYSymmetricKey *) - generateSymmetricKeyOfSize:algorithm:
 Randomly generates a new symmetric key, using the given algorithm and key-size in bits.
(NSEnumerator *) - enumerateSymmetricKeys
 Enumerates all of the symmetric keys in the keychain, as MYSymmetricKey objects.
(MYPublicKey *) - importPublicKey:
 Imports a public key into the keychain, given its external representation (as generated by -[MYPublicKey keyData].
(MYPublicKey *) - publicKeyWithDigest:
 Looks up an existing public key with the given digest.
(NSEnumerator *) - enumeratePublicKeys
 Enumerates all public keys in the keychain.
(MYCertificate *) - importCertificate:
 Imports a certificate into the keychain, given its external representation.
(MYCertificate *) - certificateWithDigest:
 Looks up an existing certificate with the given public-key digest.
(NSEnumerator *) - enumerateCertificatesWithDigest:
 Enumerates all certificates in the keychain whose public keys have the given digest.
(NSEnumerator *) - enumerateCertificates
 Enumerates all certificates in the keychain.
(NSEnumerator *) - enumerateIdentities
 Enumerates all identities in the keychain.
(MYPrivateKey *) - generateRSAKeyPairOfSize:
 Generates a new RSA key-pair and adds both keys to the keychain.
(MYPrivateKey *) - privateKeyWithDigest:
 Looks up an existing key-pair whose public key has the given digest.
(NSEnumerator *) - enumeratePrivateKeys
 Enumerates all key-pairs in the keychain.
(MYIdentity *) - identityWithDigest:

Static Public Member Functions

(MYKeychain *) + defaultKeychain
 Returns a MYKeychain instance representing the user's default keychain.
(MYKeychain *) + allKeychains
 Returns a MYKeychain instance representing the aggregate of all open keychains.

Expert (Mac-Only)

Advanced functionality, not available on iPhone.



SecKeychainRef keychainRef
 Returns the underlying SecKeychainRef for this keychain.
SecKeychainRef keychainRefOrDefault
 Returns the underlying SecKeychainRef for this keychain.
NSString * path
 The path of this keychain's file.
CSSM_CSP_HANDLE CSPHandle
 The underlying CSSM storage handle; used when calling CSSM APIs.
(MYKeychain *) + openKeychainAtPath:
 Opens a keychain file.
(MYKeychain *) + createKeychainAtPath:withPassword:
 Creates a new keychain file.
(id) - initWithKeychainRef:
 Creates a MYKeychain for an existing SecKeychainRef.
(BOOL) - deleteKeychainFile
 Closes and deletes the keychain's file.

Mac-Only

Functionality not available on iPhone.



(void) + setUserInteractionAllowed:
 Sets whether the keychain is allowed to pop up panels to interact with the user, for example to ask for permission to access keys.
(NSEnumerator *) - symmetricKeysWithAlias:
 Enumerates all public keys in the keychain that have the given alias string.
(NSEnumerator *) - publicKeysWithAlias:
 Enumerates all public keys in the keychain that have the given alias string.
(NSEnumerator *) - enumerateIdentitiesWithKeyUsage:
(MYPrivateKey *) - importPublicKey:privateKey:
 Imports a key-pair into the keychain, given the external representations of both the public and private keys.
(MYPrivateKey *) - importPublicKey:privateKey:alertTitle:alertPrompt:
 Imports a key-pair into the keychain, given the external representations of both the public and private keys.
(BOOL) - addCertificate:
 Adds a certificate to this keychain.
(MYCertificate *) - importCertificate:type:encoding:
 Imports a certificate into the keychain, given its external representation.
(MYIdentity *) - importIdentity:inFormat:error:
 Imports an identity into the keychain, given its external representation.

Detailed Description

A Keychain, a secure database of cryptographic keys.

This class wraps the Security framework's SecKeychain API.


Member Function Documentation

- (BOOL) addCertificate: (MYCertificate*)  certificate  

Adds a certificate to this keychain.

(It must not already belong to a keychain.)

+ (MYKeychain *) allKeychains  

Returns a MYKeychain instance representing the aggregate of all open keychains.

This is the instance you'll usually want to search for keys with.

- (MYCertificate *) certificateWithDigest: (MYSHA1Digest*)  pubKeyDigest  

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.)

+ (MYKeychain *) createKeychainAtPath: (NSString*)  path
withPassword: (NSString*)  password 

Creates a new keychain file.

+ (MYKeychain *) defaultKeychain  

Returns a MYKeychain instance representing the user's default keychain.

This is the instance you'll usually want to add keys to.

- (BOOL) deleteKeychainFile  

Closes and deletes the keychain's file.

You should not use this object any more.

- (NSEnumerator *) enumerateCertificates  

Enumerates all certificates in the keychain.

- (NSEnumerator *) enumerateCertificatesWithDigest: (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 *) enumerateIdentities  

Enumerates all identities in the keychain.

- (NSEnumerator *) enumeratePrivateKeys  

Enumerates all key-pairs in the keychain.

(This method does not find keys embedded in certificates, only 'bare' keys.)

- (NSEnumerator *) enumeratePublicKeys  

Enumerates all public keys in the keychain.

(This method does not find keys embedded in certificates, only 'bare' keys.)

- (NSEnumerator *) enumerateSymmetricKeys  

Enumerates all of the symmetric keys in the keychain, as MYSymmetricKey objects.

- (MYPrivateKey *) generateRSAKeyPairOfSize: (unsigned)  keySize  

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!

Parameters:
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.
- (MYSymmetricKey*) generateSymmetricKeyOfSize: (unsigned)  keySizeInBits
algorithm: (uint32_t/*CCAlgorithm */)  algorithm 

Randomly generates a new symmetric key, using the given algorithm and key-size in bits.

The key is persistently added to this keychain.

- (MYCertificate *) importCertificate: (NSData*)  data  

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 a certificate into the keychain, given its external representation.

- (MYIdentity *) importIdentity: (NSData*)  data
inFormat: (SecExternalFormat)  format
error: (NSError**)  outError 

Imports an identity into the keychain, given its external representation.

The usual format is PKCS12 (a .p12 file).

- (MYPublicKey *) importPublicKey: (NSData*)  keyData  

Imports a public key into the keychain, given its external representation (as generated by -[MYPublicKey keyData].

)

- (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.

- (MYPrivateKey *) importPublicKey: (NSData*)  pubKeyData
privateKey: (NSData*)  privKeyData
alertTitle: (NSString*)  title
alertPrompt: (NSString*)  prompt 

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.

- (id) initWithKeychainRef: (SecKeychainRef)  keychainRef  

Creates a MYKeychain for an existing SecKeychainRef.

+ (MYKeychain *) openKeychainAtPath: (NSString*)  path  

Opens a keychain file.

- (MYPrivateKey *) privateKeyWithDigest: (MYSHA1Digest*)  pubKeyDigest  

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.)

- (NSEnumerator *) publicKeysWithAlias: (NSString*)  alias  

Enumerates all public keys in the keychain that have the given alias string.

- (MYPublicKey *) publicKeyWithDigest: (MYSHA1Digest*)  pubKeyDigest  

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.)

+ (void) setUserInteractionAllowed: (BOOL)  allowed  

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.

- (NSEnumerator *) symmetricKeysWithAlias: (NSString*)  alias  

Enumerates all public keys in the keychain that have the given alias string.


Property Documentation

- (CSSM_CSP_HANDLE) CSPHandle [read, assign]

The underlying CSSM storage handle; used when calling CSSM APIs.

- (SecKeychainRef) keychainRef [read, assign]

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.

- (SecKeychainRef) keychainRefOrDefault [read, assign]

Returns the underlying SecKeychainRef for this keychain.

The special allKeychains instance returns a reference to the default keychain, as a convenience.

- (NSString *) path [read, assign]

The path of this keychain's file.


The documentation for this class was generated from the following files:
Generated on Sun Apr 17 12:23:58 2011 for MYCrypto by  doxygen 1.6.3