1 <?xml version="1.0" encoding="utf-8"?>

     2 <!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

     3 <!-- This component and the accompanying materials are made available under the terms of the License 

     4 "Eclipse Public License v1.0" which accompanies this distribution, 

     5 and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

    11   PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

    12 <concept id="GUID-0F4DE9E0-4A98-5914-9AB1-DD6CE1A5A1F3" xml:lang="en"><title>Unified

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

    52 // Broken!

    53 TRequestStatus status;

    54 certStore->DoSomething(parameters, status);

    55 User::WaitForRequest(&status);

    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>