|
1 /** |
|
2 @page page_cryptotoken_framework Cryptographic token framework |
|
3 |
|
4 @section cryptotokens_pas Purpose and scope |
|
5 This document specifies the APIs which we will define as specified in the Hurricane Security Framework Functional Specification [1]. |
|
6 |
|
7 This document assumes familiarity with the functional specification. |
|
8 |
|
9 The API definitions are organised into 4 sections: |
|
10 - @ref ct |
|
11 - @ref interfaces |
|
12 - @ref secdlg |
|
13 - @ref Securitydefs |
|
14 |
|
15 In addition, a guide to writing tokens is provided: @ref cryptotokens_Writing |
|
16 |
|
17 And a guide to the use of reference counting:@ref cryptotokens_refcount |
|
18 |
|
19 @section cryptotokens_notes General Notes |
|
20 |
|
21 - Clients of the Crypto Token Framework must use an active |
|
22 scheduler. Crypto tokens may assume that an active scheduler is |
|
23 present. |
|
24 |
|
25 @subsection cryptotokens_refs References |
|
26 All Documents can be found in <code>\\\\Londata04\\Psisoft\\Dev\\GT\\0128 Hurricane WAP</code> unless otherwise stated. |
|
27 |
|
28 -# Hurricane Security Framework Functional Specification, "HSF FS.doc" |
|
29 -# Certificate Management(Hurricane) Functional Specification |
|
30 |
|
31 @section cryptotokens_tsecdlg The dummy security dialog notifier |
|
32 |
|
33 See @ref cryptotokens_TSecdlg |
|
34 |
|
35 @section cryptotokens_revs Revision History |
|
36 <TABLE> |
|
37 <TR><TD>Date </TD><TD>Version </TD><TD>Status </TD><TD>Description</TD></TR> |
|
38 <TR><TD>25-10-2001 </TD><TD>0.01 </TD><TD>DRAFTversion </TD><TD>First draftversion</TD></TR> |
|
39 <TR><TD>31-10-2001 </TD><TD>0.02 </TD><TD>DRAFTversion </TD><TD>Updated after review</TD></TR> |
|
40 <TR><TD>15-11-2001 </TD><TD>0.03 </TD><TD>DRAFTversion </TD><TD>Updated following small changes after actual implementation</TD></TR> |
|
41 <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> |
|
42 <TR><TD>21-12-2001 </TD><TD>1.00 </TD><TD>ISSUED </TD><TD>Issued</TD></TR> |
|
43 <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> |
|
44 <TR><TD>18-03-2002 </TD><TD>2.00 </TD><TD>ISSUED </TD><TD>Minor updates</TD></TR> |
|
45 </TABLE> |
|
46 |
|
47 |
|
48 |
|
49 */ |
|
50 /** |
|
51 @page cryptotokens_Writing Writing a token type |
|
52 |
|
53 A token type is an ECom plugin that represents a particular |
|
54 implementation of cryptographic functions, for instance a WIM or a |
|
55 particular file-based certificate store. |
|
56 |
|
57 The process of writing one can be divided into the following steps: |
|
58 |
|
59 @ref cryptotokens_UIDs |
|
60 |
|
61 @ref cryptotokens_Framework |
|
62 |
|
63 @ref cryptotokens_Resource |
|
64 |
|
65 @ref cryptotokens_TokenType |
|
66 |
|
67 @ref cryptotokens_TokenInfo |
|
68 |
|
69 @ref cryptotokens_Token |
|
70 |
|
71 @ref cryptotokens_Interfaces |
|
72 |
|
73 */ |
|
74 /** |
|
75 @page cryptotokens_UIDs Understanding the use of UIDs in the framework |
|
76 |
|
77 Lots of different things are associated with UIDs. It's important |
|
78 to understand what they all are. |
|
79 |
|
80 The Token Type base class is an Interface as far as ECom is |
|
81 concerned, and has a UID to identify it. This UID is defined by the |
|
82 framework, and there's a define for it, CT_INTERFACE_UID. All you |
|
83 need to do with this UID is put it in the right place in the |
|
84 resource file. |
|
85 |
|
86 Each DLL has a UID, just like normal. Your DLL will need one. ECom |
|
87 requires your resource file to be named after the UID of the DLL. |
|
88 |
|
89 Each Token Type has a UID. It is possible (but unusual) to have several token |
|
90 types in 1 DLL, which is why they each need a UID to identify them. |
|
91 |
|
92 Each interface and attribute also has a UID to identify |
|
93 them. Normaly the interfaces and attributes will have been defined |
|
94 as part of the framework, so there will be defines for these |
|
95 values. |
|
96 |
|
97 Next: @ref cryptotokens_Framework |
|
98 Previous: @ref cryptotokens_Writing |
|
99 |
|
100 */ |
|
101 /** |
|
102 @page cryptotokens_Resource Writing the resource file. |
|
103 |
|
104 The resouce file generaly follows the ordinary format of an ECom |
|
105 resource file. It must be named after the UID of the |
|
106 implementation. The match data is interpreted as a list of UIDs of |
|
107 supported interfaces. The Opaque data contains the attributes, |
|
108 which are represented as pairs of UIDs and 4 byte values. |
|
109 |
|
110 Due to limitations in the format of ECom resource files, these |
|
111 resources must be specified as a list of bytes, with the LSB being |
|
112 first in each word of 4 bytes. An example is probably needed: |
|
113 @code |
|
114 // 101F4E4e.RSS |
|
115 // |
|
116 |
|
117 // This header file contains all the defines you need. |
|
118 #include "ct/CryptoTokenRegistryInfo.rh" |
|
119 RESOURCE REGISTRY_INFO theInfo |
|
120 { |
|
121 // This is the UID of the DLL, and also the name of this file. |
|
122 dll_uid = 0x101F4E4e; |
|
123 interfaces = |
|
124 { |
|
125 INTERFACE_INFO |
|
126 { |
|
127 // This is the ECom interface ID of all CT Token types |
|
128 interface_uid = CT_INTERFACE_UID; |
|
129 implementations = |
|
130 { |
|
131 BINARY_IMPLEMENTATION_INFO |
|
132 { |
|
133 implementation_uid = 0x101f4e4c; // UID of the token type |
|
134 version_no = 1; // Version number of this token type |
|
135 display_name = "Test Token Type 6"; // Human-readable name |
|
136 // Supported interfaces: |
|
137 default_data = {0x50, 0x4e, 0x1f, 0x10, // UID 0x101f4e50 |
|
138 0x51, 0x4e, 0x1f, 0x10, // UID 0x101f4e51 |
|
139 0x52, 0x4e, 0x1f, 0x10};// UID 0x101f4e52 |
|
140 opaque_data = { 0x4b, 0x4e, 0x1f, 0x10, // attr 2 UID 0x101f4e4b |
|
141 0x02, 0x00, 0x00, 0x00, // attr 2 value (2) |
|
142 0x4a, 0x4e, 0x1f, 0x10, // attr 1 UID 0x101f4e4a |
|
143 0x01, 0x00, 0x00, 0x00};// attr 1 value (1) |
|
144 } |
|
145 |
|
146 }; |
|
147 } |
|
148 }; |
|
149 } |
|
150 |
|
151 @endcode |
|
152 |
|
153 Next: @ref cryptotokens_TokenType |
|
154 Previous: @ref cryptotokens_Resource |
|
155 |
|
156 |
|
157 */ |
|
158 /** |
|
159 @page cryptotokens_Framework Writing the framework of the DLL and static classes. |
|
160 |
|
161 The DLL must be built with the target type ECOMIIC. This is an |
|
162 example of a simple mmp file for a token type DLL: |
|
163 @code |
|
164 TARGET TestPlugin.dll |
|
165 TARGETTYPE ECOMIIC |
|
166 |
|
167 // ECom Dll recognition UID followed by the unique UID for this dll |
|
168 UID 0x10009D8D 0x101F4E4E |
|
169 |
|
170 SOURCEPATH . |
|
171 SOURCE TestPlugin.cpp |
|
172 |
|
173 SYSTEMINCLUDE \epoc32\include \epoc32\include\ecom |
|
174 |
|
175 RESOURCE 101F4E4E.rss |
|
176 |
|
177 LIBRARY euser.lib |
|
178 LIBRARY ctframework.lib |
|
179 @endcode |
|
180 |
|
181 The DLL will need an E32Dll function, like any other SymbianOS |
|
182 DLL. For instance, in most cases it can look like this: |
|
183 @code |
|
184 GLDEF_C TInt E32Dll(TDllReason) |
|
185 { |
|
186 return ETrue; |
|
187 } |
|
188 @endcode |
|
189 |
|
190 Then a standard ECom ImplementationTable and |
|
191 ImplementationGroupProxy function is needed. Assuming your plugin |
|
192 has 1 token type in, it'll look something like this: |
|
193 @code |
|
194 // An array listing the NewL functions of all the plugins. In this |
|
195 // case, there is only 1. The UID of the token type is 0x101F4E4D. |
|
196 const TImplementationProxy ImplementationTable[] = |
|
197 { |
|
198 {{0x101F4E4D}, CTokenTypeImplementation::NewL}, |
|
199 }; |
|
200 |
|
201 // This function is needed by ECom. It will probably always look like this. |
|
202 EXPORT_C const TImplementationProxy* ImplementationGroupProxy(TInt& aTableCount) |
|
203 { |
|
204 aTableCount = sizeof(ImplementationTable) / sizeof(TImplementationProxy); |
|
205 |
|
206 return ImplementationTable; |
|
207 } |
|
208 @endcode |
|
209 |
|
210 Next: @ref cryptotokens_Resource |
|
211 Previous: @ref cryptotokens_UIDs |
|
212 |
|
213 */ |
|
214 /** |
|
215 @page cryptotokens_TokenType Writing the Token Type class |
|
216 |
|
217 The token type class needs to implement the CTokenType |
|
218 interface. This means it needs to return a list of CTokenInfo |
|
219 objects representing every token available, and to open a token |
|
220 based on a CTokenInfo object. |
|
221 |
|
222 Both the listing of the token infos and opening tokens are |
|
223 asynchronous as they may need to talk to slow external tokens such |
|
224 as WIMs. |
|
225 |
|
226 Next: @ref cryptotokens_TokenInfo |
|
227 Previous: @ref cryptotokens_Resource |
|
228 |
|
229 |
|
230 */ |
|
231 /** |
|
232 @page cryptotokens_TokenInfo Writing the Token Info class |
|
233 |
|
234 By default, the CTokenInfo contains just a label, which allows the |
|
235 user to identify which token they want to use. You can add other |
|
236 data to allow you to identify which token it refers to. If your |
|
237 token type only supports 1 token, this class will be very trivial. |
|
238 |
|
239 Next: @ref cryptotokens_Token |
|
240 Previous: @ref cryptotokens_TokenType |
|
241 |
|
242 */ |
|
243 /** |
|
244 @page cryptotokens_Token Writing the Token class |
|
245 |
|
246 The token is a subclass of MCTToken. You must define the functions |
|
247 to create interfaces, and the release function. The client must |
|
248 call Release once when it has finished with the token. In addition, |
|
249 you may wish to implement a reference counting mechanism so that |
|
250 the token object is held open until the Release functions in the |
|
251 interfaces are called. |
|
252 |
|
253 The token will almost certainly need a pointer to the token type, |
|
254 and the interfaces to the token. |
|
255 |
|
256 Next: @ref cryptotokens_Interfaces |
|
257 Previous: @ref cryptotokens_TokenInfo |
|
258 |
|
259 */ |
|
260 /** |
|
261 @page cryptotokens_Interfaces Implementing the interfaces |
|
262 |
|
263 You now need to implement the interfaces that your token |
|
264 supports. How to do this is described in the documentation for each |
|
265 interface. |
|
266 |
|
267 Contents: @ref cryptotokens_Writing |
|
268 |
|
269 */ |
|
270 /** @page cryptotokens_refcount The Use of Reference Counting in the framework |
|
271 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. |
|
272 |
|
273 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. |
|
274 |
|
275 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. |
|
276 |
|
277 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. |
|
278 |
|
279 The sequence diagram below shows the operation of the reference counting. |
|
280 |
|
281 - the application creates a token type, whose reference count is set to 1 (1&2) |
|
282 - 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 |
|
283 - the application releases the token type, so its reference count is decremented (11 & 12) |
|
284 - 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) |
|
285 - the application releases token A, so its reference count is decremented to 2 (18-19) |
|
286 - 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. |
|
287 - 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. |
|
288 @image html sequence.bmp "Reference Counting Sequence Diagram" |
|
289 */ |