[Keychain-commit] SF.net SVN: keychain: [440] trunk/Frameworks/Keychain/Keychain

[<wad...@us...>]

Revision: 440
          http://keychain.svn.sourceforge.net/keychain/?rev=440&view=rev
Author:   wadetregaskis
Date:     2007-12-09 14:01:24 -0800 (Sun, 09 Dec 2007)

Log Message:
-----------
* addInternetPassword:onServer:forAccount:port:path:inSecurityDomain:protocol:auth:replaceExisting: now takes a uint32_t for the port parameter.
* addInternetPassword:onServer:forAccount:port:path:inSecurityDomain:protocol:auth:replaceExisting: & addGenericPassword:onService:forAccount:replaceExisting: now mark the resulting KeychainItem as having an invalid password and being invisible, if the 'password' parameter is given as nil.

Modified Paths:
--------------
    trunk/Frameworks/Keychain/Keychain/Keychain.h
    trunk/Frameworks/Keychain/Keychain/Keychain.m

Modified: trunk/Frameworks/Keychain/Keychain/Keychain.h
===================================================================
--- trunk/Frameworks/Keychain/Keychain/Keychain.h	2007-12-09 21:56:48 UTC (rev 439)
+++ trunk/Frameworks/Keychain/Keychain/Keychain.h	2007-12-09 22:01:24 UTC (rev 440)
@@ -347,12 +347,12 @@
 
 /*! @method addGenericPassword:onService:forAccount:replaceExisting:
     @abstract Adds a password to the receiver for a generic service with the properties given.
-    @discussion This method does not require the user's authentication or permission in order to add the password to the receiver.  If an existing item is present with the same parameters, it will be replaced if you pass YES for the replaceExisting parameter, otherwise it will not and the error property set to an appropriate value.
-    @param password The password.
+    @discussion This method does not require the user's authentication or permission in order to add the password to the receiver.  If an existing item is present with the same parameters, its password will be replaced <i>only if</i> the 'replace' parameter is YES.  Otherwise, the operation fails and nil is returned.
+    @param password The password.  If this is nil, the resulting KeychainItem will have 'passwordIsValid' set to NO, and will be invisible by default.
     @param service A string describing the service name.  This is not in any standard format.  Examples include a domain name or IP address, a label indicating the password type (e.g. 'AIM' or 'ICQ'), or some other proprietary format.  You should try to use any existing 'standard' names where possible, in order to make the keychain useful.
     @param account The account for the service specified.  This may be nil.
     @param replace If YES, the password for an existing item will be replaced, if such an item already exists.  If NO, any existing item will not be changed.
-    @result Returns the resulting new KeychainItem, or nil if an error occurs.  You can retrieve a corresponding error code using the lastError method. */
+    @result Returns the new KeychainItem (if one was created), or the existing item (if 'replace' was YES), or otherwise nil.  You can retrieve a corresponding error code using the lastError method. */
 
 - (KeychainItem*)addGenericPassword:(NSString*)password onService:(NSString*)service forAccount:(NSString*)account replaceExisting:(BOOL)replace;
 
@@ -360,19 +360,19 @@
     @abstract Adds a password to the receiver for an internet service with the properties given.
     @discussion Most of the parameters are optional, or context-sensitive.  For instance, you needn't specify a security domain or protocol if they don't apply to your use.
 
-                This method does not require the user's authentication or permission in order to add the password to the receiver.  If an existing item is present with the same parameters, then it will be replaced if the replaceExisting parameter is YES.  Otherwise, it will not, and an error will occur.
-    @param password The password.
+                This method does not require the user's authentication or permission in order to add the password to the receiver.  If an existing item is present with the same parameters, its password will be replaced <i>only if</i> the 'replace' parameter is YES.  Otherwise, the operation fails and nil is returned.
+    @param password The password.  If this is nil, the resulting KeychainItem will have 'passwordIsValid' set to NO, and will be invisible by default.
     @param server The domain name or IP address of the server for which this password applies.  This parameter may be nil.
     @param account The login, username or account name on the server.  This parameter may be nil.
     @param port The port number, which may implicitly define a service type, for the server.  This may be 0, indicating no port specified.
     @param path The path of a resource on the server, to which this password applies.  This may be nil.
-    @param securityDomain The security domain to add this entry in.  This may (and most often will be) nil.
+    @param securityDomain The security domain to add this entry in.  This may be nil.
     @param protocol The protocol you are using.  See <a href="file:///System/Library/Frameworks/Security.framework/Headers/SecKeychain.h>SecKeychain.h</a> for predefined types.  This parameter is essentially just a Mac type (i.e. 4 bytes), and can be user-defined.  This parameter is required.
     @param authType The authentication type to be used.  See <a href="file:///System/Library/Frameworks/Security.framework/Headers/SecKeychain.h>SecKeychain.h</a> for predefined types.  You should use kSecAuthenticationTypeDefault if you have no preference or knowledge of the type to be used.  Like the protocol parameter, this a 4-byte code, which may be user defined.
     @param replace If YES then any existing item will have it's password changed, otherwise this method will fail if an item already exists.
-    @result Returns the resulting new KeychainItem, or nil if an error occurs.  You can retrieve a corresponding error code using the lastError method. */
+    @result Returns the new KeychainItem (if one was created), or the existing item (if 'replace' was YES), or otherwise nil.  You can retrieve a corresponding error code using the lastError method. */
 
-- (KeychainItem*)addInternetPassword:(NSString*)password onServer:(NSString*)server forAccount:(NSString*)account port:(UInt16)port path:(NSString*)path inSecurityDomain:(NSString*)securityDomain protocol:(SecProtocolType)protocol auth:(SecAuthenticationType)authType replaceExisting:(BOOL)replace;
+- (KeychainItem*)addInternetPassword:(NSString*)password onServer:(NSString*)server forAccount:(NSString*)account port:(uint32_t)port path:(NSString*)path inSecurityDomain:(NSString*)securityDomain protocol:(SecProtocolType)protocol auth:(SecAuthenticationType)authType replaceExisting:(BOOL)replace;
 
 /*! @method items
     @abstract Returns every single item in the keychain, even invisible ones (e.g. keys).

Modified: trunk/Frameworks/Keychain/Keychain/Keychain.m
===================================================================
--- trunk/Frameworks/Keychain/Keychain/Keychain.m	2007-12-09 21:56:48 UTC (rev 439)
+++ trunk/Frameworks/Keychain/Keychain/Keychain.m	2007-12-09 22:01:24 UTC (rev 440)
@@ -1233,6 +1233,8 @@
     }
     
 	if (nil != result) {
+		// 1) Set the creator code, if possible.
+		
 		CFBundleRef mainBundle = CFBundleGetMainBundle();
 		FourCharCode creatorCode = 0;
 		
@@ -1245,12 +1247,20 @@
 		}
 		
 		[result setCreator:creatorCode];
+		
+		
+		// 2) Mark the password as invalid (and invisible) if it was given as nil.
+		
+		if (nil == password) {
+			[result setPasswordIsValid:NO];
+			[result setIsVisible:NO];
+		}
 	}
 	
     return result;
 }
 
-- (KeychainItem*)addInternetPassword:(NSString*)password onServer:(NSString*)server forAccount:(NSString*)account port:(UInt16)port path:(NSString*)path inSecurityDomain:(NSString*)securityDomain protocol:(SecProtocolType)protocol auth:(SecAuthenticationType)authType replaceExisting:(BOOL)replace {
+- (KeychainItem*)addInternetPassword:(NSString*)password onServer:(NSString*)server forAccount:(NSString*)account port:(uint32_t)port path:(NSString*)path inSecurityDomain:(NSString*)securityDomain protocol:(SecProtocolType)protocol auth:(SecAuthenticationType)authType replaceExisting:(BOOL)replace {
     const char *serverString, *accountString, *passwordString, *pathString, *securityDomainString;
     uint32_t serverStringLength, accountStringLength, passwordStringLength, pathStringLength, securityDomainStringLength;
     SecKeychainItemRef newItem;
@@ -1333,6 +1343,8 @@
     }
     
 	if (nil != result) {
+		// 1) Set the creator code, if possible.
+		
 		CFBundleRef mainBundle = CFBundleGetMainBundle();
 		FourCharCode creatorCode = 0;
 		
@@ -1345,6 +1357,21 @@
 		}
 		
 		[result setCreator:creatorCode];
+		
+		
+		// 2) Fix up the port, if it's too large to fit in the 16-bit version that SecKeychainAddInternetPassword accepts.
+		
+		if (port > 0xffff) {
+			[result setPort:port];
+		}
+		
+		
+		// 3) Mark the password as invalid (and invisible) if it was given as nil.
+		
+		if (nil == password) {
+			[result setPasswordIsValid:NO];
+			[result setIsVisible:NO];
+		}
 	}
 	
     return result;


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.