/**+
−
   @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"+
−
*/+
−