/**

   @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"

*/