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

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

Revision: 444
          http://keychain.svn.sourceforge.net/keychain/?rev=444&view=rev
Author:   wadetregaskis
Date:     2007-12-09 15:50:26 -0800 (Sun, 09 Dec 2007)

Log Message:
-----------
* Commented out -[KeychainItem createDuplicate] until it's determined whether it works or not, and fixed as necessary.
* Completed the documentation for KeychainItem.

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

Modified: trunk/Frameworks/Keychain/Keychain/KeychainItem.h
===================================================================
--- trunk/Frameworks/Keychain/Keychain/KeychainItem.h	2007-12-09 23:49:52 UTC (rev 443)
+++ trunk/Frameworks/Keychain/Keychain/KeychainItem.h	2007-12-09 23:50:26 UTC (rev 444)
@@ -327,7 +327,7 @@
 	
 				This attribute applies only to password items (kSecInternetPasswordItemClass, kSecAppleSharePasswordItemClass and kSecGenericPasswordItemClass).
 
-				The default value, for new KeychainItems, is the creator code of the main bundle (i.e. your application).  This may be 0.
+				The default value, for keychain items created by this framework, is the creator code of the main bundle (i.e. your application).  This may be 0.  The default value for items created by other frameworks or means is typically 0, but is not explicitly defined.
 	@param creator The creator of the receiver, which may be 0 (meaning essentially 'no creator'). */
 
 - (void)setCreator:(FourCharCode)creator;
@@ -389,7 +389,7 @@
 
 /*! @method setPasswordIsValid:
 	@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.
+	@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 marked as 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.
 
@@ -417,7 +417,7 @@
 
 /*! @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.
+	@discussion The account is the login name or similar of a password.  It is not encrypted when stored in the keychain.
 
 				This attribute applies only to password items (kSecInternetPasswordItemClass, kSecAppleSharePasswordItemClass and kSecGenericPasswordItemClass).  It is a uniquing attribute for all three types.
 
@@ -488,7 +488,9 @@
 
 /*! @method setPath:
 	@abstract Sets the path of the reciever.
-	@discussion This attribute applies only to Internet passwords (kSecInternetPasswordItemClass, @link isInternetItem isInternetItem@/link), where is is a uniquing attribute.
+	@discussion e.g. the path of "http://www.example.com/cgi/query.c" is "/cgi/query.c".
+	
+				This attribute applies only to Internet passwords (kSecInternetPasswordItemClass, @link isInternetItem isInternetItem@/link), where is is a uniquing attribute.
 
 				The default for new KeychainItems, if not otherwise defined at creation time, is an empty string.
 	@param path The path.  Should not be nil (but may be an empty string). */
@@ -542,7 +544,7 @@
 	@abstract Sets the certificate encoding of the receiver.
 	@discussion This attribute applies only to certificates (kSecCertificateItemClass, @link isCertificate isCertificate@/link).
 
-				   // TODO: should this be settable?  Shouldn't we ensure this is in sync with the actual certificate data, automatically?
+				// TODO: should this be settable?  Shouldn't we ensure this is in sync with the actual certificate data, automatically?
 	@param certEncoding The certificate encoding. */
 
 - (void)setCertificateEncoding:(CSSM_CERT_ENCODING)certEncoding;
@@ -551,7 +553,7 @@
 	@abstract Sets the CRL type of the receiver.
 	@discussion This attribute applies only to CRLs (Certificate Revocation Lists).  (TODO: how does one identify a KeychainItem as such?)
 
-					   // TODO: should this be settable?  Shouldn't we ensure this is in sync with the actual CRL data, automatically?
+				// TODO: should this be settable?  Shouldn't we ensure this is in sync with the actual CRL data, automatically?
 	@param type The CRL type. */
 
 - (void)setCRLType:(CSSM_CRL_TYPE)type;
@@ -560,7 +562,7 @@
 	@abstract Sets the CRL encoding of the receiver.
 	@discussion This attribute applies only to CRLs (Certificate Revocation Lists).  (TODO: how does one identify a KeychainItem as such?)
 
-					   // TODO: should this be settable?  Shouldn't we ensure this is in sync with the actual CRL data, automatically?
+				// TODO: should this be settable?  Shouldn't we ensure this is in sync with the actual CRL data, automatically?
 	@param encoding The CRL encoding. */
 
 - (void)setCRLEncoding:(CSSM_CRL_ENCODING)encoding;
@@ -572,56 +574,410 @@
 
 - (void)setAlias:(NSString*)alias;
 
+/*! @method creationDate
+	@abstract Returns the creation date of the receiver.
+	@discussion The creation date is the time at which the receiver was added to the keychain.  If an item is moved between two keychains, the new copy will have its creation date set to the present (this is contrary to typical creation date behaviour, such as in the file system, and may change in future).
+
+				This attribute applies only to password items (kSecInternetPasswordItemClass, kSecAppleSharePasswordItemClass and kSecGenericPasswordItemClass).
+
+				You can modify this attribute using @link setCreationDate: setCreationDate:@/link.
+	@result Returns the creation date (time at which the receiver was added to the keychain), or nil if an error occurs (e.g. this attribute does not apply to the receiver). */
+
 - (NSCalendarDate*)creationDate;
+
+/*! @method modificationDate
+	@abstract Returns the time of the most recent modification to the receiver.
+	@discussion The modification date is automatically updated to the present date and time whenever the receivers data (e.g. password) or attributes are modified.
+	
+				This attribute applies only to password items (kSecInternetPasswordItemClass, kSecAppleSharePasswordItemClass and kSecGenericPasswordItemClass).
+
+				At present it cannot be set explicitly using this framework, although it is possible to do so - you should not rely on the modification date to be truthful.
+	@result Returns the time of the most recent modification to the receiver, or nil if an error occurs (e.g. this attribute does not apply to the receiver). */
+
 - (NSCalendarDate*)modificationDate;
+
+/*! @method typeDescription
+	@abstract Returns 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 and 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.
+
+				This attribute applies only to password items (kSecInternetPasswordItemClass, kSecAppleSharePasswordItemClass and kSecGenericPasswordItemClass).
+
+				The default value, for new KeychainItems, is an empty string.
+
+				You can modify this attribute using @link setTypeDescription: setTypeDescription:@/link.
+	@result Returns the description of the receiver's type (which may be an empty string), or nil if an error occurs (e.g. this attribute does not apply to the receiver). */
+
 - (NSString*)typeDescription;
+
+/*! @method comment
+	@abstract Returns 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.  This attribute should be considered user-editable.
+
+				This attribute applies only to password items (kSecInternetPasswordItemClass, kSecAppleSharePasswordItemClass and kSecGenericPasswordItemClass).
+
+				The default value, for new KeychainItems, is an empty string.
+
+				You can modify this attribute using @link setComment: setComment:@/link.
+	@result Returns the comment for the receiver (which may be an empty string), or nil if an error occurs (e.g. this attribute does not apply to the receiver). */
+
 - (NSString*)comment;
+
+/*! @method creator
+	@abstract Returns the creator code of the receiver.
+	@discussion The creator code is the Classic MacOS document creator code, identifying which application created (or otherwise presently "owns") a given item.
+
+				This attribute applies only to password items (kSecInternetPasswordItemClass, kSecAppleSharePasswordItemClass and kSecGenericPasswordItemClass).
+
+				The default value, for keychain items created by this framework, is the creator code of the main bundle (i.e. your application).  This may be 0.  The default value for items created by other frameworks or means is typically 0, but is not explicitly defined.
+
+				You can modify this attribute using @link setCreator: setCreator:@/link.  You may also wish to retrieve this value as a string, using @link creatorAsString creatorAsString@/link.
+	@result Returns the creator code of the receiver, or 0 if one is not set or an error occurs (e.g. this attribute does not apply to the receiver). */
+
 - (FourCharCode)creator;
+
+/*! @method creatorAsString
+	@abstract Returns the creator code of the receiver.
+	@discussion This is a convenience method which converts the result of @link creator creator@/link into an NSString.  Since creator codes are ultimately just 32-bit integers, this is not guaranteed to result in a human-readable string (although by convention most creator codes use ASCII alphanumerics only, making them human-readable for convenience).
+
+				You can modify this attribute using @link setCreatorFromString: setCreatorFromString:@/link.
+	@result Returns the receiver's creator code converted to an NSString, or nil if an error occurs (e.g. this attribute does not apply to the receiver). */
+
 - (NSString*)creatorAsString;
+
+/*! @method type
+	@abstract 
+	@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.
+
+				This attribute applies only to password items (kSecInternetPasswordItemClass, kSecAppleSharePasswordItemClass and kSecGenericPasswordItemClass).
+
+				The default value, for new KeychainItems, is 0.
+
+				You can modify this attribute using @link setType: setType:@/link.  You may also wish to retrieve this value as a string, using @link typeAsString typeAsString@/link.
+	@result Returns the type of the receiver, which may be 0 (meaning essentially 'no type') if no value is set, or an error occurs (e.g. this attribute does not apply to the receiver). */
+
 - (FourCharCode)type;
+
+/*! @method typeAsString
+	@abstract Returns the type code of the receiver.
+	@discussion This is a convenience method which converts the result of @link type type@/link into an NSString.  Since type codes are ultimately just 32-bit integers, this is not guaranteed to result in a human-readable string (although by convention most type codes use ASCII alphanumerics only, making them human-readable for convenience).
+
+				You can modify this attribute using @link setTypeFromString: setTypeFromString:@/link.
+	@result Returns the receiver's type code converted to an NSString, or nil if an error occurs (e.g. this attribute does not apply to the receiver). */
+
 - (NSString*)typeAsString;
+
+/*! @method label
+	@abstract Returns 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.
+
+				You may modify this attribute using @link setLabel: setLabel:@/link.
+	@result Returns the label for the receiver (which may be an empty string), or nil if an error occurs. */
+
 - (NSString*)label;
+
+/*! @method isVisible
+	@abstract Returns whether the receiver is visible or not.
+	@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.
+
+				This attribute applies only to password items (kSecInternetPasswordItemClass, kSecAppleSharePasswordItemClass and kSecGenericPasswordItemClass).
+
+				The default value, for new KeychainItems, is YES.
+
+				You may modify this attribute using @link setIsVisible: setIsVisible:@/link.
+	@result Returns whether or not the receiver should be visible to the end-user, or NO if an error occurs (e.g. this attribute does not apply to the receiver). */
+
 - (BOOL)isVisible;
+
+/*! @method passwordIsValid
+	@abstract Returns whether the receiver's content (e.g. password) 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 marked as 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.
+
+				This attribute applies only to password items (kSecInternetPasswordItemClass, kSecAppleSharePasswordItemClass and kSecGenericPasswordItemClass).
+
+				The default value, for new KeychainItems, is YES.
+
+				You may modify this attribute using @link setPasswordIsValid: setPasswordIsValid:@/link.
+	@result Returns whether or not the receiver's content (@link data data@/link) is valid, or NO if an error occurs (e.g. this attribute does not apply to the receiver). */
+
 - (BOOL)passwordIsValid;
+
+/*! @method hasCustomIcon
+	@abstract Returns whether or not the receiver has a custom icon associated with it.
+	@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.
+
+				This attribute applies only to password items (kSecInternetPasswordItemClass, kSecAppleSharePasswordItemClass and kSecGenericPasswordItemClass).
+
+				The default value, for new KeychainItems, is NO.
+
+				You may modify this attribute using @link setHasCustomIcon: setHasCustomIcon:@/link.
+	@result Returns whether or not the receiver has a custom icon, or NO if an error occurs (e.g. this attribute does not apply to the receiver). */
+
 - (BOOL)hasCustomIcon;
+
+/*! @method account
+	@abstract Returns 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.
+
+				This attribute applies only to password items (kSecInternetPasswordItemClass, kSecAppleSharePasswordItemClass and kSecGenericPasswordItemClass).  It is a uniquing attribute for all three types.
+
+				The default value for new KeychainItems, if not otherwise defined at creation time, is an empty string.
+
+				You may modify this attribute using @link setAccount: setAccount:@/link.
+	@result Returns the account for the receiver (which may be an empty string), or nil if an error occurs (e.g. this attribute does not apply to the receiver). */
+
 - (NSString*)account;
+
+/*! @method service
+	@abstract Returns the 'service' of the receiver.
+	@discussion i.e. the type of thing it is a password for.  e.g. ".Mac".
+
+				This attribute applies only to Generic passwords (kSecGenericPasswordItemClass), where it is a uniquing attribute.
+
+				The default value for new KeychainItems, if not otherwise defined at creation time, is an empty string.
+
+				You may modify this attribute using @link setService: setService:@/link.
+	@result Returns the service for the receiver (which may be an empty string), or nil if an error occurs (e.g. this attribute does not apply to the receiver). */
+
 - (NSString*)service;
+
+/*! @method userDefinedAttribute
+	@abstract Returns 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.
+
+				You may modify this attribute using @link setUserDefinedAttribute: setUserDefinedAttribute:@/link.
+	@result Returns the attribute value (which may be an empty NSData), or nil if an error occurs. */
+
 - (NSData*)userDefinedAttribute;
+
+/*! @method securityDomain
+	@abstract Returns 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.
+
+				This attribute applies only to Internet passwords (kSecInternetPasswordItemClass, @link isInternetItem isInternetItem@/link), where is is a uniquing attribute.
+
+				The default for new KeychainItems, if not otherwise defined at creation time, is an empty string.
+
+				You may modify this attribute using @link setSecurityDomain: setSecurityDomain:@/link.
+	@result Returns the security domain for the receiver (which may be an empty string), or nil if an error occurs (e.g. this attribute does not apply to the receiver). */
+
 - (NSString*)securityDomain;
+
+/*! @method server
+	@abstract Returns the server of the receiver.
+	@discussion The server is just the domain name or IP address of the server, e.g. "www.google.com" or "192.168.0.1".
+
+				This attribute applies only to AppleShare passwords (kSecAppleSharePasswordItemClass, @link isAppleShareItem isAppleShareItem@/link) and Internet passwords (kSecInternetPasswordItemClass, @link isInternetItem isInternetItem@/link).  It is a uniquing attribute for Internet passwords.
+
+				The default for new KeychainItems, if not otherwise defined at creation time, is an empty string.
+
+				You may modify this attribute using @link setServer: setServer:@/link.
+	@result Returns the server (which may be an empty string), or nil if an error occurs (e.g. this attribute does not apply to the receiver). */
+
 - (NSString*)server;
+
+/*! @method authenticationType
+	@abstract Returns the authentication type of the receiver.
+	@discussion It is possible to have two otherwise-identical passwords with different authentication types.  e.g. one for HTTP basic and one for HTTP digest.  If the authentication type is irrelevant, use kSecAuthenticationTypeDefault.
+
+				This attribute applies only to Internet passwords (kSecInternetPasswordItemClass, @link isInternetItem isInternetItem@/link), where is is a uniquing attribute.
+
+				You may modify this attribute using @link setAuthenticationType: setAuthenticationType:@/link.
+	@result Returns the authentication type of the receiver. */
+
 - (SecAuthenticationType)authenticationType;
+
+/*! @method port
+	@abstract Returns the port of the receiver.
+	@discussion This attribute applies only to Internet passwords (kSecInternetPasswordItemClass, @link isInternetItem isInternetItem@/link), where is is a uniquing attribute.
+
+				The default for new KeychainItems, if not otherwise defined at creation time, is 0.
+
+				You may modify this attribute using @link setPort: setPort:@/link.
+	@param port The port (which may be 0 if unspecified), or 0 if an error occurs (e.g. this attribute does not apply to the receiver). */
+
 - (uint32_t)port;
+
+/*! @method path
+	@abstract Returns the path of the receiver.
+	@discussion e.g. the path of "http://www.example.com/cgi/query.c" is "/cgi/query.c".
+
+				This attribute applies only to Internet passwords (kSecInternetPasswordItemClass, @link isInternetItem isInternetItem@/link), where is is a uniquing attribute.
+
+				The default for new KeychainItems, if not otherwise defined at creation time, is an empty string.
+
+				You may modify this attribute using @link setPath: setPath:@/link.
+	@result Returns the path (which may be an empty string), or nil if an error occurs (e.g. this attribute does not apply to the receiver). */
+
 - (NSString*)path;
+
+/*! @method appleShareVolume
+	@abstract Returns the AppleShare volume name of the receiver.
+	@discussion This attribute applies only to AppleShare passwords (kSecAppleSharePasswordItemClass, @link isAppleShareItem isAppleShareItem@/link), where it is a uniquing attribute.
+
+				The default for new KeychainItems, if not otherwise defined at creation time, is an empty string.
+
+				You may modify this attribute using @link setAppleShareVolume: setAppleShareVolume:@/link.
+	@result Returns the volume name (which may be an empty string), or nil if an error occurs (e.g. this attribute does not apply to the receiver). */
+
 - (NSString*)appleShareVolume;
+
+/*! @method appleShareAddress
+	@abstract Returns the AppleShare address of the receiver.
+	@discussion This attribute applies only to AppleShare passwords (kSecAppleSharePasswordItemClass, @link isAppleShareItem isAppleShareItem@/link), where it is a uniquing attribute.
+
+				The default for new KeychainItems, if not otherwise defined at creation time, is an empty string.
+
+				You may modify this attribute using @link setAppleShareAddress: setAppleShareAddress:@/link.
+	@result Returns the address (which may be an empty string), or nil if an error occurs (e.g. this attribute does not apply to the receiver). */
+
 - (NSString*)appleShareAddress;
+
+/*! @method appleShareSignature
+	@abstract Returns the AppleShare signature of the receiver.
+	@discussion This attribute applies only to AppleShare passwords (kSecAppleSharePasswordItemClass, @link isAppleShareItem isAppleShareItem@/link), where it is a uniquing attribute.
+
+				You may modify this attribute using @link setAppleShareSignature: setAppleShareSignature:@/link.
+	@result Returns the signature, or NULL if an error occurs (e.g. this attribute does not apply to the receiver). */
+
 - (SecAFPServerSignature*)appleShareSignature;
+
+/*! @method appleShareSignatureData
+	@abstract Returns the AppleShare signature of the receiver as an NSData.
+	@discussion This is a convenience method which wraps the result from @link appleShareSignature appleShareSignature@/link in an NSData.
+	@result Returns the AppleShare signature of the receiver, or nil if an error occurs (e.g. this attribute does not apply to the receiver). */
+
 - (NSData*)appleShareSignatureData;
+
+/*! @method protocol
+	@abstract Returns the protocol of the receiver.
+	@discussion This attribute applies only for internet passwords (kSecInternetPasswordItemClass, @link isInternetItem isInternetItem@/link) and AppleShare passwords (kSecAppleSharePasswordItemClass, @link isAppleShareItem isAppleShareItem@/link).  For Internet passwords it is a uniquing attribute.
+
+				There is no "default" or "generic" protocol.  If you cannot find a value the applies for your use, make up your own.
+
+				You may modify this attribute using @link setProtocol: setProtocol:@/link.
+	@result Returns the protocol, or 0 if an error occurs (e.g. this attribute does not apply to the receiver). */
+
 - (SecProtocolType)protocol;
+
+/*! @method certificateType
+	@abstract Returns the certificate type of the receiver.
+	@discussion This attribute applies only to certificates (kSecCertificateItemClass, @link isCertificate isCertificate@/link), where it is a uniquing attribute.
+
+				You may modify this attribute using @link setCertificateType: setCertificateType:@/link.
+	@result Returns the certificate type, or 0 if an error occurs (e.g. this attribute does not apply to the receiver). */
+
 - (CSSM_CERT_TYPE)certificateType;
+
+/*! @method certificateEncoding
+	@abstract Returns the certificate encoding of the receiver.
+	@discussion This attribute applies only to certificates (kSecCertificateItemClass, @link isCertificate isCertificate@/link).
+
+				You may modify this attribute using @link setCertificateEncoding: setCertificateEncoding:@/link.
+	@result Returns the certificate encoding, or 0 if an error occurs (e.g. this attribute does not apply to the receiver). */
+
 - (CSSM_CERT_ENCODING)certificateEncoding;
+
+/*! @method CRLType
+	@abstract Returns the CRL type of the receiver.
+	@discussion This attribute applies only to CRLs (Certificate Revocation Lists).  (TODO: how does one identify a KeychainItem as such?)
+
+				You may modify this attribute using @link setCRLType: setCRLType:@/link.
+	@result Returns the CRL type, or 0 if an error occurs (e.g. this attribute does not apply to the receiver). */
+
 - (CSSM_CRL_TYPE)CRLType;
+
+/*! @method CRLEncoding
+	@abstract Returns the CRL encoding of the receiver.
+	@discussion This attribute applies only to CRLs (Certificate Revocation Lists).  (TODO: how does one identify a KeychainItem as such?)
+
+				You may modify this attribute using @link setCRLEncoding: setCRLEncoding:@/link.
+	@result Returns the CRL encoding. */
+
 - (CSSM_CRL_ENCODING)CRLEncoding;
+
+/*! @method alias
+	@abstract Returns the alias of the receiver.
+	@discussion The alias is typically used for certificates as a convenient way of identifying the key attribute of the item, e.g. the email address the certificate applies to (which may in turn be useful for looking up related AddressBook entries, for example).
+
+				You may modify this attribute using @link setAlias: setAlias:@/link.
+	@result Returns the alias (which may be an empty string), or nil if an error occurs. */
+
 - (NSString*)alias;
 
+/*! @method setAccess:
+	@abstract Sets the Access of the receiver.
+	@discussion The Access associated with a KeychainItem controls how the item may be accessed by applications.  See the documentation for @link Access Access@/link for more information.
+	@param acc The Access to set.  Should not be nil. */
+
 - (void)setAccess:(Access*)acc;
+
+/*! @method access
+	@abstract Returns the Access of the receiver.
+	@discussion The Access associated with a KeychainItem controls how the item may be accessed by applications.  See the documentation for @link Access Access@/link for more information.
+
+				While you typically modify the existing Access, if available, you may replace the receiver's access entirely using @link setAccess: setAccess:@/link.
+	@result Returns the receiver's access, or nil if an error occurs. */
+
 - (Access*)access;
 
+/*! @method keychain
+	@abstract Returns the Keychain in which the receiver resides.
+	@discussion In most circumstances all KeychainItems are contained within a Keychain, although this is not guaranteed.
+	@result Returns the receiver's Keychain, if any, or nil if an error occurs. */
+
 - (Keychain*)keychain;
 
-- (KeychainItem*)createDuplicate;
+//- (KeychainItem*)createDuplicate; // Not exposed yet because I'm pretty sure it doesn't work.
 
+/*! @method certificate
+	@abstract Returns the Certificate for the receiver, if possible.
+	@discussion If the receiver is a certificate, you may get an actual Certificate instance (that allows you to fully access and use the certificate) using this method.
+
+				This only applies to certificate (@link isCertificate isCertificate@/link) items, naturally.
+	@result Returns the Certificate for the receiver, or nil if an error occurs (e.g. the receiver is not a certificate). */
+
 - (Certificate*)certificate;
 
+/*! @method deleteCompletely
+	@abstract Deletes the receiver from its keychain.
+	@discussion The lifetime of a KeychainItem instance isn't linked to the actual record in the keychain, naturaly - the KeychainItem may be deallocated and go away without affecting the item it represents.  So if you actually want to delete an item, use this method.
+
+				Once you have invoked this method, the receiver is no longer valid and cannot be used (all methods will fail). */
+
 - (void)deleteCompletely;
 
 /*! @method lastError
     @abstract Returns the last error that occured for the receiver.
-    @discussion The set of error codes encompasses those returned by Sec* functions - refer to the Security framework documentation for a list - and the CDSA error codes.  At present there are no other error codes defined for Access instances.
+    @discussion The set of error codes encompasses those returned by Sec* functions - refer to the Security framework documentation for a list - and the CDSA error codes.
 
               Please note that this error code is local to the receiver only, and not any sort of shared global value.
     @result The last error that occured, or zero if the last operation was successful. */
 
 - (OSStatus)lastError;
+
+/*! @method keychainItemRef
+	@abstract Returns the receiver's underlying SecKeychainItemRef.
+	@discussion Each KeychainItem wraps a SecKeychainItemRef, which is the Security-framework representation of keychain items.  You may use this method to retrieve this low-level reference.
+
+				The SecKeychainItemRef returned will be retained for at least the lifetime of the receiver, but you should of course CFRetain (and, later, CFRelease) it if you wish to keep the reference around.
+
+				While there aren't typically any issues with this reference being used directly alongside the use of the receiver, you should be aware that there is a potential for conflict.
+	@result Returns the receiver's SecKeychainItemRef. */
+
 - (SecKeychainItemRef)keychainItemRef;
 
 @end


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