/**
   @page page_cryptotoken_framework Cryptographic token framework
   
	@section cryptotokens_pas Purpose and scope
This document specifies the APIs which we will define as specified in the Hurricane Security Framework Functional Specification [1]. 

This document assumes familiarity with the functional specification. 

The API definitions are organised into 4 sections:
- @ref ct
- @ref interfaces
- @ref secdlg
- @ref Securitydefs

In addition, a guide to writing tokens is provided: @ref cryptotokens_Writing

And a guide to the use of reference counting:@ref cryptotokens_refcount

@section cryptotokens_notes General Notes

- Clients of the Crypto Token Framework must use an active
	scheduler. Crypto tokens may assume that an active scheduler is
	present.

	@subsection cryptotokens_refs References
All Documents can be found in <code>\\\\Londata04\\Psisoft\\Dev\\GT\\0128 Hurricane WAP</code> unless otherwise stated.

-# Hurricane Security Framework Functional Specification, "HSF FS.doc"
-# Certificate Management(Hurricane) Functional Specification

@section cryptotokens_tsecdlg The dummy security dialog notifier

See @ref cryptotokens_TSecdlg

@section cryptotokens_revs Revision History
<TABLE>
<TR><TD>Date	</TD><TD>Version	</TD><TD>Status	</TD><TD>Description</TD></TR>
<TR><TD>25-10-2001	</TD><TD>0.01	</TD><TD>DRAFTversion	</TD><TD>First draftversion</TD></TR>
<TR><TD>31-10-2001	</TD><TD>0.02	</TD><TD>DRAFTversion	</TD><TD>Updated after review</TD></TR>
<TR><TD>15-11-2001	</TD><TD>0.03	</TD><TD>DRAFTversion	</TD><TD>Updated following small changes after actual implementation</TD></TR>
<TR><TD>23-11-2001	</TD><TD>0.04	</TD><TD>DRAFTversion	</TD><TD>Changes to Security Dialog API - dropped Sign in favour of EstablishSecureConnection</TD></TR>
<TR><TD>21-12-2001	</TD><TD>1.00	</TD><TD>ISSUED	</TD><TD>Issued</TD></TR>
<TR><TD>02-01-2002	</TD><TD>1.01	</TD><TD>PROPOSED	</TD><TD>Extended, converted to Doxygen format and updated to reflect current APIs</TD></TR>
<TR><TD>18-03-2002	</TD><TD>2.00	</TD><TD>ISSUED	</TD><TD>Minor updates</TD></TR>
</TABLE>



 */
/**
   @page cryptotokens_Writing Writing a token type

   A token type is an ECom plugin that represents a particular
   implementation of cryptographic functions, for instance a WIM or a
   particular file-based certificate store. 

   The process of writing one can be divided into the following steps:

   @ref cryptotokens_UIDs

   @ref cryptotokens_Framework

   @ref cryptotokens_Resource

   @ref cryptotokens_TokenType

   @ref cryptotokens_TokenInfo

   @ref cryptotokens_Token

   @ref cryptotokens_Interfaces

 */
/**
   @page cryptotokens_UIDs Understanding the use of UIDs in the framework

   Lots of different things are associated with UIDs. It's important
   to understand what they all are.

   The Token Type base class is an Interface as far as ECom is
   concerned, and has a UID to identify it. This UID is defined by the
   framework, and there's a define for it, CT_INTERFACE_UID. All you
   need to do with this UID is put it in the right place in the
   resource file.

   Each DLL has a UID, just like normal. Your DLL will need one. ECom
   requires your resource file to be named after the UID of the DLL.

   Each Token Type has a UID. It is possible (but unusual) to have several token
   types in 1 DLL, which is why they each need a UID to identify them.

   Each interface and attribute also has a UID to identify
   them. Normaly the interfaces and attributes will have been defined
   as part of the framework, so there will be defines for these
   values.

   Next: @ref cryptotokens_Framework
   Previous: @ref cryptotokens_Writing

  */
/**
   @page cryptotokens_Resource Writing the resource file.

   The resouce file generaly follows the ordinary format of an ECom
   resource file. It must be named after the UID of the
   implementation. The match data is interpreted as a list of UIDs of
   supported interfaces. The Opaque data contains the attributes,
   which are represented as pairs of UIDs and 4 byte values.

   Due to limitations in the format of ECom resource files, these
   resources must be specified as a list of bytes, with the LSB being
   first in each word of 4 bytes. An example is probably needed:
   @code
// 101F4E4e.RSS
//

// This header file contains all the defines you need.
#include "ct/CryptoTokenRegistryInfo.rh"
RESOURCE REGISTRY_INFO theInfo
	{
	// This is the UID of the DLL, and also the name of this file.
	dll_uid = 0x101F4E4e;
	interfaces = 
		{
		INTERFACE_INFO
			{
			// This is the ECom interface ID of all CT Token types
			interface_uid = CT_INTERFACE_UID; 
			implementations = 
				{
				BINARY_IMPLEMENTATION_INFO
					{
					implementation_uid = 0x101f4e4c; // UID of the token type
					version_no = 1; // Version number of this token type
					display_name = "Test Token Type 6"; // Human-readable name
					// Supported interfaces:
					default_data = {0x50, 0x4e, 0x1f, 0x10, // UID 0x101f4e50
									0x51, 0x4e, 0x1f, 0x10, // UID 0x101f4e51
									0x52, 0x4e, 0x1f, 0x10};// UID 0x101f4e52
					opaque_data = {	0x4b, 0x4e, 0x1f, 0x10, // attr 2 UID 0x101f4e4b
									0x02, 0x00, 0x00, 0x00, // attr 2 value (2)
									0x4a, 0x4e, 0x1f, 0x10, // attr 1 UID 0x101f4e4a
									0x01, 0x00, 0x00, 0x00};// attr 1 value (1)
					}

				};
			}
		};
	}

   @endcode

   Next: @ref cryptotokens_TokenType
   Previous: @ref cryptotokens_Resource


 */
/**
   @page cryptotokens_Framework Writing the framework of the DLL and static classes. 

   The DLL must be built with the target type ECOMIIC. This is an
   example of a simple mmp file for a token type DLL:
   @code
TARGET TestPlugin.dll
TARGETTYPE ECOMIIC

// ECom Dll recognition UID followed by the unique UID for this dll
UID 0x10009D8D 0x101F4E4E

SOURCEPATH	.
SOURCE	TestPlugin.cpp

SYSTEMINCLUDE 	\epoc32\include \epoc32\include\ecom

RESOURCE	101F4E4E.rss

LIBRARY euser.lib
LIBRARY ctframework.lib
   @endcode

   The DLL will need an E32Dll function, like any other SymbianOS
   DLL. For instance, in most cases it can look like this:
   @code
GLDEF_C TInt E32Dll(TDllReason)
	{
	return ETrue;
	}
   @endcode

   Then a standard ECom ImplementationTable and
   ImplementationGroupProxy function is needed. Assuming your plugin
   has 1 token type in, it'll look something like this:
   @code
// An array listing the NewL functions of all the plugins. In this
// case, there is only 1. The UID of the token type is 0x101F4E4D.
const TImplementationProxy ImplementationTable[] = 
	{
		{{0x101F4E4D},	CTokenTypeImplementation::NewL},
	};

// This function is needed by ECom. It will probably always look like this.
EXPORT_C const TImplementationProxy* ImplementationGroupProxy(TInt& aTableCount)
	{
	aTableCount = sizeof(ImplementationTable) / sizeof(TImplementationProxy);

	return ImplementationTable;
	}
	@endcode

   Next: @ref cryptotokens_Resource
   Previous: @ref cryptotokens_UIDs

 */
/**
   @page cryptotokens_TokenType Writing the Token Type class

   The token type class needs to implement the CTokenType
   interface. This means it needs to return a list of CTokenInfo
   objects representing every token available, and to open a token
   based on a CTokenInfo object.

   Both the listing of the token infos and opening tokens are
   asynchronous as they may need to talk to slow external tokens such
   as WIMs.

   Next: @ref cryptotokens_TokenInfo
   Previous: @ref cryptotokens_Resource


 */
/**
   @page cryptotokens_TokenInfo Writing the Token Info class

   By default, the CTokenInfo contains just a label, which allows the
   user to identify which token they want to use. You can add other
   data to allow you to identify which token it refers to. If your
   token type only supports 1 token, this class will be very trivial.

   Next: @ref cryptotokens_Token
   Previous: @ref cryptotokens_TokenType

 */
/**
   @page cryptotokens_Token Writing the Token class

   The token is a subclass of MCTToken. You must define the functions
   to create interfaces, and the release function. The client must
   call Release once when it has finished with the token. In addition,
   you may wish to implement a reference counting mechanism so that
   the token object is held open until the Release functions in the
   interfaces are called.

   The token will almost certainly need a pointer to the token type,
   and the interfaces to the token.

   Next: @ref cryptotokens_Interfaces
   Previous: @ref cryptotokens_TokenInfo

 */
/**
   @page cryptotokens_Interfaces Implementing the interfaces

   You now need to implement the interfaces that your token
   supports. How to do this is described in the documentation for each
   interface.

   Contents: @ref cryptotokens_Writing
   
*/
/** @page cryptotokens_refcount The Use of Reference Counting in the framework
The token type counts active references to it. When it is created its reference count is set to 1. Each time it constructs and returns a token it increments its reference count. Its Release decrements the reference count: if the result is zero the token type resources are freed. 

The token counts active references to it. When it is created its reference count is set to 1. Each time it constructs and returns an interface it increments its reference count. Its Release() decrements the reference count: if the result is zero the token's own resources are freed, and the token calls TokenType().Release(), to signal that it no longer needs the token. 

The token interface base class implements its Release() function by calling its DoRelease() function to free its own resources, then calling Token().Release() to signal to the token that it no longer needs it.

This enables application code to create a token type, use it to create a token, then release the token type, then use the token to create an interface, then release the token; it can then, for example, pass the interface to another object without needing to worry about the fate of the token type, or the token. 

The sequence diagram below shows the operation of the reference counting. 

- the application creates a token type, whose reference count is set to 1 (1&2)
- the application uses the token type to create two tokens A and B: each token is created with a reference count of one, and the token type's reference count is incremented each time (7&11) so is now 3
- the application releases the token type, so its reference count is decremented (11 & 12)
- the application opens two interfaces implemented on token A (interfaces 1 & 2); each time the token's reference count is incremented, so is now 3 (14-17)
- the application releases token A, so its reference count is decremented to 2 (18-19)
- this process is repeated for token B (20-28): now we have 1 token type which has generated 2 tokens, each of which has generated 2 interfaces, which hold the only handles to the interfaces. The application can now forget about the ownership of the token types and tokens.
- when the application has finished with the interfaces it releases them. When each interface is released it releases the token hosting it, which decrements the reference count. When all the interfaces hosted by a token have released the token the reference count is zero and the token cleans up its own resources and releases the token type When both tokens have released the token type its own reference count is zero, so it frees its own resources.
@image html sequence.bmp "Reference Counting Sequence Diagram"
*/
