/*
 * $Id: overview.dox 131 2013-08-26 14:57:48Z ahto.truu $
 *
 * Copyright 2008-2010 GuardTime AS
 *
 * This file is part of the GuardTime client SDK.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *     http://www.apache.org/licenses/LICENSE-2.0
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
 * implied. See the License for the specific language governing
 * permissions and limitations under the License.
 */

/**
\defgroup common Common

\brief Various helper bits and pieces.

The functions described in this group are declared in the \c gt_base.h header file and implemented in the \c libgtbase library. For more implementation and usage details, see the notes for the header file.
*/

/**
\defgroup timestamps Timestamps

\brief Functions to create, encode, decode, and otherwise process Guardtime timestamp objects.

A timestamp contains the information to certify that some data existed in a given form at some given time in the past.

Guardtime timestamps are internally represented in ASN.1 and serialized and stored in DER-encoding.

A Guardtime timestamp is instanciated by:
- creating a timestamp request from a hash value using #GTTimestamp_prepareTimestampRequest() and sending that request to a timesource, then using #GTTimestamp_createTimestamp() to create a timestamp from the timesource response;
- creating a timestamp extension request from an existing timestamp by using #GTTimestamp_prepareExtensionRequest() and sending that request to an extender, then using #GTTimestamp_createExtendedTimestamp() to create an extended timestamp from the extender response;
- loading an existing DER-encoded timestamp using #GTTimestamp_DERDecode().

To save a timestamp, use #GTTimestamp_getDEREncoded() and write the resulting byte array to a file or store it in some other applicable way.

A timestamp directly only exposes the hash algorithm which was used to calculate the hash sum from which the timestamp was created (use #GTTimestamp_getAlgorithm() to get that information). All other properties, such as whether the timestamp is valid, when it was issued, etc are exposed by creating a #GTVerificationInfo object using #GTTimestamp_verify().

\see \ref publications, \ref verification

The functions described in this group are declared in the \c gt_base.h header file and implemented in the \c libgtbase library. For more implementation and usage details, see the notes for the header file.
*/

/**
\defgroup publications Publications

\brief Functions to decode and validate the information in Guardtime electronic publications.

Publications are what nail timestamps down in time: they are hash sums published in tangible media so if a timestamp can prove its participation through hashing in a publication, it also proves that it existed before that hash sum was published. Guardtime publications are printed in major newspapers across the world which makes it extremely unlikely that someone manages to destroy or falsify all copies of any given publication.

There are essentially three ways to acquire a publication the timestamp at hand should be connected to:
- extract the publication value from the timestamp and compare it to a publication in a newspaper; since the tangible sources are hard to contaminate, this is the most secure method;
- fetch an up to date publications file from an authenticated source; as the file contains publications up until the current date on which many other verifiers would be continuously dependent on, this is also a good method;
- use an archived authenticated publication file; this may not be so good, as someone may have tampered with the archival copy.

Create a #GTPublicationsFile object by feeding the bytes containing the DER-encoded publication file to the #GTPublicationsFile_DERDecode(). The #GTPublicationsFile_verify() method can then be used to verify the integrity of the publications file. The range of publications contained in a particular file can be retrieved by consulting #GTPubFileVerificationInfo::first_publication_time and #GTPubFileVerificationInfo::last_publication_time.

\see \ref verification

The functions described in this group are declared in the \c gt_base.h header file and implemented in the \c libgtbase library. For more implementation and usage details, see the notes for the header file.
*/

/**
\defgroup verification Verification

\brief Functions to verify Guardtime timestamps.

Verification is the procedure of checking whether the data at hand matches the timestamp that is supposed to be proving its authenticity and whether the timestamp itself agrees with an external reference that is supposed to back it up.

This is also the preferred method of exposing information about timestamps, since they contain several pieces of information not easily interpretable unless parsed through a verification procedure.

The basic question about a timestamp is whether it is valid:
<pre>
    GTTimestamp *gtTimestamp = ... // get the timestamp to verify
    GTVerificationInfo *gtVerificationInfo;
    int res = GTTimestamp_verify(gtTimestamp, 0, &gtVerificationInfo);
    if (res == GT_OK && gtVerificationInfo->verification_errors == GT_NO_FAILURES) {
        printf("Timestamp is valid!\n");
    } else {
        printf("Timestamp is NOT valid!\n");
    }
</pre>

However, the above procedure only checks the internal consistency of the timestamp. To make something meaningful out of it, the timestamp also needs to be connected to the data which supposedly was timestamped, as well as to a Guardtime publication (see \ref publications for info regarding how and why to acquire a publication).

\see #GTTimestamp, #GTDataHash, #GTPublicationsFile

The functions described in this group are declared in the \c gt_base.h header file and implemented in the \c libgtbase library. For more implementation and usage details, see the notes for the header file.
*/
