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