[Keychain-commit] SF.net SVN: keychain: [423] trunk/Frameworks/Keychain/Keychain/KeychainItem .h

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

Revision: 423
          http://keychain.svn.sourceforge.net/keychain/?rev=423&view=rev
Author:   wadetregaskis
Date:     2007-10-27 17:18:55 -0700 (Sat, 27 Oct 2007)

Log Message:
-----------
* Corrected older documentation, and added some new documentation.  Still lots to go, though.

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

Modified: trunk/Frameworks/Keychain/Keychain/KeychainItem.h
===================================================================
--- trunk/Frameworks/Keychain/Keychain/KeychainItem.h	2007-10-27 23:06:13 UTC (rev 422)
+++ trunk/Frameworks/Keychain/Keychain/KeychainItem.h	2007-10-28 00:18:55 UTC (rev 423)
@@ -47,27 +47,33 @@
     int _error;
 }
 
+/*! @method nameOfGetterForAttribute:
+	@abstract Returns the method name of the getter corresponding to a given attribute type.
+	@discussion You wouldn't typically need to use this, as it's explicitly required only for some internal workings of the Keychain framework, but it is available (and supported going forward) if you need it for some reason.
+	@param type The type.
+	@result Returns the method name of the getter corresponding to the given attribute type, or nil if one doesn't exist. */
+
 + (NSString*)nameOfGetterForAttribute:(SecKeychainAttrType)type;
 
 /*! @method keychainItemWithKeychainItemRef:
     @abstract Creates and returns a KeychainItem instance based on a SecKeychainItemRef.
-    @discussion The SecKeychainItemRef is retained by the new KeychainItem instance for the duration of it's life.  This method caches existing KeychainItem instances, such that multiple calls with the same SecKeychainItemRef will return the same unique KeychainItem instance.
+    @discussion The SecKeychainItemRef is retained by the new KeychainItem instance.  This method caches existing KeychainItem instances, such that multiple calls with the same SecKeychainItemRef will return the same unique KeychainItem instance (with its retain count suitably bumped).
     @param ke The SecKeychainItemRef.
-    @result If a KeychainItem instance already returns for the given SecKeychainItemRef, returns that existing instance.  Otherwise, creates a new instance and returns it.  In case of error, returns nil. */
+    @result If a KeychainItem instance already for the given SecKeychainItemRef, returns that existing instance.  Otherwise, creates a new instance and returns it.  In case of error, returns nil. */
 
 + (KeychainItem*)keychainItemWithKeychainItemRef:(SecKeychainItemRef)keychainIt;
 
 /*! @method initWithKeychainItemRef:
     @abstract Initiailizes the receiver with a SecKeychainItemRef.
-    @discussion The SecKeychainItemRef is retained by the receiver for the duration of it's lifetime.  Changes to the SecKeychainItemRef will reflect on the receiver, and vice versa.  Note that this method caches existing KeychainItem instances, such that calling this with a SecKeychainItemRef that has already been used will release the receiver and return the existing instance.
+    @discussion The SecKeychainItemRef is retained by the receiver.  Changes to the SecKeychainItemRef will reflect on the receiver, and vice versa.  Note that this method caches existing KeychainItem instances, such that calling this with a SecKeychainItemRef that has already been used will release the receiver and return the existing instance.
     @param ke The SecKeychainItemRef.
-    @result If SecKeychainItemRef is a valid keychain item, returns the receiver or the existing instance, if available (releasing the receiver in the latter case).  Otherwise, releases the receiver and returns nil. */
+    @result If a KeychainItem instance already exists for the given SecKeychainItemRef, releases the receiver and returns the existing instance (with its retain count suitably incremented).  Otherwise, initialises the receiver with the given SecKeychainItemRef and returns it.  If an error occurs, releases the receiver and returns nil. */
 
 - (KeychainItem*)initWithKeychainItemRef:(SecKeychainItemRef)keychainIt;
 
 /*! @method init
-    @abstract Reject initialiser.
-    @discussion You cannot initialise a KeychainItem using "init" - use one of the other initialisation methods.
+    @abstract Unsupported initialiser.
+    @discussion You cannot initialise a KeychainItem using "init" - use @link initWithKeychainItemRef: initWithKeychainItemRef:@/link.
     @result This method always releases the receiver and returns nil. */
 
 - (KeychainItem*)init;
@@ -113,38 +119,48 @@
 - (BOOL)isCertificate;
 
 /*! @method setData:
-    @abstract Sets the data (e.g. the password) for the receiver.
-    @discussion The data for password items is the password itself.  For certificates, it is the raw certificate (try to avoid setting the certificate in this manner; you may add Certificate instances to keychains directly).  To set passwords, naturally use the setDataString: method instead; otherwise any implicit character set conversions that are performed may yield strange results.
-    @param data The data to set for the receiver. */
+    @abstract Sets the data of the receiver.
+    @discussion The data for password items is the password itself.  For certificates, it is the raw certificate (try to avoid setting the certificate in this manner; you may add Certificate instances to keychains directly).
+	
+				Typically you will want to use @link setDataString: setDataString:@/link to modify passwords, as it handles the string encoding and conversion for you.
 
+				The data may be encrypted for storage in the keychain; this method expects the plaintext.
+
+				TODO: determine under what conditions this may fail, or prompt the user, if any.  It appears that you can always set the data, but I haven't tested extensively.
+    @param data The data to set for the receiver.  Should not be nil. */
+
 - (void)setData:(NSData*)data;
 
 /*! @method setDataString:
-    @abstract Sets the string data (e.g. the password) for the receiver.
-    @discussion The data for password items is the password itself.  For certificates, the data is the raw certificate, which needs to be set using setData: rather than this method (although Certificate instances can be added to keychains directly; avoid setting KeychainItem certificate data directly).
+    @abstract Sets the data (e.g. the password) of the receiver.
+    @discussion The data for password items is the password itself.  For certificates, the data is the raw certificate (which should be set using @link setData: setData:@/link rather than this method, to avoid string encoding and conversion issues).
+				
+				The data may be encrypted for storage in the keychain; this method expects the plaintext.
+				
+                TODO: determine under what conditions this may fail, or prompt the user, if any.  It appears that you can always set the data, but I haven't tested extensively. 
+    @param data The data to set for the receiver, replacing any and all already set for it.  Should not be nil. */
 
-                Note: I'm not sure what permissions are required to edit an item; from memory you don't need *any*, meaning you can overwrite any item at will.  This isn't a security flaw (since it doesn't expose any sensitive data), but you could argue it's a bit of a potential pitfall nonetheless.
-    @param data The data to set for the receiver, replacing any and all already set for it. */
-
 - (void)setDataString:(NSString*)data;
 
 /*! @method data
-    @abstract Returns the data of the receiver (e.g. the password).
-    @discussion The data for password items is the password itself.  For certificates, the data is the raw certificate.  You can convert between KeychainItem's & Certificate's automagically using the appropriate methods.  It is not recommended that you access a certificate's data directly using this method.
+    @abstract Returns the data of the receiver.
+    @discussion The data for password items is the password itself.  For certificates, the data is the raw certificate (although it is recommended you obtain a Certificate instance using the @link certificate certificate@/link method, and use that to interrogate the contents).
 
-                Note that unless your application is already in the receiver's Access with the appropriate privileges, the user will be prompted to enter their password and allow access to the receiver (unless of course you have disabled user interaction, in which case anything which requires user interaction will result in the operation failing).  If the user denies access nil is returned.
-    @result The data of the receiver, or nil if an error occurs (including insufficient privileges to read the receiver). */
+                Note that unless your application is already in the receiver's Access with read access, the user will be prompted to enter their password and allow access to the receiver (unless of course you have disabled user interaction, in which case anything which requires user interaction will result in the operation failing).  If the user denies access nil is returned.
 
+				The returned data is the plaintext, not the encrypted form.
+    @result The data of the receiver, or nil if an error occurs (including insufficient privileges to read the receiver, or if the user denied access). */
+
 - (NSData*)data;
 
 /*! @method dataAsString
     @abstract Returns the data of the receiver (e.g. the password) as a string.
-    @discussion The data for password items is the password itself.  For certificates, the data is the raw certificate.  You should use the 'data' method for retrieving certificate data, as it does not convert well to a string.
+    @discussion The data for password items is the password itself.  For certificates, the data is the raw certificate (which should be retrieved using @link data data@/link rather than this method, to avoid string encoding and conversion issues).
 
 				The data is assumed to be UTF-8 encoded.  If it is not, this method may fail and return nil, or may return a string which is incorrect.
 
-                Note that unless your application is already in the receiver's Access with the appropriate privileges, the user will be prompted to enter their password and allow access to the receiver (unless of course you have disabled user interaction, in which case anything which requires user interaction will result in the operation failing).  If the user denies access nil is returned.
-    @result The data of the receiver, or nil if an error occurs (including insufficient privileges to read the receiver). */
+				Note that unless your application is already in the receiver's Access with read access, the user will be prompted to enter their password and allow access to the receiver (unless of course you have disabled user interaction, in which case anything which requires user interaction will result in the operation failing).  If the user denies access nil is returned.
+    @result The data of the receiver, or nil if an error occurs (including insufficient privileges to read the receiver, or if the user denied access). */
 
 - (NSString*)dataAsString;
 
@@ -152,51 +168,158 @@
     @abstract Sets the creation date of the receiver.
     @discussion The creation date should reflect the date at which the receiver was created, *not* necessarily when it was first added to the keychain in which it currently resides.  This is similar to copying files between volumes; the creation date remains the same.  The creation date should be set automatically, as necessary.
 
-                Note that Keychain Access does not follow this behaviour.  Indeed, the built-in behaviour may or may not be as described.  Damn.
-    @param date The new creation date for the receiver. */
+                Note that Keychain Access does not follow this behaviour.  Indeed, the built-in behaviour may or may not be as described.  TODO: verify this.
 
+				The default value, for new KeychainItems, is the time at which the item was created.
+    @param date The new creation date for the receiver.  Should not be nil. */
+
 - (void)setCreationDate:(NSDate*)date;
 
 #if 0 // This doesn't work yet. :(
 /*! @method setModificationDate:
     @abstract Sets the modification date of the receiver.
-    @discussion The modification date should reflect the date at which the receiver was last modified, which does not include it's addition to the owning keychain.  The modification date should be updated automatically as necessary.
+    @discussion The modification date should reflect the date at which the receiver's data or attributes were last modified (which does not include it's addition to the owning keychain).  The modification date is updated automatically when you modify the receiver's data or attributes.
 
-                Note that Keychain Access does not follow this behaviour.  Indeed, the built-in behaviour may or may not be as described.  Damn.
-    @param date The new modification date for the receiver. */
+                Note that Keychain Access does not follow this behaviour.  TODO: describe Keychain Access's behaviour.
+    @param date The new modification date for the receiver.  Should not be nil. */
 
 - (void)setModificationDate:(NSDate*)date;
 #endif
 
 /*! @method setTypeDescription:
-    @abstract Sets the human description of the receiver's type.
-    @discussion KeychainItem's can (and 'generic' or custom types <i>should</i>) have a type description associated with them, which concisely summarises their type & purpose.  Obviously, this method can be used to set this description.  Examples include "Proteus Service Password", or "Web Forms Password", etc.
-    @param desc The description for the custom type. */
+    @abstract Sets the human-readable description of the receiver's type.
+    @discussion KeychainItem's can (and 'generic' or custom types <i>should</i>) have a type description associated with them, which concisely summarises their type & purpose.  Examples include "Proteus Service Password", or "Web Forms Password", etc.
 
+				Note that this is distinct from the item's label (@link setLabel: setLabel:@/link/@link label label@/link) and comment (@link setComment: setComment:@/link/@link comment comment@/link); it describes the <i>type</i> of item the receiver is, not the receiver specifically.
+
+				The default value, for new KeychainItems, is an empty string.
+    @param desc The description for the receiver.  Should not be nil. */
+
 - (void)setTypeDescription:(NSString*)desc;
 
 /*! @method setComment:
     @abstract Sets a human-readable comment for the receiver.
-    @discussion The comment can be anything; it is intended to be end-user readable, in a similar manner to file comments in the Finder.
-    @param comment The comment. */
+    @discussion The comment can be anything; it is intended to be end-user readable, in a similar manner to file comments in the Finder.  This attribute should be considered user-editable.
 
+				The default value, for new KeychainItems, is an empty string.
+    @param comment The comment.  Should not be nil. */
+
 - (void)setComment:(NSString*)comment;
 
 /*! @method setCreator:
     @abstract Sets the creator code of the receiver.
-    @discussion The creator code should */
+    @discussion The creator code is the Classic MacOS document creator code, identifying which application created (or otherwise presently "owns") a given item.
+	
+				The default value, for new KeychainItems, is the creator code of the main bundle (i.e. your application).  This may be 0.
+	@param creator The creator of the receiver, which may be 0 (meaning essentially 'no creator'). */
 
 - (void)setCreator:(FourCharCode)creator;
+
+/*! @method setCreatorFromString:
+    @abstract Sets the creator code of the receiver from the given string.
+    @discussion This is a convenience method which converts the given string to a FourCharCode and passes that to @link setCreator: setCreator:@/link.  The given string should be either empty (to clear the creator code) or contain four ASCII characters.  Note that NULLs are valid in the string.
+
+				// TODO: verify how bytes > 127 are interpretted... I suspect MacRoman, but this needs to be tested.
+	@param creator The creator of the receiver, which should be either an empty string or a string containing exactly four ASCII characters. */
+
 - (void)setCreatorFromString:(NSString*)creator;
+
+/*! @method setType:
+    @abstract Sets the type code of the receiver.
+    @discussion The type code is the Classic MacOS document type code, identifying the document type of a given item.  This is very distinct from the @link kind kind@/link of a KeychainItem; the 'type' does not describe the type of KeychainItem, but rather the document type with which it is associated.  This is largely just a hang-over from Classic MacOS, and is neither commonly used nor recommended for future use.
+
+				The default value, for new KeychainItems, is 0.
+	@param type The type of the receiver, which may be 0 (meaning essentially 'no type'). */
+
 - (void)setType:(FourCharCode)type;
+
+/*! @method setTypeFromString:
+    @abstract Sets the type code of the receiver from the given string.
+    @discussion This is a convenience method which converts the given string to a FourCharCode and passes that to @link setType: setType:@/link.  The given string should be either empty (to clear the type code) or contain four ASCII characters.  Note that NULLs are valid in the string.
+
+				// TODO: verify how bytes > 127 are interpretted... I suspect MacRoman, but this needs to be tested.
+	@param type The type of the receiver, which should be either an empty string or a string containing exactly four ASCII characters. */
+
 - (void)setTypeFromString:(NSString*)type;
+
+/*! @method setLabel:
+	@abstract Sets the human-readable label of the receiver.
+	@discussion The label is a human-readable, brief description of the receiver.  This attribute should be considered user-editable.
+
+				The default value, for new KeychainItems, varies; it is automatically generated based on the receiver's contents to be some suitable default.
+	@param label The label for the receiver.  Should not be nil. */
+
 - (void)setLabel:(NSString*)label;
+
+/*! @method setIsVisible:
+	@abstract Sets whether or not the receiver is visible.
+	@discussion 'Visibility' applies to the end-user only, and is something that the end-developer should account for in their application; it has no bearing on how the Keychain framework works with KeychainItems.  You might desire for an item to be invisible if it is internal to your application and not something the user needs to be aware of.
+
+				Note that in 10.4 I believe Keychain Access ignores this attribute and displays all items regardless.  TODO: verify this.
+
+				The default value, for new KeychainItems, is YES.
+	@param visible Whether or not the receiver should be visible to the end-user. */
+
 - (void)setIsVisible:(BOOL)visible;
+
+/*! @method setIsValid:
+	@abstract Sets whether or not the receiver's data is valid.
+	@discussion You may wish to add an entry to a keychain which is not actually valid, as a way of saying that you do not want to remember the real data for that item.  For example, if your application has the option to add passwords to the keychain when you first enter them, if the user decides not to do so you could add a placeholder item (with an empty password) and mark it invalid.  Then when your application, in future, searches for the password it will find the invalid item and know that it must prompt the user, and shouldn't try to store the password.
+
+				While you could use this to require the user to always enter a password, without the option of saving it, keep in mind that they ultimately could just choose to toggle this flag themselves, manually, if so inclined.  As such, don't rely on this exclusively for setting policy.  You may also want to make the receiver invisible (@link setIsVisible: setIsVisible:@/link), if it is invalid, to discourage user manipulation.
+
+				Note that as an end-developer you are responsible for handling validity appropriately; the setting of this attribute does not influence how the Keychain framework operates.
+
+				The default value, for new KeychainItems, is YES.
+	@param valid Whether or not the receiver's content (@link data data@/link) is valid. */
+
 - (void)setIsValid:(BOOL)valid;
+
+/*! @method setHasCustomIcon:
+	@abstract Sets whether or not the receiver has a custom icon.
+	@discussion Custom icons are a hang-over from the Classic MacOS Keychain Manager.  In a nutshell, if this attribute is set to YES, then a custom icon should be displayed (if available) by searching for the document icon corresponding to the receiver's @link creator creator@/link and @link type type@/link codes.
+
+				This attribute is more or less deprecated, and not recommended for future use.
+
+				The default value, for new KeychainItems, is NO.
+	@param icon Whether or not the receiver has a custom icon. */
+
 - (void)setHasCustomIcon:(BOOL)icon;
+
+/*! @method setAccount:
+	@abstract Sets the account of the receiver.
+	@discussion The account is the login name or similar of a password.  It is not encrypted when stored in the keychain.  Only password KeychainItems have this attribute; not certificates.
+
+				The default value for new KeychainItems, if not otherwise defined at creation time, is an empty string.
+	@param account The account for the receiver.  Should not be nil (but may be an empty string). */
+
 - (void)setAccount:(NSString*)account;
+
+/*! @method setService:
+	@abstract Sets the 'service' of the receiver.
+	@discussion i.e. the type of thing it is a password for.  e.g. ".Mac".  This attribute is only available on generic password (kSecGenericPasswordItemClass) KeychainItems.
+
+				The default value for new KeychainItems, if not otherwise defined at creation time, is an empty string.
+	@param service The service for the receiver.  Should not be nil (but may be an empty string). */
+
 - (void)setService:(NSString*)service;
+
+/*! @method setUserDefinedAttribute:
+	@abstract Sets the user-defined attribute of the receiver.
+	@discussion This attribute is only available on generic password (kSecGenericPasswordItemClass) KeychainItems, and is simply a blob of arbitrary data.  It is up to the end-developer to define what this attribute is, and the structure of it.  In the interest of compatibility and openness the use of this attribute is discouraged.  If you do use it, it's recommended you publish a description of its purpose and structure so that others may interoperate.
+
+				The default value, for new KeychainItems, is an empty NSData.
+	@param attribute The attribute value.  Should not be nil (but may be empty). */
+
 - (void)setUserDefinedAttribute:(NSData*)attribute;
+
+/*! @method setDomain:
+	@abstract Sets the security domain of the receiver.
+	@discussion The security domain (also know as a realm) is a way of identifying a subsection of a website which uses the same login.  For example, on www.example.com there may be a "PHPmyAdmin" domain and a "User" domain.  Where you have knowledge of the domain of a password, it is wise to reference the domain in preference to a particular path, as the user should not be prompted multiple times for the same login, for the same domain.
+
+				The default for new KeychainItems, if not otherwise defined at creation time, is an empty string.
+	@param domain The security domain for the receiver.  Should not be nil (but may be an empty string). */
+
 - (void)setDomain:(NSString*)domain;
 - (void)setServer:(NSString*)server;
 - (void)setAuthenticationType:(SecAuthenticationType)authType;


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