GTIME-TEST(1)

NAME
gtime-test - Command-line tool to test GuardTime Keyless Signature services.

SYNOPSIS
Create a signature:
gtime-test -s [ more options ] Extend a signature (use online verification service to build a hash chain to a newspaper publication):
gtime-test -x [ -i file.gtts ] [ more options ] Verify a signature as is:
gtime-test -v [ -i file.gtts | -s ] [ more options ] Verify a signature using an online verification service:
gtime-test -v -x -i file.gtts [ more options ] Download a publications file:
gtime-test -p [ more options ] Authenticate a publications file:
gtime-test -v [ -b file | -p ] [ more options ]

DESCRIPTION
This is a test tool to check GuardTime service availability. It can also be used as a general signing and signature verification tool.

OPTIONS

-s  Sign the data presented either as an input file (or stream) or a hash value; a built-in test data string is used if no data file or hash value is specified.

-S url
    The signing service URL;
    http://stamper.guardtime.net/gt-signingservice is the default.

-x  Test the online verification (extending) service; a simulated request is sent if no input signature is specified (-i); in this case no extended signature is formed, only a service request is generated and the response checked for service errors.

-X url
    The online verification (extending) service URL;
    http://verifier.guardtime.net/gt-extendingservice is the default.

-p  Download a fresh publications file (and use it for verification if applicable).

-P url
    The publications file URL;
    http://verify.guardtime.com/gt-controlpublications.bin is the default.

-v  Verify a signature (-i file); verify online with -x; or verify the result of -s, -p, -b if present.

-t  Display service timings.

-n  Print signer name in ' : '-separated hierarchical form, or numeric ID if name not available.

-r  Print list of publication references, i.e. list of newspaper and online sources where publication value could be verified. Use with extended / online verified signature (-x) or extender response (-a) or publications file (-p).

-l  Print the "extended location ID" value (service diagnostic, not useful for general public).

-a int
    The age of the simulated online verification (extending) service request; the default is 36 days; this has effect only for the online verification test (-x) if no input signature is specified.

-d  Dump detailed signature or publications file verification info.

-f file
    Data file to be signed or verified.

-H alg
    The algorithm for hashing the data file; SHA1, SHA224, SHA256, SHA384, SHA512, RIPEMD160 are supported; SHA256 is the default.

-F dh
    Data hash to be signed or verified; can be given as alg:hash-in-hex or just hash-in-hex when the algorithm is specified separately (-H).

-i file
    Input file to read the signature from.

-o file
    Output file to save the signature or publications data to.

-b file
    Input file to read the publications data from.

-V file
    Verify publications file signature verbosely against the OpenSSL-style truststore in file; this switches off default (and less verbose) verification.

-C int
    Network connect timeout, in seconds.

-c int
    Network transfer timeout, in seconds.

-h  Display a help screen and quit.

It is possible to use stdin or stdout for streaming data, give '-' as a filename argument for that. Verification result is presented as a list of succeeded or failed tests, printed to stdout or stderr respectively. In the case of any failed tests exit status from range 1-9 is returned; exit code above 9 does not imply that the signature token is invalid.

EXIT STATUS
Exit status is 0 if everything is OK, or an error code explained below (there are more details in the error message printed to stderr):

1   Verification error - data hash does not match the hash value in the signature token. Document/data/hash is modified, or it is just wrong document.

3   Verification error - could not establish trust using publications file. Signature token does not match with respective publication data, or untrusted key is used for the initial token authentication, or token is too old to verify as is (needs extending).

4   Verification error - could not verify/parse publications file.

5   Error - broken signature token (format problem).

10  Network error.

12  Network error - access denied.

13  Network error - authentication needed or wrong credentials given.

14  Input-output error - file not found, file access denied, etc.

15  Out of memory error.

16  Internal error.

20  Invalid argument to a GuardTime API function.

21  Invalid command-line argument or malformed URL.

EXAMPLES
gtime-test -s -S http://guardtime-gateway.company.com/gt-signingservice
test the signing service hosted on the server guardtime-gateway.company.com. gtime-test -x -X http://guardtime-gateway.company.com/gt-extendingservice -a 365
test the online verification service on guardtime-gateway.company.com to see that its calendar database goes back at least a year. gtime-test -v -p -P http://guardtime-gateway.company.com/gt-controlpublications.bin
download the publications data from guardtime-gateway.company.com and verify it against the built-in truststore. gtime-test -v -b pubs.bin -V /usr/share/doc/gtime/trust.pem
load the publications data from pubs.bin and verify it verbosely against the truststore in trust.pem. Please see the test script /usr/share/doc/gtime/run-tests.sh for more examples. See also the gtime(1) manual for more general signing and verification examples.

ENVIRONMENT

TZ  Sets the time zone for displayed dates and times; for example,
    TZ=CEST gtime-test -v -i file.gtts
    gives all times according to Central European Summer Time (except the publishing time, which is always shown in UTC to be consistent with how the publications appear in newspapers).

http_proxy
    Sets the proxy server to use for HTTP; format is [protocol://]host[:port].

NO_PROXY
    Gives comma-separated list of names of hosts that shouldn't go through the proxy; if set to an asterisk '*' only, matches all hosts.

Internet Explorer's proxy settings are automatically used on Windows.

AUTHOR
GuardTime AS, http://www.guardtime.com/