<?xml version="1.0" encoding="utf-8"?>
<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->
<!-- This component and the accompanying materials are made available under the terms of the License 
"Eclipse Public License v1.0" which accompanies this distribution, 
and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->
<!-- Initial Contributors:
    Nokia Corporation - initial contribution.
Contributors: 
-->
<!DOCTYPE concept
  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">
<concept id="GUID-AE96F25E-45A2-5C00-9F27-BB3E17C8E6E5" xml:lang="en"><title>Certificate
and Key Management Overview</title><abstract><p>The Certificate and Key Management component provides authentication
services for <xref href="GUID-FB2CAA46-8EBB-5F76-847C-F3B953C9D31C.dita">Public
Key Cryptography</xref>.</p></abstract><prolog><metadata><keywords/></metadata></prolog><conbody>
<section><title>Purpose</title> <p>The main purpose of the Certificate and
Key Management component is to provide validation services according to the
Public Key Infrastructure (PKI) for <xref href="GUID-C676C4E6-93AF-59E9-886D-74D59F154490.dita">X.509</xref> Certificates. </p> <p>The
Certificate and Key Management component provides interfaces for the following: </p> <ul>
<li id="GUID-A3109F52-09A5-5ACD-9844-883EB9E6E37B"><p>Storage and retrieval
of certificates </p> </li>
<li id="GUID-27F48C66-606E-594D-A1E0-8E1B7C048C6B"><p>Assignment of trust
status to a certificate on an application-by-application basis </p> </li>
<li id="GUID-CF4BAB94-8FC1-5375-BDA6-1DA46DF3F68B"><p>Certificate chain construction
and validation </p> </li>
<li id="GUID-C44175FE-15D6-5145-8F73-CAC7F10A506A"><p>Verification of trust
of a certificate </p> </li>
<li id="GUID-EFDD6039-5F57-5F41-B90C-2776B247F659"><p>Generation of asymmetric
key pairs </p> </li>
<li id="GUID-AB119A48-43E3-5C5F-80B6-F1A92E9B6531"><p>Protected storage of
keys </p> </li>
<li id="GUID-14E232E1-73F1-58EE-A435-53B3D46680D4"><p>Key import and export </p> </li>
<li id="GUID-21FCB8AB-8399-50E3-847A-53DF092BBA25"><p>Authenticated execution
of private key operations </p> </li>
</ul> </section>
<section><title>Required background</title> <p>To understand Certificate and
Key Management in detail, you need to have a basic understanding of the following: </p> <ul>
<li id="GUID-1A307F21-3BBF-525D-98B1-3AC2035786EC"><p><xref href="GUID-FB2CAA46-8EBB-5F76-847C-F3B953C9D31C.dita">Public
Key Cryptography</xref>  </p> </li>
<li id="GUID-0EA3DF92-DFE8-5265-97F6-862D5198E9FF"><p><xref href="GUID-911E9F7E-D0AD-55EC-A3F4-1D427F803780.dita">Certificates</xref>  </p> </li>
<li id="GUID-0D2E1131-4C60-56CB-BCDD-432AC5F660F1"><p><xref href="GUID-5C58F7D1-D672-5B6D-AD48-863EC68F7446.dita">Digital
Signatures</xref>  </p> </li>
</ul> </section>
<section><title>Key concepts and terms</title> <dl>
<dlentry>
<dt>Certificate</dt>
<dd><p>A certificate is an electronic document that binds an identity to a
particular public or private key pair. It is commonly used to authenticate
cryptographic public keys. </p> <p>Certificates are issued by a Certification
Authority (CA). They usually include information such as a label, serial number,
validity period, certificate format (for example, X.509) and algorithm type
(for example, MD2RSA). </p> </dd>
</dlentry>
<dlentry>
<dt>Key</dt>
<dd><p>A cryptography key is a constant value applied using a cryptographic
algorithm to encrypt text or to decrypt encrypted text. </p> <p>Keys are classified
as symmetric and asymmetric based on the type of algorithm applied. If the
same key is used for both encryption and decryption, it is symmetric. If different
keys are used for encryption and decryption, they are asymmetric. Asymmetric
keys exist in the form of a public and private key pair, where the public
key is used for encryption and the private key is used for decryption. </p> </dd>
</dlentry>
<dlentry>
<dt>Certificate Store</dt>
<dd><p>A certificate store is a database or a file that stores and manipulates
certificates. </p> <p>The certificate store provides the following functionality: </p> <ul>
<li id="GUID-4FABC2C2-8133-5398-9747-0A247344A52C"><p>Generation, storage
and retrieval certificates </p> </li>
<li id="GUID-F527AAE6-DCDE-5ECC-AB89-1299DC0800A4"><p>Assignment of trust
status to certificates </p> </li>
<li id="GUID-BA60380A-BAC7-59D4-BD7E-5C28ED24921A"><p>Retrieval of list of
applications trusting a certificate </p> </li>
</ul> </dd>
</dlentry>
<dlentry>
<dt>Key Store</dt>
<dd><p>A key store is a repository of keys that can be retrieved and used
to accomplish a variety of tasks. </p> <p>The key store provides the following
functionality: </p> <ul>
<li id="GUID-F5BC1B3C-B400-5392-A68C-ACDB84ABACFC"><p>Generation, import and
export of RSA, DSA, and DH key pairs </p> </li>
<li id="GUID-4A5C1491-C922-5C00-94D6-0E9E05310102"><p>Listing of stored keys </p> </li>
<li id="GUID-1F7B3427-3EB7-5411-A30C-0BB749C1EE73"><p>Authentication of users </p> </li>
<li id="GUID-2DB4F4DF-BB77-5B7F-A724-BBAE21D5B4F4"><p>Private key operations
for authenticated users </p> </li>
</ul> </dd>
</dlentry>
<dlentry>
<dt>Token</dt>
<dd><p>A token is a physical instantiation of an object, such as a certificate
or a key, stored in a phone. Each token belongs to a group of tokens called
a token type. For example, an X.509 certificate is a token which belongs to
the X.509 token type. </p> </dd>
</dlentry>
</dl> </section>
<section><title>Architecture</title> <p>The following diagram shows the basic
architecture of the Certificate and Key Management component. The blocks in
blue are internal to the component. </p> <fig id="GUID-4532D14E-A9FE-595C-8B75-4FA2AE57B8EA">
<image href="GUID-5BB017AA-46AE-5461-9184-98CE7FA898B9_d0e370068_href.jpg" placement="inline"/>
</fig> <p>The various blocks in the basic architecture diagram of the Certificate
and Key Management component are explained as follows: </p> <ul>
<li id="GUID-0FCBBCA0-CD31-51AB-84D1-93994EAC54E2"><p> <b>Client Application</b>:
This is a typical application that accesses the certificates or the keys of
the device through Certificate and Key Management component. </p> <p>For example,
a web browser that wishes to load a bank's web page to perform a money-transfer
operation (in a secured mode using an <codeph>https</codeph> connection) first
checks the device's certificate store for a certificate that trusts the bank's
server and then loads the particular page. </p> </li>
<li id="GUID-B649A55C-7446-56D8-85FB-98AB4879B8CE"><p> <b>Unified Stores</b>:
The <xref href="GUID-39B459CD-8210-59B5-95F4-85CE36676735.dita">Unified Stores</xref> APIs
form the primary access point for client applications to use certificates
or keys stored in the device. The <xref href="GUID-0010EB39-8C23-5453-BE96-4EFC520B6F81.dita">Unified
Certificate Store</xref> provides a unified view of all the certificates in
the device while the <xref href="GUID-695FCEB8-EA04-5C1C-A197-648275BA0281.dita">Unified
Key Store</xref> provides a similar view of all the keys in the device. </p> </li>
<li id="GUID-0A28DE19-3E16-5094-9964-32BE1BF50107"><p> <b>Generic Certificate
and Key Stores</b>: These are the various certificate and key stores in the
device. </p> </li>
<li id="GUID-197709E0-7811-55F1-9EA9-7D80389B3D0A"><p> <b>File-Based Store
Implementation</b>: The certificate and key stores use Symbian's <xref href="GUID-C7150120-74C2-5FF1-99F0-0A267393E342.dita">file-based
store implementation</xref>. Based on the operations to be performed on the
keys and certificates, the file-based implementation updates the physical
certificate and key store files. </p> </li>
</ul> </section>
<section><title>APIs</title> <p>The following table lists the key APIs of
the Certificate and Key Management component. The table lists APIs that perform
the following tasks: </p> <ul>
<li id="GUID-F6DF549D-F1B7-5662-AC36-50453FB56E02"><p>Provide implementation
for certificate and key stores, and for manipulating various types of certificates. </p> </li>
<li id="GUID-47864D9B-97A7-596F-9638-978E236212DE"><p>Perform different types
of ASN.1 (Abstract Syntax Notation One) encoding. </p> </li>
</ul> <table id="GUID-C78DF93D-7684-52FB-BA00-3A060789E26B">
<tgroup cols="2"><colspec colname="col0"/><colspec colname="col1"/>
<thead>
<row>
<entry>API</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><p> <b>Unified Store APIs</b>  </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-AD63C29A-17C3-375C-840F-42A92422300D.dita"><apiname>CUnifiedCertStore</apiname></xref>  </p> </entry>
<entry><p>Provides a common implementation for all certificate stores 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>Provides a common implementation for all key stores in the device. </p> </entry>
</row>
<row>
<entry><p> <b>Certificate APIs</b>  </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-4C645733-8F0C-3AC8-A19E-0AB005F4CE7F.dita"><apiname>CX500DistinguishedName</apiname></xref>  </p> </entry>
<entry><p>Provides implementation for parsing and matching the <xref href="GUID-C93D021E-D99A-5839-AB54-3D8D7620214A.dita">X.500</xref> distinguished
names. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-21954042-44FA-3376-A4C1-D7DE560144C8.dita"><apiname>CX520AttributeTypeAndValue</apiname></xref>  </p> </entry>
<entry><p>Provides implementation for parsing and matching attribute types
and values, as defined by the X.520 standard. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-1309FCDC-229B-36C7-85A9-4540ABC869F9.dita"><apiname>CX509GeneralName</apiname></xref>  </p> </entry>
<entry><p>Provides implementation for manipulation of X.509 certificates. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-A919BE84-8257-3911-9AD1-B1DB736346CE.dita"><apiname>CX509CertChain</apiname></xref>  </p> </entry>
<entry><p>Provides implementation for X.509 certificate chain validation. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-A9B59AEF-C278-3E20-A57B-15293F833A71.dita"><apiname>CX509RSAPublicKey</apiname></xref>  </p> </entry>
<entry><p>Provides APIs for encoding and decoding of RSA public keys. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-9AD19EB1-44D4-339A-A30A-2B43817DB2CB.dita"><apiname>CX509ExtensionBase</apiname></xref>  </p> </entry>
<entry><p>Provides APIs for manipulating various X.509 certificate extensions. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-3E94241B-3B37-3C64-8CFF-7795063160AF.dita"><apiname>CWTLSCertificate</apiname></xref>  </p> </entry>
<entry><p>Provides implementation for construction and manipulation of <xref href="GUID-A636C1B3-8AB2-52D7-BB19-4CC93F4BDD97.dita">WTLS</xref> (Wireless Transport
Layer Security) certificates. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-04C4024C-2987-37F9-8D85-ACCB3D4C1293.dita"><apiname>CWTLSName</apiname></xref>  </p> </entry>
<entry><p>Provides implementation for manipulation of WTLS names. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-A8600958-D424-366C-A56D-68A77949EA28.dita"><apiname>CWTLSRSAPublicKey</apiname></xref>  </p> </entry>
<entry><p>Provides implementation for manipulation of RSA public keys associated
with WTLS certificates. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-56E949D5-EA4F-361C-8523-2965A336B009.dita"><apiname>CWTLSCertChain</apiname></xref>  </p> </entry>
<entry><p>Provides implementation for validation of WTLS certificate chains. </p> </entry>
</row>
<row>
<entry><p> <b>ASN.1 Encoding APIs</b>  </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-1EBCC3C4-3E57-3424-BB41-E74E8120197E.dita"><apiname>CASN1EncBigInt</apiname></xref>  </p> </entry>
<entry><p>Encodes Big Integer objects. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-6B9883C8-9382-3941-A949-3D8E2B7C7EA5.dita"><apiname>CASN1EncBitString</apiname></xref>  </p> </entry>
<entry><p>Encodes bit strings (for example, keys). </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-DE64C76D-D70B-36DC-826C-1662CFBD26D4.dita"><apiname>CASN1EncBoolean</apiname></xref>  </p> </entry>
<entry><p>Encodes Boolean values. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-1E9BA30C-729E-3C49-8DB4-5D693EF2C84E.dita"><apiname>CASN1EncEncoding</apiname></xref>  </p> </entry>
<entry><p>Encapsulates already encoded information. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-964E6C04-4AE0-3085-AF0A-6580264AEF36.dita"><apiname>CASN1EncExplicitTag</apiname></xref>  </p> </entry>
<entry><p>Wraps other encoding objects and provides them with an explicit
tag. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-523EA13D-42F1-31DE-95F2-91AC56C58B62.dita"><apiname>CASN1EncGeneralizedTime</apiname></xref>  </p> </entry>
<entry><p>Encodes time-related objects. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-B4839A2D-E3C1-3405-8776-38A3F5D47FD3.dita"><apiname>CASN1EncInt</apiname></xref>  </p> </entry>
<entry><p>Encodes <codeph>TInt</codeph> objects. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-1ED494A4-503F-3651-946E-E99771348EF6.dita"><apiname>CASN1EncNull</apiname></xref>  </p> </entry>
<entry><p>Encodes NULL values. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-45B0317A-CBB5-369E-877B-C166F9BAE3DF.dita"><apiname>CASN1EncObjectIdentifier</apiname></xref>  </p> </entry>
<entry><p>Encodes object identifiers. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-4170E6D8-A1A5-3E84-B12D-D737CEC0A698.dita"><apiname>CASN1EncOctetString</apiname></xref>  </p> </entry>
<entry><p>Encodes octet strings. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-1B53FA4B-3D36-38AF-97CE-6BA64E9520F3.dita"><apiname>CASN1EncPrimitive</apiname></xref>  </p> </entry>
<entry><p>All ASN.1 primitive type encoding classes derive from this class. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-22AC4FE1-1EB4-341C-9CF8-F153F0346858.dita"><apiname>CASN1EncPrintableString</apiname></xref>  </p> </entry>
<entry><p>Encodes printable strings. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-A0846E03-BC80-3549-B59D-A0F2230E9AC9.dita"><apiname>CASN1EncSequence</apiname></xref>  </p> </entry>
<entry><p>Encodes the <xref href="http://www.asn1.org/books/Explain.html" scope="external">SEQUENCE</xref> and <xref href="http://www.asn1.org/books/Explain.html" scope="external">SEQUENCE-OF</xref> data types. </p> </entry>
</row>
<row>
<entry><p> <xref href="GUID-98D3BDD5-8136-3C66-8381-73E0A8EE910E.dita"><apiname>CASN1EncSet</apiname></xref>  </p> </entry>
<entry><p>Encodes the <xref href="http://www.asn1.org/books/Explain.html" scope="external">SET</xref> and <xref href="http://www.asn1.org/books/Explain.html" scope="external">SET-OF</xref> data types. </p> </entry>
</row>
</tbody>
</tgroup>
</table> </section>
<section><title>Typical uses</title> <p>The Certificate and Key Management
component performs the following tasks: </p> <ul>
<li id="GUID-1C7ED95B-442D-5D05-8E20-95B0F3E17438"><p>Validating certificates
in PKIX </p> </li>
<li id="GUID-8D85F504-F3AB-545E-8FF1-3F6FCEC0D5E8"><p>Adding certificates </p> </li>
<li id="GUID-AC9BF0B0-1A1B-5995-A443-F4E21123CE56"><p>Finding certificates </p> </li>
<li id="GUID-24C041AA-A7BF-5887-B993-E1EA5BA35B66"><p>Managing applicability
and trust settings </p> </li>
<li id="GUID-1FC9F3D9-69C5-56E1-99F6-31B36644B42D"><p>Removing certificates </p> </li>
<li id="GUID-2923D772-0455-5B9A-BD9E-0CC20678A729"><p>Retrieving certificates </p> </li>
<li id="GUID-B1BEDD53-5309-529F-B29A-C42D62ABCC3E"><p>Creating keys </p> </li>
<li id="GUID-46E25298-08E8-560B-9084-5BD38154FA32"><p>Importing keys </p> </li>
<li id="GUID-6FFE5197-8FA0-5760-A068-544CBAB21798"><p>Exporting keys </p> </li>
<li id="GUID-6B1E12DA-6B0C-58F5-8A31-3BF5D2A9D464"><p>Retrieving keys </p> </li>
<li id="GUID-F13A93BD-B5F5-5FD8-A035-817EFD6A2CF6"><p>Deleting keys </p> </li>
<li id="GUID-3BC3D476-6DE9-5DF2-AC9E-7952C87C38DE"><p>Signing keys </p> </li>
<li id="GUID-B9D742CE-C2DE-5930-B3E6-4837B7AC1579"><p>Retrieving key stores </p> </li>
<li id="GUID-0B2B267D-F907-5E0D-BE31-DDB4D06F51D8"><p>Setting and retrieving
authentication policies </p> </li>
<li id="GUID-ED651B05-554A-5B02-BDAF-B61282F7DB4D"><p>Setting use and management
policies </p> </li>
</ul> <p>See <xref href="GUID-B946BDF0-C5D8-57E2-9D05-7BE134AD032E.dita">Unified
Certificate Store Tutorial</xref> and <xref href="GUID-6C6AED40-D5B3-5613-8F92-FD2CB711AE54.dita">Unified
Keystore Tutorials</xref> for details of these tasks. </p> </section>
</conbody><related-links>
<link href="GUID-6F73ED8C-E259-5717-AB84-0C2933A866DA.dita"><linktext>OS Security
Concepts</linktext></link>
</related-links></concept>