7 Nokia Corporation - initial contribution. |
7 Nokia Corporation - initial contribution. |
8 Contributors: |
8 Contributors: |
9 --> |
9 --> |
10 <!DOCTYPE concept |
10 <!DOCTYPE concept |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
11 PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd"> |
12 <concept xml:lang="en" id="GUID-0F4DE9E0-4A98-5914-9AB1-DD6CE1A5A1F3"><title>Unified Stores Overview </title><prolog><metadata><keywords/></metadata></prolog><conbody><p>A Symbian platform device may contain zero or more individual certificate stores, and zero or more key stores. Software implementations for both of these are supplied, and device creators may add their own, perhaps using special hardware on the device - for example, using a WIM. The certificate store and key store classes act as central interfaces for certificate and key management, so that application writers do not need to know details of the specific implementations present. These classes automatically discover all implementations of the relevant interface on the device using the crypto token framework. </p> <p>The certificate and key stores centralize and amalgamate the individual certstore and keystore implementations. The stores are unified in the sense that client requests, which relate to all store implementations (such as "list keys" or "list certificates"), are passed to every implementation in turn, and the results collated. Requests that relate to a specific store are routed to the correct implementation. </p> <p>Clients should only use the certificate store and key store classes to access certificates and keys. There is no need to use the crypto token framework directly, and although this is possible, it is not recommended. </p> <section><title>Programming with the Certificate Store and the Key |
12 <concept id="GUID-0F4DE9E0-4A98-5914-9AB1-DD6CE1A5A1F3" xml:lang="en"><title>Unified |
13 Store</title> <p>The ctframework component provides the interfaces for key store and certificate store implementations, and the unified stores themselves are implemented in Certificate Management's (certman's) certstore component. Programs wishing to use the unified stores should therefore be linked against both <codeph>certstore.lib</codeph> and <codeph>ctframework.lib</codeph>. Note that <codeph>certstore.lib</codeph> provides both the <xref href="GUID-0010EB39-8C23-5453-BE96-4EFC520B6F81.dita">unified certificate store</xref> and the <xref href="GUID-695FCEB8-EA04-5C1C-A197-648275BA0281.dita">unified key store</xref>. </p> <p>The software certificate store implementation supplied with Symbian platform is provided by <codeph>filecertstore.dll</codeph>, and this runs entirely in the client application. The software key store runs in a separate server process - this is implemented by <codeph>fstokenserver.exe</codeph>, and the client side part that communicates with the server is provided by <codeph>fstokencli.dll</codeph>. The unified stores use the ECom framework to load these DLLs automatically, so there is no need to link against them in client applications. </p> <p>Within the header files for the Unified Certificate Store and the Unified Key Store, most of the functions are asynchronous and this means that clients need to be implemented as active objects to work. All calls to asynchronous functions must be called from the context of active objects - the active scheduler will call the client's <codeph>RunL()</codeph> function when the asynchronous function completes. </p> <p>This means that the following code will not work: </p> <codeblock id="GUID-6D87CFA3-44ED-5B24-B17C-6A5A77854688" xml:space="preserve"> |
13 Stores Overview </title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>A Symbian platform device may contain zero or more individual certificate |
|
15 stores, and zero or more key stores. Software implementations for both of |
|
16 these are supplied, and device creators may add their own, perhaps using special |
|
17 hardware on the device - for example, using a WIM. The certificate store and |
|
18 key store classes act as central interfaces for certificate and key management, |
|
19 so that application writers do not need to know details of the specific implementations |
|
20 present. These classes automatically discover all implementations of the relevant |
|
21 interface on the device using the crypto token framework. </p> |
|
22 <p>The certificate and key stores centralize and amalgamate the individual |
|
23 certstore and keystore implementations. The stores are unified in the sense |
|
24 that client requests, which relate to all store implementations (such as "list |
|
25 keys" or "list certificates"), are passed to every implementation in turn, |
|
26 and the results collated. Requests that relate to a specific store are routed |
|
27 to the correct implementation. </p> |
|
28 <p>Clients should only use the certificate store and key store classes to |
|
29 access certificates and keys. There is no need to use the crypto token framework |
|
30 directly, and although this is possible, it is not recommended. </p> |
|
31 <section id="GUID-490A4096-02BF-47F9-B630-3E5CE07E43AD"><title>Programming with the Certificate Store and the Key |
|
32 Store</title> <p>The ctframework component provides the interfaces for |
|
33 key store and certificate store implementations, and the unified stores themselves |
|
34 are implemented in Certificate Management's (certman's) certstore component. |
|
35 Programs wishing to use the unified stores should therefore be linked against |
|
36 both <codeph>certstore.lib</codeph> and <codeph>ctframework.lib</codeph>. |
|
37 Note that <codeph>certstore.lib</codeph> provides both the <xref href="GUID-0010EB39-8C23-5453-BE96-4EFC520B6F81.dita">unified |
|
38 certificate store</xref> and the <xref href="GUID-695FCEB8-EA04-5C1C-A197-648275BA0281.dita">unified |
|
39 key store</xref>. </p> <p>The software certificate store implementation supplied |
|
40 with the Symbian platform is provided by <codeph>filecertstore.dll</codeph>, |
|
41 and this runs entirely in the client application. The software key store runs |
|
42 in a separate server process - this is implemented by <codeph>fstokenserver.exe</codeph>, |
|
43 and the client side part that communicates with the server is provided by <codeph>fstokencli.dll</codeph>. |
|
44 The unified stores use the ECom framework to load these DLLs automatically, |
|
45 so there is no need to link against them in client applications. </p> <p>Within |
|
46 the header files for the Unified Certificate Store and the Unified Key Store, |
|
47 most of the functions are asynchronous and this means that clients need to |
|
48 be implemented as active objects to work. All calls to asynchronous functions |
|
49 must be called from the context of active objects - the active scheduler will |
|
50 call the client's <codeph>RunL()</codeph> function when the asynchronous function |
|
51 completes. </p> <p>This means that the following code will not work: </p> <codeblock id="GUID-6D87CFA3-44ED-5B24-B17C-6A5A77854688" xml:space="preserve"> |
14 // Broken! |
52 // Broken! |
15 TRequestStatus status; |
53 TRequestStatus status; |
16 certStore->DoSomething(parameters, status); |
54 certStore->DoSomething(parameters, status); |
17 User::WaitForRequest(&status); |
55 User::WaitForRequest(&status); |
18 </codeblock> </section> <section><title>APIs</title> <p>The following table provides information on the APIs for the unified certificate store and the unified key store. </p> <table id="GUID-09857F72-9410-5F5A-BE8E-61D5BD04D01D"><tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/><thead><row><entry>API</entry> <entry>Description</entry> </row> </thead> <tbody><row><entry><p> <xref href="GUID-AD63C29A-17C3-375C-840F-42A92422300D.dita"><apiname>CUnifiedCertStore</apiname></xref> </p> </entry> <entry><p>This class provides a unified view of all the certificate store implementations in the device. </p> </entry> </row> <row><entry><p> <xref href="GUID-818689D6-EB99-382E-A435-D9C6C5D464DE.dita"><apiname>CUnifiedKeyStore</apiname></xref> </p> </entry> <entry><p>This class provides a unified view of all the certificate store implementations in the device. </p> </entry> </row> </tbody> </tgroup> </table> </section> </conbody></concept> |
56 </codeblock> </section> |
|
57 <section id="GUID-92B8798E-3963-49C9-8994-60CDAC33AC74"><title>APIs</title> <p>The following table provides information on |
|
58 the APIs for the unified certificate store and the unified key store. </p> <table id="GUID-09857F72-9410-5F5A-BE8E-61D5BD04D01D"> |
|
59 <tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/> |
|
60 <thead> |
|
61 <row> |
|
62 <entry>API</entry> |
|
63 <entry>Description</entry> |
|
64 </row> |
|
65 </thead> |
|
66 <tbody> |
|
67 <row> |
|
68 <entry><p> <xref href="GUID-AD63C29A-17C3-375C-840F-42A92422300D.dita"><apiname>CUnifiedCertStore</apiname></xref> </p> </entry> |
|
69 <entry><p>This class provides a unified view of all the certificate store |
|
70 implementations in the device. </p> </entry> |
|
71 </row> |
|
72 <row> |
|
73 <entry><p> <xref href="GUID-818689D6-EB99-382E-A435-D9C6C5D464DE.dita"><apiname>CUnifiedKeyStore</apiname></xref> </p> </entry> |
|
74 <entry><p>This class provides a unified view of all the certificate store |
|
75 implementations in the device. </p> </entry> |
|
76 </row> |
|
77 </tbody> |
|
78 </tgroup> |
|
79 </table> </section> |
|
80 </conbody></concept> |