/**

@page overview_X509_and_PKIX X.509 and PKIX
\n

A @ref certificate consists of a public key together with some identifying information, all of which is signed with a 
@ref CA "Certificate Authority's" (CA's) private key. Different @ref certificate specifications elaborate on this in different ways 
with varying syntax, encoding rules and processing requirements. 

Currently, X.509 is the dominant specification and is used by @ref TLS, @ref SMIME "S/MIME" and @ref IPSec. In addition to this 
certificate type, the Symbian OS also provides support for and implements @ref WTLS certificates: this page deals with 
X.509, for information on WTLS see @ref overview_WTLS Certificates Overview.


<hr>

@section need_for_profiles_in_x509 The need for profiles in X.509

The X.509 specification alone is not restrictive or specific enough to form the basis of an implementation of a 
certificate management component. Realisation of this fact has led to the creation of a set of mostly incompatible 
profiles.

While X.509 defines an extensible syntax for all the data structures required to perform certificate management, a profile
adds three things:
@li a restriction on the sorts of data structures that an implementation is required to understand
@li a requirement that certain specific sorts of data structure be present, so an implementation may rely on their 
presence
@li a clear definition of the behaviour of a certificate management component, i.e. a specification of what it is supposed 
to do with the data structures involved

The best example of this is seen in certificate extensions. X.509 defines the syntax of a series of extension types, and 
permits new extensions to be defined using object identifiers. It does not require the presence of any extensions and does
not clearly indicate what it means to support a particular extension. Thus an implementation cannot know which extensions 
will be present, or exactly what to do with them. A profile like PKIX defines a set of extensions that a PKIX-compliant 
certificate management component must be able to deal with, which extensions can be assumed to be present, and a definition
of what it means to deal with them. 

The distinction between X.509 and its profiles is largely one of syntax versus behaviour: X.509 defines the syntax of the
objects, and the profile defines how the presence and values of objects affects the behaviour of certificate management. 
In addition, a profile may define extra pieces of syntax, specific to the application for which it is designed.


 

<hr>

@section profile_support_in_certman Profile support in Certman

Certificate Management implements X.509 along with one profile, the PKIX profile, defined in RFC 2549. Its design attempts
to incorporate the distinction between X.509 and its profiles, enabling further additions to be made to the X.509 part 
without affecting any profiles, and enabling further profiles to be defined without affecting the X.509 specific part.

The decision to use a particular profile rests with the application.

All general classes defined in X.509 are prefixed with 'X509', all profile specific classes are prefixed with the name of 
the profile.


<hr>

@section x509_specific_part X.509 specific part

The @ref X509_certificate "X.509 certificate" itself and the generic extension object are both clearly part of X.509 itself.

The generic extension object is simply an ASN1 'any defined by' structure, with accessors for its @ref OID and its encapsulated
data.

The @ref X509_certificate "X.509 certificate" provides a function that, given a particular @ref OID, returns a pointer to a particular extension object
or NULL if the extension is not present. It also provides functions to verify its signature, given a key, and return the 
various data members that @ref X509 "X.509" requires, such as its subject and issuer DNs. However, it does not provide accessors for 
any particular extensions (e.g. there is no KeyUsage() function, since it cannot be assumed that key usage is present).

A generic certificate chain object is also provided; this simply has a set of X.509 certificates, provides accessors to 
them and implements a function to decode a set of certificates from @ref DER encoded @ref ASN "ASN.1".

Specific extension classes are in a bit of a no-man's land. This is because many of them are defined by @ref X509 "X.509", but more 
can be added by any profile, and a profile will require the use of a particular set of extensions. So, all the extensions 
used by @ref PKIX in @ref X509 "X.509" have been implemented on the assumption that they are likely to be useful for other profiles, 
however, profiles are free to define extra extensions. Since these extension classes are implemented in @ref X509 "X.509", they only 
define the syntax of the extension, not the way it should be used. Because they are radically different they do not share 
a common base class.


<hr>

@section profile_specific_part Profile specific part

The profile specific part defines two significant public classes:

@li \b PKIX \b certificate \b chain \b object \n
	This is main class which encapsulates path processing in the @ref PKIX profile. Thus it defines which extensions are 
	required, which extensions are understood, and how they are understood. 

@li \b PKIX \b validation \b result \b object \n
	This is constructed by the chain object in the course of validation and handed to the client to examine.

These classes are described in more detail in Certificate validation in @ref PKIX; the validation process discussed there is 
@ref PKIX specific.




*/