The Guardtime Client SDK for C uses OpenSSL for cryptographic functions and data encoding, and on Linux also cURL for HTTP transport. The SDK is compatible with all platforms where OpenSSL (and optionally cURL) is available.

In addition to the source, which the customers can compile on any platform where the required support libraries are available, there are two precompiled versions of the SDK:

• Windows static and dynamic libraries for use with the Microsoft Visual C++ compiler (tested with VC 2010 on Windows XP Professional, but should work under any reasonably recent version of Windows);
• Linux static and shared libraries for use with the GNU C or C++ compiler (tested with GCC 4.1 on Debian 4.0, but should work under any reasonably recent distribution).

The SDK is also known to compile and work under Mac OS X 10.5 (using system standard GCC and OpenSSL 0.9.8 from MacPorts) and Red Hat Enterprise Linux 5 (using system standard GCC and libraries).

Note that:

• OpenSSL libraries have to be version 0.9.8 or newer, otherwise the SHA-256 hash algorithm  is not available;
• Default implementation of HTTP transport for requests to the Guardtime services is included in the SDK, however developers are free to use any other libraries providing that functionality; in that case the cURL libraries are not needed.

• OpenSSL libraries and header files: you can download the sources from the OpenSSL Project and compile your own or get the precompiled version from here;
• Guardtime Client SDK libraries and header files: you can download the sources from here and compile your own or get the precompiled version from here (note that the source distribution also includes examples);
• Guardtime Client SDK documentation in HTML and PDF;
• The locations (URLs) of a the service provider.

• OpenSSL libraries and header files: you can download the sources from the OpenSSL Project and compile your own or get the precompiled version through the standard package distribution mechanisms:
  • on Debian (4.0 or newer), this means issuing the command
    sudo apt-get install libssl-dev
  • on Red Hat (RHEL 5 or newer), this means issuing the command
    sudo yum install openssl-devel
• cURL libraries and header files: you can download the sources from the cURL Project and compile your own or get the precompiled version through the standard package distribution mechanisms:
  • on Debian (4.0 or newer), this means issuing the command
    sudo apt-get install libcurl3-dev
  • on Red Hat (RHEL 5 or newer), this means issuing the command
    sudo yum install curl-devel
• Guardtime Client SDK libraries and header files: you can download the sources from here and compile your own or get the 32-bit precompiled version from here or the 64-bit precompiled version from here (note that the source distribution also includes examples);
• Guardtime Client SDK documentation in HTML and PDF;
• The locations (URLs) of your KSI service provider

On Windows

The basic compile and link command line from the “Visual Studio Command Prompt” (all on a single line):

 cl.exe example.c /MT /I C:\gt\include /link /libpath:C:\gt\lib /libpath:C:\openssl\lib libgtbaseMT.lib libeay32MT.lib user32.lib gdi32.lib advapi32.lib

Replace C:\gt and C:\openssl with the directories where you unpacked the Guardtime and OpenSSL libraries, of course.

When compiling, keep in mind that mixing code compiled with different /Mxx settings is dangerous. It’s best to always use the Guardtime and OpenSSL libraries that match the /Mxx setting you specified for compiling your own source code.

For more specific instructions for the examples included with the SDK, please see the comments within each example.

On Linux

The basic compile and link command (all on a single line):

gcc example.c -o example -I/usr/local/gt/include -L/usr/local/gt/lib -L/usr/local/ssl/lib -lgtbase -lcrypto -lrt

To also include the HTTP transport library, extend the command to (still all on a single line):

gcc example.c -o example -I/usr/local/gt/include -L/usr/local/gt/lib -L/usr/local/curl/lib -L/usr/local/ssl/lib -lgthttp -lgtbase -lcurl -lcrypto -lrt

In both cases, replace /usr/local/gt, /usr/local/ssl /usr/local/curl with the directories where you unpacked the Guardtime, OpenSSL, and cURL libraries, of course.

In case you installed the Guardtime, OpenSSL, and cURL packages in the system default locations or used the standard packages, you can omit the corresponding -I and -L options altogether.

For more specific instructions for the examples included with the SDK, please see the comments within each example.

• digitally sign a record;
• extend a  signature;
• verify a signature.

Each example also contains more specific compilation and usage instructions.

Note that the operations to view and verify signatures  have been merged, therefore there is no separate view a signature use case.

When calling the verification functions in the SDK, it is important to realize that the verification chain is a three-link one:

1. the data hash connects the data to the signature;
2. the signature  connects the data hash to a publication;
3. the publication connects the signature to physical media, thus independently proving its age.

The SDK can only provide the middle link. The connection to the source data has to be provided by the host application. For ultimate security, looking up the computed Publication Code in physical media has to be performed by a human being.

The Guardtime Client SDK for Java uses the Bouncy Castle API for cryptographic functions and data encoding. The Bouncy Castle API provides the Java Cryptography Extension (JCE) and the Java Cryptography Architecture (JCA).

The SDK works with all J2SE 1.5-compatible platforms (including Java SE 6 and Java SE 7). It has been tested to work under:

• Windows XP (Sun Java 1.5, Sun Java 6.0);
• Mac OS X (Sun Java 1.5);
• Debian/Ubuntu Linux (Sun Java 6.0).

Currently the Bouncy Castle API is not compatible with the Free Java SDK (based on SableVM), and the Guardtime SDK is not compatible with Sun J2SE 1.4 or earlier.

The Guardtime PDF Toolkit for Java additionally depends on the iText library.

What needs to be installed to use the Guardtime Client Java SDK:

• The Java Development Kit (JDK), Standard Edition 5.0 or later;
• The Bouncy Castle Crypto API for JDK 1.5, version 1.47  (in the following referred to as bcprov-XXX-XXX.jar, where you have to substitute the actual version numbers for XXX);
• The Guardtime Client SDK for Java itself (in the following referred to as GTJavaSDK-X.X.X.jar, where you have to substitute the actual version number for X.X.X);
• The Guardtime SDK reference documentation;
• The Guardtime SDK source code that also includes examples;
• The locations (URLs) of your Guardtime services, as provided by your integration contact at Guardtime.

Addtionally for the Guardtime PDF Toolkit for Java:

• The Guardtime PDF Toolkit itself;
• The Guardtime PDF Toolkit reference documentation;
• The Guardtime PDF Toolkit source code that also includes examples;
• The iText library itself;
• The iText library reference documentation;
• The iText library source code.

Compiling projects manually from the command line is usually not the preferred method, but the basic information needed to compile and run the fictional example Example.java can be adapted to suit the development environment at hand.

From the Command Line on Linux

To compile the example (all on a single line):

javac -classpath .:/usr/local/gt/GTJavaSDK-X.X.X.jar:/usr/local/gt/bcprov-XXX-XXX.jar Example.java

To run it (all on a single line):

java -classpath .:/usr/local/gt/GTJavaSDK-X.X.X.jar:/usr/local/gt/bcprov-XXX-XXX.jar Example

In both cases, replace /usr/local/gt with the directory where you installed the Guardtime and BouncyCastle libraries, of course.

Note that in Linux, classpath entries are separated by colons (:).

From the Command Line on Windows

To compile the example (all on a single line):

javac -classpath .;C:\gt\GTJavaSDK-X.X.X.jar;C:\gt\bcprov-XXX-XXX.jar Example.java

To run it (all on a single line):

java -classpath .;C:\gt\GTJavaSDK-X.X.X.jar;C:\gt\bcprov-XXX-XXX.jar Example

In both cases, replace C:\gt with the directory where you installed the Guardtime and BouncyCastle libraries, of course.

Note that in Windows, classpath entries are separated by semicolons (;).

From the Eclipse IDE

In the Eclipse IDE, add the two jar files as “external archives” to your project:

• right-click the current project in the Package View list;
• in that menu, select Build Path > Add external archives...;
• navigate to required jar files, select them, and click OK.

To execute an example under Eclipse:

• choose a class to Run As > Java Application;
• provide the full absolute path for filename parameters.

• digitally sign a record;
• extend a signature;
• verify a signature.

Each example also contains more specific compilation and usage instructions.

Note that the operations to view and verify signatures has been merged, therefore there is no separate view a signature use case.

When calling the verification functions in the SDK, it is important to realize that the verification chain is a three-link one:

1. the data hash connects the data to the Keyless Signature;
2. the signature connects the data hash to a publication;
3. the publication connects the signature e to physical media, thus independently proving its age.

The SDK can only provide the middle link. The connection to the source data has to be provided by the host application. For ultimate security, looking up the computed Publcation Code in physical media has to be performed by a human being.

• PHP version 5.3.0 or newer;
• support for OpenSSL:
  • OpenSSL 0.9.8 or newer has to be installed;
  • PHP has to be compiled with the --with-openssl option (default in most binary distributions of PHP);
  • the php_openssl extension has to be enabled in php.ini;
  • see the PHP documentation for more details;
• support for cURL:
  • libcurl 7.10.5 or newer has to be installed;
  • PHP has to be compiled with the --with-curl option (default in most binary distributions of PHP);
  • the php_curl extension has to be enabled in php.ini;
  • see the PHP documentation for more details;
• support for BCMath:
  • PHP has to be compiled with the --with-bcmath option (default in most binary distributions of PHP);
  • see the PHP documentation for more details.

• PHP version 5.3.0 or newer, with support for OpenSSL, cURL, and BCMath enabled, as described above;
• The Guardtime Client SDK for PHP itself;
• The Guardtime SDK reference documentation that also includes examples;
• The locations (URLs) of your Guardtime Gateway Server, as provided by your integration contact at Guardtime.

require_once(PATH_TO_Guardtime_PHP);

in your source code.

The example code included in the reference documentation illustrates the main use cases which can be performed with the Guardtime Client SDK:

• digitally sign a data item;
• verify a signature.

Note that the operations to view and verify signatures been merged, as it makes no sense to view the properties of a signature unless it’s known to be valid.

In the example code each use case is illustrated as a separate stand-alone application, but in a real integration scenario the tasks should be implemented in a signature handler called by the parent application. Also the code is the minimum you need for running the example (in particular, it omits most error handling) and the snippets here are further stripped down for readability.

Digitally Sign data”

To digitally sign data, there are three steps that need to be performed:

1. compute a hash value of the data to be signed;
2. send a request to the Gateway server and receive a signature in response;
3. save the signature for archival along with the data.

The minimal code to perform those steps is along the following lines:

// hash the data file using the default algorithm (currently SHA-256)
$dataHash = new GTDataHash(GTHashAlgorithm::getByName('DEFAULT'));
$dataHash->updateFile(DATA_FILE_NAME);
$dataHash->close();

// request a timestamp for the hash value
$timestamp = GTHttpClient::create($dataHash, TIMESTAMPING_SERVICE_URL);

// save the timestamp for archiving it along with the data file
$timestamp->save(TIMESTAMP_FILE_NAME);

Verify a signature”

To verify a signature, there are five steps that need to be performed:

1. load the signature;
2. calculate the data hash;
3. acquire a trusted publication;
4. verify the Publication Code
5. display verification information.

The minimal code to perform those steps is along the following lines:

// load the timestamp
$timestamp = GTTimestamp::load(TIMESTAMP_FILE_NAME);

// hash the data file using the algorithm from the timestamp
$dataHash = new GTDataHash($timestamp->getHashAlgorithm());
$dataHash->updateFile(DATA_FILE_NAME);
$dataHash->close();

// load the publications file // we assume it’s trusted local copy and skip verification here $pubFile = GTPublicationsFile::load(PUBLICATIONS_FILE_NAME);

// verify against the publications file $result = GTHttpClient::verify($timestamp, $dataHash, null, $pubFile); if ($result->isValid()) { echo $timestamp->getProperty(GTTimestamp::REGISTERED_TIME) . “\n”; } else { echo “Verification failed\n”; }

When calling the verification functions in the SDK, it is important to realize that the verification chain is a three-link one:

1. the data hash connects the data to the signature;
2. the signature connects the data hash to a publication;
3. the publication connects the signature to physical media, thus independently proving its age.

The SDK can only provide the middle link. The connection to the source data has to be provided by the host application. For ultimate security, looking up the computed Publication Code in physical media has to be performed by a human being.

Node.JS version 0.6.0 or newer; Linux, MacOS, Solaris.

Follow these steps below:

1. Install Node.JS;
2. Install NPM (Node Package Manager);
3. Issue ‘npm install Guardtime’ on command line;

…or download code from Github and install manually (node-waf configure / node-waf build / node-waf install).

OpenSSL development libraries must be installed, and must be the same version as in the underlying Node.JS platform. Strange things may happen if the versions don’t match.

The following code snippet signs a text string and then verifies it.

The following code signs files specified as command line arguments. Characteristically to Node.JS this happens in parallel.

There are many more API usage examples in the unit-test file tests.js.

Please refer to https://github.com/ristik/node-guardtime/blob/master/node-guardtime-api.markdown.