Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 555 lines (383 sloc) 20.61 kb
d2cc8a6 Risto Laanoja use detected or specified libgt
authored
1 # Guardtime Node.js API
247ae96 Risto Laanoja eat both Buffer and binary string, service auth, more robust service err...
authored
2
33b3da2 Risto Laanoja expose signature properties, changeable service parameters, doc update
authored
3 Module is split into two classes:
4
5 * `TimeSignature` encapsulates signature token and offers some low-level 'static' methods;
d2cc8a6 Risto Laanoja use detected or specified libgt
authored
6 * `GuardTime` is service layer bridging tokens to Guardtime services.
33b3da2 Risto Laanoja expose signature properties, changeable service parameters, doc update
authored
7
b75dc86 Risto Laanoja support console.log(TimeSignature) and doc improvement
authored
8 TimeSignature is exported as guardtime.TimeSignature. Initialize and use like:
33b3da2 Risto Laanoja expose signature properties, changeable service parameters, doc update
authored
9
10 var gt = require('guardtime');
11 gt.conf({signeruri: 'http://my.gateway/gt-signingservice',
12 verifieruri: 'http://my.gateway/gt-extendingservice'});
b75dc86 Risto Laanoja support console.log(TimeSignature) and doc improvement
authored
13
14 gt.sign('some data', function (error, token){
33b3da2 Risto Laanoja expose signature properties, changeable service parameters, doc update
authored
15 if (error)
b75dc86 Risto Laanoja support console.log(TimeSignature) and doc improvement
authored
16 throw error;
17 console.log('Very secure time: ', token.getRegisteredTime());
18 gt.verify('some data', token, function(error, checkflags, properties){
19 if (error) throw error;
20 console.log('Signature OK, signed by ' + properties.location_name);
21 })
22 });
23
24 If you need to store and retrieve the TimeSignature token then use something like
25
26 arbitraryDatabase.putBlob(id, token.getContent());
27 retrievedToken = new gt.TimeSignature(arbitraryDatabase.getBlob(id));
28
29 or
30
31 gt.save('file.gtts', token, function (error){
32 if (error) throw error;
33 gt.load('file.gtts', function (error, retrievedToken){
34 if (error) throw error;
35 console.log('Loaded' + retrievedToken);
36 });
33b3da2 Risto Laanoja expose signature properties, changeable service parameters, doc update
authored
37 });
38
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
39
33b3da2 Risto Laanoja expose signature properties, changeable service parameters, doc update
authored
40
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
41 ### Guardtime
42
43 * [Guardtime.js](#guardtime)
44 * [conf](#conf)
45 * [sign](#sign)
46 * [signFile](#signfile)
47 * [signHash](#signhash)
48 * [verify](#verify)
49 * [verifyFile](#verifyfile)
50 * [verifyHash](#verifyHash)
51 * [Signature Propertiess](#signature-properties)
52 * [save](#save)
53 * [load](#load)
54 * [loadSync](#loadsync)
55 * [extend](#extend)
56 * [loadPublications](#loadpublications)
57 * [Result Flags](#result-flags)
33b3da2 Risto Laanoja expose signature properties, changeable service parameters, doc update
authored
58
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
59 ### Time Signature
60
61 * [Time Signature](#time-signature)
62 * [TimeSignature](#timesignature)
63 * [getContent](#getcontent)
64 * [getRegisteredTime](#getregisteredtime)
65 * [getSignerName](#getsignername)
66 * [getHashAlgorithm](#gethashalgorithm)
67 * [Other Functions](#other-functions)
33b3da2 Risto Laanoja expose signature properties, changeable service parameters, doc update
authored
68
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
69 ----
33b3da2 Risto Laanoja expose signature properties, changeable service parameters, doc update
authored
70
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
71 <a name="guardtime" />
72 ## Guardtime
33b3da2 Risto Laanoja expose signature properties, changeable service parameters, doc update
authored
73
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
74 The Guardtime module offers access to signature and transport utilities. Most developers will rely on functions from this module almost exclusively.
33b3da2 Risto Laanoja expose signature properties, changeable service parameters, doc update
authored
75
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
76 Include this module in your code with:
33b3da2 Risto Laanoja expose signature properties, changeable service parameters, doc update
authored
77
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
78 ```javascript
79 var gt = require('guardtime');
80 ```
81 ----
33b3da2 Risto Laanoja expose signature properties, changeable service parameters, doc update
authored
82
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
83 <a name="conf" />
84 ### conf(configuration)
33b3da2 Risto Laanoja expose signature properties, changeable service parameters, doc update
authored
85
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
86 Allows for the use of a custom URI as the Gateway. The defaults are sufficient for general use. This value should be updated if you are using an internal Gateway.
87
88 __Arguments__
33b3da2 Risto Laanoja expose signature properties, changeable service parameters, doc update
authored
89
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
90 * configuration - Object containing fields specifying Gateway URI and publications lifetime. Fields are:
91 * `signeruri` - Address of the Signing service
92 * `verifieruri` - Address of the Extending service
93 * `publicationsuri` - Address from which to download the publications file
94 * `signerthreads` - Signing service connection pool max. size, i.e. max. number of parallel signing requests.
95 * `verifierthreads` - Verifier service connection pool size.
96 * `publicationsdata` - This is used internally and is automatically loaded if empty or expired
97 * `publicationslifetime` - Number of seconds before we reload the publications file, default is 7 hours
33b3da2 Risto Laanoja expose signature properties, changeable service parameters, doc update
authored
98
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
99 __Example__
33b3da2 Risto Laanoja expose signature properties, changeable service parameters, doc update
authored
100
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
101 ```javascript
102 //These are the default values
103 gt.conf({
104 signeruri: 'http://stamper.guardtime.net/gt-signingservice', // or replace with private Gateway address
105 verifieruri: 'http://verifier.guardtime.net/gt-extendingservice', // or replace with private Gateway address
106 publicationsuri: 'http://verify.guardtime.com/gt-controlpublications.bin', // ok for most scenarios
107 signerthreads: 16, // Service connection pool size limit,
108 verifierthreads: 2, // ie. max number of parallel network connections
109 publicationsdata: '', // automatically loaded from publicationsuri if blank or expired
110 publicationslifetime: 60*60*7 // seconds; if publicationsdata is older then it will be reloaded
111 });
112 ```
33b3da2 Risto Laanoja expose signature properties, changeable service parameters, doc update
authored
113
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
114 ----
33b3da2 Risto Laanoja expose signature properties, changeable service parameters, doc update
authored
115
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
116 <a name="sign" />
117 ### sign(string, callback)
33b3da2 Risto Laanoja expose signature properties, changeable service parameters, doc update
authored
118
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
119 Signs the provided string. This will automatically calculate the hash of the provided string, using SHA256 as the hash algorithm. It will then send this hash to the Guardtime Signer, which will return a signature token. The signature token is passed to the callback function. This method is the complement of [verify()](#verify).
33b3da2 Risto Laanoja expose signature properties, changeable service parameters, doc update
authored
120
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
121 __Arguments__
33b3da2 Risto Laanoja expose signature properties, changeable service parameters, doc update
authored
122
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
123 * string - The string of data to be signed
124 * callback(error, token) - Called upon completion or in the event of an error. token is a TimeSignature object.
33b3da2 Risto Laanoja expose signature properties, changeable service parameters, doc update
authored
125
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
126 __Example__
33b3da2 Risto Laanoja expose signature properties, changeable service parameters, doc update
authored
127
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
128 ```javascript
129 var data = "Hello, world";
130 gt.sign(data, function(err, token) {
131 if(err)
132 throw err;
133 console.log('Signed at ' + token.getRegisteredTime());
134 //Record the token
135 arbitraryDb.putBlob(id, token.getContent());
136 });
137 ```
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
138
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
139 ----
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
140
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
141 <a name="signfile" />
142 ### signFile(file, callback)
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
143
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
144 Similar to [sign()](#sign), except that this function calculates the hash of a file instead of a string. Uses default hash algorithm. It will then send this hash to the Guardtime Signer, which will return a signature token. The signature token is passed to the callback function. This method is the complement of [verifyFile()](#verifyfile).
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
145
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
146 __Arguments__
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
147
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
148 * file - String indicating the location of the file to be hashed
149 * callback(error, token) - Called upon completion or in the event of an error. 'token' is a TimeSignature object.
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
150
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
151 __Example__
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
152
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
153 ```javascript
154 gt.signFile('/path/to/file', function(err, token) {
155 if(err)
156 throw err;
157 console.log('Signed at ' + token.getRegisteredTime());
158 //Record the token
159 arbitraryDb.putBlob(id, token.getContent());
160 });
161 ```
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
162
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
163 ----
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
164
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
165 <a name="signhash" />
166 ### signHash(hash, algorithm, callback)
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
167
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
168 Signs the given hash, using the specified hash algorithm. It will then send this hash to the Guardtime Signer, which will return a signature token. The signature token is passed to the callback function. This method is the complement of [verifyHash()](#verifyhash).
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
169
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
170 __Arguments__
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
171
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
172 * hash - Buffer or String containing the hash value of the data to be signed.
173 * algorithm - A string representing the algorithm that was used to sign the data. This must be correct or the signature may fail to validate in the future. Uses OpenSSL-style hash algorithm names (sha1, sha256, sha512 etc.)
174 * callback(error, token) - Called upon completion or in the event of an error. token is a TimeSignature object.
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
175
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
176 __Example__
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
177
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
178 ```javascript
179 var data = 'Hello, world';
180 var hash = SomeHashFunction(data, 'SHA256'); //Some method of hashing.
181 gt.signHash(hash, 'SHA256', function(err, token) {
182 if(err)
183 throw err;
184 console.log('Signed at ' + token.getRegisteredTime());
185 //Record the token
186 arbitraryDb.putBlob(id, token.getContent());
187 });
188 ```
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
189
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
190 ----
9cddd29 Risto Laanoja 0.3 - new call getSignerName(), fresh GT C API, better buildscript, unit...
authored
191
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
192 <a name="verify" />
193 ### verify(string, token, callback)
194
195 This method verifies the given string against the given token, passing results to the callback function. This is the complement to [sign()](#sign).
196
197 __Arguments__
198
199 * string - A string containing data which will be hashed using SHA256 and compared against the token.
200 * token - The TimeSignature token generated when the data was originally signed.
201 * callback(error, result, properties) - Called upon completion or in the event of an error. 'result' is an integer assembled from a bitfield. Its fields are [included](#result-flags) in this document, but they do not need to be validated as an error will return an exception. 'properties' contains the data returned during the verification. Its fields are [below](#signature-properties).
202
203 __Example__
204
205 ```javascript
206 var string = 'Hello, world';
207 var token = new gt.TimeSignature(arbitraryDb.getBlob(id));
208 gt.verify(string, token, function(err, result, properties) {
209 if(err)
210 throw err;
211 console.log('Signed by ' + properties.location_id + ' at ' + properties.registered_time);
212 //A full list of property values is included in this document
213 });
214 ```
215
216 ----
217
218 <a name="verifyFile" />
219 ### verifyFile(file, token, callback)
220
221 This method verifies the given file against the given token, passing results to the callback function. This is the complement of [signFile()](#signfile).
222
223 __Arguments__
224
225 * file - A string indicating the location of the file to be hashed.
226 * token - The TimeSignature token generated when the data was successfully signed.
227 * callback(error, result, properties) - Called upon completion or in the event of an error. 'result' is an integer assembled from a bitfield. Its fields are [included](#result-flags) in this document, but they do not need to be validated as an error will return an exception. 'properties' contains the data returned during the verification. Its fields are [below](#signature-properties).
228
229 __Example__
230
231 ```javascript
232 var token = new gt.TimeSignature(arbitraryDb.getBlob(id));
233 gt.verifyFile('/path/to/file', token, function(err, result, properties) {
234 if(err)
235 throw err;
236 console.log('Signed by ' + properties.location_id + ' at ' + properties.registered_time);
237 //A full list of property values is included in this document
238 });
239 ```
240
241 ----
242
243 <a name="verifyhash" />
244 ### verifyHash(hash, algorithm, token, callback)
245
246 This method verifies the given hash against the given token, passing results to the callback function. This is the complement of [signHash()](#signhash).
247
248 __Arguments__
249
250 * hash - Buffer containing the hash value of the data to be signed.
251 * algorithm - A string representing the algorithm that was used to sign the data. This must be correct or the signature may fail to validate in the future. Uses OpenSSL-style hash algorithm names.
252 * callback(error, result, properties) - Called upon completion or in the event of an error. 'result' is an integer assembled from a bitfield. Its fields are [included](#result-flags) in this document, but they do not need to be validated as an error will return an exception. 'properties' contains the data returned during the verification. Its fields are [below](#signature-properties).
253
254 __Example__
255
256 ```javascript
257 var data = 'Hello, world';
258 var hash = SomeHashFunction(data, 'SHA256'); //Some method of hashing.
259 var token = new gt.TimeSignature(arbitraryDb.getBlob(id));
260
261 gt.verifyHash(hash, token, token.getHashAlgorithm(), function(err, result, properties) {
262 if(err)
263 throw err;
264 console.log('Signed by ' + properties.location_id + ' at ' + properties.registered_time);
265 //A full list of property values is included in this document
266 });
267 ```
268
269 ----
270
271 <a name="signature-properties" />
272 #### Signature Properties:
273
274 - `verification_status` : flags about checks performed, see `resultflags` below.
275 - `location_id`: Numeric ID of issuing server (gateway), *trusted*. Obsolete.
276 - `location_name`: Human-readable ID of issuing server (gateway), *trusted* as it is set by upstream infrastructure and cannot be modified by gateway operator. Formatted as a ':' separated hierarchical list of entities; UTF-8 encoding.
277 - `registered_time`: Date object encapsulating *trusted* signing time/date.
278 - `policy`: Legally binding and audited signing policy OID.
279 - `hash_value`, `hash_algorithm`: Hash value of original signed doc, and name of used hash algorithm.
280 - `issuer_name`: Name of issuing server (gateway). May be changed by the gateway operator, take it as a 'label'.
281 - `public_key_fingerprint`: (present if 'PUBLIC_KEY_SIGNATURE_PRESENT'). Fingerprint of certificate used to sign the token; matches with whitelist published in _publications file_. Will be superseded with newspaper publication when it becomes available.
282 - `publication_string`: (this and following fields present if 'PUBLICATION_CHECKED'). Publication value used to validate the token, matches with newspaper publication value.
283 - `publication_time`, `publication_identifier`: Date object which encapsulates publishing time; _identifier_ is same encoding as Unix _time_t_ value.
284 - `pub_reference_list`: Human-readable pointers to trusted media which could be used to validate the _publication string_. Encoded as an array of UTF-8 strings.
285
286 **Note** that depending on publication data availability some fields may not be present.
287
288 ----
289
290 <a name="save" />
291 ### save(file, token, callback)
292
293 This is a simple utility to save a token to disk. It serializes a token and writes it out to the specified file. Note that if the given file already exists it may be overwritten. This method is asynchronous. It is the complement of [load()](#load).
294
295 __Arguments__
296
297 * file - A string indicating the location where the token should be saved.
298 * token - The TimeSignature token to be written to disc.
299 * callback(error) - Called upon completion or in the event of an error.
300
301 __Example__
302
303 ```javascript
304 var token = getToken(); //Get a token
305
306 gt.save('/path/to/file', token, function(err) {
307 if(err)
308 throw err;
309 });
310 ```
311
312 ----
313
314 <a name="load" />
315 ### load(file, callback)
316
317 This is the complement of [save()](#save). It will load a token from the specified file and return it to the callback function. This method is asynchronous.
318
319 __Arguments__
320
321 * file - A string indicating the location of a signature file.
322 * callback(error, token) - Called upon completion or in the event of an error. 'token' is a TimeSignature object containing the signature token.
323
324 __Example__
325
326 ```javascript
327 gt.load('/path/to/file', function(err, token) {
328 if(err)
329 throw err;
330 gt.verify('Hello, world', token, function(err, result, properties) {
331 if(err)
332 throw err;
333 console.log('Greeting file was signed at: ' + properties.registered_time);
334 });
335 });
336 ```
337
338 ----
339
340 <a name="loadsync" />
341 ### loadSync(file)
342
343 This loads a token from a file *synchronously*. The TimeSignature token is returned directly.
344
345 __Arguments__
346
347 * file - A string indicating the location of the file to be loaded.
348
349 __Return__
350
351 * TimeSignature token - The TimeSignature token from that file.
352
353 __Throws__
354
355 * Exception - in the event of an error.
356
357 __Example__
358
359 ```javascript
360 var token = gt.loadSync('/path/to/file');
361 ```
362
363 ----
364
365 <a name="extend" />
366 ### extend(token, callback)
367
368 This function extends a given signature. It is primarily used internally and is called automatically when a signature is verified. A developer should generally not need to call this function directly.
369
370 __Arguments__
371
372 * token - The TimeSignature to be extended
373 * callback(error, token) - Returns the original token, not a new one. Note that an error does not necessarily mean that the signature is broken.
374
375 ----
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
376
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
377 <a name="loadpublications" />
378 ### loadPublications(callback)
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
379
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
380 This function loads or updates the publications file. This function is used internally. It is rare that a developer needs to call this directly, as it is called automatically in the event of an empty or expired publications file.
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
381
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
382 __Arguments__
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
383
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
384 * callback(error) - Function to be called upon completion or in the event of an error.
385
386 ----
387
388 <a name="result-flags" />
389 #### Result Flags
390
391 The following flags are present in callbacks from a [verify()](#verify) function. They are loaded as a bit field. Most developers will not need to consider these, they are checked automatically. The information here is also present in the 'properties' field of the callback. These are included primarily for backwards compatibility.
392
393 - `gt.VER_RES.PUBLIC_KEY_SIGNATURE_PRESENT`: Token is verified using RSA signature; newspaper publication is not yet available or accessible.
394 - `gt.VER_RES.PUBLICATION_REFERENCE_PRESENT`: Properties list includes human-readable array of newspapers or other trusted media references which could be used for independent signature verification.
395 - `gt.VER_RES.DOCUMENT_HASH_CHECKED`: Document content or hash was provided and it matches the hash value in signature token. Always present.
396 - `gt.VER_RES.PUBLICATION_CHECKED`: Token is verified using trusted publication which is printed in newspapers for independent verification.
397
398 ----
399
400 <a name="time-signature" />
401 ## TimeSignature
402
403 The TimeSignature module encapsulates a Guardime signature token. The following methods will be useful to developers:
404
405 ---
406
407 <a name="timesignature" />
408 ### TimeSignature(data)
409
410 Constructs a new TimeSignature from a serialized data blob, such as a blob retrieved from a database.
411
412 __Arguments__
413
414 * data - A binary blob, such as a blob from a database, either String or Buffer. This blob can be generated with [getContent()](#getcontent).
415
416 __Return__
417
418 * TimeSignature token - The TimeSignature token.
419
420 __Throws__
421
422 * Exception - in the event of an error.
423
424 __Example__
425
426 ```javascript
427 var blob = arbitraryDb.getBlob(id);
428 var token = new gt.TimeSignature(blob);
429 ```
430
431 ---
432
433 <a name="getcontent" />
434 ### getContent()
435
436 Returns the serialized form of a signature token. Useful when placing a signature into a database, sending over the network, etc.
437
438 __Return__
439
440 * Buffer buffer - The binary representation of the token.
441
442 __Throws__
443
444 * Exception - in the event of an error.
445
446 __Example__
447
448 ```javascript
449 var token = getToken(); //Get a token
450 var blob = token.getContent();
451 arbitraryDb.putBlob(id, blob);
452 ```
453
454 ---
455
456 <a name="getregisteredtime" />
457 ### getRegisteredTime()
458
459 Returns a Date object containing the time at which the token was registered. Useful if you need to check when a token was registered without calling verify().
460
461 __Return__
462
463 * Date registered_time - The date & time at which the object was registered.
464
465 __Example__
466
467 ```javascript
468 var token = getToken(); //Get a token
469 var date = token.getRegisteredTime();
470 console.log('Signed at: ' + date);
471 ```
472
473 ----
474
475 <a name="getsignername" />
476 ### getSignerName()
477
478 Returns signer's identity as ':' delimited hierarchial list of responsible authenticators.
479 If the token does not contain an identity then an empty string ('') is returned.
480
481 __Return__
482
483 * String signerid - Signer's identity
484
485 __Example__
486
487 ```javascript
488 var token = getToken(); //Get a token
489 var id = token.getSignerName();
490 console.log('Signed by: ' + id);
491 ```
492
493
494 ----
495
496 <a name="gethashalgorithm" />
497 ### getHashAlgorithm()
498
499 Returns the name of the hash algorithm that was used to create the data in this token. The hash algorithm name is useful with functions such as [gt.verifyHash()](#verifyhash) -- comparing hash values is meaningful only if these hashes were created using same hash algorithm.
500
501 __Return__
502
503 * String hash_algorithm - The name of the algorithm that was used to create the hash in this token.
504
505 __Example__
506
507 ```javascript
508 var token = getToken(); //Get a token
509 var algo = token.getHashAlgorithm();
510 console.log('Token generated using algorithm: ' + algo);
511 ```
512
513 ----
514
515 <a name="other-functions" />
516 ### Other Functions
517
518 The following functions are most likely not interesting for general public.
519
520 ---
521
522 ###### `Object signature_properties = timesignature.verify()`
523 Verifies the internal consistency of the signature token and returns structure with signature properties. See `guardtime.verify()`. Throws an exception in case of error or 'broken' signature. Does not use network services.
524
525 ###### `Boolean earlier = timesignature.isEarlierThan(TimeSignature ts2)`
526 Compares two signature tokens, returns True if encapsulated token is _provably_ older than one provided as an argument. False otherwise.
527
528 ###### `Buffer request = timesignature.composeExtendingRequest()`
529 Creates a request data blob to be sent to the Verification service.
530
531 ###### `Boolean extended = timesignature.isExtended()`
532 Returns True if timesignature token has all missing bits of hash-chain embedded for offline
533 verification. False otherwise.
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
534
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
535 ###### `Integer checks_done = timesignature.verifyHash(hash, String algo)`
536 Compares given hash to hash in signature token; only meaningful when hash algorithm is exactly same as signing hash algorithm (get with token.getHashAlgorithm()).
537 Returns a bitfield with verification information, constructed in the same format as above.
538 *Note* that validation of the return value is unnecessary, in case of errors or negative validation result an Exception is thrown.
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
539
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
540 ###### `Boolean ok = timesignature.extend(response)`
541 Creates 'extended' version of TimeSignature token by including missing bits of the hash chain.
542 Input: Buffer or String with verification service response; returns True or throws an Exception.
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
543
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
544 ###### 'static' functions for internal use:
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
545
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
546 `Buffer request = TimeSignature.composeRequest(hash, String hashalgorithm)`
547 Creates request data to be sent to signing service. Input: binary hash (Buffer or String) and hash algorithm name.
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
548
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
549 `Buffer der_token_content = TimeSignature.processResponse(response)`
550 Creates DER encoded serialized TimeSignature, usually fed to TimeSignature constructor.
b64dbf8 Risto Laanoja fixes in buildscrpt, initial api doc
authored
551 Input: response from signing service.
552
6534242 Risto Laanoja documentation improvements by https://github.com/esquire-
authored
553 `Boolean ok = TimeSignature.verifyPublications(der_publications_file_content)`
554 Verifies publications file (this is used by a higher level verification routine).
555 Returns True or throws exception.
Something went wrong with that request. Please try again.