/**

@page overview_Certificate_Validation_in_PKIX Certificate Validation in PKIX

<hr>

@section certificate_chain Certificate Chain

Certificate validation is a recursive process. It begins with the need to verify the @ref digital_signature "digital signature" on some data presented by 

an @ref EE "End Entity" (EE). This involves checking that the key pair is actually owned by that @ref EE. To do this, the 

public signing key of that EE is acquired by getting its @ref certificate. That @ref certificate would have been 

signed by the EE's @ref CA "certification authority" (CA), so the @ref digital_signature "digital signature" on the @ref certificate can be 

verified by getting the @ref CA's public signing key. In turn, the @ref CA's certificate may need verifying, in which case

the process is repeated until it bottoms out when an entity that is already trusted is reached; that entity is 

usually self signed. This process is illustrated in the figure below:

@image html Certman_X509_Certificate_Validation_chain.png 

\n\n

The set of @ref certificates from an @ref EE up to a trusted root @ref CA_certificate "CA certificate" is called a certificate chain. 

Once a certificate chain has been constructed, the @ref EE's key pair at the start can validated.

<hr>

@section input_to_certificate_validation Input to Certificate Validation

The following inputs need to be supplied to the validation process:

@li @ref End_Entity_and_Intermediate_Certificates

@li @ref Trusted_Root_Certificates

@li @ref Validation_Time

@li @ref Acceptable_Policies

@subsection End_Entity_and_Intermediate_Certificates End Entity & Intermediate Certificates

A set of @ref certificates, from the entity requesting @ref authentication up to, but not including, one already trusted 

by the @ref relying_party "relying party". 

Where these @ref certificates come from is potentially a difficult problem, if certificate management is expected to search

for intermediate certificates in remote repositories; however for @ref TLS, at least servers are required to supply a 

complete, ordered set of certificates in the form of @ref DER encoded @ref ASN "ASN.1"; so client code can just pass this into 

the certificate chain object.

@subsection Trusted_Root_Certificates Trusted Root Certificates

@ref Authentication cannot be done entirely by software: there must be a point at which the user confirms that they trust 

a particular entity. The validation algorithm can only ascertain that if the user trusts certificate X then they may also 

trust certificate Y. Certificates that the user trusts directly are called @ref root_certificate "root certificates" because they are the root

of the validation chain; they are usually self-signed. 

It is likely that different applications will have different requirements about which @ref certificates may be considered 

trust roots, and for the level of protection they require for trust roots. To this end, applications will pass in a unique

ID (\c TUid) which Certificate Management will use to identify the application, and so work out which @ref certificates 

can be considered trusted for that application. 

For additional flexibility, an overload is provided enabling clients to pass a set of @ref root_certificate "root certificates" directly into

the validation function. 

For more detailed discussion of the storage and management of root certificates 

see Root Certificate Management and Storage.

@subsection Validation_Time Validation Time

The time for which validation will be performed.

@subsection Acceptable_Policies Acceptable Policies

A set of @ref OID "OID"s, each of which represents a certification policy acceptable to the application. This enables client 

code to restrict the @ref certificates that may occur in a valid certificate chain. Client code does not have to specify 

any preferred policies here. An empty set is interpreted as any policy.

<hr>

@section chain_validation Chain Validation

@subsection chain_construction Chain Construction

The chain object parses the encoded set of certificates. The first certificate is considered to be the @ref EE 

certificate, and subsequent @ref certificates must each certify the preceding one. The chain object then searches the set 

of trusted @ref root_certificate "root certificates" for a certificate trusted by the client and whose subject name matches the issuer name 

in the last certificate in the decoded set. If two or more match, it will attempt to resolve this be comparing the 

authority key ID in the last certificate with the subject key ID in each candidate root. If this extension is not present,

it will attempt to find a single root by signature verification. If no root is found, validation will fail immediately 

with an error.

@subsection initialisation_of_chain_validation_algorithm Initialisation of Chain Validation Algorithm

The certificate chain initialises the following state variables:

@li Validation Time: time for which validation is calculated. Initialised to the time supplied by client code. 

@li Initial Policies: set of policy @ref OIDs, initialised to the policies supplied by client code 

@li Acceptable Policies: set of X.509 policy information objects, initially any policy 

@li Mapped Policies: set of policy @ref OIDs, initially empty

@li Excluded Subtrees: set of X.500 General Name objects, initially empty

@li Permitted Subtrees: set of X.500 General Name objects, initially any subtree

@li Max Path Length: integer representing the maximum path length. Initially the actual path length 

@li Inhibit Policy Mapping: integer whose value is the number of certificates that may appear after the current one before

	policy mapping is no longer permitted. Initially the chain length

@li Require Explicit Policy: integer whose value is the number of certificates that may appear after the current one 

	before an acceptable policy @ref OID must appear in the certificate. Initially the chain length

@li Current Cert: integer whose value is the position of the current certificate in the chain. Initially the chain length -1

<hr>

@section validation_algorithm Validation Algorithm

Validation of a certificate chain starts at the root and ends at the @ref EE "End Entity" (EE). It returns a result object which

includes:

@li a single error value, which consists of a reason for the error and an integer identifying which @ref certificate the 

	error is associated with. If the reason is anything other than \c EValidatedOK then validation has failed.

@li a set of warning values, each consisting of a reason for the warning and an integer identifying which @ref certificate the 

	warning is associated with. 

@li a set of policies accepted in the course of validating the chain.

The reason the warnings are present is that it is sometimes impossible for Certificate Management to work out if an 

irregularity is an error or not, because it depends on the context of the @ref certificate (e.g. the use to which its key 

will be put) which is only known by client code. Warnings give client code a chance to evaluate these irregularities.

For each @ref certificate the actions described below are performed:

@li Signature Verification & Name Chaining -- Each @ref certificate must be signed by, and its subject name should match the

	issuer name in, the certificate above it in the chain. The only exception is the @ref root_certificate "root certificate", which, if it 

	claims to be self signed (i.e. its subject and issuer names match) must really be self signed; otherwise its signature

	is not verified, but a warning is generated. 

@li Validity Period Checking -- For each certificate, the Validation Time must lie within the validity period in the 

	certificate. 

@li Extension Processing -- Extensions can be marked critical; all critical extensions must be 'recognized and processed' 

	or the certificate must be rejected. For some extensions it is either unclear what this means, or it clearly makes no 

	sense, and in these cases a common response is to reject the certificate if the extension is marked critical. It is 

	impossible to guarantee support for some extensions.

@li Revocation Checking

Additionally, for each certificate:

@li the \em Max \em Path \em Length, \em Inhibit \em Policy \em Mapping and \em Require \em Explicit \em Policy variables 

	are decremented, 

@li and Current Cert must be less than or equal to \em Max \em Path \em Length.

When validation is complete the \em Acceptable \em Policies variable will be copied into the set of policies in the result

object.