guardtime 0.0.1 → 0.0.2

data/ChangeLog

@@ -0,0 +1,8 @@
+Release 0.0.2 (2013-01-02 by risto):
+	- added RDoc
+	- new function 'extend'
+	- minor bug: double free when 'extended' signature is verified
+	- GT library init done at 'require' time instead of instantiation time.
+
+Release 0.0.1 (2013-01-05 by risto):
+	- initial verion

data/INSTALL

@@ -1,22 +1,27 @@
-Dependencies:
+= Dependencies:
 
 - libcurl
 - openssl 0.9.8+
 - GuardTime C API
 
-installation on Debian:
+== installation on Debian:
 
-apt-get install ruby ruby-dev rubygems
-apt-get install libcurl-dev openssl-dev
-wget http://download.guardtime.com/libgt-0.3.11-src.tgz
-tar xfz libgt-0.3.11-src.tgz
-cd libgt-0.3.11
-./configure --disable-shared
-make
-sudo make install
-cd ..
-sudo gem install guardtime-x.y.z.gem
-  or
-sudo gem install guardtime
+   apt-get install ruby ruby-dev rubygems
+   apt-get install libcurl-dev openssl-dev
+   wget http://download.guardtime.com/libgt-0.3.11-src.tgz
+   tar xfz libgt-0.3.11-src.tgz
+   cd libgt-0.3.11
+   ./configure --disable-shared
+   make
+   sudo make install
+   cd ..
+   sudo gem install guardtime-x.y.z.gem
+or
+   sudo gem install guardtime
 
-Adjust at other platforms.
+
+== installation on OpenSolaris / OpenIndiana / Illumous / SmartOS
+
+Please use 
+   CPPFLAGS="-I/opt/local/include -fPIC" LDFLAGS="-L/opt/local/lib -R/opt/local/lib"  ./configure --prefix=/opt/local --disable-shared
+for configuring the GuardTime C API. Adjust dependency install commands etc.

data/ext/guardtime.c

@@ -173,8 +173,8 @@ cleanup:
 		*ver = ver_tmp;
 		ver_tmp = NULL;
 	}
-
-	GTTimestamp_free(ext);
+	if (ext != ts)
+		GTTimestamp_free(ext);
 	GTVerificationInfo_free(ver_tmp);
 
 	return res;
@@ -229,6 +229,22 @@ static void get_gtdatahash2(VALUE algo, VALUE digest, GTDataHash *dh)
 	dh->digest_length = RSTRING_LEN(digest);
 }
 
+/* 
+ * call-seq: 
+ *		sign(Digest) -> signature_token
+ *		sign(hashalgname, binarydigest) -> signature_token
+ *
+ * * *Args*    :
+ *   - +Digest+ -> Digest object, implementing supported hahs algorithm, encapsulating already calculated hash value.
+ *		example: guardtime.sign(Digest.SHA2.new(256).update('this string shall be signed'))
+ *   - +hashalgname+ -> String with OpenSSL style hash algorithm name, either SHA256, SHA224, SHA384, SHA512, SHA1 or RIPEMD160.
+ *   - +binarydigest+ -> String with binary hash value.
+ * * *Returns* :
+ *   - String containing binary data with Guardime signature token. May be directly saved etc.
+ * * *Raises* :
+ *   - +ArgumentError+ -> if any value is nil or wrong type.
+ *   - +RuntimeError+ -> other errors, including network, hash value etc.
+ */
 static VALUE
 guardtime_sign(int argc, VALUE *argv, VALUE obj)
 {
@@ -263,6 +279,52 @@ guardtime_sign(int argc, VALUE *argv, VALUE obj)
 	return result;
 }
 
+/* 
+ * call-seq: 
+ *		extend(sig) -> extended_signature_token
+ *
+ * * *Args*    :
+ *   - +sig+ -> String containing binary data with Guardime signature token. May be directly loaded from file.
+ * * *Returns* :
+ *   - String containing binary data with Guardime signature token. May be directly saved etc.
+ * * *Raises* :
+ *   - +ArgumentError+ -> if any value is nil or wrong type.
+ *   - +RuntimeError+ -> other errors, including network, hash value, token too new or old etc. Proper description is in the error message.
+ * Extended signature token may be used for 'independent' verification without any keys or services. Just data, token and newspaper with published value.
+ * There is no point in extending the signature before next newspaper publication is performed. Good rule of thumb is to wait for 35 days, or until 15th date plus 5 more days.
+ */
+static VALUE
+guardtime_extend(VALUE obj, VALUE in)
+{
+	int res;
+	GTDataHash dh;
+	GTTimestamp *ts, *ts2;
+	unsigned char *data;
+    size_t data_length;
+    GuardTimeData *gt;
+	VALUE result;
+
+	StringValue(in);
+	Data_Get_Struct(obj, GuardTimeData, gt);
+	res = GTTimestamp_DERDecode(RSTRING_PTR(in), 
+    					RSTRING_LEN(in), &ts);
+    if (res != GT_OK)
+		rb_raise(rb_eArgError, GT_getErrorString(res));
+
+	res = GTHTTP_extendTimestamp(ts, gt->verifieruri, &ts2);
+	GTTimestamp_free(ts);
+	if (res != GT_OK)
+		rb_raise(rb_eRuntimeError, GT_getErrorString(res));
+
+    res = GTTimestamp_getDEREncoded(ts2, &data, &data_length);
+	if (res != GT_OK)
+		rb_raise(rb_eRuntimeError, GT_getErrorString(res));
+
+    result = rb_str_new((char*)data, data_length);
+    GT_free(data);
+	return result;
+}
+
 // load and parse/verify pub. file, populate state.
 int loadpubs_helper(GuardTimeData *gt) {
 	int res = GT_OK;
@@ -359,6 +421,63 @@ format_hash_algorithm(int alg)
 	}
 }
 
+/* 
+ * call-seq:
+ *		verify(sig) -> true/false
+ *		verify(sig, Digest) -> true/false
+ *		verify(sig, hashalgname, binarydigest) -> true/false
+ *		verify(sig, ...) {|resulthash| ... statement }  -> value_of_last_cb_statement
+ *
+ * * *Args*    :
+ *   - +sig+ -> String containing binary data with Guardime signature token. May be directly loaded from file.
+ *   - +Digest+ -> Digest object, implementing supported hash algorithm, encapsulating already calculated hash value. 
+ *   - +hashalgname+ -> String with OpenSSL style hash algorithm name, either SHA256, SHA224, SHA384, SHA512, SHA1 or RIPEMD160.
+ *   - +binarydigest+ -> String with binary hash value. Obtain with +Digest.digest+ for example.
+ *   - +code_block+   -> Optional code block serves two purposes: 1) Allows to implement _verification_policies_, i.e. add additional checks to the signature verification, and 2) Gives access to signature properties present in code block argument +resulthash+.
+ * * *Returns* :
+ *   - either +true+ or +false+, depending on the result of verification. If code block is used then the value returned by last statement of code block is passed through.
+ * * *Raises* :
+ *   - +ArgumentError+ -> if any value is nil or wrong type, or signature token is corrupted.
+ *   - +RuntimeError+ -> other errors, including network, hash value etc.
+ * 
+ * Code block receives parameter +resulthash+ which is populated with signature properties. There are following keys:
+ * *verification_errors*::	bitfield containing verification errors. See class constants. Verification is successful only if value equals to <tt>GuardTime::NO_FAILURES</tt>
+ * *verification_status*::	Numeric bitfield -- flags identifying successful verification checks. See class constants.
+ * *time*::				Time object containing signing (time-stamp) datum.
+ * *registered_time*::	Numeric containing 'time_t' representation (seconds since Epoch) of the signing datum.
+ * *hash_algorithm*::	String with OpenSSL style hash algorithm name; this algorithm was used for hashing the original data.
+ * *hash_value*::		Hash of the signed data, formatted as String of ':'-separated hex octets.
+ * *location_name*::	String containing signature issuer name within the GuardTime network. Example: 'GT : GT : Customer'
+ * *location_id*::		String containing '.' separated customer address hierarchy.
+ * *policy*::			String with signing/time-stamping policy OID.
+ * *publication_identifier*::	Publication ID, Numeric.
+ * *publication_string*::		Control string for verifying the timestamp using a hardcopy publication, the value is base32(time+alg+hash+crc32)
+ * *pub_reference_list*::		Array of UTF-8 encoded Strings containing list of newspaper issues or other media used for publishing verification values.
+ * *publication_time*::			Time object containing datum of publishing time which could be used for intependent 'newspaper based' verification.
+ * *public_key_fingerprint*::	String with PKI key fingerprint which could be used for extra verification until newspaper hash-link publication becomes available. List of trusted keys is published with publications file.
+ *
+ * * *Notes*
+ *   - hash algorithm must match one used for hashing the original data during signing. See example below.
+ *   - finish the code block with <tt>resulthash[:verification_errors] == GuardTime::NO_FAILURES</tt> if You care of the return value!
+ *
+ * * *Examples*
+ *   - Default behaviour (without code block) is acheved with following code: 
+ *        result = guardtime_obj.verify(token) do |resulthash|
+ * 		 		resulthash[:verification_errors] == GuardTime::NO_FAILURES
+ *        end
+ *   - Verification flow with loading token, determining hash alg., hashing file, verifying with signer ID check.
+ *        token = slurpbinaryfile('importantdata.txt.gtts')
+ *        hasher = GuardTime.getnewdigester(token)
+ *        hasher << slurpbinaryfile('importantdata.txt')
+ *        gt = GuardTime.new
+ *        signedAt = nil
+ *        okay = gt.verify(token, hasher) do |r|
+ *              signedAt = r[:time]
+ *              /companyname$/ =~ r[:location_name] and 
+ * 		 		   r[:verification_errors] == GuardTime::NO_FAILURES
+ *        end
+ *        puts "data signed at #{signedAt.utc.to_s}" if okay
+ */
 static VALUE
 guardtime_verify(int argc, VALUE *argv, VALUE obj)
 {
@@ -393,7 +512,7 @@ guardtime_verify(int argc, VALUE *argv, VALUE obj)
 		    break;
     }
 
-    if (res != GT_OK) {
+	if (res != GT_OK) {
 	    GTTimestamp_free(ts);
 		rb_raise(rb_eRuntimeError, GT_getErrorString(res));
 	}
@@ -430,7 +549,6 @@ guardtime_verify(int argc, VALUE *argv, VALUE obj)
 
 		RBSET("time", time_t_to_Time( verification_info->implicit_data->registered_time ));
 		RBSET("publication_time", time_t_to_Time( verification_info->explicit_data->publication_identifier ));
-
    	} else
    		retval = verification_info->verification_errors == GT_NO_FAILURES ? Qtrue : Qfalse;
 
@@ -443,8 +561,18 @@ guardtime_verify(int argc, VALUE *argv, VALUE obj)
 		return retval;
 }
 
-
-// returns instance of Digester::... with same hashalg.
+/* 
+ * call-seq: 
+ *		GuardTime.getnewdigester(signature) -> instance_of_Digest
+ *
+ * * *Args*    :
+ *   - +signature+ -> String containing Guardtime signature token
+ * * *Returns* :
+ *   - instantiated object of Digest::... implementing exactly same hashing algorithm used for hashing the original signed data.
+ * * *Raises* :
+ *   - +TypeError+ -> wrong argument datatype.
+ *   - +RuntimeError+ -> other errors like corrupted token etc.
+ */
 static VALUE
 guardtime_getnewdigester(VALUE self, VALUE tsdata)
 {
@@ -496,7 +624,18 @@ guardtime_getnewdigester(VALUE self, VALUE tsdata)
 	return Qnil;
 }
 
-
+/* 
+ * call-seq: 
+ *		GuardTime.gethashalg(signature) -> algorithm_name
+ *
+ * * *Args*    :
+ *   - +signature+ -> String containing Guardtime signature token
+ * * *Returns* :
+ *   - String with OpenSSL style hash algorithm name used for hashing the signed data.
+ * * *Raises* :
+ *   - +TypeError+ -> wrong argument datatype.
+ *   - +RuntimeError+ -> other errors like corrupted token etc.
+ */
 static VALUE
 guardtime_gethashalg(VALUE self, VALUE tsdata)
 {
@@ -583,8 +722,9 @@ guardtime_free(GuardTimeData *gt)
 	if (gt) {
         if (gt->pub != NULL)
         	GTPublicationsFile_free(gt->pub);
-        GTHTTP_finalize();
-        GT_finalize();
+        // we'll initialize gt libs when module is 'required' to keep singletons happy; thus free at end of time.
+        // GTHTTP_finalize();
+        // GT_finalize();
    		free(gt);
 	}
 
@@ -593,16 +733,8 @@ guardtime_free(GuardTimeData *gt)
 static VALUE
 guardtime_allocate(VALUE self) 
 {
-	int res;
 	GuardTimeData *gt;
 
-	res = GT_init();
-	if (res != GT_OK)
-		rb_raise(rb_eRuntimeError, GT_getErrorString(res));
-	res = GTHTTP_init("ruby api 0.0", 1);
-	if (res != GT_OK)
-		rb_raise(rb_eRuntimeError, GT_getErrorString(res));
-
 	gt = ALLOC(GuardTimeData);
 	// DATA_PTR(self) = gt;
 	gt->signeruri   = DEFAULT_SIGNERURI;
@@ -614,8 +746,20 @@ guardtime_allocate(VALUE self)
 	return Data_Wrap_Struct(self, 0, guardtime_free, gt);
 }
 
-
-// GuardTime.new(blaah)
+/* 
+ * call-seq: 
+ *		GuardTime.new 		-> obj
+ *		GuardTime.new(confighash) -> obj
+ *
+ * * *Args*    :
+ *   - +confighash+ -> Optional Hash containing configuration parameters. Defaults:
+ *    { :signeruri =>       'http://verifier.guardtime.net/gt-extendingservice',
+ *      :verifieruri =>     'http://verifier.guardtime.net/gt-extendingservice',  # if blank String then online verification is not used
+ *      :publicationsuri => 'http://verify.guardtime.com/gt-controlpublications.bin',
+ *      :loadpubs => 'auto'    ## or once, always, no, auto (update every 8 hours)
+ *    }
+ * Please use env. parameters to specify proxy ({syntax}[http://curl.haxx.se/docs/manpage.html#ENVIRONMENT]), Internet Explorer settints will be used on Windows. Specify url as <em>http://name:pass@site/url</em> for basic auth.
+ */
 static VALUE
 guardtime_initialize(int argc, VALUE *argv, VALUE obj)
 {	
@@ -626,26 +770,79 @@ guardtime_initialize(int argc, VALUE *argv, VALUE obj)
 	return obj;
 }
 
-
+/* 
+ * This API provides access to GuardTime keyless signature service.
+ * Please refer to http://www.guardtime.com/signatures/technology-overview/ for technology overview.
+ * 
+ * The two main operations are signing and verification. Signing involves cryptographically binding the data whose integrity is to be protected to the audited time value and server component's identity in a way that neither the data, the time value nor identity could later be changed undetectably. Verification means checking that the binding is still intact.
+ *
+ * To get a sigature token from a GuardTime service, the client application computes a hash value of the data to be signed and submits the hash value to the signing service. The service returns a signature token binding the hash value to the current time. The interaction follows the standard cryptographic time-stamping protocol defined in the RFC 3161.
+ *
+ * Every month, GuardTime creates an Integrity Code and publishes it in several newspapers across the world. The Integrity Code is a summary of all signatures issued by the GuardTime data integrity services. Any signature issued prior to the creation of the Integrity Code can be traced to it to unambiguously prove the signature’s issuing time, issuer ID and link to signed data, effectively proving the data integrity.
+ *
+ * The proof connecting the signature to the Integrity Code can be inserted back into the token in a process we call extending. An extended signature token is completely independent of GuardTime. Only the original data, the signature and any copy of the newspaper where the Integrity Code is published will be necessary to prove the intgerity of the document.
+ * 
+ * For convenience, GuardTime publishes an electronic archive containing all Integrity Codes since the launch of the service and all valid signing keys. This electronic archive can be used to automate mass verification of thousands of timestamps (whether extended or not) per second in a large archive.
+ */
 void Init_guardtime()
 {
+	int res;
+	res = GT_init();
+	if (res != GT_OK)
+		rb_raise(rb_eRuntimeError, GT_getErrorString(res));
+	res = GTHTTP_init("ruby api 0.0.1", 1);
+	if (res != GT_OK)
+		rb_raise(rb_eRuntimeError, GT_getErrorString(res));
+
     rb_cGuardTime = rb_define_class("GuardTime", rb_cObject);
 	rb_define_alloc_func(rb_cGuardTime, guardtime_allocate);
 	rb_define_method(rb_cGuardTime, "initialize", guardtime_initialize, -1);
 	rb_define_method(rb_cGuardTime, "sign", guardtime_sign, -1);
+	rb_define_method(rb_cGuardTime, "extend", guardtime_extend, 1);
 	rb_define_method(rb_cGuardTime, "verify", guardtime_verify, -1);
 	rb_define_singleton_method(rb_cGuardTime, "gethashalg", guardtime_gethashalg, 1);
 	rb_define_singleton_method(rb_cGuardTime, "getnewdigester", guardtime_getnewdigester, 1);
 
+	/**
+	 * \ingroup verification
+	 *
+	 * Timestamp verification status codes.
+	 *
+	 * \note The values are bit flags so that a single +int+ can contain any combination of them.
+	 */	
+	/* The PKI signature was present in the signature. */	
+	rb_define_const(rb_cGuardTime, "PUBLIC_KEY_SIGNATURE_PRESENT", INT2NUM(GT_PUBLIC_KEY_SIGNATURE_PRESENT));
+	/* Publication references (list of newspaper etc sources to verify publication value) are present in the signature. */
+	rb_define_const(rb_cGuardTime, "PUBLICATION_REFERENCE_PRESENT", INT2NUM(GT_PUBLICATION_REFERENCE_PRESENT));
+	/* The signature was checked against the document hash. */
+	rb_define_const(rb_cGuardTime, "DOCUMENT_HASH_CHECKED", INT2NUM(GT_DOCUMENT_HASH_CHECKED));
+	/* The signature was checked against the publication data. */
+	rb_define_const(rb_cGuardTime, "PUBLICATION_CHECKED", INT2NUM(GT_PUBLICATION_CHECKED));
+
+	/**
+	 * \ingroup verification
+	 *
+	 * Signature verification error codes.
+	 *
+	 * \note Values other than +GT_NO_FAILURES+ are bit flags so that
+	 * a single +int+ can contain any combination of them.
+	 */
+	/* The verification completed successfully. */
 	rb_define_const(rb_cGuardTime, "NO_FAILURES", INT2NUM(GT_NO_FAILURES));
+	/* The level bytes inside the hash chains are improperly ordered. */
 	rb_define_const(rb_cGuardTime, "SYNTACTIC_CHECK_FAILURE", INT2NUM(GT_SYNTACTIC_CHECK_FAILURE));
+	/* The hash chain computation result does not match the publication imprint. */	
 	rb_define_const(rb_cGuardTime, "HASHCHAIN_VERIFICATION_FAILURE", INT2NUM(GT_HASHCHAIN_VERIFICATION_FAILURE));
+	/* The +signed_data+ structure is incorrectly composed, i.e. wrong data
+	 * is signed or the signature does not match with the public key in the
+	 * timestamp. */
 	rb_define_const(rb_cGuardTime, "PUBLIC_KEY_SIGNATURE_FAILURE", INT2NUM(GT_PUBLIC_KEY_SIGNATURE_FAILURE));
+	/* Public key of signature token is not found among trusted ones in publications file. */
 	rb_define_const(rb_cGuardTime, "NOT_VALID_PUBLIC_KEY_FAILURE", INT2NUM(GT_NOT_VALID_PUBLIC_KEY_FAILURE));
+	/* Timestamp does not match with the document it is claimed to belong to. */
 	rb_define_const(rb_cGuardTime, "WRONG_DOCUMENT_FAILURE", INT2NUM(GT_WRONG_DOCUMENT_FAILURE));
+	 /* The publications file is inconsistent with the corresponding data in
+	  * timestamp - publication identifiers do not match or published hash
+	  * values do not match.  */
 	rb_define_const(rb_cGuardTime, "NOT_VALID_PUBLICATION", INT2NUM(GT_NOT_VALID_PUBLICATION));
-	rb_define_const(rb_cGuardTime, "PUBLIC_KEY_SIGNATURE_PRESENT", INT2NUM(GT_PUBLIC_KEY_SIGNATURE_PRESENT));
-	rb_define_const(rb_cGuardTime, "PUBLICATION_REFERENCE_PRESENT", INT2NUM(GT_PUBLICATION_REFERENCE_PRESENT));
-	rb_define_const(rb_cGuardTime, "DOCUMENT_HASH_CHECKED", INT2NUM(GT_DOCUMENT_HASH_CHECKED));
-	rb_define_const(rb_cGuardTime, "PUBLICATION_CHECKED", INT2NUM(GT_PUBLICATION_CHECKED));
 }

data/test/tc_guardtime.rb

@@ -3,12 +3,11 @@ require 'digest/sha2'
 require 'test/unit'
 
 class TestGuardTime < Test::Unit::TestCase
- 
-  def test_old
-  	file = File.open(File.dirname(__FILE__) + File::SEPARATOR + 'cat.gif.gtts', 'rb')
-  	ts = file.read
-  	file.close
 
+  def test_old
+    ts = File.open( File.dirname(__FILE__) + File::SEPARATOR + 'cat.gif.gtts', 'rb' ) do |f|
+        f.read
+    end
   	gt3 = GuardTime.new
   	assert( gt3.verify(ts) )
     assert_raise ArgumentError do
@@ -36,6 +35,19 @@ class TestGuardTime < Test::Unit::TestCase
     	r[:verification_errors] == GuardTime::NO_FAILURES
       end
     )
+    # extending token first, then verifying
+    assert( tsext = gt3.extend(ts) )
+    gt4 = GuardTime.new({:loadpubs => 'once', :verifieruri => ''})
+    gt4.verify(tsext, h3) do |r|
+        assert_equal( GuardTime::PUBLICATION_CHECKED | GuardTime::PUBLICATION_REFERENCE_PRESENT | 
+                    GuardTime::DOCUMENT_HASH_CHECKED, r[:verification_status])
+    end
+    # verification without extending
+    gt4.verify(ts, h3) do |r|
+        assert_equal( GuardTime::PUBLICATION_CHECKED | GuardTime::PUBLIC_KEY_SIGNATURE_PRESENT |
+                    GuardTime::DOCUMENT_HASH_CHECKED, r[:verification_status])
+    end
+
 
   end
 
@@ -101,6 +113,10 @@ class TestGuardTime < Test::Unit::TestCase
     	r[:verification_errors] == GuardTime::NO_FAILURES
     end
     )
+    exception = assert_raise RuntimeError do
+        ext = gt.extend(ts)
+    end
+    assert_match /not yet available/, exception.message
  end
  
 end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 0
-  - 1
-  version: 0.0.1
+  - 2
+  version: 0.0.2
 platform: ruby
 authors: 
 - GuardTime AS
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2013-01-03 00:00:00 +02:00
+date: 2013-01-05 00:00:00 +02:00
 default_executable: 
 dependencies: []
 
@@ -32,8 +32,11 @@ extra_rdoc_files: []
 files: 
 - COPYING
 - INSTALL
+- ChangeLog
 - ext/guardtime.c
 - ext/extconf.rb
+- test/cat.gif
+- test/cat.gif.gtts
 - test/tc_guardtime.rb
 has_rdoc: true
 homepage: http://www.guardtime.com/